2004-05-25 08:52:06 +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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
2004-05-26 06:58:32 +02:00
|
|
|
<h2 id=socket>The socket namespace</h2>
|
2004-05-25 08:52:06 +02:00
|
|
|
|
|
|
|
|
<p>
|
2004-06-15 08:24:00 +02:00
|
|
|
The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
2004-06-16 22:41:03 +02:00
|
|
|
<p>
|
|
|
|
|
To obtain the <tt>socket</tt> namespace, run:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<pre class=example>
|
|
|
|
|
-- loads the socket module
|
|
|
|
|
local socket = require("socket")
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
2004-05-25 08:52:06 +02:00
|
|
|
<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<p class=name id=debug>
|
2004-06-15 08:24:00 +02:00
|
|
|
socket.<b>DEBUG</b>
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=description>
|
|
|
|
|
This constant is set to <tt><b>true</b></tt> if the library was compiled
|
|
|
|
|
with debug support.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<p class=name id=protect>
|
2004-06-15 08:24:00 +02:00
|
|
|
socket.<b>protect(</b>func<b>)</b>
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=description>
|
|
|
|
|
Converts a function that throws exceptions into a safe function.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=parameters>
|
2004-06-16 22:41:03 +02:00
|
|
|
<tt>Func</tt> is a function that calls
|
|
|
|
|
<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
|
|
|
|
|
to throw exceptions.
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=return>
|
2004-06-15 08:24:00 +02:00
|
|
|
Returns an equivalent function that instead of throwing exceptions,
|
2004-05-25 08:52:06 +02:00
|
|
|
returns <tt><b>nil</b></tt> followed by an error message.
|
|
|
|
|
</p>
|
|
|
|
|
|
2004-06-16 22:41:03 +02:00
|
|
|
<p class=note>
|
|
|
|
|
Note: Beware that if your function performs some illegal operation that
|
|
|
|
|
raises an error, the protected function will catch the error and return it
|
|
|
|
|
as a string. This is because the <a href=#try><tt>try</tt></a> function
|
|
|
|
|
uses errors as the mechanism to throw exceptions.
|
|
|
|
|
</p>
|
|
|
|
|
|
2004-05-26 06:58:32 +02:00
|
|
|
<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<p class=name id=select>
|
|
|
|
|
socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=description>
|
|
|
|
|
Waits for a number of sockets to change status.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=parameters>
|
|
|
|
|
<tt>Recvt</tt> is an array with the sockets to test for characters
|
|
|
|
|
available for reading. Sockets in the <tt>sendt</tt> array are watched to
|
|
|
|
|
see if it is OK to immediately write on them. <tt>Timeout</tt> is the
|
|
|
|
|
maximum amount of time (in seconds) to wait for a change in status. A
|
|
|
|
|
<tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
|
|
|
|
|
function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
|
2004-06-16 22:41:03 +02:00
|
|
|
be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
|
|
|
|
|
non-numeric indices) in the arrays will be silently ignored.
|
2004-05-26 06:58:32 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=return> The function returns a table with the sockets ready for
|
|
|
|
|
reading, a table with the sockets ready for writing and an error message.
|
|
|
|
|
The error message is "<tt>timeout</tt>" if a timeout condition was met and
|
|
|
|
|
<tt><b>nil</b></tt> otherwise. The returned tables are associative, to
|
|
|
|
|
simplify the test if a specific socket has changed status.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=note>
|
2004-06-15 08:24:00 +02:00
|
|
|
<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
|
2004-05-26 06:58:32 +02:00
|
|
|
on non-blocking TCP sockets. The function may return a socket as
|
|
|
|
|
writable even though the socket is <em>not</em> ready for sending.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=note>
|
2004-06-16 03:02:14 +02:00
|
|
|
<b>Another important note</b>: calling select with a server socket in the receive parameter before a call to accept does <em>not</em> guarantee
|
2004-05-26 06:58:32 +02:00
|
|
|
<a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
|
2004-06-15 08:24:00 +02:00
|
|
|
Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
|
2004-05-26 06:58:32 +02:00
|
|
|
method or <tt>accept</tt> might block forever.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=note>
|
|
|
|
|
Interesting note: as mentioned in some manuals, calling select with both
|
|
|
|
|
sets empty and a non-null timeout is a fairly portable way to sleep with
|
|
|
|
|
sub-second precision.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<p class=name id=sink>
|
|
|
|
|
socket.<b>sink(</b>mode, socket<b>)</b>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=description>
|
|
|
|
|
Creates an
|
2004-06-15 08:24:00 +02:00
|
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
2004-05-26 06:58:32 +02:00
|
|
|
sink from a stream socket object.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=parameters>
|
|
|
|
|
<tt>Mode</tt> defines the behaviour of the sink. The following
|
|
|
|
|
options are available:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
|
|
|
|
|
<em>chunked transfer coding</em>, closing the socket when done;
|
|
|
|
|
<li> <tt>"close-when-done"</tt>: sends all received data through the
|
|
|
|
|
socket, closing the socket when done;
|
|
|
|
|
<li> <tt>"keep-open"</tt>: sends all received data through the
|
|
|
|
|
socket, leaving it open when done.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<tt>Socket</tt> is the stream socket object used to send the data.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=return>
|
|
|
|
|
The function returns a sink with the appropriate behavior.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<p class=name id=source>
|
|
|
|
|
socket.<b>source(</b>mode, socket [, length]<b>)</b>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=description>
|
|
|
|
|
Creates an
|
2004-06-15 08:24:00 +02:00
|
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
2004-05-26 06:58:32 +02:00
|
|
|
source from a stream socket object.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=parameters>
|
2004-06-16 06:28:21 +02:00
|
|
|
<tt>Mode</tt> defines the behavior of the source. The following
|
2004-05-26 06:58:32 +02:00
|
|
|
options are available:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
|
|
|
|
|
<em>chunked transfer coding</em> before returning the data;
|
|
|
|
|
<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
|
|
|
|
|
socket. This mode requires the extra argument <tt>length</tt>;
|
|
|
|
|
<li> <tt>"until-closed"</tt>: receives data from a socket until the other
|
|
|
|
|
side closes the connection.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<tt>Socket</tt> is the stream socket object used to receive the data.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=return>
|
|
|
|
|
The function returns a source with the appropriate behavior.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
2004-05-25 08:52:06 +02:00
|
|
|
|
|
|
|
|
<p class=name id=try>
|
2004-06-16 22:41:03 +02:00
|
|
|
socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=description>
|
|
|
|
|
Throws an exception in case of error.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=parameters>
|
2004-06-16 22:41:03 +02:00
|
|
|
<tt>Ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> can be arbitrary
|
|
|
|
|
arguments, but are usually the return values of a function call
|
|
|
|
|
nested with <tt>try</tt>.
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=return>
|
2004-06-16 22:41:03 +02:00
|
|
|
The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
|
|
|
|
|
<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt>. Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub>.
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<pre class=example>
|
|
|
|
|
-- connects or throws an exception with the appropriate error message
|
|
|
|
|
c = socket.try(socket.connect("localhost", 80))
|
|
|
|
|
</pre>
|
|
|
|
|
|
2004-06-16 22:41:03 +02:00
|
|
|
<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
2004-05-25 08:52:06 +02:00
|
|
|
|
|
|
|
|
<p class=name id=version>
|
2004-06-15 08:24:00 +02:00
|
|
|
socket.<b>VERSION</b>
|
2004-05-25 08:52:06 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class=description>
|
|
|
|
|
This constant has a string describing the current LuaSocket version.
|
|
|
|
|
</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>
|
