txlyre
/
winamp
mirror of https://git.lumaeris.com/mirrors/winamp


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479
							<!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="index.html">home</a> &middot;
<a href="index.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>

<!-- 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=debug>
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 <tt>socket._SETSIZE</tt>. 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> <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. 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> <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>

<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<p class=name id=socketinvalid>
socket.<b>_SOCKETINVALID</b>
</p>

<p class=description>
The OS value for an invalid socket.
</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> &middot;
<a href="index.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>