Network support for the Lua language

home · download · installation · introduction · reference

## FTP

FTP (File Transfer Protocol) is a protocol used to transfer files between hosts. The `ftp` namespace offers thorough support to FTP, under a simple interface. The implementation conforms to RFC 959.

High level functions are provided supporting the most common operations. These high level functions are implemented on top of a lower level interface. Using the low-level interface, users can easily create their own functions to access any operation supported by the FTP protocol. For that, check the implementation.

To really benefit from this module, a good understanding of LTN012, Filters sources and sinks is necessary.

To obtain the `ftp` namespace, run:

    -- loads the FTP module and any libraries it requires
    local ftp = require("socket.ftp")

URLs MUST conform to RFC 1738, that is, an URL is a string in the form:

> `[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][type=a|i]`

The following constants in the namespace can be set to control the default behavior of the FTP module:

- `PASSWORD`: default anonymous password.
- `TIMEOUT`: sets the timeout for all I/O operations;
- `USER`: default anonymous user;

ftp.get(url)
ftp.get{
host = string,
sink = LTN12 sink,
argument or path = string,
[user = string,]
[password = string]
[command = string,]
[port = number,]
[type = string,]
[step = LTN12 pump step,]
[create = function]
}

The `get` function has two forms. The simple form has fixed functionality: it downloads the contents of a URL and returns it as a string. The generic form allows a lot more control, as explained below.

If the argument of the `get` function is a table, the function expects at least the fields `host`, `sink`, and one of `argument` or `path` (`argument` takes precedence). `Host` is the server to connect to. `Sink` is the simple LTN12 sink that will receive the downloaded data. `Argument` or `path` give the target path to the resource in the server. The optional arguments are the following:

- `user`, `password`: User name and password used for authentication. Defaults to "`ftp:anonymous@anonymous.org`";
- `command`: The FTP command used to obtain data. Defaults to "`retr`", but see example below;
- `port`: The port to used for the control connection. Defaults to 21;
- `type`: The transfer mode. Can take values "`i`" or "`a`". Defaults to whatever is the server default;
- `step`: LTN12 pump step function used to pass data from the server to the sink. Defaults to the LTN12 `pump.step` function;
- `create`: An optional function to be used instead of `socket.tcp` when the communications socket is created.

If successful, the simple version returns the URL contents as a string, and the generic function returns 1. In case of error, both functions return `nil` and an error message describing the error.

    -- load the ftp support
    local ftp = require("socket.ftp")

    -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
    -- and get file "lua.tar.gz" from directory "pub/lua" as binary.
    f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")

    -- load needed modules
    local ftp = require("socket.ftp")
    local ltn12 = require("ltn12")
    local url = require("socket.url")

    -- a function that returns a directory listing
    function nlst(u)
        local t = {}
        local p = url.parse(u)
        p.command = "nlst"
        p.sink = ltn12.sink.table(t)
        local r, e = ftp.get(p)
        return r and table.concat(t), e
    end

ftp.put(url, content)
ftp.put{
host = string,
source = LTN12 sink,
argument or path = string,
[user = string,]
[password = string]
[command = string,]
[port = number,]
[type = string,]
[step = LTN12 pump step,]
[create = function]
}

The `put` function has two forms. The simple form has fixed functionality: it uploads a string of content into a URL. The generic form allows a lot more control, as explained below.

If the argument of the `put` function is a table, the function expects at least the fields `host`, `source`, and one of `argument` or `path` (`argument` takes precedence). `Host` is the server to connect to. `Source` is the simple LTN12 source that will provide the contents to be uploaded. `Argument` or `path` give the target path to the resource in the server. The optional arguments are the following:

- `user`, `password`: User name and password used for authentication. Defaults to "`ftp:anonymous@anonymous.org`";
- `command`: The FTP command used to send data. Defaults to "`stor`", but see example below;
- `port`: The port to used for the control connection. Defaults to 21;
- `type`: The transfer mode. Can take values "`i`" or "`a`". Defaults to whatever is the server default;
- `step`: LTN12 pump step function used to pass data from the server to the sink. Defaults to the LTN12 `pump.step` function;
- `create`: An optional function to be used instead of `socket.tcp` when the communications socket is created.

Both functions return 1 if successful, or `nil` and an error message describing the reason for failure.

    -- load the ftp support
    local ftp = require("socket.ftp")

    -- Log as user "fulano" on server "ftp.example.com",
    -- using password "silva", and store a file "README" with contents
    -- "wrong password, of course"
    f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
        "wrong password, of course")

    -- load the ftp support
    local ftp = require("socket.ftp")
    local ltn12 = require("ltn12")

    -- Log as user "fulano" on server "ftp.example.com",
    -- using password "silva", and append to the remote file "LOG", sending the
    -- contents of the local file "LOCAL-LOG"
    f, e = ftp.put{
      host = "ftp.example.com",
      user = "fulano",
      password = "silva",
      command = "appe",
      argument = "LOG",
      source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
    }