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:
-- loads the FTP module and any libraries it requires
local ftp = require("socket.ftp")
socket.ftp
socket.ftp.get(url) | Downloads the contents of a URL. |
socket.ftp.put(table) | Uploads a string of content into a URL. |
socket.ftp
socket.ftp.get(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]
}
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:
-- 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)
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:
-- 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"))
}