2003-08-31 03:00:15 +02:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
|
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<title>LuaSocket: Network support for the Lua language</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 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="introduction.html">introduction</a> ·
|
|
|
|
|
<a href="reference.html">reference</a>
|
|
|
|
|
</p>
|
|
|
|
|
</center>
|
|
|
|
|
<hr>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- 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
|
2004-01-24 03:47:24 +01:00
|
|
|
returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
|
2003-08-31 03:00:15 +02:00
|
|
|
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
|
2004-01-24 03:47:24 +01:00
|
|
|
returns <b><tt>nil</tt></b>.
|
2003-08-31 03:00:15 +02:00
|
|
|
</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.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class="return">
|
|
|
|
|
In case of success, the method return the
|
|
|
|
|
received datagram. In case of timeout, the method returns
|
2004-01-24 03:47:24 +01:00
|
|
|
<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
|
2003-08-31 03:00:15 +02:00
|
|
|
</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.
|
|
|
|
|
Beware that the maximum datagram size for UDP is 576 bytes.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class="return">
|
|
|
|
|
If successful, the method returns 1. In case of
|
2004-01-24 03:47:24 +01:00
|
|
|
error, the method returns <b><tt>nil</tt></b> followed by the
|
2003-08-31 03:00:15 +02:00
|
|
|
'<tt>refused</tt>' 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. Beware that the maximum datagram size for UDP is
|
|
|
|
|
576 bytes. <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
|
2004-01-24 03:47:24 +01:00
|
|
|
error, the method returns <b><tt>nil</tt></b> followed by the
|
2003-08-31 03:00:15 +02:00
|
|
|
'<tt>refused</tt>' 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
|
2004-01-24 03:47:24 +01:00
|
|
|
<b><tt>nil</tt></b> followed by an error message. In case of success, the
|
2003-08-31 03:00:15 +02:00
|
|
|
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
|
2004-01-24 03:47:24 +01:00
|
|
|
error, the method returns <b><tt>nil</tt></b> followed by an error
|
2003-08-31 03:00:15 +02:00
|
|
|
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
|
2003-09-21 22:00:23 +02:00
|
|
|
only modify an option if you are sure you need it.</p>
|
2003-08-31 03:00:15 +02:00
|
|
|
<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
|
2004-01-24 03:47:24 +01:00
|
|
|
<b><tt>nil</tt></b> followed by an error message otherwise.
|
2003-08-31 03:00:15 +02:00
|
|
|
</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
|
2004-01-24 03:47:24 +01:00
|
|
|
the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
|
2003-08-31 03:00:15 +02:00
|
|
|
<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="introduction.html">introduction</a> ·
|
|
|
|
|
<a href="reference.html">reference</a>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<small>
|
|
|
|
|
Last modified by Diego Nehab on <br>
|
|
|
|
|
Sat Aug 9 01:00:41 PDT 2003
|
|
|
|
|
</small>
|
|
|
|
|
</p>
|
|
|
|
|
</center>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
