source/texk/web2c/luatexdir/luasocket/doc/udp.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 UDP support">
   7 <meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support">
   8 <title>LuaSocket: UDP 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
  38 <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  39
  40 <h2 id="udp">UDP</h2>
  41
  42 <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  43
  44 <p class="name" id="socket.udp">
  45 socket.<b>udp()</b>
  46 </p>
  47
  48 <p class="description">
  49 Creates and returns an unconnected IPv4 UDP object.
  50 Unconnected objects support the
  51 <a href="#sendto"><tt>sendto</tt></a>,
  52 <a href="#receive"><tt>receive</tt></a>,
  53 <a href="#receivefrom"><tt>receivefrom</tt></a>,
  54 <a href="#getoption"><tt>getoption</tt></a>,
  55 <a href="#getsockname"><tt>getsockname</tt></a>,
  56 <a href="#setoption"><tt>setoption</tt></a>,
  57 <a href="#settimeout"><tt>settimeout</tt></a>,
  58 <a href="#setpeername"><tt>setpeername</tt></a>,
  59 <a href="#setsockname"><tt>setsockname</tt></a>, and
  60 <a href="#close"><tt>close</tt></a>.
  61 The <a href="#setpeername"><tt>setpeername</tt></a>
  62 is used to connect the object.
  63 </p>
  64
  65 <p class="return">
  66 In case of success, a new unconnected UDP object
  67 returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
  68 an error message.
  69 </p>
  70
  71 <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  72
  73 <p class="name" id="socket.udp6">
  74 socket.<b>udp6()</b>
  75 </p>
  76
  77 <p class="description">
  78 Creates and returns an unconnected IPv6 UDP object.
  79 Unconnected objects support the
  80 <a href="#sendto"><tt>sendto</tt></a>,
  81 <a href="#receive"><tt>receive</tt></a>,
  82 <a href="#receivefrom"><tt>receivefrom</tt></a>,
  83 <a href="#getoption"><tt>getoption</tt></a>,
  84 <a href="#getsockname"><tt>getsockname</tt></a>,
  85 <a href="#setoption"><tt>setoption</tt></a>,
  86 <a href="#settimeout"><tt>settimeout</tt></a>,
  87 <a href="#setpeername"><tt>setpeername</tt></a>,
  88 <a href="#setsockname"><tt>setsockname</tt></a>, and
  89 <a href="#close"><tt>close</tt></a>.
  90 The <a href="#setpeername"><tt>setpeername</tt></a>
  91 is used to connect the object.
  92 </p>
  93
  94 <p class="return">
  95 In case of success, a new unconnected UDP object
  96 returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
  97 an error message.
  98 </p>
  99
 100 <p class=note>
 101 Note: The TCP object returned will have the option
 102 "<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
 103 </p>
 104
 105
 106
 107 <!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 108
 109 <!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 110
 111 <p class="name" id="close">
 112 connected:<b>close()</b><br>
 113 unconnected:<b>close()</b>
 114 </p>
 115
 116 <p class="description">
 117 Closes a UDP object. The internal socket
 118 used by the object is closed and the local address to which the
 119 object was bound is made available to other applications. No
 120 further operations (except for further calls to the <tt>close</tt>
 121 method) are allowed on a closed socket.
 122 </p>
 123
 124 <p class="note">
 125 Note: It is important to close all used sockets
 126 once they are not needed, since, in many systems, each socket uses
 127 a file descriptor, which are limited system resources.
 128 Garbage-collected objects are automatically closed before
 129 destruction, though.
 130 </p>
 131
 132 <!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 133
 134 <p class="name" id="getpeername">
 135 connected:<b>getpeername()</b>
 136 </p>
 137
 138 <p class="description">
 139 Retrieves information about the peer
 140 associated with a connected UDP object.
 141 </p>
 142
 143
 144 <p class=return>
 145 Returns a string with the IP address of the peer, the
 146 port number that peer is using for the connection,
 147 and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
 148 In case of error, the method returns <b><tt>nil</tt></b>.
 149 </p>
 150
 151 <p class="note">
 152 Note: It makes no sense to call this method on unconnected objects.
 153 </p>
 154
 155 <!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 156
 157 <p class="name" id="getsockname">
 158 connected:<b>getsockname()</b><br>
 159 unconnected:<b>getsockname()</b>
 160 </p>
 161
 162 <p class="description">
 163 Returns the local address information associated to the object.
 164 </p>
 165
 166
 167 <p class=return>
 168 The method returns a string with local IP address, a number with
 169 the local port,
 170 and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
 171 In case of error, the method returns <b><tt>nil</tt></b>.
 172 </p>
 173
 174 <p class="note">
 175 Note: UDP sockets are not bound to any address
 176 until the <a href="#setsockname"><tt>setsockname</tt></a> or the
 177 <a href="#sendto"><tt>sendto</tt></a> method is called for the
 178 first time (in which case it is bound to an ephemeral port and the
 179 wild-card address).
 180 </p>
 181
 182 <!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 183
 184 <p class="name" id="receive">
 185 connected:<b>receive(</b>[size]<b>)</b><br>
 186 unconnected:<b>receive(</b>[size]<b>)</b>
 187 </p>
 188
 189 <p class="description">
 190 Receives a datagram from the UDP object. If
 191 the UDP object is connected, only datagrams coming from the peer
 192 are accepted. Otherwise, the returned datagram can come from any
 193 host.
 194 </p>
 195
 196 <p class="parameters">
 197 The optional <tt>size</tt> parameter
 198 specifies the maximum size of the datagram to be retrieved. If
 199 there are more than <tt>size</tt> bytes available in the datagram,
 200 the excess bytes are discarded. If there are less then
 201 <tt>size</tt> bytes available in the current datagram, the
 202 available bytes are returned. If <tt>size</tt> is omitted, the
 203 maximum datagram size is used (which is currently limited by the
 204 implementation to 8192 bytes).
 205 </p>
 206
 207 <p class="return">
 208 In case of success, the method returns the
 209 received datagram. In case of timeout, the method returns
 210 <b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
 211 </p>
 212
 213 <!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 214
 215 <p class="name" id="receivefrom">
 216 unconnected:<b>receivefrom(</b>[size]<b>)</b>
 217 </p>
 218
 219 <p class="description">
 220 Works exactly as the <a href="#receive"><tt>receive</tt></a>
 221 method, except it returns the IP
 222 address and port as extra return values (and is therefore slightly less
 223 efficient).
 224 </p>
 225
 226 <!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 227
 228 <p class="name" id="getoption">
 229 connected:<b>getoption()</b><br>
 230 unconnected:<b>getoption()</b>
 231 </p>
 232
 233 <p class="description">
 234 Gets an option value from the UDP object.
 235 See <a href=#setoption><tt>setoption</tt></a> for
 236 description of the option names and values.
 237 </p>
 238
 239 <p class="parameters"><tt>Option</tt> is a string with the option name.
 240 <ul>
 241 <li> '<tt>dontroute</tt>'
 242 <li> '<tt>broadcast</tt>'
 243 <li> '<tt>reuseaddr</tt>'
 244 <li> '<tt>reuseport</tt>'
 245 <li> '<tt>ip-multicast-loop</tt>'
 246 <li> '<tt>ipv6-v6only</tt>'
 247 <li> '<tt>ip-multicast-if</tt>'
 248 <li> '<tt>ip-multicast-ttl</tt>'
 249 <li> '<tt>ip-add-membership</tt>'
 250 <li> '<tt>ip-drop-membership</tt>'
 251 </ul>
 252 </p>
 253
 254 <p class=return>
 255 The method returns the option <tt>value</tt> in case of
 256 success, or
 257 <b><tt>nil</tt></b> followed by an error message otherwise.
 258 </p>
 259
 260 <!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 261
 262 <p class="name" id="send">
 263 connected:<b>send(</b>datagram<b>)</b>
 264 </p>
 265
 266 <p class="description">
 267 Sends a datagram to the UDP peer of a connected object.
 268 </p>
 269
 270 <p class="parameters">
 271 <tt>Datagram</tt> is a string with the datagram contents.
 272 The maximum datagram size for UDP is 64K minus IP layer overhead.
 273 However datagrams larger than the link layer packet size will be
 274 fragmented, which may deteriorate performance and/or reliability.
 275 </p>
 276
 277 <p class="return">
 278 If successful, the method returns 1. In case of
 279 error, the method returns <b><tt>nil</tt></b> followed by an error message.
 280 </p>
 281
 282 <p class="note">
 283 Note: In UDP, the <tt>send</tt> method never blocks
 284 and the only way it can fail is if the underlying transport layer
 285 refuses to send a message to the specified address (i.e. no
 286 interface accepts the address).
 287 </p>
 288
 289 <!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 290
 291 <p class="name" id="sendto">
 292 unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
 293 </p>
 294
 295 <p class="description">
 296 Sends a datagram to the specified IP address and port number.
 297 </p>
 298
 299 <p class="parameters">
 300 <tt>Datagram</tt> is a string with the
 301 datagram contents.
 302 The maximum datagram size for UDP is 64K minus IP layer overhead.
 303 However datagrams larger than the link layer packet size will be
 304 fragmented, which may deteriorate performance and/or reliability.
 305 <tt>Ip</tt> is the IP address of the recipient.
 306 Host names are <em>not</em> allowed for performance reasons.
 307
 308 <tt>Port</tt> is the port number at the recipient.
 309 </p>
 310
 311 <p class="return">
 312 If successful, the method returns 1. In case of
 313 error, the method returns <b><tt>nil</tt></b> followed by an error message.
 314 </p>
 315
 316 <p class="note">
 317 Note: In UDP, the <tt>send</tt> method never blocks
 318 and the only way it can fail is if the underlying transport layer
 319 refuses to send a message to the specified address (i.e. no
 320 interface accepts the address).
 321 </p>
 322
 323 <!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 324
 325 <p class="name" id="setpeername">
 326 connected:<b>setpeername(</b>'*'<b>)</b><br>
 327 unconnected:<b>setpeername(</b>address, port<b>)</b>
 328 </p>
 329
 330 <p class="description">
 331 Changes the peer of a UDP object. This
 332 method turns an unconnected UDP object into a connected UDP
 333 object or vice versa.
 334 </p>
 335
 336 <p class="description">
 337 For connected objects, outgoing datagrams
 338 will be sent to the specified peer, and datagrams received from
 339 other peers will be discarded by the OS. Connected UDP objects must
 340 use the <a href="#send"><tt>send</tt></a> and
 341 <a href="#receive"><tt>receive</tt></a> methods instead of
 342 <a href="#sendto"><tt>sendto</tt></a> and
 343 <a href="#receivefrom"><tt>receivefrom</tt></a>.
 344 </p>
 345
 346 <p class="parameters">
 347 <tt>Address</tt> can be an IP address or a
 348 host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
 349 '<tt>*</tt>' and the object is connected, the peer association is
 350 removed and the object becomes an unconnected object again. In that
 351 case, the <tt>port</tt> argument is ignored.
 352 </p>
 353
 354 <p class="return">
 355 In case of error the method returns
 356 <b><tt>nil</tt></b> followed by an error message. In case of success, the
 357 method returns 1.
 358 </p>
 359
 360 <p class="note">
 361 Note: Since the address of the peer does not have
 362 to be passed to and from the OS, the use of connected UDP objects
 363 is recommended when the same peer is used for several transmissions
 364 and can result in up to 30% performance gains.
 365 </p>
 366
 367 <p class=note>
 368 Note: Starting with LuaSocket 2.1, the host name resolution
 369 depends on whether the socket was created by <a
 370 href=#socket.udp><tt>socket.udp</tt></a> or <a
 371 href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
 372 the appropriate family are tried in succession until the
 373 first success or until the last failure.
 374 </p>
 375
 376 <!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 377
 378 <p class="name" id="setsockname">
 379 unconnected:<b>setsockname(</b>address, port<b>)</b>
 380 </p>
 381
 382 <p class="description">
 383 Binds the UDP object to a local address.
 384 </p>
 385
 386 <p class="parameters">
 387 <tt>Address</tt> can be an IP address or a
 388 host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
 389 all local interfaces using the constant <tt>INADDR_ANY</tt>. If
 390 <tt>port</tt> is 0, the system chooses an ephemeral port.
 391 </p>
 392
 393 <p class="return">
 394 If successful, the method returns 1. In case of
 395 error, the method returns <b><tt>nil</tt></b> followed by an error
 396 message.
 397 </p>
 398
 399 <p class="note">
 400 Note: This method can only be called before any
 401 datagram is sent through the UDP object, and only once. Otherwise,
 402 the system automatically binds the object to all local interfaces
 403 and chooses an ephemeral port as soon as the first datagram is
 404 sent. After the local address is set, either automatically by the
 405 system or explicitly by <tt>setsockname</tt>, it cannot be
 406 changed.
 407 </p>
 408
 409 <!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 410
 411 <p class="name" id="setoption">
 412 connected:<b>setoption(</b>option [, value]<b>)</b><br>
 413 unconnected:<b>setoption(</b>option [, value]<b>)</b>
 414 </p>
 415
 416 <p class="description">
 417 Sets options for the UDP object. Options are
 418 only needed by low-level or time-critical applications. You should
 419 only modify an option if you are sure you need it.</p>
 420 <p class="parameters"><tt>Option</tt> is a string with the option
 421 name, and <tt>value</tt> depends on the option being set:
 422 </p>
 423
 424 <ul>
 425 <li> '<tt>dontroute</tt>': Indicates that outgoing
 426 messages should bypass the standard routing facilities.
 427 Receives a boolean value;
 428 <li> '<tt>broadcast</tt>': Requests permission to send
 429 broadcast datagrams on the socket.
 430 Receives a boolean value;
 431 <li> '<tt>reuseaddr</tt>': Indicates that the rules used in
 432 validating addresses supplied in a <tt>bind()</tt> call
 433 should allow reuse of local addresses.
 434 Receives a boolean value;
 435 <li> '<tt>reuseport</tt>': Allows completely duplicate
 436 bindings by multiple processes if they all set
 437 '<tt>reuseport</tt>' before binding the port.
 438 Receives a boolean value;
 439 <li> '<tt>ip-multicast-loop</tt>':
 440 Specifies whether or not a copy of an outgoing multicast
 441 datagram is delivered to the sending host as long as it is a
 442 member of the multicast group.
 443 Receives a boolean value;
 444 <li> '<tt>ipv6-v6only</tt>':
 445 Specifies whether to restrict <tt>inet6</tt> sockets to
 446 sending and receiving only IPv6 packets.
 447 Receive a boolean value;
 448 <li> '<tt>ip-multicast-if</tt>':
 449 Sets the interface over which outgoing multicast datagrams
 450 are sent.
 451 Receives an IP address;
 452 <li> '<tt>ip-multicast-ttl</tt>':
 453 Sets the Time To Live in the IP header for outgoing
 454 multicast datagrams.
 455 Receives a number;
 456 <li> '<tt>ip-add-membership</tt>':
 457 Joins the multicast group specified.
 458 Receives a table with fields
 459 <tt>multiaddr</tt> and <tt>interface</tt>, each containing an
 460 IP address;
 461 <li> '<tt>ip-drop-membership</tt>': Leaves the multicast
 462 group specified.
 463 Receives a table with fields
 464 <tt>multiaddr</tt> and <tt>interface</tt>, each containing an
 465 IP address.
 466 </ul>
 467
 468 <p class="return">
 469 The method returns 1 in case of success, or
 470 <b><tt>nil</tt></b> followed by an error message otherwise.
 471 </p>
 472
 473 <p class=note>
 474 Note: The descriptions above come from the man pages.
 475 </p>
 476
 477 <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 478
 479 <p class="name" id="settimeout">
 480 connected:<b>settimeout(</b>value<b>)</b><br>
 481 unconnected:<b>settimeout(</b>value<b>)</b>
 482 </p>
 483
 484 <p class="description">
 485 Changes the timeout values for the object.  By default, the
 486 <a href="#receive"><tt>receive</tt></a> and
 487 <a href="#receivefrom"><tt>receivefrom</tt></a>
 488 operations are blocking. That is, any call to the methods will block
 489 indefinitely, until data arrives.  The <tt>settimeout</tt> function defines
 490 a limit on the amount of time the functions can block. When a timeout is
 491 set and the specified amount of time has elapsed, the affected methods
 492 give up and fail with an error code.
 493 </p>
 494
 495 <p class="parameters">
 496 The amount of time to wait is specified as
 497 the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
 498 <tt>value</tt> allows operations to block indefinitely. Negative
 499 timeout values have the same effect.
 500 </p>
 501
 502 <p class="note">
 503 Note: In UDP, the <a href="#send"><tt>send</tt></a>
 504 and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
 505 datagram is just passed to the OS and the call returns
 506 immediately). Therefore, the <tt>settimeout</tt> method has no
 507 effect on them.
 508 </p>
 509
 510 <p class="note">
 511 Note: The old <tt>timeout</tt> method is
 512 deprecated. The name has been changed for sake of uniformity, since
 513 all other method names already contained verbs making their
 514 imperative nature obvious.
 515 </p>
 516
 517 <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 518
 519 <div class=footer>
 520 <hr>
 521 <center>
 522 <p class=bar>
 523 <a href="index.html">home</a> &middot;
 524 <a href="index.html#download">download</a> &middot;
 525 <a href="installation.html">installation</a> &middot;
 526 <a href="introduction.html">introduction</a> &middot;
 527 <a href="reference.html">reference</a>
 528 </p>
 529 <p>
 530 <small>
 531 Last modified by Diego Nehab on <br>
 532 Thu Apr 20 00:26:01 EDT 2006
 533 </small>
 534 </p>
 535 </center>
 536 </div>
 537
 538 </body>
 539 </html>