mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-12-26 20:38:22 +01:00
540 lines
16 KiB
HTML
540 lines
16 KiB
HTML
<!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="index.html">home</a> ·
|
|
<a href="index.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 IPv4 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="#getoption"><tt>getoption</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>
|
|
|
|
<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class="name" id="socket.udp6">
|
|
socket.<b>udp6()</b>
|
|
</p>
|
|
|
|
<p class="description">
|
|
Creates and returns an unconnected IPv6 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="#getoption"><tt>getoption</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>
|
|
|
|
<p class=note>
|
|
Note: The TCP object returned will have the option
|
|
"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
|
|
</p>
|
|
|
|
|
|
|
|
<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<!-- 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 a string with the IP address of the peer, the
|
|
port number that peer is using for the connection,
|
|
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
|
In case of error, the method returns <b><tt>nil</tt></b>.
|
|
</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, a number with
|
|
the local port,
|
|
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
|
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>
|
|
|
|
<!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class="name" id="getoption">
|
|
connected:<b>getoption()</b><br>
|
|
unconnected:<b>getoption()</b>
|
|
</p>
|
|
|
|
<p class="description">
|
|
Gets an option value from the UDP object.
|
|
See <a href=#setoption><tt>setoption</tt></a> for
|
|
description of the option names and values.
|
|
</p>
|
|
|
|
<p class="parameters"><tt>Option</tt> is a string with the option name.
|
|
<ul>
|
|
<li> '<tt>dontroute</tt>'
|
|
<li> '<tt>broadcast</tt>'
|
|
<li> '<tt>reuseaddr</tt>'
|
|
<li> '<tt>reuseport</tt>'
|
|
<li> '<tt>ip-multicast-loop</tt>'
|
|
<li> '<tt>ipv6-v6only</tt>'
|
|
<li> '<tt>ip-multicast-if</tt>'
|
|
<li> '<tt>ip-multicast-ttl</tt>'
|
|
<li> '<tt>ip-add-membership</tt>'
|
|
<li> '<tt>ip-drop-membership</tt>'
|
|
</ul>
|
|
</p>
|
|
|
|
<p class=return>
|
|
The method returns the option <tt>value</tt> in case of
|
|
success, or
|
|
<b><tt>nil</tt></b> followed by an error message otherwise.
|
|
</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>
|
|
|
|
<p class=note>
|
|
Note: Starting with LuaSocket 3.0, the host name resolution
|
|
depends on whether the socket was created by <a
|
|
href=#socket.udp><tt>socket.udp</tt></a> or <a
|
|
href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
|
|
the appropriate family are tried in succession until the
|
|
first success or until the last failure.
|
|
</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>': Indicates that outgoing
|
|
messages should bypass the standard routing facilities.
|
|
Receives a boolean value;
|
|
<li> '<tt>broadcast</tt>': Requests permission to send
|
|
broadcast datagrams on the socket.
|
|
Receives a boolean value;
|
|
<li> '<tt>reuseaddr</tt>': Indicates that the rules used in
|
|
validating addresses supplied in a <tt>bind()</tt> call
|
|
should allow reuse of local addresses.
|
|
Receives a boolean value;
|
|
<li> '<tt>reuseport</tt>': Allows completely duplicate
|
|
bindings by multiple processes if they all set
|
|
'<tt>reuseport</tt>' before binding the port.
|
|
Receives a boolean value;
|
|
<li> '<tt>ip-multicast-loop</tt>':
|
|
Specifies whether or not a copy of an outgoing multicast
|
|
datagram is delivered to the sending host as long as it is a
|
|
member of the multicast group.
|
|
Receives a boolean value;
|
|
<li> '<tt>ipv6-v6only</tt>':
|
|
Specifies whether to restrict <tt>inet6</tt> sockets to
|
|
sending and receiving only IPv6 packets.
|
|
Receive a boolean value;
|
|
<li> '<tt>ip-multicast-if</tt>':
|
|
Sets the interface over which outgoing multicast datagrams
|
|
are sent.
|
|
Receives an IP address;
|
|
<li> '<tt>ip-multicast-ttl</tt>':
|
|
Sets the Time To Live in the IP header for outgoing
|
|
multicast datagrams.
|
|
Receives a number;
|
|
<li> '<tt>ip-add-membership</tt>':
|
|
Joins the multicast group specified.
|
|
Receives a table with fields
|
|
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
|
IP address;
|
|
<li> '<tt>ip-drop-membership</tt>': Leaves the multicast
|
|
group specified.
|
|
Receives a table with fields
|
|
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
|
IP address.
|
|
</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="index.html">home</a> ·
|
|
<a href="index.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>
|