aboutsummaryrefslogtreecommitdiff
path: root/doc/ftp.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ftp.html')
-rw-r--r--doc/ftp.html122
1 files changed, 61 insertions, 61 deletions
diff --git a/doc/ftp.html b/doc/ftp.html
index 091c88f..7f7da2e 100644
--- a/doc/ftp.html
+++ b/doc/ftp.html
@@ -1,5 +1,5 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
@@ -13,22 +13,22 @@
13 13
14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot; 30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a> 31<a href="reference.html">reference</a>
32</p> 32</p>
33</center> 33</center>
34<hr> 34<hr>
@@ -36,7 +36,7 @@
36 36
37<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 37<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38 38
39<h2 id=ftp>FTP</h2> 39<h2 id="ftp">FTP</h2>
40 40
41<p> 41<p>
42FTP (File Transfer Protocol) is a protocol used to transfer files 42FTP (File Transfer Protocol) is a protocol used to transfer files
@@ -50,28 +50,28 @@ High level functions are provided supporting the most common operations.
50These high level functions are implemented on top of a lower level 50These high level functions are implemented on top of a lower level
51interface. Using the low-level interface, users can easily create their 51interface. Using the low-level interface, users can easily create their
52own functions to access <em>any</em> operation supported by the FTP 52own functions to access <em>any</em> operation supported by the FTP
53protocol. For that, check the implementation. 53protocol. For that, check the implementation.
54</p> 54</p>
55 55
56<p> 56<p>
57To really benefit from this module, a good understanding of 57To really benefit from this module, a good understanding of
58<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> 58<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
59LTN012, Filters sources and sinks</a> is necessary. 59LTN012, Filters sources and sinks</a> is necessary.
60</p> 60</p>
61 61
62<p> 62<p>
63To obtain the <tt>ftp</tt> namespace, run: 63To obtain the <tt>ftp</tt> namespace, run:
64</p> 64</p>
65 65
66<pre class=example> 66<pre class="example">
67-- loads the FTP module and any libraries it requires 67-- loads the FTP module and any libraries it requires
68local ftp = require("socket.ftp") 68local ftp = require("socket.ftp")
69</pre> 69</pre>
70 70
71<p> 71<p>
72URLs MUST conform to 72URLs MUST conform to
73<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, 73<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
74that is, an URL is a string in the form: 74that is, an URL is a string in the form:
75</p> 75</p>
76 76
77<blockquote> 77<blockquote>
@@ -81,19 +81,19 @@ that is, an URL is a string in the form:
81 81
82<p> 82<p>
83The following constants in the namespace can be set to control the default behavior of 83The following constants in the namespace can be set to control the default behavior of
84the FTP module: 84the FTP module:
85</p> 85</p>
86 86
87<ul> 87<ul>
88<li> <tt>PASSWORD</tt>: default anonymous password. 88<li> <tt>PASSWORD</tt>: default anonymous password.</li>
89<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; 89<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
90<li> <tt>USER</tt>: default anonymous user; 90<li> <tt>USER</tt>: default anonymous user;</li>
91</ul> 91</ul>
92 92
93 93
94<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 94<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
95 95
96<p class=name id=get> 96<p class="name" id="get">
97ftp.<b>get(</b>url<b>)</b><br> 97ftp.<b>get(</b>url<b>)</b><br>
98ftp.<b>get{</b><br> 98ftp.<b>get{</b><br>
99&nbsp;&nbsp;host = <i>string</i>,<br> 99&nbsp;&nbsp;host = <i>string</i>,<br>
@@ -109,19 +109,19 @@ ftp.<b>get{</b><br>
109<b>}</b> 109<b>}</b>
110</p> 110</p>
111 111
112<p class=description> 112<p class="description">
113The <tt>get</tt> function has two forms. The simple form has fixed 113The <tt>get</tt> function has two forms. The simple form has fixed
114functionality: it downloads the contents of a URL and returns it as a 114functionality: it downloads the contents of a URL and returns it as a
115string. The generic form allows a <em>lot</em> more control, as explained 115string. The generic form allows a <em>lot</em> more control, as explained
116below. 116below.
117</p> 117</p>
118 118
119<p class=parameters> 119<p class="parameters">
120If the argument of the <tt>get</tt> function is a table, the function 120If the argument of the <tt>get</tt> function is a table, the function
121expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of 121expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
122<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes 122<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
123precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is 123precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
124the <em>simple</em> 124the <em>simple</em>
125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
126sink that will receive the downloaded data. <tt>Argument</tt> or 126sink that will receive the downloaded data. <tt>Argument</tt> or
127<tt>path</tt> give the target path to the resource in the server. The 127<tt>path</tt> give the target path to the resource in the server. The
@@ -129,28 +129,28 @@ optional arguments are the following:
129</p> 129</p>
130<ul> 130<ul>
131<li><tt>user</tt>, <tt>password</tt>: User name and password used for 131<li><tt>user</tt>, <tt>password</tt>: User name and password used for
132authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; 132authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
133<li><tt>command</tt>: The FTP command used to obtain data. Defaults to 133<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
134"<tt>retr</tt>", but see example below; 134"<tt>retr</tt>", but see example below;</li>
135<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; 135<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
136<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or 136<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
137"<tt>a</tt>". Defaults to whatever is the server default; 137"<tt>a</tt>". Defaults to whatever is the server default;</li>
138<li><tt>step</tt>: 138<li><tt>step</tt>:
139<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 139<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
140pump step function used to pass data from the 140pump step function used to pass data from the
141server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; 141server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
142<li><tt>create</tt>: An optional function to be used instead of 142<li><tt>create</tt>: An optional function to be used instead of
143<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. 143<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
144</ul> 144</ul>
145 145
146<p class=return> 146<p class="return">
147If successful, the simple version returns the URL contents as a 147If successful, the simple version returns the URL contents as a
148string, and the generic function returns 1. In case of error, both 148string, and the generic function returns 1. In case of error, both
149functions return <b><tt>nil</tt></b> and an error message describing the 149functions return <b><tt>nil</tt></b> and an error message describing the
150error. 150error.
151</p> 151</p>
152 152
153<pre class=example> 153<pre class="example">
154-- load the ftp support 154-- load the ftp support
155local ftp = require("socket.ftp") 155local ftp = require("socket.ftp")
156 156
@@ -159,7 +159,7 @@ local ftp = require("socket.ftp")
159f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") 159f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
160</pre> 160</pre>
161 161
162<pre class=example> 162<pre class="example">
163-- load needed modules 163-- load needed modules
164local ftp = require("socket.ftp") 164local ftp = require("socket.ftp")
165local ltn12 = require("ltn12") 165local ltn12 = require("ltn12")
@@ -178,7 +178,7 @@ end
178 178
179<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 179<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
180 180
181<p class=name id=put> 181<p class="name" id="put">
182ftp.<b>put(</b>url, content<b>)</b><br> 182ftp.<b>put(</b>url, content<b>)</b><br>
183ftp.<b>put{</b><br> 183ftp.<b>put{</b><br>
184&nbsp;&nbsp;host = <i>string</i>,<br> 184&nbsp;&nbsp;host = <i>string</i>,<br>
@@ -194,57 +194,57 @@ ftp.<b>put{</b><br>
194<b>}</b> 194<b>}</b>
195</p> 195</p>
196 196
197<p class=description> 197<p class="description">
198The <tt>put</tt> function has two forms. The simple form has fixed 198The <tt>put</tt> function has two forms. The simple form has fixed
199functionality: it uploads a string of content into a URL. The generic form 199functionality: it uploads a string of content into a URL. The generic form
200allows a <em>lot</em> more control, as explained below. 200allows a <em>lot</em> more control, as explained below.
201</p> 201</p>
202 202
203<p class=parameters> 203<p class="parameters">
204If the argument of the <tt>put</tt> function is a table, the function 204If the argument of the <tt>put</tt> function is a table, the function
205expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of 205expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
206<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes 206<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
207precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is 207precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
208the <em>simple</em> 208the <em>simple</em>
209<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 209<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
210source that will provide the contents to be uploaded. 210source that will provide the contents to be uploaded.
211<tt>Argument</tt> or 211<tt>Argument</tt> or
212<tt>path</tt> give the target path to the resource in the server. The 212<tt>path</tt> give the target path to the resource in the server. The
213optional arguments are the following: 213optional arguments are the following:
214</p> 214</p>
215<ul> 215<ul>
216<li><tt>user</tt>, <tt>password</tt>: User name and password used for 216<li><tt>user</tt>, <tt>password</tt>: User name and password used for
217authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; 217authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
218<li><tt>command</tt>: The FTP command used to send data. Defaults to 218<li><tt>command</tt>: The FTP command used to send data. Defaults to
219"<tt>stor</tt>", but see example below; 219"<tt>stor</tt>", but see example below;</li>
220<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; 220<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
221<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or 221<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
222"<tt>a</tt>". Defaults to whatever is the server default; 222"<tt>a</tt>". Defaults to whatever is the server default;</li>
223<li><tt>step</tt>: 223<li><tt>step</tt>:
224<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 224<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
225pump step function used to pass data from the 225pump step function used to pass data from the
226server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; 226server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
227<li><tt>create</tt>: An optional function to be used instead of 227<li><tt>create</tt>: An optional function to be used instead of
228<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. 228<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
229</ul> 229</ul>
230 230
231<p class=return> 231<p class="return">
232Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error 232Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
233message describing the reason for failure. 233message describing the reason for failure.
234</p> 234</p>
235 235
236<pre class=example> 236<pre class="example">
237-- load the ftp support 237-- load the ftp support
238local ftp = require("socket.ftp") 238local ftp = require("socket.ftp")
239 239
240-- Log as user "fulano" on server "ftp.example.com", 240-- Log as user "fulano" on server "ftp.example.com",
241-- using password "silva", and store a file "README" with contents 241-- using password "silva", and store a file "README" with contents
242-- "wrong password, of course" 242-- "wrong password, of course"
243f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", 243f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
244 "wrong password, of course") 244 "wrong password, of course")
245</pre> 245</pre>
246 246
247<pre class=example> 247<pre class="example">
248-- load the ftp support 248-- load the ftp support
249local ftp = require("socket.ftp") 249local ftp = require("socket.ftp")
250local ltn12 = require("ltn12") 250local ltn12 = require("ltn12")
@@ -253,7 +253,7 @@ local ltn12 = require("ltn12")
253-- using password "silva", and append to the remote file "LOG", sending the 253-- using password "silva", and append to the remote file "LOG", sending the
254-- contents of the local file "LOCAL-LOG" 254-- contents of the local file "LOCAL-LOG"
255f, e = ftp.put{ 255f, e = ftp.put{
256 host = "ftp.example.com", 256 host = "ftp.example.com",
257 user = "fulano", 257 user = "fulano",
258 password = "silva", 258 password = "silva",
259 command = "appe", 259 command = "appe",
@@ -265,15 +265,15 @@ f, e = ftp.put{
265 265
266<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 266<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
267 267
268<div class=footer> 268<div class="footer">
269<hr> 269<hr>
270<center> 270<center>
271<p class=bar> 271<p class="bar">
272<a href="index.html">home</a> &middot; 272<a href="index.html">home</a> &middot;
273<a href="index.html#download">download</a> &middot; 273<a href="index.html#download">download</a> &middot;
274<a href="installation.html">installation</a> &middot; 274<a href="installation.html">installation</a> &middot;
275<a href="introduction.html">introduction</a> &middot; 275<a href="introduction.html">introduction</a> &middot;
276<a href="reference.html">reference</a> 276<a href="reference.html">reference</a>
277</p> 277</p>
278<p> 278<p>
279<small> 279<small>