| <!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="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> |
| |
| <!-- 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> |
| |
| <!-- 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(</b>address, port [, locaddr, locport]<b>)</b> |
| </p> |
| |
| <p class=description> |
| This function is a shortcut that creates and returns a TCP client object |
| connected to a remote <tt>host</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>). |
| </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> |
| |
| <!-- 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. It will be called |
| in <em>protected</em> mode. |
| </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, |
| returns <tt><b>nil</b></tt> followed by an error message. |
| </p> |
| |
| <p class=note> |
| Note: Beware that if your function performs some illegal operation that |
| raises an error, the protected function will catch the error and return it |
| as a string. This is because the <a href=#try><tt>try</tt></a> function |
| uses errors as the mechanism to throw exceptions. |
| </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 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>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> |
| |
| <!-- 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> <tt>"close-when-done"</tt>: sends all received data through the |
| socket, closing the socket when done; |
| <li> <tt>"keep-open"</tt>: sends all received data through the |
| socket, leaving it open when done. |
| </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. |
| </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> <tt>"by-length"</tt>: receives a fixed number of bytes from the |
| socket. This mode requires the extra argument <tt>length</tt>; |
| <li> <tt>"until-closed"</tt>: receives data from a socket until the other |
| side closes the connection. |
| </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> |
| |
| <!-- time ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class=name id=gettime> |
| socket.<b>gettime()</b> |
| </p> |
| |
| <p class=description> |
| Returns the time in seconds, relative to the origin of the |
| universe. 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> |
| |
| <!-- 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 of error. The exception can only be caught |
| by the <a href=#protect><tt>protect</tt></a> function. It does not explode |
| into an error message. |
| </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>. Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub>. |
| </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="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:54 EDT 2006 |
| </small> |
| </p> |
| </center> |
| </div> |
| |
| </body> |
| </html> |