aboutsummaryrefslogtreecommitdiff
path: root/docs/ftp.html
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
committerCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
commit5c4fc93d5f4137bf4c22ddf1a048c907a4a26727 (patch)
treea9a68e1f6a9c3bfe2b64fa1c3a4098865b7d3b5d /docs/ftp.html
parentccef3bc4e2aa6ee5b997a80aabb58f4ff0b0e98f (diff)
parent43a97b7f0053313b43906371dbdc226271e6c8ab (diff)
downloadluasocket-hjelmeland-patch-1.tar.gz
luasocket-hjelmeland-patch-1.tar.bz2
luasocket-hjelmeland-patch-1.zip
Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1
Diffstat (limited to 'docs/ftp.html')
-rw-r--r--docs/ftp.html288
1 files changed, 288 insertions, 0 deletions
diff --git a/docs/ftp.html b/docs/ftp.html
new file mode 100644
index 0000000..7f7da2e
--- /dev/null
+++ b/docs/ftp.html
@@ -0,0 +1,288 @@
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.</li>
89<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
90<li> <tt>USER</tt>: default anonymous user;</li>
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>";</li>
133<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
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;</li>
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;</li>
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;</li>
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.</li>
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>";</li>
218<li><tt>command</tt>: The FTP command used to send data. Defaults to
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;</li>
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;</li>
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;</li>
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.</li>
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-03-21 05:35:40 +0000