Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1

1 files changed, 287 insertions, 246 deletions

diff --git a/doc/tcp.html b/docs/tcp.html
index fb627a1..a26228d 100644
--- a/doc/tcp.html
+++ b/docs/tcp.html
@@ -13,17 +13,17 @@
 
 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<div class=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">
+<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
+<tr><td align="center" valign="top">Network support for the Lua language
 </td></tr>
 </table>
-<p class=bar>
+<p class="bar">
 <a href="index.html">home</a> &middot;
 <a href="index.html#download">download</a> &middot;
 <a href="installation.html">installation</a> &middot;
@@ -38,122 +38,45 @@
 
 <h2 id="tcp">TCP</h2>
 
-<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id="socket.tcp">
-socket.<b>tcp()</b>
-</p>
-
-<p class=description>
-Creates and returns an 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>
-
-<p class=note>
-Note: The choice between IPv4 and IPv6 happens during a call to
-<a href=#bind><tt>bind</tt></a> or <a
-href=#bind><tt>connect</tt></a>, depending on the address
-family obtained from the resolver.
-</p>
-
-<p class=note>
-Note: Before the choice between IPv4 and IPv6 happens,
-the internal socket object is invalid and therefore <a
-href=#setoption><tt>setoption</tt></a> will fail.
-</p>
-
-<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id="socket.tcp4">
-socket.<b>tcp4()</b>
-</p>
-
-<p class=description>
-Creates and returns an IPv4 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>
-
-<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id="socket.tcp6">
-socket.<b>tcp6()</b>
-</p>
-
-<p class=description>
-Creates and returns an IPv6 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>
-
-<p class=note>
-Note: The TCP object returned will have the option
-"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
-</p>
-
 <!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="accept">
+<p class="name" id="accept">
 server:<b>accept()</b>
 </p>
 
-<p class=description>
+<p class="description">
 Waits  for  a  remote connection on the server
 object and returns a client object representing that connection.
 </p>
 
-<p class=return>
+<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>
+<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>
+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">
+<p class="name" id="bind">
 master:<b>bind(</b>address, port<b>)</b>
 </p>
 
-<p class=description>
+<p class="description">
 Binds a master object to <tt>address</tt> and <tt>port</tt> on the
 local host.
+</p>
 
-<p class=parameters>
+<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>
@@ -164,25 +87,25 @@ If <tt>port</tt> is 0, the system automatically
 chooses an ephemeral port.
 </p>
 
-<p class=return>
+<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>
+<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">
+<p class="name" id="close">
 master:<b>close()</b><br>
 client:<b>close()</b><br>
 server:<b>close()</b>
 </p>
 
-<p class=description>
+<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
@@ -190,7 +113,7 @@ bound is made  available to other  applications. No further  operations
 a closed socket.
 </p>
 
-<p class=note>
+<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
@@ -199,90 +122,166 @@ automatically closed before destruction, though.
 
 <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="connect">
+<p class="name" id="connect">
 master:<b>connect(</b>address, port<b>)</b>
 </p>
 
-<p class=description>
+<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>.
+<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>
+<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>
+<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>
+<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>
+<p class="note">
 Note: Starting with LuaSocket 2.0,
-the <a href=#settimeout><tt>settimeout</tt></a>
+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
+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>
 
-<p class=note>
+<p class="note">
 Note: Starting with LuaSocket 3.0, the host name resolution
-depends on whether the socket was created by <a
-href=#socket.tcp><tt>socket.tcp</tt></a> or <a
-href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from
-the appropriate family are tried in succession until the
-first success or until the last failure.
+depends on whether the socket was created by
+<a href="#socket.tcp"><tt>socket.tcp</tt></a>,
+<a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or
+<a href="#socket.tcp6"><tt>socket.tcp6</tt></a>. Addresses from
+the appropriate family (or both) are tried in the order
+returned by the resolver until the
+first success or until the last failure. If the timeout was
+set to zero, only the first address is tried.
+</p>
+
+<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="dirty">
+master:<b>dirty()</b><br>
+client:<b>dirty()</b><br>
+server:<b>dirty()</b>
+</p>
+
+<p class="description">
+Check the read buffer status.
+</p>
+
+<p class="return">
+Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
+</p>
+
+<p class="note">
+Note: <b>This is an internal method, use at your own risk.</b>
+</p>
+
+
+<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="getfd">
+master:<b>getfd()</b><br>
+client:<b>getfd()</b><br>
+server:<b>getfd()</b>
+</p>
+
+<p class="description">
+Returns the underling socket descriptor or handle associated to the object.
+</p>
+
+<p class="return">
+The descriptor or handle. In case the object has been closed, the return value
+will be -1. For an invalid socket it will be <a href="socket.html#socketinvalid">
+<tt>_SOCKETINVALID</tt></a>.
+</p>
+
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be
+portable. Use at your own risk. </b>
+</p>
+
+
+<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="getoption">
+client:<b>getoption(option)</b><br>
+server:<b>getoption(option)</b>
+</p>
+
+<p class="description">
+Gets options for the TCP object.
+See <a href="#setoption"><tt>setoption</tt></a> for description of the
+option names and values.
+</p>
+
+<p class="parameters">
+<tt>Option</tt> is a string with the option name.</p>
+<ul>
+<li> '<tt>keepalive</tt>'</li>
+<li> '<tt>linger</tt>'</li>
+<li> '<tt>reuseaddr</tt>'</li>
+<li> '<tt>tcp-nodelay</tt>'</li>
+</ul>
+
+<p class="return">
+The method returns the option <tt>value</tt> in case of success, or
+<b><tt>nil</tt></b> followed by an error message otherwise.
 </p>
 
