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

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

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.

<pre class=example>
t = socket.gettime()
-- do stuff
print(socket.gettime() - t .. " seconds elapsed")
</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.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. It will be called 
in protected mode.

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,
returns <tt>nil</tt> followed by an error message.

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.

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

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

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

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

The function returns a source with the appropriate behavior.

socket._SETSIZE

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

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

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.

<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>. Otherwise, it calls <tt>error</tt> passing <tt>ret</tt>2.

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

Name	Size	Permission
.	rwxr-xr-x	-
..	rwxr-xr-x	-
README	237 bytes	rw-r--r--
dns.html	4.6 KB	rw-r--r--
ftp.html	9.34 KB	rw-r--r--
http.html	11.18 KB	rw-r--r--
index.html	7.39 KB	rw-r--r--
installation.html	3.79 KB	rw-r--r--
introduction.html	12.14 KB	rw-r--r--
ltn12.html	10.68 KB	rw-r--r--
lua05.ppt	297 KB	rw-r--r--
luasocket.png	11.46 KB	rw-r--r--
mime.html	13.83 KB	rw-r--r--
reference.css	950 bytes	rw-r--r--
reference.html	7.41 KB	rw-r--r--
smtp.html	14.16 KB	rw-r--r--
socket.html	13.54 KB	rw-r--r--
tcp.html	20.96 KB	rw-r--r--
udp.html	16.52 KB	rw-r--r--
url.html	8.23 KB	rw-r--r--

Avacostn - Moslem

Filemanager

Server Info

User Info