Mercurial > luasocket
diff doc/tcp.html @ 0:4b915342e2a8
LuaSocket 2.0.2 + CMake build description.
| author | Eric Wing <ewing . public |-at-| gmail . com> |
|---|---|
| date | Tue, 26 Aug 2008 18:40:01 -0700 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/tcp.html Tue Aug 26 18:40:01 2008 -0700 @@ -0,0 +1,533 @@ +<!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>