<!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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a> 
</p>
</center>
<hr>
</div>

<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<h2 id=tcp>TCP</h2> 

<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=socket.tcp> 
socket.<b>tcp()</b>
</p>

<p class=description> 
Creates and returns a TCP master object. A master object can
be transformed into a server object with the method 
<a href=#bind><tt>bind</tt></a> or into a client object with the method 
<a href=#connect><tt>connect</tt></a>. The only other method
supported by a master object is the <a href=#close><tt>close</tt></a>
method.</p>

<p class=return>
In case of success, a new master object is returned. In case of error,
<tt>nil</tt> is returned, followed by an error message.
</p>

<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=accept> 
server:<b>accept()</b>
</p>

<p class=description>
Waits  for  a  remote connection on the server
object and returns a client object representing that connection.
</p>

<p class=return>
If a connection is successfully initiated, a client object is returned.  
If a  timeout condition  is  met,  the method  returns <tt>nil</tt> followed
by the error string '<tt>timeout</tt>'. 
</p>

<p class=note>
Note: calling <a href=misc.html#socket.select><tt>socket.select</tt></a>
with   a  server   object   in
the <tt>receive</tt>  parameter  before  a   call  to  <tt>accept</tt> does
<em>not</em> guarantee  <tt>accept</tt> will  return immediately.  Use the <a
href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
might block until <em>another</em> client shows up.
</p>

<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=bind> 
master:<b>bind(</b>address, port [, backlog]<b>)</b>
</p>

<p class=description>
Binds a master object to <tt>address</tt> and <tt>port</tt> on the
local host, transforming it into a server object.  Server
objects support the 
<a href=#accept><tt>accept</tt></a>,  
<a href=#getsockname><tt>getsockname</tt></a>, 
<a href=#setoption><tt>setoption</tt></a>, 
<a href=#settimeout><tt>settimeout</tt></a>, 
and <a href=#close><tt>close</tt></a> methods.  
</p>

<p class=parameters>
<tt>Address</tt> can be an IP address or a host name. 
<tt>Port</tt> must be an integer number in the range [0..64K]. 
If <tt>address</tt>
is '<tt>*</tt>', the system binds to all local interfaces
using the <tt>INADDR_ANY</tt> constant. If <tt>port</tt> is 0, the system automatically
chooses an ephemeral port.  The optional parameter <tt>backlog</tt>, which
defaults to 1, specifies the  number  of  client connections that can
be queued waiting for service. If the queue is full and another  client
attempts connection,  the connection is  refused.
</p>

<p class=return>
In case of  success, the  method returns  1. In case of error, the
method returns <tt>nil</tt> followed by an error message.
</p>

<p class=note>
Note: The function <tt>socket.bind</tt> is available and is a short
for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>bind</tt> method.
</p>

<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=close> 
master:<b>close()</b><br>
client:<b>close()</b><br>
server:<b>close()</b>
</p>

<p class=description>
Closes  a TCP object. The internal socket used by the object is closed
and the local  address   to  which the object was
bound is made  available to other  applications. No further  operations
(except  for  further calls  to the <tt>close</tt> method)  are allowed on
a closed socket. 
</p>

<p class=note>
Note:  It is  important to  close all  used  sockets once  they are  not
needed,  since, in  many systems,  each socket  uses a  file descriptor,
which are limited system resources. Garbage-collected objects are
automatically closed before destruction, though. 
</p>

<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=connect>
master:<b>connect(</b>address, port<b>)</b>
</p>

<p class=description>
Attempts to connect a master object to a remote host, transforming it into a
client object. Client objects support methods 
<a href=#send><tt>send</tt></a>,
<a href=#receive><tt>receive</tt></a>, 
<a href=#getsockname><tt>getsockname</tt></a>, 
<a href=#getpeername><tt>getpeername</tt></a>,
<a href=#settimeout><tt>settimeout</tt></a>, 
and <a href=#close><tt>close</tt></a>.
</p>

<p class=parameters>
<tt>Address</tt> can be an IP address or a host name. 
<tt>Port</tt> must be an integer number in the range [1..64K]. 
</p>

<p class=return>
In case of error, the method returns <tt>nil</tt> followed by a string
describing the error. In case of success, the method returns 1.
</p>

<p class=note>
Note: The function <tt>socket.connect</tt> is available and is a short
for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>connect</tt> method.
</p>

<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=getpeername>
client:<b>getpeername()</b>
</p>

<p class=description>
Returns information about the remote side of a connected client object.
</p>

<p class=return>
Returns a string with the IP address of the peer, followed by the 
port number that peer is using for the connection. 
In case of error, the method returns <tt>nil</tt>. 
</p>

<p class=note>
Note: It makes no sense to call this method on server objects.
</p>

<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=getsockname>
client:<b>getsockname()</b><br>
server:<b>getsockname()</b>
</p>

<p class=description>
Returns the local address information associated to the object. 
</p>

<p class=return>
The method returns a string with local IP address and a number with 
the port. In case of error, the method returns <tt>nil</tt>.
</p>

<p class=note>
Note: Naturally, for a server object, the address and port returned are
those passed to the <a href=#bind>bind</a> method. If the port value
passed to bind was 0, the OS assigned ephemeral port is returned. For
client objects, both the address and port are ephemeral and these are the
values returned.  
</p>

<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=receive>
client:<b>receive(</b>[pattern<sub>1</sub>, pattern<sub>2</sub>,
... pattern<sub>N</sub>]<b>)</b>
</p>

<p class=description>
Reads data from a client object, according to the specified <em>read
patterns</em>.  Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. 
</p>

