| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| |
| <head> |
| <meta name="description" content="LuaSocket: The UDP support"> |
| <meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support"> |
| <title>LuaSocket: UDP support</title> |
| <link rel="stylesheet" href="reference.css" type="text/css"> |
| </head> |
| |
| <body> |
| |
| <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <div class=header> |
| <hr> |
| <center> |
| <table summary="LuaSocket logo"> |
| <tr><td align=center><a href="http://www.lua.org"> |
| <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> |
| </a></td></tr> |
| <tr><td align=center valign=top>Network support for the Lua language |
| </td></tr> |
| </table> |
| <p class=bar> |
| <a href="home.html">home</a> · |
| <a href="home.html#download">download</a> · |
| <a href="installation.html">installation</a> · |
| <a href="introduction.html">introduction</a> · |
| <a href="reference.html">reference</a> |
| </p> |
| </center> |
| <hr> |
| </div> |
| |
| |
| <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <h2 id=udp>UDP</h2> |
| |
| <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="socket.udp"> |
| socket.<b>udp()</b> |
| </p> |
| |
| <p class="description"> |
| Creates and returns an unconnected UDP object. Unconnected objects support the |
| <a href="#sendto"><tt>sendto</tt></a>, |
| <a href="#receive"><tt>receive</tt></a>, |
| <a href="#receivefrom"><tt>receivefrom</tt></a>, |
| <a href="#getsockname"><tt>getsockname</tt></a>, |
| <a href="#setoption"><tt>setoption</tt></a>, |
| <a href="#settimeout"><tt>settimeout</tt></a>, |
| <a href="#setpeername"><tt>setpeername</tt></a>, |
| <a href="#setsockname"><tt>setsockname</tt></a>, and |
| <a href="#close"><tt>close</tt></a>. |
| The <a href="#setpeername"><tt>setpeername</tt></a> |
| is used to connect the object. |
| </p> |
| |
| <p class="return"> |
| In case of success, a new unconnected UDP object |
| returned. In case of error, <b><tt>nil</tt></b> is returned, followed by |
| an error message. |
| </p> |
| |
| <!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="close"> |
| connected:<b>close()</b><br> |
| unconnected:<b>close()</b> |
| </p> |
| |
| <p class="description"> |
| Closes a UDP object. The internal socket |
| used by the object is closed and the local address to which the |
| object was bound is made available to other applications. No |
| further operations (except for further calls to the <tt>close</tt> |
| method) are allowed on a closed socket. |
| </p> |
| |
| <p class="note"> |
| Note: It is important to close all used sockets |
| once they are not needed, since, in many systems, each socket uses |
| a file descriptor, which are limited system resources. |
| Garbage-collected objects are automatically closed before |
| destruction, though. |
| </p> |
| |
| <!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="getpeername"> |
| connected:<b>getpeername()</b> |
| </p> |
| |
| <p class="description"> |
| Retrieves information about the peer |
| associated with a connected UDP object. |
| </p> |
| |
| <p class="return"> |
| Returns the IP address and port number of the peer. |
| </p> |
| |
| <p class="note"> |
| Note: It makes no sense to call this method on unconnected objects. |
| </p> |
| |
| <!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="getsockname"> |
| connected:<b>getsockname()</b><br> |
| unconnected:<b>getsockname()</b> |
| </p> |
| |
| <p class="description"> |
| Returns the local address information associated to the object. |
| </p> |
| |
| <p class="return"> |
| The method returns a string with local IP |
| address and a number with the port. In case of error, the method |
| returns <b><tt>nil</tt></b>. |
| </p> |
| |
| <p class="note"> |
| Note: UDP sockets are not bound to any address |
| until the <a href="#setsockname"><tt>setsockname</tt></a> or the |
| <a href="#sendto"><tt>sendto</tt></a> method is called for the |
| first time (in which case it is bound to an ephemeral port and the |
| wild-card address). |
| </p> |
| |
| <!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="receive"> |
| connected:<b>receive(</b>[size]<b>)</b><br> |
| unconnected:<b>receive(</b>[size]<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Receives a datagram from the UDP object. If |
| the UDP object is connected, only datagrams coming from the peer |
| are accepted. Otherwise, the returned datagram can come from any |
| host. |
| </p> |
| |
| <p class="parameters"> |
| The optional <tt>size</tt> parameter |
| specifies the maximum size of the datagram to be retrieved. If |
| there are more than <tt>size</tt> bytes available in the datagram, |
| the excess bytes are discarded. If there are less then |
| <tt>size</tt> bytes available in the current datagram, the |
| available bytes are returned. If <tt>size</tt> is omitted, the |
| maximum datagram size is used (which is currently limited by the |
| implementation to 8192 bytes). |
| </p> |
| |
| <p class="return"> |
| In case of success, the method returns the |
| received datagram. In case of timeout, the method returns |
| <b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'. |
| </p> |
| |
| <!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="receivefrom"> |
| unconnected:<b>receivefrom(</b>[size]<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Works exactly as the <a href="#receive"><tt>receive</tt></a> |
| method, except it returns the IP |
| address and port as extra return values (and is therefore slightly less |
| efficient). |
| </p> |
| |
| <!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="send"> |
| connected:<b>send(</b>datagram<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Sends a datagram to the UDP peer of a connected object. |
| </p> |
| |
| <p class="parameters"> |
| <tt>Datagram</tt> is a string with the datagram contents. |
| The maximum datagram size for UDP is 64K minus IP layer overhead. |
| However datagrams larger than the link layer packet size will be |
| fragmented, which may deteriorate performance and/or reliability. |
| </p> |
| |
| <p class="return"> |
| If successful, the method returns 1. In case of |
| error, the method returns <b><tt>nil</tt></b> followed by an error message. |
| </p> |
| |
| <p class="note"> |
| Note: In UDP, the <tt>send</tt> method never blocks |
| and the only way it can fail is if the underlying transport layer |
| refuses to send a message to the specified address (i.e. no |
| interface accepts the address). |
| </p> |
| |
| <!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="sendto"> |
| unconnected:<b>sendto(</b>datagram, ip, port<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Sends a datagram to the specified IP address and port number. |
| </p> |
| |
| <p class="parameters"> |
| <tt>Datagram</tt> is a string with the |
| datagram contents. |
| The maximum datagram size for UDP is 64K minus IP layer overhead. |
| However datagrams larger than the link layer packet size will be |
| fragmented, which may deteriorate performance and/or reliability. |
| <tt>Ip</tt> is the IP address of the recipient. |
| Host names are <em>not</em> allowed for performance reasons. |
| |
| <tt>Port</tt> is the port number at the recipient. |
| </p> |
| |
| <p class="return"> |
| If successful, the method returns 1. In case of |
| error, the method returns <b><tt>nil</tt></b> followed by an error message. |
| </p> |
| |
| <p class="note"> |
| Note: In UDP, the <tt>send</tt> method never blocks |
| and the only way it can fail is if the underlying transport layer |
| refuses to send a message to the specified address (i.e. no |
| interface accepts the address). |
| </p> |
| |
| <!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="setpeername"> |
| connected:<b>setpeername(</b>'*'<b>)</b><br> |
| unconnected:<b>setpeername(</b>address, port<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Changes the peer of a UDP object. This |
| method turns an unconnected UDP object into a connected UDP |
| object or vice versa. |
| </p> |
| |
| <p class="description"> |
| For connected objects, outgoing datagrams |
| will be sent to the specified peer, and datagrams received from |
| other peers will be discarded by the OS. Connected UDP objects must |
| use the <a href="#send"><tt>send</tt></a> and |
| <a href="#receive"><tt>receive</tt></a> methods instead of |
| <a href="#sendto"><tt>sendto</tt></a> and |
| <a href="#receivefrom"><tt>receivefrom</tt></a>. |
| </p> |
| |
| <p class="parameters"> |
| <tt>Address</tt> can be an IP address or a |
| host name. <tt>Port</tt> is the port number. If <tt>address</tt> is |
| '<tt>*</tt>' and the object is connected, the peer association is |
| removed and the object becomes an unconnected object again. In that |
| case, the <tt>port</tt> argument is ignored. |
| </p> |
| |
| <p class="return"> |
| In case of error the method returns |
| <b><tt>nil</tt></b> followed by an error message. In case of success, the |
| method returns 1. |
| </p> |
| |
| <p class="note"> |
| Note: Since the address of the peer does not have |
| to be passed to and from the OS, the use of connected UDP objects |
| is recommended when the same peer is used for several transmissions |
| and can result in up to 30% performance gains. |
| </p> |
| |
| <!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="setsockname"> |
| unconnected:<b>setsockname(</b>address, port<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Binds the UDP object to a local address. |
| </p> |
| |
| <p class="parameters"> |
| <tt>Address</tt> can be an IP address or a |
| host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to |
| all local interfaces using the constant <tt>INADDR_ANY</tt>. If |
| <tt>port</tt> is 0, the system chooses an ephemeral port. |
| </p> |
| |
| <p class="return"> |
| If successful, the method returns 1. In case of |
| error, the method returns <b><tt>nil</tt></b> followed by an error |
| message. |
| </p> |
| |
| <p class="note"> |
| Note: This method can only be called before any |
| datagram is sent through the UDP object, and only once. Otherwise, |
| the system automatically binds the object to all local interfaces |
| and chooses an ephemeral port as soon as the first datagram is |
| sent. After the local address is set, either automatically by the |
| system or explicitly by <tt>setsockname</tt>, it cannot be |
| changed. |
| </p> |
| |
| <!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="setoption"> |
| connected:<b>setoption(</b>option [, value]<b>)</b><br> |
| unconnected:<b>setoption(</b>option [, value]<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Sets options for the UDP object. Options are |
| only needed by low-level or time-critical applications. You should |
| only modify an option if you are sure you need it.</p> |
| <p class="parameters"><tt>Option</tt> is a string with the option |
| name, and <tt>value</tt> depends on the option being set: |
| </p> |
| |
| <ul> |
| <li>'<tt>dontroute</tt>': Setting this option to <tt>true</tt> |
| indicates that outgoing messages should bypass the standard routing |
| facilities;</li> |
| <li>'<tt>broadcast</tt>': Setting this option to <tt>true</tt> |
| requests permission to send broadcast datagrams on the |
| socket.</li> |
| </ul> |
| |
| <p class="return"> |
| The method returns 1 in case of success, or |
| <b><tt>nil</tt></b> followed by an error message otherwise. |
| </p> |
| |
| <p class="note"> |
| Note: The descriptions above come from the man |
| pages. |
| </p> |
| |
| <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class="name" id="settimeout"> |
| connected:<b>settimeout(</b>value<b>)</b><br> |
| unconnected:<b>settimeout(</b>value<b>)</b> |
| </p> |
| |
| <p class="description"> |
| Changes the timeout values for the object. By default, the |
| <a href="#receive"><tt>receive</tt></a> and |
| <a href="#receivefrom"><tt>receivefrom</tt></a> |
| operations are blocking. That is, any call to the methods will block |
| indefinitely, until data arrives. The <tt>settimeout</tt> function defines |
| a limit on the amount of time the functions can block. When a timeout is |
| set and the specified amount of time has elapsed, the affected methods |
| give up and fail with an error code. |
| </p> |
| |
| <p class="parameters"> |
| The amount of time to wait is specified as |
| the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout |
| <tt>value</tt> allows operations to block indefinitely. Negative |
| timeout values have the same effect. |
| </p> |
| |
| <p class="note"> |
| Note: In UDP, the <a href="#send"><tt>send</tt></a> |
| and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the |
| datagram is just passed to the OS and the call returns |
| immediately). Therefore, the <tt>settimeout</tt> method has no |
| effect on them. |
| </p> |
| |
| <p class="note"> |
| Note: The old <tt>timeout</tt> method is |
| deprecated. The name has been changed for sake of uniformity, since |
| all other method names already contained verbs making their |
| imperative nature obvious. |
| </p> |
| |
| <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <div class=footer> |
| <hr> |
| <center> |
| <p class=bar> |
| <a href="home.html">home</a> · |
| <a href="home.html#download">download</a> · |
| <a href="installation.html">installation</a> · |
| <a href="introduction.html">introduction</a> · |
| <a href="reference.html">reference</a> |
| </p> |
| <p> |
| <small> |
| Last modified by Diego Nehab on <br> |
| Thu Apr 20 00:26:01 EDT 2006 |
| </small> |
| </p> |
| </center> |
| </div> |
| |
| </body> |
| </html> |