aboutsummaryrefslogtreecommitdiff
path: root/doc/ftp.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2004-06-15 06:24:00 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2004-06-15 06:24:00 +0000
commit58096449c6044b7aade5cd41cfd71c6bec1d273d (patch)
tree1814ffebe89c4c2556d84f97f66db37a7e8b4554 /doc/ftp.html
parent9ed7f955e5fc69af9bf1794fa2c8cd227981ba24 (diff)
downloadluasocket-58096449c6044b7aade5cd41cfd71c6bec1d273d.tar.gz
luasocket-58096449c6044b7aade5cd41cfd71c6bec1d273d.tar.bz2
luasocket-58096449c6044b7aade5cd41cfd71c6bec1d273d.zip
Manual is almost done. HTTP is missing.
Implemented new distribution scheme. Select is now purely C. HTTP reimplemented seems faster dunno why. LTN12 functions that coroutines fail gracefully.
Diffstat (limited to 'doc/ftp.html')
-rw-r--r--doc/ftp.html272
1 files changed, 144 insertions, 128 deletions
diff --git a/doc/ftp.html b/doc/ftp.html
index 6776a17..a0c9268 100644
--- a/doc/ftp.html
+++ b/doc/ftp.html
@@ -35,9 +35,9 @@
35 35
36<p> 36<p>
37FTP (File Transfer Protocol) is a protocol used to transfer files 37FTP (File Transfer Protocol) is a protocol used to transfer files
38between hosts. The module <tt>ftp.lua</tt> offers simple FTP support, 38between hosts. The module <tt>ftp.lua</tt> offers simple FTP support.
39allowing applications to download and upload files, and list directory 39Applications can easily download and upload files.
40contents. The implementation conforms to 40The implementation conforms to
41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>. 41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>.
42</p> 42</p>
43 43
@@ -49,175 +49,191 @@ URLs MUST conform to
49 49
50<blockquote> 50<blockquote>
51<tt> 51<tt>
52[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i|d]</tt> 52[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i]</tt>
53</blockquote> 53</blockquote>
54 54
55<p>
56High level functions are provided supporting the most common operations.
57These high level functions are implemented on top of a lower level
58interface. By using the low-level interface, users can easily create their
59own functions to access <em>any</em> operation supported by the FTP
60protocol. For that, check the implementation.
61</p>
62
63<p>
64To use some of the functions in this module, a good understanding of
65<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
66LTN012, Filters sources and sinks</a> is necessary.
67</p>
68
69<p>
70The following constants can be set to control the default behaviour of
71the FTP module:
72</p>
73
74<ul>
75<li> <tt>PASSWORD</tt>: default anonymous password.
76<li> <tt>PORT</tt>: default port used for the control connection;
77<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
78<li> <tt>USER</tt>: default anonymous user;
79</ul>
80
55<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 81<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
56 82
57<p class=name id=get> 83<p class=name id=get>
58socket.ftp.<b>get(</b>url<b>)</b><br> 84ftp.<b>get(</b>url<b>)</b><br>
59socket.ftp.<b>get{</b><br> 85ftp.<b>get{</b><br>
60&nbsp;&nbsp;url = <i>string</i>,<br> 86&nbsp;&nbsp;host = <i>string</i>,<br>
61&nbsp;&nbsp;type = <i>string</i>,<br> 87&nbsp;&nbsp;sink = <i>LTN12 sink</i>,<br>
62&nbsp;&nbsp;user = <i>string</i>,<br> 88&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
63&nbsp;&nbsp;password = <i>string</i><br> 89&nbsp;&nbsp;[user = <i>string</i>,]<br>
90&nbsp;&nbsp;[password = <i>string</i>]<br>
91&nbsp;&nbsp;[command = <i>string</i>,]<br>
92&nbsp;&nbsp;[port = <i>number</i>,]<br>
93&nbsp;&nbsp;[type = <i>string</i>,]<br>
94&nbsp;&nbsp;[step = <i>LTN12 pump step</i>],<br>
64<b>}</b> 95<b>}</b>
65</p> 96</p>
66 97
67<p class=description> 98<p class=description>
68Downloads an URL from a FTP server. 99The <tt>get</tt> function has two forms. The simple form has fixed
100functionality: it downloads the contents of a URL and returns it as a
101string. The generic form allows a <em>lot</em> more control, as explained
102below.
69</p> 103</p>
70 104
71<p class=parameters> 105<p class=parameters>
72The function can be called either directly with a <tt>url</tt> 106If the argument of the <tt>get</tt> function is a table, the function
73or with a <em>request table</em>. 107expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
74Fields passed explicitly in the request table override those 108<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
75present in the <tt>url</tt>. 109precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
76</p> 110the LTN12 sink that will receive the downloaded data. <tt>Argument</tt> or
77 111<tt>path</tt> give the target path to the resource in the server. The
78<p class=parameters> 112optional arguments are the following:
79The parameter <tt>type</tt> accepts values '<tt>a</tt>' (ASCII, the
80default), '<tt>i</tt>' (binary) or '<tt>d</tt>' (directory listing) and
81determines the transfer type. If <tt>&lt;path&gt;</tt> ends with a
82'<tt>/</tt>' or <tt>type</tt> is '<tt>d</tt>', a directory listing of
83<tt>&lt;path&gt;</tt> is returned. If no <tt>user</tt> is provided in the
84<tt>url</tt> or explicitly, the function tries to log in as user
85'<tt>anonymous</tt>'.
86</p> 113</p>
114<ul>
115<li><tt>user</tt>, <tt>password</tt>: User name and password used for
116authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
117<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
118"<tt>retr</tt>", but see example below;
119<li><tt>port</tt>: The port to contacct the server at. Defaults to 21;
120<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
121"<tt>a</tt>". Defaults to whatever is the server default;
122<li><tt>step</tt>: LTN12 pump step function used to pass data from the
123server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
124</ul>
87 125
88<p class=return> 126<p class=return>
89If successful, the function returns 127If successful, the simple version returns the URL contents as a
90the file content as a string. In case of error, the function returns 128string, and the generic function returns 1. In case of error, both
91<b><tt>nil</tt></b> and an error message describing the error. 129functions return <b><tt>nil</tt></b> and an error message describing the
130error.
92</p> 131</p>
93 132
94<pre class=example> 133<pre class=example>
95-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br", 134-- load the ftp support
96-- go to directory "pub/lua" and get file "lua.tar.gz" as binary. 135local ftp = require("ftp")
97f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
98 136
99-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br", 137-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
100-- go to director "pub" and retrieve directory listing of directory "lua" 138-- and get file "lua.tar.gz" from directory "pub/lua" as binary.
101f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d") 139f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
102
103-- Log as user "diego", password "nehab", on server "ftp.tecgraf.puc-rio.br",
104-- go to directory "tec/luasocket/bin" and retrieve file "luasocket.exe"
105-- (actually, fails because of wrong password, of course)
106f, e = socket.ftp.get{
107 url = "ftp://ftp.tecgraf.puc-rio.br/tec/luasocket/bin/luasocket.exe",
108 user = "diego",
109 password = "nehab",
110 type = "i"
111}
112-- f returns nil, and e returns an appropriate error message
113</pre> 140</pre>
114 141
115<!-- get_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 142<pre class=example>
116 143-- load needed modules
117<p class=name id=get_cb> 144local ftp = require("ftp")
118socket.ftp.<b>get_cb{</b><br> 145local ltn12 = require("ltn12")
119&nbsp;&nbsp;url = <i>string</i>,<br> 146local url = require("url")
120&nbsp;&nbsp;type = <i>string</i>,<br> 147
121&nbsp;&nbsp;content_cb = <i>receive-callback</i>,<br> 148-- a function that returns a directory listing
122&nbsp;&nbsp;user = <i>string</i>,<br> 149function ls(u)
123&nbsp;&nbsp;password = <i>string</i><br> 150 local t = {}
124<b>}</b> 151 local p = url.parse(u)
125</p> 152 p.command = "nlst"
126 153 p.sink = ltn12.sink.table(t)
127<p class=description> 154 local r, e = ftp.get(p)
128Same as <a href="#get"><tt>get</tt></a>, but the library returns 155 return r and table.concat(t), e
129the content of the downloaded file to the receive callback 156end
130<tt>content_cb</tt>. 157</pre>
131</p>
132
133<p class=note>
134Note: for more information on callbacks, refer to
135<a href="stream.html#stream">Streaming with callbacks</a>.
136</p>
137 158
138<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 159<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139 160
140<p class=name id=put> 161<p class=name id=put>
141socket.ftp.<b>put(</b>url, content<b>)</b><br> 162ftp.<b>put(</b>url, content<b>)</b><br>
142socket.ftp.<b>put{</b><br> 163ftp.<b>put{</b><br>
143&nbsp;&nbsp;url = <i>string</i>,<br> 164&nbsp;&nbsp;host = <i>string</i>,<br>
144&nbsp;&nbsp;content = <i>string</i>,<br> 165&nbsp;&nbsp;source = <i>LTN12 sink</i>,<br>
145&nbsp;&nbsp;type = <i>string</i>,<br> 166&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
146&nbsp;&nbsp;user = <i>string</i>,<br> 167&nbsp;&nbsp;[user = <i>string</i>,]<br>
147&nbsp;&nbsp;password = <i>string</i><br> 168&nbsp;&nbsp;[password = <i>string</i>]<br>
169&nbsp;&nbsp;[command = <i>string</i>,]<br>
170&nbsp;&nbsp;[port = <i>number</i>,]<br>
171&nbsp;&nbsp;[type = <i>string</i>,]<br>
172&nbsp;&nbsp;[step = <i>LTN12 pump step</i>],<br>
148<b>}</b> 173<b>}</b>
149</p> 174</p>
150 175
151<p class=description> 176<p class=description>
152Upload a file to a FTP server. 177The <tt>put</tt> function has two forms. The simple form has fixed
178functionality: it uploads a string of content into a URL. The generic form
179allows a <em>lot</em> more control, as explained below.
153</p> 180</p>
154 181
155<p class=parameters> 182<p class=parameters>
156The function can be called directly with a 183If the argument of the <tt>put</tt> function is a table, the function
157<tt>url</tt> and <tt>content</tt> parameters, or with a 184expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
158<em>request table</em>. 185<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
159Values passed explicitly in the request table override those present in 186precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
160the <tt>url</tt>. The parameter <tt>type</tt> accept values 187the LTN12 source that will provide the contents to be uploaded.
161'<tt>a</tt>' (ASCII, the default) or '<tt>i</tt>' (binary) and 188<tt>Argument</tt> or
162determines the transfer type. If no <tt>user</tt> is provided, the 189<tt>path</tt> give the target path to the resource in the server. The
163function tries to log in as '<tt>anonymous</tt>'. 190optional arguments are the following:
164</p> 191</p>
192<ul>
193<li><tt>user</tt>, <tt>password</tt>: User name and password used for
194authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
195<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
196"<tt>retr</tt>", but see example below;
197<li><tt>port</tt>: The port to contacct the server at. Defaults to 21;
198<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
199"<tt>a</tt>". Defaults to whatever is the server default;
200<li><tt>step</tt>: LTN12 pump step function used to pass data from the
201server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
202</ul>
165 203
166<p class=return> 204<p class=return>
167If successful, the function returns 1. In case of error, the 205Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
168function returns <b><tt>nil</tt></b> followed by a string describing the error. 206message describing the reason for failure.
169</p> 207</p>
170 208
171<pre class=example> 209<pre class=example>
172-- Log as user "anonymous" on server "ftp.free.org" and store file 210-- load the ftp support
173-- "hello" with contents "hello world!", using binary mode for the transfer 211local ftp = require("ftp")
174r, e = socket.ftp.put("ftp://ftp.free.org/hello;type=i", "hello world!\n")
175
176-- Does exactly the same, but logging in as diego
177r, e = socket.ftp.put{
178 url = "ftp://ftp.free.org/hello",
179 type = "i",
180 user = "diego",
181 password = "nehab",
182 content = "hello world\n"
183}
184</pre>
185</blockquote>
186
187<!-- put_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
188
189<p class=name id=put_cb>
190socket.ftp.<b>put_cb{</b><br>
191&nbsp;&nbsp;url = <i>string</i>,<br>
192&nbsp;&nbsp;type = <i>string</i>,<br>
193&nbsp;&nbsp;content_cb = <i>send-callback</i>,<br>
194&nbsp;&nbsp;user = <i>string</i>,<br>
195&nbsp;&nbsp;password = <i>string</i><br>
196<b>}</b>
197</p>
198
199<p class=description>
200Same as <a href="#put"><tt>put</tt></a>, but the
201library obtains the contents of the file to be uploaded using the send
202callback <tt>content_cb</tt>.
203</p>
204 212
205<p class=note> 213-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
206Note: for more information on callbacks, refer to 214-- using password "nehab", and store a file "README" with contents
207<a href="stream.html#stream">Streaming with callbacks</a>. 215-- "wrong password, of course"
208</p> 216f, e = ftp.put("ftp://diego:nehab@ftp.tecgraf.puc-rio.br/README", "wrong password, of course")
217</pre>
209 218
210<pre class=example> 219<pre class=example>
211-- Log as user "anonymous" on server "ftp.free.org" and store file 220-- load the ftp support
212-- "hello" with contents of the same file in the current directory, 221local ftp = require("ftp")
213-- using binary mode for the transfer 222local ltn12 = require("ltn12")
214r, e = socket.ftp.put_cb{ 223
215 url = "ftp://ftp.free.org/hello", 224-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
216 type = "i", 225-- using password "nehab", and append to the file "LOG", sending the
217 content_cb = socket.callback.send_file(io.open("hello", "r")) 226-- contents of a local file
227f, e = ftp.put{
228 host = "ftp.tecgraf.puc-rio.br",
229 user = "diego",
230 password = "nehab",
231 command = "appe",
232 argument = "LOG",
233 source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
218} 234}
219</pre> 235</pre>
220</blockquote> 236
221 237
222<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 238<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
223 239