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