mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-11-19 11:48:21 +01:00
58096449c6
Implemented new distribution scheme. Select is now purely C. HTTP reimplemented seems faster dunno why. LTN12 functions that coroutines fail gracefully.
406 lines
12 KiB
HTML
406 lines
12 KiB
HTML
<!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>
|
|
|
|
|
|
<!-- 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.
|
|
</p>
|
|
|
|
<p class="return">
|
|
In case of success, the method return 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.
|
|
Beware that the maximum datagram size for UDP is 576 bytes.
|
|
</p>
|
|
|
|
<p class="return">
|
|
If successful, the method returns 1. In case of
|
|
error, the method returns <b><tt>nil</tt></b> followed by the
|
|
'<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
|
|
error, the method returns <b><tt>nil</tt></b> followed by the
|
|
'<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
|
|
<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="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>
|