Root Zanli
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
doc
/
lua-socket
/
Filename :
socket.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 core namespace"> <meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support"> <title>LuaSocket: The socket namespace</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="https://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> <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <h2 id="socket">The socket namespace</h2> <p> The <tt>socket</tt> namespace contains the core functionality of LuaSocket. </p> <p> To obtain the <tt>socket</tt> namespace, run: </p> <pre class="example"> -- loads the socket module local socket = require("socket") </pre> <!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="headers.canonic"> socket.headers.<b>canonic</b></p> <p> The <tt>socket.headers.canonic</tt> table is used by the HTTP and SMTP modules to translate from lowercase field names back into their canonic capitalization. When a lowercase field name exists as a key in this table, the associated value is substituted in whenever the field name is sent out. </p> <p> You can obtain the <tt>headers</tt> namespace if case run-time modifications are required by running: </p> <pre class="example"> -- loads the headers module local headers = require("headers") </pre> <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="bind"> socket.<b>bind(</b>address, port [, backlog]<b>)</b> </p> <p class="description"> This function is a shortcut that creates and returns a TCP server object bound to a local <tt>address</tt> and <tt>port</tt>, ready to accept client connections. Optionally, user can also specify the <tt>backlog</tt> argument to the <a href="tcp.html#listen"><tt>listen</tt></a> method (defaults to 32). </p> <p class="note"> Note: The server object returned will have the option "<tt>reuseaddr</tt>" set to <tt><b>true</b></tt>. </p> <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="connect"> socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> </p> <p class="description"> This function is a shortcut that creates and returns a TCP client object connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally, the user can also specify the local address and port to bind (<tt>locaddr</tt> and <tt>locport</tt>), or restrict the socket family to "<tt>inet</tt>" or "<tt>inet6</tt>". Without specifying <tt>family</tt> to <tt>connect</tt>, whether a tcp or tcp6 connection is created depends on your system configuration. Two variations of connect are defined as simple helper functions that restrict the <tt>family</tt>, <tt>socket.connect4</tt> and <tt>socket.connect6</tt>. </p> <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="debug"> socket.<b>_DEBUG</b> </p> <p class="description"> This constant is set to <tt><b>true</b></tt> if the library was compiled with debug support. </p> <!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="datagramsize"> socket.<b>_DATAGRAMSIZE</b> </p> <p class="description"> Default datagram size used by calls to <a href="udp.html#receive"><tt>receive</tt></a> and <a href="udp.html#receivefrom"><tt>receivefrom</tt></a>. (Unless changed in compile time, the value is 8192.) </p> <!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="gettime"> socket.<b>gettime()</b> </p> <p class="description"> Returns the UNIX time in seconds. You should subtract the values returned by this function to get meaningful values. </p> <pre class="example"> t = socket.gettime() -- do stuff print(socket.gettime() - t .. " seconds elapsed") </pre> <!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="newtry"> socket.<b>newtry(</b>finalizer<b>)</b> </p> <p class="description"> Creates and returns a <em>clean</em> <a href="#try"><tt>try</tt></a> function that allows for cleanup before the exception is raised. </p> <p class="parameters"> <tt>Finalizer</tt> is a function that will be called before <tt>try</tt> throws the exception. </p> <p class="return"> The function returns your customized <tt>try</tt> function. </p> <p class="note"> Note: This idea saved a <em>lot</em> of work with the implementation of protocols in LuaSocket: </p> <pre class="example"> foo = socket.protect(function() -- connect somewhere local c = socket.try(socket.connect("somewhere", 42)) -- create a try function that closes 'c' on error local try = socket.newtry(function() c:close() end) -- do everything reassured c will be closed try(c:send("hello there?\r\n")) local answer = try(c:receive()) ... try(c:send("good bye\r\n")) c:close() end) </pre> <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="protect"> socket.<b>protect(</b>func<b>)</b> </p> <p class="description"> Converts a function that throws exceptions into a safe function. This function only catches exceptions thrown by the <a href="#try"><tt>try</tt></a> and <a href="#newtry"><tt>newtry</tt></a> functions. It does not catch normal Lua errors. </p> <p class="parameters"> <tt>Func</tt> is a function that calls <a href="#try"><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) to throw exceptions. </p> <p class="return"> Returns an equivalent function that instead of throwing exceptions in case of a failed <a href="#try"><tt>try</tt></a> call, returns <tt><b>nil</b></tt> followed by an error message. </p> <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="select"> socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> </p> <p class="description"> Waits for a number of sockets to change status. </p> <p class="parameters"> <tt>Recvt</tt> is an array with the sockets to test for characters available for reading. Sockets in the <tt>sendt</tt> array are watched to see if it is OK to immediately write on them. <tt>Timeout</tt> is the maximum amount of time (in seconds) to wait for a change in status. A <tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with non-numeric indices) in the arrays will be silently ignored. </p> <p class="return"> The function returns a list with the sockets ready for reading, a list with the sockets ready for writing and an error message. The error message is "<tt>timeout</tt>" if a timeout condition was met, "<tt>select failed</tt>" if the call to <tt>select</tt> failed, and <tt><b>nil</b></tt> otherwise. The returned tables are doubly keyed both by integers and also by the sockets themselves, to simplify the test if a specific socket has changed status. </p> <p class="note"> <b>Note:</b> <tt>select</tt> can monitor a limited number of sockets, as defined by the constant <a href="#setsize"> <tt>socket._SETSIZE</tt></a>. This number may be as high as 1024 or as low as 64 by default, depending on the system. It is usually possible to change this at compile time. Invoking <tt>select</tt> with a larger number of sockets will raise an error. </p> <p class="note"> <b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail on non-blocking TCP sockets. The function may return a socket as writable even though the socket is <em>not</em> ready for sending. </p> <p class="note"> <b>Another important note</b>: calling select with a server socket in the receive parameter before a call to accept does <em>not</em> guarantee <a href="tcp.html#accept"><tt>accept</tt></a> will return immediately. Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a> method or <tt>accept</tt> might block forever. </p> <p class="note"> <b>Yet another note</b>: If you close a socket and pass it to <tt>select</tt>, it will be ignored. </p> <p class="note"> <b>Using select with non-socket objects</b>: Any object that implements <tt>getfd</tt> and <tt>dirty</tt> can be used with <tt>select</tt>, allowing objects from other libraries to be used within a <tt>socket.select</tt> driven loop. </p> <!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="setsize"> socket.<b>_SETSIZE</b> </p> <p class="description"> The maximum number of sockets that the <a href="#select"><tt>select</tt></a> function can handle. </p> <!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="sink"> socket.<b>sink(</b>mode, socket<b>)</b> </p> <p class="description"> Creates an <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> sink from a stream socket object. </p> <p class="parameters"> <tt>Mode</tt> defines the behavior of the sink. The following options are available: </p> <ul> <li> <tt>"http-chunked"</tt>: sends data through socket after applying the <em>chunked transfer coding</em>, closing the socket when done;</li> <li> <tt>"close-when-done"</tt>: sends all received data through the socket, closing the socket when done;</li> <li> <tt>"keep-open"</tt>: sends all received data through the socket, leaving it open when done.</li> </ul> <p> <tt>Socket</tt> is the stream socket object used to send the data. </p> <p class="return"> The function returns a sink with the appropriate behavior. </p> <!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="skip"> socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> </p> <p class="description"> Drops a number of arguments and returns the remaining. </p> <p class="parameters"> <tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> are the arguments. </p> <p class="return"> The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. </p> <p class="note"> Note: This function is useful to avoid creation of dummy variables: </p> <pre class="example"> -- get the status code and separator from SMTP server reply local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) </pre> <!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="sleep"> socket.<b>sleep(</b>time<b>)</b> </p> <p class="description"> Freezes the program execution during a given amount of time. </p> <p class="parameters"> <tt>Time</tt> is the number of seconds to sleep for. If <tt>time</tt> is negative, the function returns immediately. </p> <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="source"> socket.<b>source(</b>mode, socket [, length]<b>)</b> </p> <p class="description"> Creates an <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source from a stream socket object. </p> <p class="parameters"> <tt>Mode</tt> defines the behavior of the source. The following options are available: </p> <ul> <li> <tt>"http-chunked"</tt>: receives data from socket and removes the <em>chunked transfer coding</em> before returning the data;</li> <li> <tt>"by-length"</tt>: receives a fixed number of bytes from the socket. This mode requires the extra argument <tt>length</tt>;</li> <li> <tt>"until-closed"</tt>: receives data from a socket until the other side closes the connection.</li> </ul> <p> <tt>Socket</tt> is the stream socket object used to receive the data. </p> <p class="return"> The function returns a source with the appropriate behavior. </p> <!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="socketinvalid"> socket.<b>_SOCKETINVALID</b> </p> <p class="description"> The OS value for an invalid socket. This can be used with <a href="tcp.html#getfd"> <tt>tcp:getfd</tt></a> and <a href="tcp.html#setfd"><tt>tcp:setfd</tt></a> methods. </p> <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="try"> socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> </p> <p class="description"> Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using <tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught by a <a href="#protect"><tt>protect</tt></a>ed function only. </p> <p class="parameters"> <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary arguments, but are usually the return values of a function call nested with <tt>try</tt>. </p> <p class="return"> The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if <tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>. Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to distinguish exceptions from runtime errors. </p> <pre class="example"> -- connects or throws an exception with the appropriate error message c = socket.try(socket.connect("localhost", 80)) </pre> <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <p class="name" id="version"> socket.<b>_VERSION</b> </p> <p class="description"> This constant has a string describing the current LuaSocket version. </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:54 EDT 2006 </small> </p> </center> </div> </body> </html>