Module socket.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.

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.
• PORT: default port used for the control connection;
• TIMEOUT: sets the timeout for all I/O operations;
• USER: default anonymous user;

Usage:

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

Type socket.ftp

socket.ftp.get(url)	Downloads the contents of a URL.
socket.ftp.put(table)	Uploads a string of content into a URL.

Type socket.ftp

Field(s)

socket.ftp.get(url)

Downloads the contents of a URL.

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. -- call to simple form ftp.get(url)

-- Call to generic form 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]

}

Parameter

• url : URL of content to download as a #string or 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#socket.tcp when the communications socket is created.

Return values

1. #string: If successful, the simple version returns the URL contents as a #string.

2. #number: If successful, the generic function returns 1.

3. #nil, #string: In case of error, #nil and an error message describing the error.

Usages:

• -- 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
  

socket.ftp.put(table)

Uploads a string of content into a URL.

Parameter

• #table 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#socket.tcp when the communications socket is created.

Return values

1. #number: 1 If successful

2. #nil, #string: In case of error, #nil and an error message describing the error.

Usage:

-- 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"))
}