FM / lua-socket

/usr/share/doc/lua-socket

Name	Size	Mode	Actions
CHANGELOG.md	4189	0644	edit dl rm
dns.html	4752	0644	edit dl rm
ftp.html	9599	0644	edit dl rm
http.html	11865	0644	edit dl rm
index.html	4431	0644	edit dl rm
installation.html	3881	0644	edit dl rm
introduction.html	12433	0644	edit dl rm
ltn12.html	11483	0644	edit dl rm
luasocket.png	11732	0644	edit dl rm
mime.html	14246	0644	edit dl rm
README.md	939	0644	edit dl rm
reference.css	975	0644	edit dl rm
reference.html	7928	0644	edit dl rm
smtp.html	14621	0644	edit dl rm
socket.html	14704	0644	edit dl rm
tcp.html	24022	0644	edit dl rm
udp.html	18727	0644	edit dl rm
url.html	8430	0644	edit dl rm

Edit: /usr/share/doc/lua-socket/socket.html (14704B)

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

cmd: