luasocket-2.0.2/doc/tcp.html - nest-learning-thermostat/5.1.7/luasocket - Git at Google

 <!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 TCP/IP support">
 <meta name="keywords" content="Lua, LuaSocket, Socket, TCP, Library, Network, Support">
 <title>LuaSocket: TCP/IP support</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="home.html">home</a> &middot;
 <a href="home.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>
 </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=#listen><tt>listen</tt></a> (after a call to <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,
 <b><tt>nil</tt></b> 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 <b><tt>nil</tt></b>
 followed by the error string '<tt>timeout</tt>'. Other errors are
 reported by <b><tt>nil</tt></b> followed by a message describing the error.
 </p>

 <p class=note>
 Note: calling <a href=socket.html#select><tt>socket.select</tt></a>
 with   a  server   object   in
 the <tt>recvt</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<b>)</b>
 </p>

 <p class=description>
 Binds a master object to <tt>address</tt> and <tt>port</tt> on the
 local host.

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

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

 <p class=note>
 Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a>
 is available and is a shortcut for the creation of server sockets.
 </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 <b><tt>nil</tt></b> followed by a string
 describing the error. In case of success, the method returns 1.
 </p>

 <p class=note>
 Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a>
 is available and is a shortcut for the creation of client sockets.
 </p>

 <p class=note>
 Note: Starting with LuaSocket 2.0,
 the <a href=#settimeout><tt>settimeout</tt></a>
 method affects the behavior of <tt>connect</tt>, causing it to return
 with an error in case of a timeout. If that happens, you can still call <a
 href=socket.html#select><tt>socket.select</tt></a> with the socket in the
 <tt>sendt</tt> table. The socket will be writable when the connection is
 established.
 </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 <b><tt>nil</tt></b>.
 </p>

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

 <!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

 <p class=name id=getsockname>
 master:<b>getsockname()</b><br>
 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 <b><tt>nil</tt></b>.
 </p>

 <!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

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

 <p class=description>
 Returns accounting information on the socket, useful for throttling
 of bandwidth.
 </p>

 <p class=return>
 The method returns the number of bytes received, the number of bytes sent,
 and the age of the socket object in seconds.
 </p>

 <!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

 <p class=name id=listen>
 master:<b>listen(</b>backlog<b>)</b>
 </p>

 <p class=description>
 Specifies the socket is willing to receive connections, transforming the
 object 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>
 The parameter <tt>backlog</tt> 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 <b><tt>nil</tt></b> followed by an error message.
 </p>

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

 <p class=name id=receive>
 client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
 </p>

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

 <p class=parameters>
 <tt>Pattern</tt> 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. In fact, <em>all</em> CR characters are
 ignored by the pattern. This is the default pattern;
 <li> <tt>number</tt>:  causes the  method to read  a specified <tt>number</tt>
 of bytes from the socket.
 </ul>

 <p class=parameters>
 <tt>Prefix</tt> is an optional string to be concatenated to the beginning
 of any received data before return.
 </p>

 <p class=return>
 If successful, the method returns the received pattern. In case of error,
 the method returns <tt><b>nil</b></tt> followed by an error message which
 can be 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.
 Also, after the error message, the function returns the partial result of
 the transmission.
 </p>

 <p class=note>
 <b>Important note</b>: This function was changed <em>severely</em>. It used
 to support multiple patterns (but I have never seen this feature used) and
 now it doesn't anymore.  Partial results used to be returned in the same
 way as successful results. This last feature violated the idea that all
 functions should return <tt><b>nil</b></tt> on error.  Thus it was changed
 too.
 </p>

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

 <p class=name id=send>
 client:<b>send(</b>data [, i [, j]]<b>)</b>
 </p>

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

 <p class=parameters>
 <tt>Data</tt> is the string to be sent. The optional arguments
 <tt>i</tt> and <tt>j</tt> work exactly like the standard
 <tt>string.sub</tt> Lua function to allow the selection of a
 substring to be sent.
 </p>

 <p class=return>
 If successful, the method returns the index of the last byte
 within <tt>[i, j]</tt> that has been sent.  Notice that, if
 <tt>i</tt> is 1 or absent, this is effectively the total
 number of bytes sent.  In case of error, the method returns
 <b><tt>nil</tt></b>, followed by an error message, followed
 by the index of the last byte within <tt>[i, j]</tt> that
 has been sent. You might want to try again from the byte
 following that.  The error message can be '<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: Output is <em>not</em> buffered. For small strings,
 it is always better to concatenate them in Lua
 (with the '<tt>..</tt>' operator) and send the result in one call
 instead of calling the method several times.
 </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 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>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;

 <li> '<tt>linger</tt>': Controls the action taken when unsent data are
 queued on a 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>reuseaddr</tt>': Setting this option indicates that the rules
 used in validating addresses supplied in a call to
 <a href=#bind><tt>bind</tt></a> should allow reuse of local addresses;

 <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
 disables the Nagle's algorithm for the connection.

 </ul>

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

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

 <!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

 <p class=name id=setstats>
 master:<b>setstats(</b>received, sent, age<b>)</b><br>
 client:<b>setstats(</b>received, sent, age<b>)</b><br>
 server:<b>setstats(</b>received, sent, age<b>)</b><br>
 </p>

 <p class=description>
 Resets accounting information on the socket, useful for throttling
 of bandwidth.
 </p>

 <p class=parameters>
 <tt>Received</tt> is a number with the new number of bytes received.
 <tt>Sent</tt> is a number with the new number of bytes sent.
 <tt>Age</tt> is the new age in seconds.
 </p>

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

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

 <p class=name id=settimeout>
 master:<b>settimeout(</b>value [, mode]<b>)</b><br>
 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  <b><tt>nil</tt></b>  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. Also, function that accept host names
 and perform automatic name resolution might be blocked by the resolver for
 longer than the specified timeout value.
 </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>

 <!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

 <p class=name id=shutdown>
 client:<b>shutdown(</b>mode<b>)</b><br>
 </p>

 <p class=description>
 Shuts down part of a full-duplex connection.
 </p>

 <p class=parameters>
 Mode tells which way of the connection should be shut down and can
 take the value:
 <ul>
 <li>"<tt>both</tt>": disallow further sends and receives on the object.
 This is the default mode;
 <li>"<tt>send</tt>": disallow further sends on the object;
 <li>"<tt>receive</tt>": disallow further receives on the object.
 </ul>

 <p class=return>
 This function returns 1.
 </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="installation.html">installation</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>
 Thu Apr 20 00:25:57 EDT 2006
 </small>
 </p>
 </center>
 </div>

 </body>
 </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 TCP/IP support">
	<meta name="keywords" content="Lua, LuaSocket, Socket, TCP, Library, Network, Support">
	<title>LuaSocket: TCP/IP support</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="home.html">home</a> ·
	<a href="home.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>

	<!-- 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=#listen><tt>listen</tt></a> (after a call to <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,
	<b><tt>nil</tt></b> 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 <b><tt>nil</tt></b>
	followed by the error string '<tt>timeout</tt>'. Other errors are
	reported by <b><tt>nil</tt></b> followed by a message describing the error.
	</p>

	<p class=note>
	Note: calling <a href=socket.html#select><tt>socket.select</tt></a>
	with a server object in
	the <tt>recvt</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<b>)</b>
	</p>

	<p class=description>
	Binds a master object to <tt>address</tt> and <tt>port</tt> on the
	local host.

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

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

	<p class=note>
	Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a>
	is available and is a shortcut for the creation of server sockets.
	</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 <b><tt>nil</tt></b> followed by a string
	describing the error. In case of success, the method returns 1.
	</p>

	<p class=note>
	Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a>
	is available and is a shortcut for the creation of client sockets.
	</p>

	<p class=note>
	Note: Starting with LuaSocket 2.0,
	the <a href=#settimeout><tt>settimeout</tt></a>
	method affects the behavior of <tt>connect</tt>, causing it to return
	with an error in case of a timeout. If that happens, you can still call <a
	href=socket.html#select><tt>socket.select</tt></a> with the socket in the
	<tt>sendt</tt> table. The socket will be writable when the connection is
	established.
	</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 <b><tt>nil</tt></b>.
	</p>

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

	<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

	<p class=name id=getsockname>
	master:<b>getsockname()</b><br>
	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 <b><tt>nil</tt></b>.
	</p>

	<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

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

	<p class=description>
	Returns accounting information on the socket, useful for throttling
	of bandwidth.
	</p>

	<p class=return>
	The method returns the number of bytes received, the number of bytes sent,
	and the age of the socket object in seconds.
	</p>

	<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

	<p class=name id=listen>
	master:<b>listen(</b>backlog<b>)</b>
	</p>

	<p class=description>
	Specifies the socket is willing to receive connections, transforming the
	object 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>
	The parameter <tt>backlog</tt> 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 <b><tt>nil</tt></b> followed by an error message.
	</p>

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

	<p class=name id=receive>
	client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
	</p>

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

	<p class=parameters>
	<tt>Pattern</tt> 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 10), optionally preceded by a
	CR character (ASCII 13). The CR and LF characters are not included in
	the returned line. In fact, <em>all</em> CR characters are
	ignored by the pattern. This is the default pattern;
	<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt>
	of bytes from the socket.
	</ul>

	<p class=parameters>
	<tt>Prefix</tt> is an optional string to be concatenated to the beginning
	of any received data before return.
	</p>

	<p class=return>
	If successful, the method returns the received pattern. In case of error,
	the method returns <tt><b>nil</b></tt> followed by an error message which
	can be 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.
	Also, after the error message, the function returns the partial result of
	the transmission.
	</p>

	<p class=note>
	<b>Important note</b>: This function was changed <em>severely</em>. It used
	to support multiple patterns (but I have never seen this feature used) and
	now it doesn't anymore. Partial results used to be returned in the same
	way as successful results. This last feature violated the idea that all
	functions should return <tt><b>nil</b></tt> on error. Thus it was changed
	too.
	</p>

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

	<p class=name id=send>
	client:<b>send(</b>data [, i [, j]]<b>)</b>
	</p>

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

	<p class=parameters>
	<tt>Data</tt> is the string to be sent. The optional arguments
	<tt>i</tt> and <tt>j</tt> work exactly like the standard
	<tt>string.sub</tt> Lua function to allow the selection of a
	substring to be sent.
	</p>

	<p class=return>
	If successful, the method returns the index of the last byte
	within <tt>[i, j]</tt> that has been sent. Notice that, if
	<tt>i</tt> is 1 or absent, this is effectively the total
	number of bytes sent. In case of error, the method returns
	<b><tt>nil</tt></b>, followed by an error message, followed
	by the index of the last byte within <tt>[i, j]</tt> that
	has been sent. You might want to try again from the byte
	following that. The error message can be '<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: Output is <em>not</em> buffered. For small strings,
	it is always better to concatenate them in Lua
	(with the '<tt>..</tt>' operator) and send the result in one call
	instead of calling the method several times.
	</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 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>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;

	<li> '<tt>linger</tt>': Controls the action taken when unsent data are
	queued on a 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>reuseaddr</tt>': Setting this option indicates that the rules
	used in validating addresses supplied in a call to
	<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses;

	<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
	disables the Nagle's algorithm for the connection.

	</ul>

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

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

	<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

	<p class=name id=setstats>
	master:<b>setstats(</b>received, sent, age<b>)</b><br>
	client:<b>setstats(</b>received, sent, age<b>)</b><br>
	server:<b>setstats(</b>received, sent, age<b>)</b><br>
	</p>

	<p class=description>
	Resets accounting information on the socket, useful for throttling
	of bandwidth.
	</p>

	<p class=parameters>
	<tt>Received</tt> is a number with the new number of bytes received.
	<tt>Sent</tt> is a number with the new number of bytes sent.
	<tt>Age</tt> is the new age in seconds.
	</p>

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

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

	<p class=name id=settimeout>
	master:<b>settimeout(</b>value [, mode]<b>)</b><br>
	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 <b><tt>nil</tt></b> 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. Also, function that accept host names
	and perform automatic name resolution might be blocked by the resolver for
	longer than the specified timeout value.
	</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>

	<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

	<p class=name id=shutdown>
	client:<b>shutdown(</b>mode<b>)</b><br>
	</p>

	<p class=description>
	Shuts down part of a full-duplex connection.
	</p>

	<p class=parameters>
	Mode tells which way of the connection should be shut down and can
	take the value:
	<ul>
	<li>"<tt>both</tt>": disallow further sends and receives on the object.
	This is the default mode;
	<li>"<tt>send</tt>": disallow further sends on the object;
	<li>"<tt>receive</tt>": disallow further receives on the object.
	</ul>

	<p class=return>
	This function returns 1.
	</p>

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

	<div class=footer>
	<hr>
	<center>
	<p class=bar>
	<a href="home.html">home</a> ·
	<a href="home.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:57 EDT 2006
	</small>
	</p>
	</center>
	</div>

	</body>
	</html>