LuaSocket: Network support for the Lua language

FTP

FTP (File Transfer Protocol) is a protocol used to transfer files between hosts. The module ftp.lua offers simple FTP support. Applications can easily download and upload files. The implementation conforms to RFC 959.

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]

High level functions are provided supporting the most common operations. These high level functions are implemented on top of a lower level interface. By 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 use some of the functions in this module, a good understanding of LTN012, Filters sources and sinks is necessary.

The following constants can be set to control the default behaviour of the FTP module:

PASSWORD: default anonymous password.
PORT: default port used for the control connection;
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],
}

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 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 contacct the server at. 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.

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("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("ftp")
local ltn12 = require("ltn12")
local url = require("url")

-- a function that returns a directory listing
function ls(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],
}

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 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 obtain data. Defaults to "retr", but see example below;
port: The port to contacct the server at. 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.

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

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

-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
-- using password "nehab", and store a file "README" with contents 
-- "wrong password, of course"
f, e = ftp.put("ftp://diego:nehab@ftp.tecgraf.puc-rio.br/README", "wrong password, of course")

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

-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
-- using password "nehab", and append to the file "LOG", sending the
-- contents of a local file 
f, e = ftp.put{
  host = "ftp.tecgraf.puc-rio.br", 
  user = "diego",
  password = "nehab",
  command = "appe",
  argument = "LOG",
  source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
}