mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-12-26 04:28:20 +01:00
f960b3872a
Documented headers.lua Update copyright date everywhere Remove RCSID from files Move version back to 2.1 rather than 2.1.1 Fixed url package to support ipv6 hosts Changed "domain" to "family" in tcp and udp structures Implemented getfamily methods
453 lines
13 KiB
HTML
453 lines
13 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 core namespace">
|
|
<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
|
|
<title>LuaSocket: The socket namespace</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>
|
|
|
|
<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h2 id=socket>The socket namespace</h2>
|
|
|
|
<p>
|
|
The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
|
|
</p>
|
|
|
|
<p>
|
|
To obtain the <tt>socket</tt> namespace, run:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- loads the socket module
|
|
local socket = require("socket")
|
|
</pre>
|
|
|
|
<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=bind>
|
|
socket.<b>bind(</b>address, port [, backlog]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
This function is a shortcut that creates and returns a TCP server object
|
|
bound to a local <tt>address</tt> and <tt>port</tt>, ready to
|
|
accept client connections. Optionally,
|
|
user can also specify the <tt>backlog</tt> argument to the
|
|
<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32).
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: The server object returned will have the option "<tt>reuseaddr</tt>"
|
|
set to <tt><b>true</b></tt>.
|
|
</p>
|
|
|
|
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=connect>
|
|
socket.<b>connect(</b>address, port [, locaddr, locport]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
This function is a shortcut that creates and returns a TCP client object
|
|
connected to a remote <tt>host</tt> at a given <tt>port</tt>. Optionally,
|
|
the user can also specify the local address and port to bind
|
|
(<tt>locaddr</tt> and <tt>locport</tt>).
|
|
</p>
|
|
|
|
<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=debug>
|
|
socket.<b>_DEBUG</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
This constant is set to <tt><b>true</b></tt> if the library was compiled
|
|
with debug support.
|
|
</p>
|
|
|
|
<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=gettime>
|
|
socket.<b>gettime()</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Returns the time in seconds, relative to the origin of the
|
|
universe. You should subtract the values returned by this function
|
|
to get meaningful values.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
t = socket.gettime()
|
|
-- do stuff
|
|
print(socket.gettime() - t .. " seconds elapsed")
|
|
</pre>
|
|
|
|
<!-- socket.headers ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id="headers.canonic">
|
|
socket.headers.<b>canonic</b></p>
|
|
|
|
<p> The <tt>socket.headers.canonic</tt> table
|
|
is used by the HTTP and SMTP modules to translate from
|
|
lowercase field names back into their canonic
|
|
capitalization. When a lowercase field name exists as a key
|
|
in this table, the associated value is substituted in
|
|
whenever the field name is sent out.
|
|
</p>
|
|
|
|
<p>
|
|
You can obtain the <tt>headers</tt> namespace if case run-time
|
|
modifications are required by running:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- loads the headers module
|
|
local headers = require("headers")
|
|
</pre>
|
|
|
|
<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=newtry>
|
|
socket.<b>newtry(</b>finalizer<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates and returns a <em>clean</em>
|
|
<a href="#try"><tt>try</tt></a>
|
|
function that allows for cleanup before the exception
|
|
is raised.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Finalizer</tt> is a function that will be called before
|
|
<tt>try</tt> throws the exception. It will be called
|
|
in <em>protected</em> mode.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns your customized <tt>try</tt> function.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: This idea saved a <em>lot</em> of work with the
|
|
implementation of protocols in LuaSocket:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
foo = socket.protect(function()
|
|
-- connect somewhere
|
|
local c = socket.try(socket.connect("somewhere", 42))
|
|
-- create a try function that closes 'c' on error
|
|
local try = socket.newtry(function() c:close() end)
|
|
-- do everything reassured c will be closed
|
|
try(c:send("hello there?\r\n"))
|
|
local answer = try(c:receive())
|
|
...
|
|
try(c:send("good bye\r\n"))
|
|
c:close()
|
|
end)
|
|
</pre>
|
|
|
|
|
|
<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=protect>
|
|
socket.<b>protect(</b>func<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Converts a function that throws exceptions into a safe function. This
|
|
function only catches exceptions thrown by the <a href=#try><tt>try</tt></a>
|
|
and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal
|
|
Lua errors.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<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.
|
|
</p>
|
|
|
|
<p class=return>
|
|
Returns an equivalent function that instead of throwing exceptions,
|
|
returns <tt><b>nil</b></tt> followed by an error message.
|
|
</p>
|
|
|
|
<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>
|
|
|
|
<!-- 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
|
|
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.
|
|
</p>
|
|
|
|
<p class=return> The function returns a list with the sockets ready for
|
|
reading, a list 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
|
|
doubly keyed both by integers and also by the sockets
|
|
themselves, to simplify the test if a specific socket has
|
|
changed status.
|
|
</p>
|
|
|
|
<p class=note>
|
|
<b>Note: </b>: <tt>select</tt> can monitor a limited number
|
|
of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This
|
|
number may be as high as 1024 or as low as 64 by default,
|
|
depending on the system. It is usually possible to change this
|
|
at compile time. Invoking <tt>select</tt> with a larger
|
|
number of sockets will raise an error.
|
|
</p>
|
|
|
|
<p class=note>
|
|
<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
|
|
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>
|
|
<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
|
|
<a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
|
|
Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
|
|
method or <tt>accept</tt> might block forever.
|
|
</p>
|
|
|
|
<p class=note>
|
|
<b>Yet another note</b>: If you close a socket and pass
|
|
it to <tt>select</tt>, it will be ignored.
|
|
</p>
|
|
|
|
<p class=note>
|
|
<b>Using select with non-socket objects</b>: Any object that implements <tt>getfd</tt> and <tt>dirty</tt> can be used with <tt>select</tt>, allowing objects from other libraries to be used within a <tt>socket.select</tt> driven loop.
|
|
</p>
|
|
|
|
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=sink>
|
|
socket.<b>sink(</b>mode, socket<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates an
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
|
sink from a stream socket object.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Mode</tt> defines the behavior 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>
|
|
|
|
<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=skip>
|
|
socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Drops a number of arguments and returns the remaining.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
|
|
<tt>ret<sub>N</sub></tt> are the arguments.
|
|
</p>
|
|
|
|
<p class=return>
|
|
The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: This function is useful to avoid creation of dummy variables:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- get the status code and separator from SMTP server reply
|
|
local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
|
|
</pre>
|
|
|
|
<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=sleep>
|
|
socket.<b>sleep(</b>time<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Freezes the program execution during a given amount of time.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Time</tt> is the number of seconds to sleep for. If
|
|
<tt>time</tt> is negative, the function returns immediately.
|
|
</p>
|
|
|
|
<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=source>
|
|
socket.<b>source(</b>mode, socket [, length]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Creates an
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
|
source from a stream socket object.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Mode</tt> defines the behavior of the source. The following
|
|
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>
|
|
|
|
<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=setsize>
|
|
socket.<b>_SETSIZE</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
The maximum number of sockets that the <a
|
|
href=#select><tt>select</tt></a> function can handle.
|
|
</p>
|
|
|
|
<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=try>
|
|
socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
Throws an exception in case of error. The exception can only be caught
|
|
by the <a href=#protect><tt>protect</tt></a> function. It does not explode
|
|
into an error message.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
|
|
arguments, but are usually the return values of a function call
|
|
nested with <tt>try</tt>.
|
|
</p>
|
|
|
|
<p class=return>
|
|
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>.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- connects or throws an exception with the appropriate error message
|
|
c = socket.try(socket.connect("localhost", 80))
|
|
</pre>
|
|
|
|
<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=version>
|
|
socket.<b>_VERSION</b>
|
|
</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="index.html">home</a> ·
|
|
<a href="index.html#down">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:25:54 EDT 2006
|
|
</small>
|
|
</p>
|
|
</center>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|