aboutsummaryrefslogtreecommitdiff
path: root/doc/ftp.html
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2022-03-24 18:11:07 +0300
committerCaleb Maclennan <caleb@alerque.com>2022-03-24 18:11:07 +0300
commit2de8ddfbb837a75b1cb5f09a656379c1e7cc589c (patch)
tree20b5f7b8a48d1c126763daca3860fcfb7c3b59a7 /doc/ftp.html
parentf9e1d03f3c6c9fc59dd3b91716debc23aebf947f (diff)
parent5ed8b66e6d0c295f95fade159ada0f97f482b2ac (diff)
downloadluasocket-2de8ddfbb837a75b1cb5f09a656379c1e7cc589c.tar.gz
luasocket-2de8ddfbb837a75b1cb5f09a656379c1e7cc589c.tar.bz2
luasocket-2de8ddfbb837a75b1cb5f09a656379c1e7cc589c.zip
Merge remote-tracking branch 'upstream/master' into test-builds
Diffstat (limited to 'doc/ftp.html')
-rw-r--r--doc/ftp.html288
1 files changed, 0 insertions, 288 deletions
diff --git a/doc/ftp.html b/doc/ftp.html
deleted file mode 100644
index 091c88f..0000000
--- a/doc/ftp.html
+++ /dev/null
@@ -1,288 +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>TIMEOUT</tt>: sets the timeout for all I/O operations;
90<li> <tt>USER</tt>: default anonymous user;
91</ul>
92
93
94<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
95
96<p class=name id=get>
97ftp.<b>get(</b>url<b>)</b><br>
98ftp.<b>get{</b><br>
99&nbsp;&nbsp;host = <i>string</i>,<br>
100&nbsp;&nbsp;sink = <i>LTN12 sink</i>,<br>
101&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
102&nbsp;&nbsp;[user = <i>string</i>,]<br>
103&nbsp;&nbsp;[password = <i>string</i>]<br>
104&nbsp;&nbsp;[command = <i>string</i>,]<br>
105&nbsp;&nbsp;[port = <i>number</i>,]<br>
106&nbsp;&nbsp;[type = <i>string</i>,]<br>
107&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
108&nbsp;&nbsp;[create = <i>function</i>]<br>
109<b>}</b>
110</p>
111
112<p class=description>
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
115string. The generic form allows a <em>lot</em> more control, as explained
116below.
117</p>
118
119<p class=parameters>
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
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
124the <em>simple</em>
125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
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
128optional arguments are the following:
129</p>
130<ul>
131<li><tt>user</tt>, <tt>password</tt>: User name and password used for
132authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
133<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
134"<tt>retr</tt>", but see example below;
135<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
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;
138<li><tt>step</tt>:
139<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
140pump step function used to pass data from the
141server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
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.
144</ul>
145
146<p class=return>
147If successful, the simple version returns the URL contents as a
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
150error.
151</p>
152
153<pre class=example>
154-- load the ftp support
155local ftp = require("socket.ftp")
156
157-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
158-- and get file "lua.tar.gz" from directory "pub/lua" as binary.
159f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
160</pre>
161
162<pre class=example>
163-- load needed modules
164local ftp = require("socket.ftp")
165local ltn12 = require("ltn12")
166local url = require("socket.url")
167
168-- a function that returns a directory listing
169function nlst(u)
170 local t = {}
171 local p = url.parse(u)
172 p.command = "nlst"
173 p.sink = ltn12.sink.table(t)
174 local r, e = ftp.get(p)
175 return r and table.concat(t), e
176end
177</pre>
178
179<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
180
181<p class=name id=put>
182ftp.<b>put(</b>url, content<b>)</b><br>
183ftp.<b>put{</b><br>
184&nbsp;&nbsp;host = <i>string</i>,<br>
185&nbsp;&nbsp;source = <i>LTN12 sink</i>,<br>
186&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
187&nbsp;&nbsp;[user = <i>string</i>,]<br>
188&nbsp;&nbsp;[password = <i>string</i>]<br>
189&nbsp;&nbsp;[command = <i>string</i>,]<br>
190&nbsp;&nbsp;[port = <i>number</i>,]<br>
191&nbsp;&nbsp;[type = <i>string</i>,]<br>
192&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
193&nbsp;&nbsp;[create = <i>function</i>]<br>
194<b>}</b>
195</p>
196
197<p class=description>
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
200allows a <em>lot</em> more control, as explained below.
201</p>
202
203<p class=parameters>
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
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
208the <em>simple</em>
209<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
210source that will provide the contents to be uploaded.
211<tt>Argument</tt> or
212<tt>path</tt> give the target path to the resource in the server. The
213optional arguments are the following:
214</p>
215<ul>
216<li><tt>user</tt>, <tt>password</tt>: User name and password used for
217authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
218<li><tt>command</tt>: The FTP command used to send data. Defaults to
219"<tt>stor</tt>", but see example below;
220<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
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;
223<li><tt>step</tt>:
224<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
225pump step function used to pass data from the
226server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
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.
229</ul>
230
231<p class=return>
232Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
233message describing the reason for failure.
234</p>
235
236<pre class=example>
237-- load the ftp support
238local ftp = require("socket.ftp")
239
240-- Log as user "fulano" on server "ftp.example.com",
241-- using password "silva", and store a file "README" with contents
242-- "wrong password, of course"
243f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
244 "wrong password, of course")
245</pre>
246
247<pre class=example>
248-- load the ftp support
249local ftp = require("socket.ftp")
250local ltn12 = require("ltn12")
251
252-- Log as user "fulano" on server "ftp.example.com",
253-- using password "silva", and append to the remote file "LOG", sending the
254-- contents of the local file "LOCAL-LOG"
255f, e = ftp.put{
256 host = "ftp.example.com",
257 user = "fulano",
258 password = "silva",
259 command = "appe",
260 argument = "LOG",
261 source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
262}
263</pre>
264
265
266<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
267
268<div class=footer>
269<hr>
270<center>
271<p class=bar>
272<a href="index.html">home</a> &middot;
273<a href="index.html#download">download</a> &middot;
274<a href="installation.html">installation</a> &middot;
275<a href="introduction.html">introduction</a> &middot;
276<a href="reference.html">reference</a>
277</p>
278<p>
279<small>
280Last modified by Diego Nehab on <br>
281Thu Apr 20 00:25:18 EDT 2006
282</small>
283</p>
284</center>
285</div>
286
287</body>
288</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-01 12:18:19 +0000