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