source/texk/web2c/luatexdir/luasocket/doc/ftp.html

   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>
  42 FTP  (File Transfer  Protocol)  is a  protocol  used  to transfer  files
  43 between hosts.  The <tt>ftp</tt> namespace offers thorough support
  44 to 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>
  49 High level functions are provided supporting the most common operations.
  50 These high level functions are implemented on top of a lower level
  51 interface. Using the low-level interface, users can easily create their
  52 own functions to access <em>any</em> operation supported by the FTP
  53 protocol.  For that, check the implementation.
  54 </p>
  55
  56 <p>
  57 To really benefit from this module, a good understanding of
  58 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
  59 LTN012, Filters sources and sinks</a> is necessary.
  60 </p>
  61
  62 <p>
  63 To obtain the <tt>ftp</tt> namespace, run:
  64 </p>
  65
  66 <pre class=example>
  67 -- loads the FTP module and any libraries it requires
  68 local ftp = require("socket.ftp")
  69 </pre>
  70
  71 <p>
  72 URLs MUST conform to
  73 <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
  74 that 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>
  83 The following constants in the namespace can be set to control the default behavior of
  84 the 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>
  98 ftp.<b>get(</b>url<b>)</b><br>
  99 ftp.<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>
 114 The <tt>get</tt> function has two forms. The simple form has fixed
 115 functionality: it downloads the contents of a URL and returns it as a
 116 string. The generic form allows a <em>lot</em> more control, as explained
 117 below.
 118 </p>
 119
 120 <p class=parameters>
 121 If the argument of the <tt>get</tt> function is a table, the function
 122 expects 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
 124 precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
 125 the <em>simple</em>
 126 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
 127 sink 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
 129 optional arguments are the following:
 130 </p>
 131 <ul>
 132 <li><tt>user</tt>, <tt>password</tt>: User name and password used for
 133 authentication. 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>
 141 pump step function used to pass data from the
 142 server 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>
 148 If successful, the simple version returns the URL  contents as a
 149 string, and the generic function returns 1.  In case of error,  both
 150 functions return <b><tt>nil</tt></b> and an error message describing the
 151 error.
 152 </p>
 153
 154 <pre class=example>
 155 -- load the ftp support
 156 local 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.
 160 f, 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
 165 local ftp = require("socket.ftp")
 166 local ltn12 = require("ltn12")
 167 local url = require("socket.url")
 168
 169 -- a function that returns a directory listing
 170 function 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
 177 end
 178 </pre>
 179
 180 <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 181
 182 <p class=name id=put>
 183 ftp.<b>put(</b>url, content<b>)</b><br>
 184 ftp.<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>
 199 The <tt>put</tt> function has two forms. The simple form has fixed
 200 functionality: it uploads a string of content into a URL. The generic form
 201 allows a <em>lot</em> more control, as explained below.
 202 </p>
 203
 204 <p class=parameters>
 205 If the argument of the <tt>put</tt> function is a table, the function
 206 expects 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
 208 precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
 209 the <em>simple</em>
 210 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
 211 source 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
 214 optional arguments are the following:
 215 </p>
 216 <ul>
 217 <li><tt>user</tt>, <tt>password</tt>: User name and password used for
 218 authentication. 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>
 226 pump step function used to pass data from the
 227 server 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>
 233 Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
 234 message describing the reason for failure.
 235 </p>
 236
 237 <pre class=example>
 238 -- load the ftp support
 239 local 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"
 244 f, 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
 250 local ftp = require("socket.ftp")
 251 local 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"
 256 f, 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>
 281 Last modified by Diego Nehab on <br>
 282 Thu Apr 20 00:25:18 EDT 2006
 283 </small>
 284 </p>
 285 </center>
 286 </div>
 287
 288 </body>
 289 </html>