aboutsummaryrefslogtreecommitdiff
path: root/doc/ftp.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
commit982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch)
tree8f96f9e9fa1e6bef8b8356037986ddc18673cade /doc/ftp.html
parent6789b83ff5c15296267f880d3b98cf8a1800c30a (diff)
downloadluasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.gz
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.bz2
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.zip
LuaSocket 2.0 User's Manual.
Diffstat (limited to 'doc/ftp.html')
-rw-r--r--doc/ftp.html243
1 files changed, 243 insertions, 0 deletions
diff --git a/doc/ftp.html b/doc/ftp.html
new file mode 100644
index 0000000..8072afe
--- /dev/null
+++ b/doc/ftp.html
@@ -0,0 +1,243 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html>
2
3<head>
4<title>LuaSocket: Network support for the Lua language</title>
5<link rel="stylesheet" href="reference.css" type="text/css">
6</head>
7
8<body>
9
10<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
11
12<div class=header>
13<hr>
14<center>
15<table summary="LuaSocket logo">
16<tr><td align=center><a href="http://www.lua.org">
17<img border=0 alt="LuaSocket" src="luasocket.png">
18</a></td></tr>
19<tr><td align=center valign=top>Network support for the Lua language
20</td></tr>
21</table>
22<p class=bar>
23<a href="home.html">home</a> &middot;
24<a href="home.html#download">download</a> &middot;
25<a href="introduction.html">introduction</a> &middot;
26<a href="reference.html">reference</a>
27</p>
28</center>
29<hr>
30</div>
31
32<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
33
34<h2 id=ftp>FTP</h2>
35
36<p>
37FTP (File Transfer Protocol) is a protocol used to transfer files
38between hosts. The module <tt>ftp.lua</tt> offers simple FTP support,
39allowing applications to download and upload files, and list directory
40contents. The implementation conforms to
41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>.
42</p>
43
44<p>
45URLs MUST conform to
46<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
471738</a>, that is, an URL is a string in the form:
48</p>
49
50<blockquote>
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>
53</blockquote>
54
55<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
56
57<p class=name id=get>
58socket.ftp.<b>get(</b>url<b>)</b><br>
59socket.ftp.<b>get{</b><br>
60&nbsp;&nbsp;url = <i>string</i>,<br>
61&nbsp;&nbsp;type = <i>string</i>,<br>
62&nbsp;&nbsp;user = <i>string</i>,<br>
63&nbsp;&nbsp;password = <i>string</i><br>
64<b>}</b>
65</p>
66
67<p class=description>
68Downloads an URL from a FTP server.
69</p>
70
71<p class=parameters>
72The function can be called either directly with a <tt>url</tt>
73or with a <em>request table</em>.
74Fields passed explicitly in the request table override those
75present in the <tt>url</tt>.
76</p>
77
78<p class=parameters>
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>
87
88<p class=return>
89If successful, the function returns
90the file content as a string. In case of error, the function returns
91<tt>nil</tt> and an error message describing the error.
92</p>
93
94<pre class=example>
95-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
96-- go to directory "pub/lua" and get file "lua.tar.gz" as binary.
97f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
98
99-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
100-- go to director "pub" and retrieve directory listing of directory "lua"
101f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d")
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>
114
115<!-- get_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
116
117<p class=name id=get_cb>
118socket.ftp.<b>get_cb{</b><br>
119&nbsp;&nbsp;url = <i>string</i>,<br>
120&nbsp;&nbsp;type = <i>string</i>,<br>
121&nbsp;&nbsp;content_cb = <i>receive-callback</i>,<br>
122&nbsp;&nbsp;user = <i>string</i>,<br>
123&nbsp;&nbsp;password = <i>string</i><br>
124<b>}</b>
125</p>
126
127<p class=description>
128Same as <a href="#get"><tt>get</tt></a>, but the library returns
129the content of the downloaded file to the receive callback
130<tt>content_cb</tt>.
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
138<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class=name id=put>
141socket.ftp.<b>put(</b>url, content<b>)</b><br>
142socket.ftp.<b>put{</b><br>
143&nbsp;&nbsp;url = <i>string</i>,<br>
144&nbsp;&nbsp;content = <i>string</i>,<br>
145&nbsp;&nbsp;type = <i>string</i>,<br>
146&nbsp;&nbsp;user = <i>string</i>,<br>
147&nbsp;&nbsp;password = <i>string</i><br>
148<b>}</b>
149</p>
150
151<p class=description>
152Upload a file to a FTP server.
153</p>
154
155<p class=parameters>
156The function can be called directly with a
157<tt>url</tt> and <tt>content</tt> parameters, or with a
158<em>request table</em>.
159Values passed explicitly in the request table override those present in
160the <tt>url</tt>. The parameter <tt>type</tt> accept values
161'<tt>a</tt>' (ASCII, the default) or '<tt>i</tt>' (binary) and
162determines the transfer type. If no <tt>user</tt> is provided, the
163function tries to log in as '<tt>anonymous</tt>'.
164</p>
165
166<p class=return>
167If successful, the function returns 1. In case of error, the
168function returns <tt>nil</tt> followed by a string describing the error.
169</p>
170
171<pre class=example>
172-- Log as user "anonymous" on server "ftp.free.org" and store file
173-- "hello" with contents "hello world!", using binary mode for the transfer
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
205<p class=note>
206Note: for more information on callbacks, refer to
207<a href="stream.html#stream">Streaming with callbacks</a>.
208</p>
209
210<pre class=example>
211-- Log as user "anonymous" on server "ftp.free.org" and store file
212-- "hello" with contents of the same file in the current directory,
213-- using binary mode for the transfer
214r, e = socket.ftp.put_cb{
215 url = "ftp://ftp.free.org/hello",
216 type = "i",
217 content_cb = socket.callback.send_file(io.open("hello", "r"))
218}
219</pre>
220</blockquote>
221
222<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
223
224<div class=footer>
225<hr>
226<center>
227<p class=bar>
228<a href="home.html">home</a> &middot;
229<a href="home.html#download">download</a> &middot;
230<a href="introduction.html">introduction</a> &middot;
231<a href="reference.html">reference</a>
232</p>
233<p>
234<small>
235Last modified by Diego Nehab on <br>
236Sat Aug 9 01:00:41 PDT 2003
237</small>
238</p>
239</center>
240</div>
241
242</body>
243</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-12 21:40:53 +0000