mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-11-08 22:38:21 +01:00
62a4c505e4
Making better tests for error messages. Changed a few names. Moved gethostname to inet.c.
416 lines
14 KiB
HTML
416 lines
14 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>
|
|
|
|
<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h2 id=tcp>TCP</h2>
|
|
|
|
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=socket.tcp>
|
|
socket.<b>tcp()</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a TCP master object. A master object can
|
|
be transformed into a server object with the method
|
|
<a href=#bind><tt>bind</tt></a> or into a client object with the method
|
|
<a href=#connect><tt>connect</tt></a>. The only other method
|
|
supported by a master object is the <a href=#close><tt>close</tt></a>
|
|
method.</p>
|
|
|
|
<p class=return>
|
|
In case of success, a new master object is returned. In case of error,
|
|
<b><tt>nil</tt></b> is returned, followed by an error message.
|
|
</p>
|
|
|
|
<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=accept>
|
|
server:<b>accept()</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Waits for a remote connection on the server
|
|
object and returns a client object representing that connection.
|
|
</p>
|
|
|
|
<p class=return>
|
|
If a connection is successfully initiated, a client object is returned.
|
|
If a timeout condition is met, the method returns <b><tt>nil</tt></b> followed
|
|
by the error string '<tt>timeout</tt>'.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: calling <a href=misc.html#socket.select><tt>socket.select</tt></a>
|
|
with a server object in
|
|
the <tt>receive</tt> parameter before a call to <tt>accept</tt> does
|
|
<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
|
|
href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
|
|
might block until <em>another</em> client shows up.
|
|
</p>
|
|
|
|
<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=bind>
|
|
master:<b>bind(</b>address, port [, backlog]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Binds a master object to <tt>address</tt> and <tt>port</tt> on the
|
|
local host, transforming it into a server object. Server
|
|
objects support the
|
|
<a href=#accept><tt>accept</tt></a>,
|
|
<a href=#getsockname><tt>getsockname</tt></a>,
|
|
<a href=#setoption><tt>setoption</tt></a>,
|
|
<a href=#settimeout><tt>settimeout</tt></a>,
|
|
and <a href=#close><tt>close</tt></a> methods.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Address</tt> can be an IP address or a host name.
|
|
<tt>Port</tt> must be an integer number in the range [0..64K].
|
|
If <tt>address</tt>
|
|
is '<tt>*</tt>', the system binds to all local interfaces
|
|
using the <tt>INADDR_ANY</tt> constant. If <tt>port</tt> is 0, the system automatically
|
|
chooses an ephemeral port. The optional parameter <tt>backlog</tt>, which
|
|
defaults to 1, specifies the number of client connections that can
|
|
be queued waiting for service. If the queue is full and another client
|
|
attempts connection, the connection is refused.
|
|
</p>
|
|
|
|
<p class=return>
|
|
In case of success, 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: The function <tt>socket.bind</tt> is available and is a short
|
|
for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>bind</tt> method.
|
|
</p>
|
|
|
|
<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=close>
|
|
master:<b>close()</b><br>
|
|
client:<b>close()</b><br>
|
|
server:<b>close()</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Closes a TCP 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>
|
|
|
|
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=connect>
|
|
master:<b>connect(</b>address, port<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Attempts to connect a master object to a remote host, transforming it into a
|
|
client object. Client objects support methods
|
|
<a href=#send><tt>send</tt></a>,
|
|
<a href=#receive><tt>receive</tt></a>,
|
|
<a href=#getsockname><tt>getsockname</tt></a>,
|
|
<a href=#getpeername><tt>getpeername</tt></a>,
|
|
<a href=#settimeout><tt>settimeout</tt></a>,
|
|
and <a href=#close><tt>close</tt></a>.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Address</tt> can be an IP address or a host name.
|
|
<tt>Port</tt> must be an integer number in the range [1..64K].
|
|
</p>
|
|
|
|
<p class=return>
|
|
In case of error, the method returns <b><tt>nil</tt></b> followed by a string
|
|
describing the error. In case of success, the method returns 1.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: The function <tt>socket.connect</tt> is available and is a short
|
|
for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>connect</tt> method.
|
|
</p>
|
|
|
|
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=getpeername>
|
|
client:<b>getpeername()</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Returns information about the remote side of a connected client object.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns a string with the IP address of the peer, followed by the
|
|
port number that peer is using for the connection.
|
|
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 server objects.
|
|
</p>
|
|
|
|
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=getsockname>
|
|
client:<b>getsockname()</b><br>
|
|
server:<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: Naturally, for a server object, the address and port returned are
|
|
those passed to the <a href=#bind>bind</a> method. If the port value
|
|
passed to bind was 0, the OS assigned ephemeral port is returned. For
|
|
client objects, both the address and port are ephemeral and these are the
|
|
values returned.
|
|
</p>
|
|
|
|
<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=receive>
|
|
client:<b>receive(</b>[pattern<sub>1</sub>, pattern<sub>2</sub>,
|
|
... pattern<sub>N</sub>]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Reads data from a client object, according to the specified <em>read
|
|
patterns</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
The parameters <tt>pattern</tt><sub>1</sub>, <tt>pattern</tt><sub>2</sub>, ...
|
|
<tt>pattern</tt><sub>N</sub> can be any of the following:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> '<tt>*a</tt>': reads from the socket until the connection is
|
|
closed. No end-of-line translation is performed;
|
|
<li> '<tt>*l</tt>': reads a line of text from the socket. The line is
|
|
terminated by a LF character (ASCII 10), optionally preceded by a
|
|
CR character (ASCII 13). The CR and LF characters are not included in
|
|
the returned line. This is the default pattern;
|
|
<li> <tt>number</tt>: causes the method to read <tt>number</tt> raw
|
|
bytes from the socket.
|
|
</ul>
|
|
|
|
<p class=return>
|
|
The method returns one value for each pattern, followed by a single
|
|
error code that can be <b><tt>nil</tt></b> in case of success, the string
|
|
'<tt>closed</tt>' in case the connection was closed before the
|
|
transmission was completed or the string '<tt>timeout</tt>' in case
|
|
there was a timeout during the operation.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: In case of error, the method always return everything it managed
|
|
to download before the error condition was met.
|
|
</p>
|
|
|
|
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=send>
|
|
client:<b>send(</b>string<sub>1</sub> [,
|
|
string<sub>2</sub>, ... string<sub>N</sub>]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Sends data through client object.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
All parameters should be strings. For small strings, it is always better to
|
|
concatenate them in Lua (with the '<tt>..</tt>' operator) and pass the
|
|
result to LuaSocket instead of passing several independent strings.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The method returns the number of bytes accepted by the transport layer,
|
|
followed by an error code. The error code is <b><tt>nil</tt></b> if the operation
|
|
completed with no errors, the string '<tt>closed</tt>' in case
|
|
the connection was closed before the transmission was completed or the
|
|
string '<tt>timeout</tt>' in case there was a timeout during the
|
|
operation.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: The return values for the <tt>send</tt> method have been changed in
|
|
LuaSocket 2.0! In previous versions, the method returned only the
|
|
error message. Since returning <b><tt>nil</tt></b> in case of success goes
|
|
against all other LuaSocket methods and functions, the
|
|
<tt>send</tt> method been changed for the sake of uniformity.
|
|
</p>
|
|
|
|
<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=setoption>
|
|
client:<b>setoption(</b>option [, value]<b>)</b><br>
|
|
server:<b>setoption(</b>option [, value]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Sets options for the TCP 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:
|
|
|
|
<ul>
|
|
<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> disables the
|
|
Nagle's algorithm for the connection;
|
|
<li> '<tt>linger</tt>': Controls the action taken when unsent data are
|
|
queued on a socket and a close is performed. The value is a table with a
|
|
boolean entry '<tt>on</tt>' and a numeric entry for the time interval
|
|
'<tt>timeout</tt>' in seconds.
|
|
If the '<tt>on</tt>' field is set to <tt>true</tt>,
|
|
the system will block the process on the close attempt until it is able to
|
|
transmit the data or until '<tt>timeout</tt>' has passed. If '<tt>on</tt>'
|
|
is <tt>false</tt> and a close is issued, the system will process the close
|
|
in a manner that allows the process to continue as quickly as possible. I
|
|
do not advise you to set this to anything other than zero.
|
|
<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
|
|
the periodic transmission of messages on a connected socket. Should the
|
|
connected party fail to respond to these messages, the connection is
|
|
considered broken and processes using the socket are notified.
|
|
</ul>
|
|
|
|
<p class=return>
|
|
The method returns 1 in case of success, or <b><tt>nil</tt></b> otherwise.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: The descriptions above come from the man pages.
|
|
</p>
|
|
|
|
<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=settimeout>
|
|
client:<b>settimeout(</b>value [, mode]<b>)</b><br>
|
|
server:<b>settimeout(</b>value [, mode]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Changes the timeout values for the object. By default,
|
|
all I/O operations are blocking. That is, any call to the methods
|
|
<a href=#send><tt>send</tt></a>,
|
|
<a href=#receive><tt>receive</tt></a>, and
|
|
<a href=#accept><tt>accept</tt></a>
|
|
will block indefinitely, until the operation completes. The
|
|
<tt>settimeout</tt> method defines a limit on the amount of time the
|
|
I/O methods 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. There are two timeout modes and
|
|
both can be used together for fine tuning:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on
|
|
the amount of time LuaSocket can be blocked by the operating system
|
|
while waiting for completion of any single I/O operation. This is the
|
|
default mode;</li>
|
|
|
|
<li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on
|
|
the amount of time LuaSocket can block a Lua script before returning from
|
|
a call.</li>
|
|
</ul>
|
|
|
|
<p class=parameters>
|
|
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: although timeout values have millisecond precision in LuaSocket,
|
|
large blocks can cause I/O functions not to respect timeout values due
|
|
to the time the library takes to transfer blocks to and from the OS
|
|
and to and from the Lua interpreter.
|
|
</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#down">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>
|