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