Root Zanli
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
doc
/
lua-socket
/
Filename :
tcp.html
back
Copy
<!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="index.html">home</a> · <a href="index.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> <!-- 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> <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 or <tt>IN6ADDR_ANY_INIT</tt>, according to the family. 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> <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>, <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"> 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, 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"> 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, a number with the local port, 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> <!-- 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> <!-- 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"> 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> <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> <li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> of bytes from the socket.</li> </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, followed by a (possibly empty) string containing the partial that was received. The error message 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. </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:</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;</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 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> <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> <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> 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.</li> </ul> <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"> 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> <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"> This function returns 1. </p> <!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <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"> 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"> No return value. </p> <p class="note"> Note: <b>This is an internal method. Unlikely to be portable. Use at your own risk. </b> </p> <!-- 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> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <div class="footer"> <hr> <center> <p class="bar"> <a href="index.html">home</a> · <a href="index.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>