Mercurial > luasocket

diff doc/socket.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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/socket.html	Tue Aug 26 18:40:01 2008 -0700
@@ -0,0 +1,404 @@
+<!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> &middot;
+<a href="home.html#download">download</a> &middot;
+<a href="installation.html">installation</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<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> &middot;
+<a href="home.html#down">download</a> &middot;
+<a href="installation.html">installation</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<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>