+
 <!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="getpeername">
+<p class="name" id="getpeername">
 client:<b>getpeername()</b>
 </p>
 
-<p class=description>
+<p class="description">
 Returns information about the remote side of a connected client object.
 </p>
 
-<p class=return>
+<p class="return">
 Returns a string with the IP address of the peer, the
 port number that peer is using for the connection,
 and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
 In case of error, the method returns <b><tt>nil</tt></b>.
 </p>
 
-<p class=note>
+<p class="note">
 Note: It makes no sense to call this method on server objects.
 </p>
 
 <!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="getsockname">
+<p class="name" id="getsockname">
 master:<b>getsockname()</b><br>
 client:<b>getsockname()</b><br>
 server:<b>getsockname()</b>
 </p>
 
-<p class=description>
+<p class="description">
 Returns the local address information associated to the object.
 </p>
 
-<p class=return>
+<p class="return">
 The method returns a string with local IP address, a number with
 the local port,
 and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
@@ -291,83 +290,97 @@ In case of error, the method returns <b><tt>nil</tt></b>.
 
 <!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="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>
+<p class="description">
 Returns accounting information on the socket, useful for throttling
 of bandwidth.
 </p>
 
-<p class=return>
+<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>
 
+<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="gettimeout">
+master:<b>gettimeout()</b><br>
+client:<b>gettimeout()</b><br>
+server:<b>gettimeout()</b>
+</p>
+
+<p class="description">
+Returns the current block timeout followed by the curent
+total timeout.
+</p>
+
+
 <!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="listen">
+<p class="name" id="listen">
 master:<b>listen(</b>backlog<b>)</b>
 </p>
 
-<p class=description>
+<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.
+<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>
+<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>
+<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">
+<p class="name" id="receive">
 client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
 </p>
 
-<p class=description>
+<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>
+<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;
+closed. No end-of-line translation is performed;</li>
 <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;
+ignored by the pattern. This is the default pattern;</li>
 <li> <tt>number</tt>:  causes the  method to read  a specified <tt>number</tt>
-of bytes from the socket.
+of bytes from the socket.</li>
 </ul>
 
-<p class=parameters>
+<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>
+<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, followed by a (possibly empty) string containing
@@ -377,7 +390,7 @@ 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>
+<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
@@ -388,22 +401,22 @@ too.
 
 <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="send">
+<p class="name" id="send">
 client:<b>send(</b>data [, i [, j]]<b>)</b>
 </p>
 
-<p class=description>
+<p class="description">
 Sends <tt>data</tt> through client object.
 </p>
 
-<p class=parameters>
+<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>
+<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
@@ -417,7 +430,7 @@ was  completed or the string  '<tt>timeout</tt>'  in  case
 there was  a  timeout  during  the operation.
 </p>
 
-<p class=note>
+<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
@@ -426,27 +439,27 @@ instead of calling the method several times.
 
 <!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="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>
+<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>
+<p class="parameters">
 <tt>Option</tt> is a string with the option name, and <tt>value</tt>
-depends on the option being set:
+depends on the option being set:</p>
 
 <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;
+considered broken and processes using the socket are notified;</li>
 
 <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
@@ -457,101 +470,85 @@ 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;
+zero;</li>
 
 <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;
+<a href="#bind"><tt>bind</tt></a> should allow reuse of local addresses;</li>
 
 <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
-disables the Nagle's algorithm for the connection;
+disables the Nagle's algorithm for the connection;</li>
+
+<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!</li>
+
+<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!</li>
+
+<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!</li>
+
+<li> '<tt>tcp-defer-accept</tt>': value for <tt>TCP_DEFER_ACCEPT</tt> Linux only!!</li>
+
+<li> '<tt>tcp-fastopen</tt>': value for <tt>TCP_FASTOPEN</tt> Linux only!!</li>
+
+<li> '<tt>tcp-fastopen-connect</tt>': value for <tt>TCP_FASTOPEN_CONNECT</tt> Linux only!!</li>
 
 <li> '<tt>ipv6-v6only</tt>':
 Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to
-sending and receiving only IPv6 packets.
+sending and receiving only IPv6 packets.</li>
 </ul>
 
-<p class=return>
+<p class="return">
 The method returns 1 in case of success, or <b><tt>nil</tt></b>
 followed by an error message otherwise.
 </p>
 
-<p class=note>
+<p class="note">
 Note: The descriptions above come from the man pages.
 </p>
 