<p class=parameters>
The parameters <tt>pattern</tt><sub>1</sub>, <tt>pattern</tt><sub>2</sub>, ...
<tt>pattern</tt><sub>N</sub> can be any of the following: 
</p>

<ul>
<li> '<tt>*a</tt>':  reads from  the  socket  until the  connection  is
closed. No end-of-line translation is performed;
<li> '<tt>*l</tt>':  reads a line of  text from the socket.  The line is
terminated by a  LF character (ASCII&nbsp;10), optionally  preceded by a
CR character (ASCII&nbsp;13). The CR and LF characters are not included in
the returned line. This is the default pattern;
<li> <tt>number</tt>:  causes the  method to read  <tt>number</tt> raw
bytes from the socket.
</ul>

<p class=return>
The method  returns one value for  each pattern, followed by  a single
error  code that  can be  <tt>nil</tt> in  case of  success, the  string
'<tt>closed</tt>'  in   case  the  connection  was   closed  before  the
transmission  was completed  or  the string  '<tt>timeout</tt>' in  case
there was a timeout during  the operation. 
</p>

<p class=note>
Note: In case of error, the method always return everything it managed
to download before the error condition was met.
</p>

<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=send>
client:<b>send(</b>string<sub>1</sub> [,
string<sub>2</sub>, ... string<sub>N</sub>]<b>)</b>
</p>

<p class=description>
Sends data through client object.
</p>

<p class=parameters>
All parameters should be strings. For small strings, it is always better to
concatenate them in Lua (with the '<tt>..</tt>' operator) and pass the 
result to LuaSocket instead of passing several independent strings.
</p>

<p class=return>
The method returns the number of bytes accepted by the transport layer,
followed by an error code. The error code is <tt>nil</tt> if the operation
completed with no errors, the string '<tt>closed</tt>' in case
the connection was  closed before the transmission was  completed or the
string  '<tt>timeout</tt>'  in  case  there was  a  timeout  during  the
operation.
</p>

<p class=note>
Note: The return values for the <tt>send</tt> method have been changed in
LuaSocket 2.0! In previous versions, the method returned only the
error message. Since returning <tt>nil</tt> in case of success goes 
against all other LuaSocket methods and functions, the 
<tt>send</tt> method been changed for the sake of uniformity. 
</p>

<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=setoption>
client:<b>setoption(</b>option [, value]<b>)</b><br>
server:<b>setoption(</b>option [, value]<b>)</b>
</p>

<p class=description>
Sets options for the TCP object. Options are only needed by low-level or
time-critical applications. You should only modify a an option if you 
are sure you need it. 
</p>

<p class=parameters>
<tt>Option</tt> is a string with the option name, and <tt>value</tt> 
depends on the option being set:

<ul>
<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> disables the
Nagle's algorithm for the connection;
<li> '<tt>linger</tt>': Controls the action taken when unsent data are
queued on socket and a close is performed.  The value is a table with a
boolean entry '<tt>on</tt>' and a numeric entry for the time interval
'<tt>timeout</tt>' in seconds.
 If the '<tt>on</tt>' field is set to <tt>true</tt>,
the system will block the process on the close attempt until it is able to
transmit the data or until '<tt>timeout</tt>' has passed. If '<tt>on</tt>'
is <tt>false</tt> and a close is issued, the system will process the close
in a manner that allows the process to continue as quickly as possible. I
do not advise you to set this to anything other than zero. 
<li> '<tt>keepalive</tt>':  Setting this option to <tt>true</tt> enables
the periodic transmission of messages on a connected socket. Should the
     connected party fail to respond to these messages, the connection is
considered broken and processes using the socket are notified. 
</ul>

<p class=return>
The method returns 1 in case of success, or <tt>nil</tt> otherwise.
</p>

<p class=note>
Note: The descriptions above come from the man pages.
</p>

<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=settimeout>
client:<b>settimeout(</b>value [, mode]<b>)</b><br>
server:<b>settimeout(</b>value [, mode]<b>)</b>
</p>

<p class=description>
Changes the timeout  values for the object. By default,
all I/O  operations are  blocking. That  is, any  call to  the methods
<a href=#send><tt>send</tt></a>, 
<a href=#receive><tt>receive</tt></a>, and 
<a href=#accept><tt>accept</tt></a>
will  block indefinitely,  until the operation completes.  The
<tt>settimeout</tt>  method defines a  limit on the  amount  of   time  the
I/O methods can  block. When a timeout is set and the specified amount of
time has elapsed, the affected methods give up and fail with an error code.
</p>

<p class=parameters>
The amount of time to wait is specified  as  the
<tt>value</tt> parameter, in seconds. There  are two timeout  modes and
both can be used together for fine tuning: 
</p>

<ul>
<li> '<tt>b</tt>': <em>block</em> timeout.  Specifies the upper limit on
the amount  of time  LuaSocket can  be blocked  by the  operating system
while waiting for completion of any single I/O operation. This is the
default mode;</li>

<li> '<tt>t</tt>':  <em>total</em> timeout. Specifies the  upper limit on
the amount of  time LuaSocket can block a Lua  script before returning from
a call.</li> 
</ul>

<p class=parameters>
The  <tt>nil</tt>  timeout  <tt>value</tt> allows  operations  to  block
indefinitely. Negative timeout values have the same effect.
</p>

<p class=note>
Note: although  timeout values  have millisecond  precision in LuaSocket,
large  blocks can cause I/O functions not to  respect timeout values due
to the time the library takes to  transfer blocks to and from the  OS
and to and from the Lua interpreter. 
</p>

<p class=note>
Note: The old <tt>timeout</tt> method is deprecated. The name has been
changed for sake of uniformity, since all other method names already
contained verbs making their imperative nature obvious.
</p>

<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<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>