source/texk/web2c/luatexdir/luasocket/doc/socket.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: The core namespace">
   7 <meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
   8 <title>LuaSocket: The socket namespace</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 <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  38
  39 <h2 id=socket>The socket namespace</h2>
  40
  41 <p>
  42 The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
  43 </p>
  44
  45 <p>
  46 To obtain the <tt>socket</tt> namespace, run:
  47 </p>
  48
  49 <pre class=example>
  50 -- loads the socket module
  51 local socket = require("socket")
  52 </pre>
  53
  54 <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  55
  56 <p class=name id=bind>
  57 socket.<b>bind(</b>address, port [, backlog]<b>)</b>
  58 </p>
  59
  60 <p class=description>
  61 This function is a shortcut that creates and returns a TCP server object
  62 bound to a local <tt>address</tt> and <tt>port</tt>, ready to
  63 accept client connections. Optionally,
  64 user can also specify the <tt>backlog</tt> argument to the
  65 <a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32).
  66 </p>
  67
  68 <p class=note>
  69 Note: The server object returned will have the option "<tt>reuseaddr</tt>"
  70 set to <tt><b>true</b></tt>.
  71 </p>
  72
  73 <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  74
  75 <p class=name id=connect>
  76 socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b>
  77 </p>
  78
  79 <p class=description>
  80 This function is a shortcut that creates and returns a TCP client object
  81 connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally,
  82 the user can also specify the local address and port to bind
  83 (<tt>locaddr</tt> and <tt>locport</tt>), or restrict the socket family
  84 to "<tt>inet</tt>" or "<tt>inet6</tt>".
  85 Without specifying <tt>family</tt> to <tt>connect</tt>, whether a tcp or tcp6
  86 connection is created depends on your system configuration. Two variations
  87 of connect are defined as simple helper functions that restrict the
  88 <tt>family</tt>, <tt>socket.connect4</tt> and <tt>socket.connect6</tt>.
  89 </p>
  90
  91 <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  92
  93 <p class=name id=debug>
  94 socket.<b>_DEBUG</b>
  95 </p>
  96
  97 <p class=description>
  98 This constant is set to <tt><b>true</b></tt> if the library was compiled
  99 with debug support.
 100 </p>
 101
 102 <!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 103
 104 <p class=name id=gettime>
 105 socket.<b>gettime()</b>
 106 </p>
 107
 108 <p class=description>
 109 Returns the time in seconds, relative to the origin of the
 110 universe. You should subtract the values returned by this function
 111 to get meaningful values.
 112 </p>
 113
 114 <pre class=example>
 115 t = socket.gettime()
 116 -- do stuff
 117 print(socket.gettime() - t .. " seconds elapsed")
 118 </pre>
 119
 120 <!-- socket.headers ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 121
 122 <p class=name id="headers.canonic">
 123 socket.headers.<b>canonic</b></p>
 124
 125 <p> The <tt>socket.headers.canonic</tt> table
 126 is used by the HTTP and SMTP modules to translate from
 127 lowercase field names back into their canonic
 128 capitalization. When a lowercase field name exists as a key
 129 in this table, the associated value is substituted in
 130 whenever the field name is sent out.
 131 </p>
 132
 133 <p>
 134 You can obtain the <tt>headers</tt> namespace if case run-time
 135 modifications are required by running:
 136 </p>
 137
 138 <pre class=example>
 139 -- loads the headers module
 140 local headers = require("headers")
 141 </pre>
 142
 143 <!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 144
 145 <p class=name id=newtry>
 146 socket.<b>newtry(</b>finalizer<b>)</b>
 147 </p>
 148
 149 <p class=description>
 150 Creates and returns a <em>clean</em>
 151 <a href="#try"><tt>try</tt></a>
 152 function that allows for cleanup before the exception
 153 is  raised.
 154 </p>
 155
 156 <p class=parameters>
 157 <tt>Finalizer</tt> is a function that will be called before
 158 <tt>try</tt> throws the exception. It will be called
 159 in <em>protected</em> mode.
 160 </p>
 161
 162 <p class=return>
 163 The function returns your customized <tt>try</tt> function.
 164 </p>
 165
 166 <p class=note>
 167 Note: This idea saved a <em>lot</em> of work with the
 168 implementation of protocols in LuaSocket:
 169 </p>
 170
 171 <pre class=example>
 172 foo = socket.protect(function()
 173     -- connect somewhere
 174     local c = socket.try(socket.connect("somewhere", 42))
 175     -- create a try function that closes 'c' on error
 176     local try = socket.newtry(function() c:close() end)
 177     -- do everything reassured c will be closed
 178     try(c:send("hello there?\r\n"))
 179     local answer = try(c:receive())
 180     ...
 181     try(c:send("good bye\r\n"))
 182     c:close()
 183 end)
 184 </pre>
 185
 186
 187 <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 188
 189 <p class=name id=protect>
 190 socket.<b>protect(</b>func<b>)</b>
 191 </p>
 192
 193 <p class=description>
 194 Converts a function that throws exceptions into a safe function. This
 195 function only catches exceptions thrown by the <a href=#try><tt>try</tt></a>
 196 and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal
 197 Lua errors.
 198 </p>
 199
 200 <p class=parameters>
 201 <tt>Func</tt> is a function that calls
 202 <a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
 203 to throw exceptions.
 204 </p>
 205
 206 <p class=return>
 207 Returns an equivalent function that instead of throwing exceptions,
 208 returns <tt><b>nil</b></tt> followed by an error message.
 209 </p>
 210
 211 <p class=note>
 212 Note: Beware that if your function performs some illegal operation that
 213 raises an error, the protected function will catch the error and return it
 214 as a string. This is because the <a href=#try><tt>try</tt></a> function
 215 uses errors as the mechanism to throw exceptions.
 216 </p>
 217
 218 <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 219
 220 <p class=name id=select>
 221 socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
 222 </p>
 223
 224 <p class=description>
 225 Waits for a number of sockets to change status.
 226 </p>
 227
 228 <p class=parameters>
 229 <tt>Recvt</tt> is an array with the sockets to test for characters
 230 available for reading. Sockets in the <tt>sendt</tt> array are watched to
 231 see if it is OK to immediately write on them.  <tt>Timeout</tt> is the
 232 maximum amount of time (in seconds) to wait for a change in status.  A
 233 <tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
 234 function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
 235 be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
 236 non-numeric indices) in the arrays will be silently ignored.
 237 </p>
 238
 239 <p class=return> The function returns a list with the sockets ready for
 240 reading, a list with the sockets ready for writing and an error message.
 241 The error message is "<tt>timeout</tt>" if a timeout condition was met and
 242 <tt><b>nil</b></tt> otherwise. The returned tables are
 243 doubly keyed both by integers and also by the sockets
 244 themselves, to simplify the test if a specific socket has
 245 changed status.
 246 </p>
 247
 248 <p class=note>
 249 <b>Note: </b>: <tt>select</tt> can monitor a limited number
 250 of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This
 251 number may be as high as 1024 or as low as 64 by default,
 252 depending on the system. It is usually possible to change this
 253 at compile time. Invoking <tt>select</tt> with a larger
 254 number of sockets will raise an error.
 255 </p>
 256
 257 <p class=note>
 258 <b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
 259 on non-blocking TCP sockets. The function may return a socket as
 260 writable even though the socket is <em>not</em> ready for sending.
 261 </p>
 262
 263 <p class=note>
 264 <b>Another important note</b>: calling select with a server socket in the receive parameter before a call to accept does <em>not</em> guarantee
 265 <a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
 266 Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
 267 method or <tt>accept</tt> might block forever.
 268 </p>
 269
 270 <p class=note>
 271 <b>Yet another note</b>: If you close a socket and pass
 272 it to <tt>select</tt>, it will be ignored.
 273 </p>
 274
 275 <p class=note>
 276 <b>Using select with non-socket objects</b>: Any object that implements <tt>getfd</tt> and <tt>dirty</tt> can be used with <tt>select</tt>, allowing objects from other libraries to be used within a <tt>socket.select</tt> driven loop.
 277 </p>
 278
 279 <!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 280
 281 <p class=name id=sink>
 282 socket.<b>sink(</b>mode, socket<b>)</b>
 283 </p>
 284
 285 <p class=description>
 286 Creates an
 287 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
 288 sink from a stream socket object.
 289 </p>
 290
 291 <p class=parameters>
 292 <tt>Mode</tt> defines the behavior of the sink. The following
 293 options are available:
 294 </p>
 295 <ul>
 296 <li> <tt>"http-chunked"</tt>: sends data through socket after applying the
 297 <em>chunked transfer coding</em>, closing the socket when done;
 298 <li> <tt>"close-when-done"</tt>: sends all received data through the
 299 socket, closing the socket when done;
 300 <li> <tt>"keep-open"</tt>: sends all received data through the
 301 socket, leaving it open when done.
 302 </ul>
 303 <p>
 304 <tt>Socket</tt> is the stream socket object used to send the data.
 305 </p>
 306
 307 <p class=return>
 308 The function returns a sink with the appropriate behavior.
 309 </p>
 310
 311 <!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 312
 313 <p class=name id=skip>
 314 socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ...  ret<sub>N</sub>]<b>)</b>
 315 </p>
 316
 317 <p class=description>
 318 Drops a number of arguments and returns the remaining.
 319 </p>
 320
 321 <p class=parameters>
 322 <tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
 323 <tt>ret<sub>N</sub></tt> are the arguments.
 324 </p>
 325
 326 <p class=return>
 327 The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
 328 </p>
 329
 330 <p class=note>
 331 Note: This function is useful to avoid creation of dummy variables:
 332 </p>
 333
 334 <pre class=example>
 335 -- get the status code and separator from SMTP server reply
 336 local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
 337 </pre>
 338
 339 <!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 340
 341 <p class=name id=sleep>
 342 socket.<b>sleep(</b>time<b>)</b>
 343 </p>
 344
 345 <p class=description>
 346 Freezes the program execution during a given amount of time.
 347 </p>
 348
 349 <p class=parameters>
 350 <tt>Time</tt> is the number of seconds to sleep for. If
 351 <tt>time</tt> is negative, the function returns immediately.
 352 </p>
 353
 354 <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 355
 356 <p class=name id=source>
 357 socket.<b>source(</b>mode, socket [, length]<b>)</b>
 358 </p>
 359
 360 <p class=description>
 361 Creates an
 362 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
 363 source from a stream socket object.
 364 </p>
 365
 366 <p class=parameters>
 367 <tt>Mode</tt> defines the behavior of the source. The following
 368 options are available:
 369 </p>
 370 <ul>
 371 <li> <tt>"http-chunked"</tt>: receives data from socket and removes the
 372 <em>chunked transfer coding</em> before returning the data;
 373 <li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
 374 socket. This mode requires the extra argument <tt>length</tt>;
 375 <li> <tt>"until-closed"</tt>: receives data from a socket until the other
 376 side closes the connection.
 377 </ul>
 378 <p>
 379 <tt>Socket</tt> is the stream socket object used to receive the data.
 380 </p>
 381
 382 <p class=return>
 383 The function returns a source with the appropriate behavior.
 384 </p>
 385
 386 <!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 387
 388 <p class=name id=setsize>
 389 socket.<b>_SETSIZE</b>
 390 </p>
 391
 392 <p class=description>
 393 The maximum number of sockets that the <a
 394 href=#select><tt>select</tt></a> function can handle.
 395 </p>
 396
 397 <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 398
 399 <p class=name id=try>
 400 socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
 401 </p>
 402
 403 <p class=description>
 404 Throws an exception in case of error. The exception can only be caught
 405 by the <a href=#protect><tt>protect</tt></a> function. It does not explode
 406 into an error message.
 407 </p>
 408
 409 <p class=parameters>
 410 <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
 411 arguments, but are usually the return values of a function call
 412 nested with <tt>try</tt>.
 413 </p>
 414
 415 <p class=return>
 416 The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
 417 <tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt>. Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub>.
 418 </p>
 419
 420 <pre class=example>
 421 -- connects or throws an exception with the appropriate error message
 422 c = socket.try(socket.connect("localhost", 80))
 423 </pre>
 424
 425 <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 426
 427 <p class=name id=version>
 428 socket.<b>_VERSION</b>
 429 </p>
 430
 431 <p class=description>
 432 This constant has a string describing the current LuaSocket version.
 433 </p>
 434
 435 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 436
 437 <div class=footer>
 438 <hr>
 439 <center>
 440 <p class=bar>
 441 <a href="index.html">home</a> &middot;
 442 <a href="index.html#down">download</a> &middot;
 443 <a href="installation.html">installation</a> &middot;
 444 <a href="introduction.html">introduction</a> &middot;
 445 <a href="reference.html">reference</a>
 446 </p>
 447 <p>
 448 <small>
 449 Last modified by Diego Nehab on <br>
 450 Thu Apr 20 00:25:54 EDT 2006
 451 </small>
 452 </p>
 453 </center>
 454 </div>
 455
 456 </body>
 457 </html>