LuaSocket: FTP support

From f98977b2dac48fc66822402b095336e683715126 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 23 Mar 2022 00:09:53 +0300 Subject: Move doc→docs so we can serve it with GitHub Pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/ftp.html | 288 ----------------------------------------------------------- 1 file changed, 288 deletions(-) delete mode 100644 doc/ftp.html (limited to 'doc/ftp.html') diff --git a/doc/ftp.html b/doc/ftp.html deleted file mode 100644 index 7f7da2e..0000000 --- a/doc/ftp.html +++ /dev/null @@ -1,288 +0,0 @@ - - - - - - -LuaSocket: FTP support - - - - - - - - - - - -

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

- - - - - - - - -- cgit v1.2.3-55-g6feb