Google

Edit File: socket.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>

<div class="header">
<hr>
<center>
<table summary="LuaSocket logo">
<tr><td align="center"><a href="https://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>

<a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>

</center>
<hr>
</div>

<h2 id="socket">The socket namespace</h2>

The <tt>socket</tt> namespace contains the core functionality of LuaSocket.

To obtain the <tt>socket</tt> namespace, run:

<pre class="example">
-- loads the socket module
local socket = require("socket")
</pre>

socket.headers.canonic

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.

You can obtain the <tt>headers</tt> namespace if case run-time
modifications are required by running:

<pre class="example">
-- loads the headers module
local headers = require("headers")
</pre>

socket.bind(address, port [, backlog])

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).

Note: The server object returned will have the option "<tt>reuseaddr</tt>"
set to <tt>true</tt>.

socket.connect[46](address, port [, locaddr] [, locport] [, family])

This function is a shortcut that creates and returns a TCP client object
connected to a remote <tt>address</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>), or restrict the socket family
to "<tt>inet</tt>" or "<tt>inet6</tt>".
Without specifying <tt>family</tt> to <tt>connect</tt>, whether a tcp or tcp6
connection is created depends on your system configuration. Two variations
of connect are defined as simple helper functions that restrict the
<tt>family</tt>, <tt>socket.connect4</tt> and <tt>socket.connect6</tt>.

socket._DEBUG

This constant is set to <tt>true</tt> if the library was compiled
with debug support.

socket._DATAGRAMSIZE

Default datagram size used by calls to
<a href="udp.html#receive"><tt>receive</tt></a> and
<a href="udp.html#receivefrom"><tt>receivefrom</tt></a>.
(Unless changed in compile time, the value is 8192.)

socket.gettime()

Returns the UNIX time in seconds. You should subtract the values returned by this function
to get meaningful values.

<pre class="example">
t = socket.gettime()
-- do stuff
print(socket.gettime() - t .. " seconds elapsed")
</pre>

socket.newtry(finalizer)

Creates and returns a clean
<a href="#try"><tt>try</tt></a>
function that allows for cleanup before the exception
is raised.

<tt>Finalizer</tt> is a function that will be called before
<tt>try</tt> throws the exception.

The function returns your customized <tt>try</tt> function.

Note: This idea saved a lot of work with the
implementation of protocols in LuaSocket:

<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>

socket.protect(func)

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.

<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.

Returns an equivalent function that instead of throwing exceptions in case of
a failed <a href="#try"><tt>try</tt></a> call, returns <tt>nil</tt>
followed by an error message.

socket.select(recvt, sendt [, timeout])

Waits for a number of sockets to change status.

<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>nil</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>nil</tt>. Non-socket values (or values with
non-numeric indices) in the arrays will be silently ignored.

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, "<tt>select failed</tt>" if the call
to <tt>select</tt> failed, and
<tt>nil</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.

Note: <tt>select</tt> can monitor a limited number
of sockets, as defined by the constant <a href="#setsize">
<tt>socket._SETSIZE</tt></a>. 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.

Important note: 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 not ready for sending.

Another important note: calling select with a server socket in the receive parameter before a call to accept does not 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.

Yet another note: If you close a socket and pass
it to <tt>select</tt>, it will be ignored.

Using select with non-socket objects: 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.

socket._SETSIZE

The maximum number of sockets that the <a
href="#select"><tt>select</tt></a> function can handle.

socket.sink(mode, socket)

Creates an
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
sink from a stream socket object.

<tt>Mode</tt> defines the behavior of the sink. The following
options are available:

<ul>
<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
chunked transfer coding, closing the socket when done;</li>
<li> <tt>"close-when-done"</tt>: sends all received data through the
socket, closing the socket when done;</li>
<li> <tt>"keep-open"</tt>: sends all received data through the
socket, leaving it open when done.</li>
</ul>

<tt>Socket</tt> is the stream socket object used to send the data.

The function returns a sink with the appropriate behavior.

socket.skip(d [, ret1, ret2 ... retN])

Drops a number of arguments and returns the remaining.

<tt>D</tt> is the number of arguments to drop. <tt>Ret1</tt> to
<tt>retN</tt> are the arguments.

The function returns <tt>retd+1</tt> to <tt>retN</tt>.

Note: This function is useful to avoid creation of dummy variables:

<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>

socket.sleep(time)

Freezes the program execution during a given amount of time.

<tt>Time</tt> is the number of seconds to sleep for. If
<tt>time</tt> is negative, the function returns immediately.

socket.source(mode, socket [, length])

Creates an
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
source from a stream socket object.

<tt>Mode</tt> defines the behavior of the source. The following
options are available:

<ul>
<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
chunked transfer coding before returning the data;</li>
<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
socket. This mode requires the extra argument <tt>length</tt>;</li>
<li> <tt>"until-closed"</tt>: receives data from a socket until the other
side closes the connection.</li>
</ul>

<tt>Socket</tt> is the stream socket object used to receive the data.

The function returns a source with the appropriate behavior.

socket._SOCKETINVALID

The OS value for an invalid socket. This can be used with <a href="tcp.html#getfd">
<tt>tcp:getfd</tt></a> and <a href="tcp.html#setfd"><tt>tcp:setfd</tt></a> methods.

socket.try(ret1 [, ret2 ... retN])

Throws an exception in case <tt>ret1</tt> is falsy, using
<tt>ret2</tt> as the error message. The exception is supposed to be caught
by a <a href="#protect"><tt>protect</tt></a>ed function only.

<tt>Ret1</tt> to <tt>retN</tt> can be arbitrary
arguments, but are usually the return values of a function call
nested with <tt>try</tt>.

The function returns <tt>ret</tt>1 to <tt>ret</tt>N if
<tt>ret</tt>1 is not <tt>nil</tt> or <tt>false</tt>.
Otherwise, it calls <tt>error</tt> passing <tt>ret</tt>2 wrapped
in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to
distinguish exceptions from runtime errors.

<pre class="example">
-- connects or throws an exception with the appropriate error message
c = socket.try(socket.connect("localhost", 80))
</pre>

socket._VERSION

This constant has a string describing the current LuaSocket version.

<div class="footer">
<hr>
<center>

<a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>



Last modified by Diego Nehab on 
Thu Apr 20 00:25:54 EDT 2006


</center>
</div>

</body>
</html>