...

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
 "http://www.w3.org/TR/html4/strict.dtd">
<html>

<head>
<meta name="description" content="LuaSocket: FTP support">
<meta name="keywords" content="Lua, LuaSocket, FTP, Network, Library, Support">
<title>LuaSocket: FTP support</title>
<link rel="stylesheet" href="reference.css" type="text/css">
</head>

<body>

<div class="header">
<hr>
<center>
<table summary="LuaSocket logo">
<tr><td align="center"><a href="http://www.lua.org">
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr>
<tr><td align="center" valign="top">Network support for the Lua language
</td></tr>
</table>

<a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>

</center>
<hr>
</div>

FTP (File Transfer Protocol) is a protocol used to transfer files
between hosts. The <tt>ftp</tt> namespace offers thorough support
to FTP, under a simple interface. The implementation conforms to
<a href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</a>.

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
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
LTN012, Filters sources and sinks</a> is necessary.

To obtain the <tt>ftp</tt> namespace, run:

<pre class="example">
-- loads the FTP module and any libraries it requires
local ftp = require("socket.ftp")
</pre>

URLs MUST conform to
<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
that is, an URL is a string in the form:

<blockquote>
<tt>
[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][type=a|i]</tt>
</blockquote>

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

<ul>
<li> <tt>PASSWORD</tt>: default anonymous password.</li>
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
<li> <tt>USER</tt>: default anonymous user;</li>
</ul>

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

The <tt>get</tt> 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 <tt>get</tt> function is a table, the function
expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
the simple
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
sink that will receive the downloaded data. <tt>Argument</tt> or
<tt>path</tt> give the target path to the resource in the server. The
optional arguments are the following:

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

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 <tt>nil</tt> and an error message describing the
error.

<pre class="example">
-- 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")
</pre>

<pre class="example">
-- 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
</pre>

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

The <tt>put</tt> 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 <tt>put</tt> function is a table, the function
expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
the simple
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
source that will provide the contents to be uploaded.
<tt>Argument</tt> or
<tt>path</tt> give the target path to the resource in the server. The
optional arguments are the following:

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

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

<pre class="example">
-- 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")
</pre>

<pre class="example">
-- 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"))
}
</pre>

<div class="footer">
<hr>
<center>

<a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>



Last modified by Diego Nehab on 
Thu Apr 20 00:25:18 EDT 2006


</center>
</div>

</body>
</html>

.	Edit
..	Edit
CHANGELOG.md	Edit
README.md	Edit
dns.html	Edit
ftp.html	Edit
http.html	Edit
index.html	Edit
installation.html	Edit
introduction.html	Edit
ltn12.html	Edit
luasocket.png	Edit
mime.html	Edit
reference.css	Edit
reference.html	Edit
smtp.html	Edit
socket.html	Edit
tcp.html	Edit
udp.html	Edit
url.html	Edit