luasocket/doc/ftp.html

289 lines
9.4 KiB
HTML
Raw Normal View History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
2004-06-21 08:07:58 +02:00
<html>
2003-08-31 03:00:15 +02:00
<head>
2004-06-21 08:07:58 +02:00
<meta name="description" content="LuaSocket: FTP support">
<meta name="keywords" content="Lua, LuaSocket, FTP, Network, Library, Support">
2004-06-21 08:07:58 +02:00
<title>LuaSocket: FTP support</title>
2003-08-31 03:00:15 +02:00
<link rel="stylesheet" href="reference.css" type="text/css">
</head>
<body>
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class="header">
2003-08-31 03:00:15 +02:00
<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">
2003-08-31 03:00:15 +02:00
</a></td></tr>
<tr><td align="center" valign="top">Network support for the Lua language
2003-08-31 03:00:15 +02:00
</td></tr>
</table>
<p class="bar">
2009-05-27 11:31:38 +02:00
<a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot;
2004-12-13 07:26:01 +01:00
<a href="installation.html">installation</a> &middot;
2003-08-31 03:00:15 +02:00
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
2003-08-31 03:00:15 +02:00
</p>
</center>
<hr>
</div>
<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id="ftp">FTP</h2>
2003-08-31 03:00:15 +02:00
<p>
FTP (File Transfer Protocol) is a protocol used to transfer files
2004-06-16 06:28:21 +02:00
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>.
2003-08-31 03:00:15 +02:00
</p>
<p>
High level functions are provided supporting the most common operations.
These high level functions are implemented on top of a lower level
2004-06-16 06:28:21 +02:00
interface. Using the low-level interface, users can easily create their
own functions to access <em>any</em> operation supported by the FTP
protocol. For that, check the implementation.
</p>
<p>
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.
</p>
<p>
2004-06-16 22:41:03 +02:00
To obtain the <tt>ftp</tt> namespace, run:
2004-06-16 06:28:21 +02:00
</p>
<pre class="example">
2004-06-16 06:28:21 +02:00
-- loads the FTP module and any libraries it requires
2005-02-08 11:01:01 +01:00
local ftp = require("socket.ftp")
2004-06-16 06:28:21 +02:00
</pre>
<p>
2004-06-16 06:28:21 +02:00
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:
2004-06-16 06:28:21 +02:00
</p>
<blockquote>
<tt>
[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i]</tt>
</blockquote>
<p>
The following constants in the namespace can be set to control the default behavior of
the FTP module:
</p>
<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>
2004-06-16 06:28:21 +02:00
2003-08-31 03:00:15 +02:00
<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class="name" id="get">
ftp.<b>get(</b>url<b>)</b><br>
ftp.<b>get{</b><br>
&nbsp;&nbsp;host = <i>string</i>,<br>
&nbsp;&nbsp;sink = <i>LTN12 sink</i>,<br>
&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
&nbsp;&nbsp;[user = <i>string</i>,]<br>
&nbsp;&nbsp;[password = <i>string</i>]<br>
&nbsp;&nbsp;[command = <i>string</i>,]<br>
&nbsp;&nbsp;[port = <i>number</i>,]<br>
&nbsp;&nbsp;[type = <i>string</i>,]<br>
2004-06-16 22:41:03 +02:00
&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
2005-08-12 07:56:32 +02:00
&nbsp;&nbsp;[create = <i>function</i>]<br>
2003-08-31 03:00:15 +02:00
<b>}</b>
</p>
<p class="description">
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 <em>lot</em> more control, as explained
below.
2003-08-31 03:00:15 +02:00
</p>
<p class="parameters">
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 <em>simple</em>
2004-06-16 22:41:03 +02:00
<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:
2003-08-31 03:00:15 +02:00
</p>
<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>:
2004-06-16 22:41:03 +02:00
<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>
2005-10-05 05:16:17 +02:00
<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>
2003-08-31 03:00:15 +02:00
<p class="return">
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 <b><tt>nil</tt></b> and an error message describing the
error.
2003-08-31 03:00:15 +02:00
</p>
<pre class="example">
-- load the ftp support
2005-02-08 11:01:01 +01:00
local ftp = require("socket.ftp")
2003-08-31 03:00:15 +02:00
-- 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")
2003-08-31 03:00:15 +02:00
</pre>
<pre class="example">
-- load needed modules
2005-02-08 11:01:01 +01:00
local ftp = require("socket.ftp")
local ltn12 = require("ltn12")
2005-02-08 11:01:01 +01:00
local url = require("socket.url")
-- a function that returns a directory listing
2004-11-27 08:58:04 +01:00
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>
2003-08-31 03:00:15 +02:00
<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class="name" id="put">
ftp.<b>put(</b>url, content<b>)</b><br>
ftp.<b>put{</b><br>
&nbsp;&nbsp;host = <i>string</i>,<br>
&nbsp;&nbsp;source = <i>LTN12 sink</i>,<br>
&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
&nbsp;&nbsp;[user = <i>string</i>,]<br>
&nbsp;&nbsp;[password = <i>string</i>]<br>
&nbsp;&nbsp;[command = <i>string</i>,]<br>
&nbsp;&nbsp;[port = <i>number</i>,]<br>
&nbsp;&nbsp;[type = <i>string</i>,]<br>
2004-06-16 22:41:03 +02:00
&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
2005-08-12 07:56:32 +02:00
&nbsp;&nbsp;[create = <i>function</i>]<br>
2003-08-31 03:00:15 +02:00
<b>}</b>
</p>
<p class="description">
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 <em>lot</em> more control, as explained below.
2003-08-31 03:00:15 +02:00
</p>
<p class="parameters">
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 <em>simple</em>
<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:
2003-08-31 03:00:15 +02:00
</p>
<ul>
<li><tt>user</tt>, <tt>password</tt>: User name and password used for
authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
2004-06-16 06:28:21 +02:00
<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>
2004-06-16 22:41:03 +02:00
pump step function used to pass data from the
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
2005-10-05 05:16:17 +02:00
<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>
2003-08-31 03:00:15 +02:00
<p class="return">
Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
message describing the reason for failure.
2003-08-31 03:00:15 +02:00
</p>
<pre class="example">
-- load the ftp support
2005-02-08 11:01:01 +01:00
local ftp = require("socket.ftp")
2003-08-31 03:00:15 +02:00
2004-06-21 00:19:54 +02:00
-- 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",
2004-06-16 06:28:21 +02:00
"wrong password, of course")
</pre>
2003-08-31 03:00:15 +02:00
<pre class="example">
-- load the ftp support
2005-02-08 11:01:01 +01:00
local ftp = require("socket.ftp")
local ltn12 = require("ltn12")
2004-06-21 00:19:54 +02:00
-- Log as user "fulano" on server "ftp.example.com",
-- using password "silva", and append to the remote file "LOG", sending the
2004-06-16 06:28:21 +02:00
-- contents of the local file "LOCAL-LOG"
f, e = ftp.put{
host = "ftp.example.com",
2004-06-21 00:19:54 +02:00
user = "fulano",
password = "silva",
command = "appe",
argument = "LOG",
source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
2003-08-31 03:00:15 +02:00
}
</pre>
2003-08-31 03:00:15 +02:00
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class="footer">
2003-08-31 03:00:15 +02:00
<hr>
<center>
<p class="bar">
2009-05-27 11:31:38 +02:00
<a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot;
2004-12-13 07:26:01 +01:00
<a href="installation.html">installation</a> &middot;
2003-08-31 03:00:15 +02:00
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
2003-08-31 03:00:15 +02:00
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Thu Apr 20 00:25:18 EDT 2006
2003-08-31 03:00:15 +02:00
</small>
</p>
</center>
</div>
</body>
</html>