mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-07-03 11:49:47 +02:00
58096449c6
Implemented new distribution scheme. Select is now purely C. HTTP reimplemented seems faster dunno why. LTN12 functions that coroutines fail gracefully.
260 lines
8.2 KiB
HTML
260 lines
8.2 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html>
|
|
|
|
<head>
|
|
<title>LuaSocket: Network support for the Lua language</title>
|
|
<link rel="stylesheet" href="reference.css" type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=header>
|
|
<hr>
|
|
<center>
|
|
<table summary="LuaSocket logo">
|
|
<tr><td align=center><a href="http://www.lua.org">
|
|
<img 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>
|
|
<p class=bar>
|
|
<a href="home.html">home</a> ·
|
|
<a href="home.html#download">download</a> ·
|
|
<a href="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
</center>
|
|
<hr>
|
|
</div>
|
|
|
|
<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h2 id=ftp>FTP</h2>
|
|
|
|
<p>
|
|
FTP (File Transfer Protocol) is a protocol used to transfer files
|
|
between hosts. The module <tt>ftp.lua</tt> offers simple FTP support.
|
|
Applications can easily download and upload files.
|
|
The implementation conforms to
|
|
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>.
|
|
</p>
|
|
|
|
<p>
|
|
URLs MUST conform to
|
|
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
|
|
1738</a>, that is, an URL is a string in the form:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<tt>
|
|
[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][<i>type</i>=a|i]</tt>
|
|
</blockquote>
|
|
|
|
<p>
|
|
High level functions are provided supporting the most common operations.
|
|
These high level functions are implemented on top of a lower level
|
|
interface. By 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 use some of the functions in this module, a good understanding of
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
|
|
LTN012, Filters sources and sinks</a> is necessary.
|
|
</p>
|
|
|
|
<p>
|
|
The following constants can be set to control the default behaviour of
|
|
the FTP module:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> <tt>PASSWORD</tt>: default anonymous password.
|
|
<li> <tt>PORT</tt>: default port used for the control connection;
|
|
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
|
|
<li> <tt>USER</tt>: default anonymous user;
|
|
</ul>
|
|
|
|
<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=get>
|
|
ftp.<b>get(</b>url<b>)</b><br>
|
|
ftp.<b>get{</b><br>
|
|
host = <i>string</i>,<br>
|
|
sink = <i>LTN12 sink</i>,<br>
|
|
argument <i>or</i> path = <i>string</i>,<br>
|
|
[user = <i>string</i>,]<br>
|
|
[password = <i>string</i>]<br>
|
|
[command = <i>string</i>,]<br>
|
|
[port = <i>number</i>,]<br>
|
|
[type = <i>string</i>,]<br>
|
|
[step = <i>LTN12 pump step</i>],<br>
|
|
<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.
|
|
</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 LTN12 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:
|
|
</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><tt>command</tt>: The FTP command used to obtain data. Defaults to
|
|
"<tt>retr</tt>", but see example below;
|
|
<li><tt>port</tt>: The port to contacct the server at. Defaults to 21;
|
|
<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><tt>step</tt>: LTN12 pump step function used to pass data from the
|
|
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
|
|
</ul>
|
|
|
|
<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.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load the ftp support
|
|
local ftp = require("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("ftp")
|
|
local ltn12 = require("ltn12")
|
|
local url = require("url")
|
|
|
|
-- a function that returns a directory listing
|
|
function ls(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>
|
|
|
|
<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=put>
|
|
ftp.<b>put(</b>url, content<b>)</b><br>
|
|
ftp.<b>put{</b><br>
|
|
host = <i>string</i>,<br>
|
|
source = <i>LTN12 sink</i>,<br>
|
|
argument <i>or</i> path = <i>string</i>,<br>
|
|
[user = <i>string</i>,]<br>
|
|
[password = <i>string</i>]<br>
|
|
[command = <i>string</i>,]<br>
|
|
[port = <i>number</i>,]<br>
|
|
[type = <i>string</i>,]<br>
|
|
[step = <i>LTN12 pump step</i>],<br>
|
|
<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.
|
|
</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 LTN12 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:
|
|
</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><tt>command</tt>: The FTP command used to obtain data. Defaults to
|
|
"<tt>retr</tt>", but see example below;
|
|
<li><tt>port</tt>: The port to contacct the server at. Defaults to 21;
|
|
<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><tt>step</tt>: LTN12 pump step function used to pass data from the
|
|
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
|
|
</ul>
|
|
|
|
<p class=return>
|
|
Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
|
|
message describing the reason for failure.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load the ftp support
|
|
local ftp = require("ftp")
|
|
|
|
-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
|
|
-- using password "nehab", and store a file "README" with contents
|
|
-- "wrong password, of course"
|
|
f, e = ftp.put("ftp://diego:nehab@ftp.tecgraf.puc-rio.br/README", "wrong password, of course")
|
|
</pre>
|
|
|
|
<pre class=example>
|
|
-- load the ftp support
|
|
local ftp = require("ftp")
|
|
local ltn12 = require("ltn12")
|
|
|
|
-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
|
|
-- using password "nehab", and append to the file "LOG", sending the
|
|
-- contents of a local file
|
|
f, e = ftp.put{
|
|
host = "ftp.tecgraf.puc-rio.br",
|
|
user = "diego",
|
|
password = "nehab",
|
|
command = "appe",
|
|
argument = "LOG",
|
|
source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
|
|
}
|
|
</pre>
|
|
|
|
|
|
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=footer>
|
|
<hr>
|
|
<center>
|
|
<p class=bar>
|
|
<a href="home.html">home</a> ·
|
|
<a href="home.html#download">download</a> ·
|
|
<a href="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
<p>
|
|
<small>
|
|
Last modified by Diego Nehab on <br>
|
|
Sat Aug 9 01:00:41 PDT 2003
|
|
</small>
|
|
</p>
|
|
</center>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|