-<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id="getoption">
-client:<b>getoption(</b>option)</b><br>
-server:<b>getoption(</b>option)</b>
-</p>
-
-<p class=description>
-Gets options for the TCP object.
-See <a href=#setoption><tt>setoption</tt></a> for description of the
-option names and values.
-</p>
-
-<p class=parameters>
-<tt>Option</tt> is a string with the option name.
-<ul>
-
-<li> '<tt>keepalive</tt>'
-<li> '<tt>linger</tt>'
-<li> '<tt>reuseaddr</tt>'
-<li> '<tt>tcp-nodelay</tt>'
-</ul>
-
-<p class=return>
-The method returns the option <tt>value</tt> in case of success, or
-<b><tt>nil</tt></b> followed by an error message otherwise.
-</p>
-
 <!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="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>
+<p class="description">
 Resets accounting information on the socket, useful for throttling
 of bandwidth.
 </p>
 
-<p class=parameters>
+<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>
+<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">
+<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>
+<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>
+<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>
+<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:
@@ -568,12 +565,12 @@ the amount of  time LuaSocket can block a Lua  script before returning from
 a call.</li>
 </ul>
 
-<p class=parameters>
+<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>
+<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
@@ -582,7 +579,7 @@ and perform automatic name resolution might be blocked by the resolver for
 longer than the specified timeout value.
 </p>
 
-<p class=note>
+<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.
@@ -590,94 +587,138 @@ contained verbs making their imperative nature obvious.
 
 <!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="shutdown">
+<p class="name" id="shutdown">
 client:<b>shutdown(</b>mode<b>)</b><br>
 </p>
 
-<p class=description>
+<p class="description">
 Shuts down part of a full-duplex connection.
 </p>
 
-<p class=parameters>
+<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.
+This is the default mode;</li>
+<li>"<tt>send</tt>": disallow further sends on the object;</li>
+<li>"<tt>receive</tt>": disallow further receives on the object.</li>
 </ul>
+</p>
 
-<p class=return>
+<p class="return">
 This function returns 1.
 </p>
 
-<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="dirty">
-master:<b>dirty()</b><br>
-client:<b>dirty()</b><br>
-server:<b>dirty()</b>
+<p class="name" id="setfd">
+master:<b>setfd(</b>fd<b>)</b><br>
+client:<b>setfd(</b>fd<b>)</b><br>
+server:<b>setfd(</b>fd<b>)</b>
 </p>
 
-<p class=description>
-Check the read buffer status.
+<p class="description">
+Sets the underling socket descriptor or handle associated to the object. The current one
+is simply replaced, not closed, and no other change to the object state is made.
+To set it as invalid use <a href="socket.html#socketinvalid"><tt>_SOCKETINVALID</tt></a>.
 </p>
 
-<p class=return>
-Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
+<p class="return">
+No return value.
 </p>
 
-<p class=note>
-Note: <b>This is an internal method, any use is unlikely to be portable.</b>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be
+portable. Use at your own risk. </b>
 </p>
 
-<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="getfd">
-master:<b>getfd()</b><br>
-client:<b>getfd()</b><br>
-server:<b>getfd()</b>
+<p class="name" id="socket.tcp">
+socket.<b>tcp()</b>
 </p>
 
-<p class=description>
-Returns the underling socket descriptor or handle associated to the object.
+<p class="description">
+Creates and returns an 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>
 
-<p class=return>
-The descriptor or handle. In case the object has been closed, the return will be -1.
+<p class="note">
+Note: The choice between IPv4 and IPv6 happens during a call to
+<a href="#bind"><tt>bind</tt></a> or <a
+href="#bind"><tt>connect</tt></a>, depending on the address
+family obtained from the resolver.
 </p>
 
-<p class=note>
-Note: <b>This is an internal method, any use is unlikely to be portable.</b>
+<p class="note">
+Note: Before the choice between IPv4 and IPv6 happens,
+the internal socket object is invalid and therefore <a
+href="#setoption"><tt>setoption</tt></a> will fail.
 </p>
 
-<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<p class=name id="setfd">
-master:<b>setfd(</b>fd<b>)</b><br>
-client:<b>setfd(</b>fd<b>)</b><br>
-server:<b>setfd(</b>fd<b>)</b>
+<p class="name" id="socket.tcp4">
+socket.<b>tcp4()</b>
 </p>
 
-<p class=description>
-Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made.
+<p class="description">
+Creates and returns an IPv4 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>
 
-<p class=return>
-No return value.
+<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="socket.tcp6">
+socket.<b>tcp6()</b>
 </p>
 
-<p class=note>
-Note: <b>This is an internal method, any use is unlikely to be portable.</b>
+<p class="description">
+Creates and returns an IPv6 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>
 
+<p class="note">
+Note: The TCP object returned will have the option
+"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
+</p>
+
+
+
 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<div class=footer>
+<div class="footer">
 <hr>
 <center>
-<p class=bar>
+<p class="bar">
 <a href="index.html">home</a> &middot;
 <a href="index.html#down">download</a> &middot;
 <a href="installation.html">installation</a> &middot;