1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2
"http://www.w3.org/TR/html4/strict.dtd">
6
<meta name="description" content="LuaSocket: The core namespace">
7
<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
8
<title>LuaSocket: The socket namespace</title>
9
<link rel="stylesheet" href="reference.css" type="text/css">
14
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
19
<table summary="LuaSocket logo">
20
<tr><td align=center><a href="http://www.lua.org">
21
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23
<tr><td align=center valign=top>Network support for the Lua language
27
<a href="home.html">home</a> ·
28
<a href="home.html#download">download</a> ·
29
<a href="installation.html">installation</a> ·
30
<a href="introduction.html">introduction</a> ·
31
<a href="reference.html">reference</a>
37
<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
<h2 id=socket>The socket namespace</h2>
42
The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
46
To obtain the <tt>socket</tt> namespace, run:
50
-- loads the socket module
51
local socket = require("socket")
54
<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
56
<p class=name id=bind>
57
socket.<b>bind(</b>address, port [, backlog]<b>)</b>
61
This function is a shortcut that creates and returns a TCP server object
62
bound to a local <tt>address</tt> and <tt>port</tt>, ready to
63
accept client connections. Optionally,
64
user can also specify the <tt>backlog</tt> argument to the
65
<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32).
69
Note: The server object returned will have the option "<tt>reuseaddr</tt>"
70
set to <tt><b>true</b></tt>.
73
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
75
<p class=name id=connect>
76
socket.<b>connect(</b>address, port [, locaddr, locport]<b>)</b>
80
This function is a shortcut that creates and returns a TCP client object
81
connected to a remote <tt>host</tt> at a given <tt>port</tt>. Optionally,
82
the user can also specify the local address and port to bind
83
(<tt>locaddr</tt> and <tt>locport</tt>).
86
<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
88
<p class=name id=debug>
93
This constant is set to <tt><b>true</b></tt> if the library was compiled
97
<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
99
<p class=name id=newtry>
100
socket.<b>newtry(</b>finalizer<b>)</b>
103
<p class=description>
104
Creates and returns a <em>clean</em>
105
<a href="#try"><tt>try</tt></a>
106
function that allows for cleanup before the exception
111
<tt>Finalizer</tt> is a function that will be called before
112
<tt>try</tt> throws the exception. It will be called
113
in <em>protected</em> mode.
117
The function returns your customized <tt>try</tt> function.
121
Note: This idea saved a <em>lot</em> of work with the
122
implementation of protocols in LuaSocket:
126
foo = socket.protect(function()
128
local c = socket.try(socket.connect("somewhere", 42))
129
-- create a try function that closes 'c' on error
130
local try = socket.newtry(function() c:close() end)
131
-- do everything reassured c will be closed
132
try(c:send("hello there?\r\n"))
133
local answer = try(c:receive())
135
try(c:send("good bye\r\n"))
141
<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
143
<p class=name id=protect>
144
socket.<b>protect(</b>func<b>)</b>
147
<p class=description>
148
Converts a function that throws exceptions into a safe function. This
149
function only catches exceptions thrown by the <a href=#try><tt>try</tt></a>
150
and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal
155
<tt>Func</tt> is a function that calls
156
<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
161
Returns an equivalent function that instead of throwing exceptions,
162
returns <tt><b>nil</b></tt> followed by an error message.
166
Note: Beware that if your function performs some illegal operation that
167
raises an error, the protected function will catch the error and return it
168
as a string. This is because the <a href=#try><tt>try</tt></a> function
169
uses errors as the mechanism to throw exceptions.
172
<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
174
<p class=name id=select>
175
socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
178
<p class=description>
179
Waits for a number of sockets to change status.
183
<tt>Recvt</tt> is an array with the sockets to test for characters
184
available for reading. Sockets in the <tt>sendt</tt> array are watched to
185
see if it is OK to immediately write on them. <tt>Timeout</tt> is the
186
maximum amount of time (in seconds) to wait for a change in status. A
187
<tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
188
function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
189
be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
190
non-numeric indices) in the arrays will be silently ignored.
193
<p class=return> The function returns a list with the sockets ready for
194
reading, a list with the sockets ready for writing and an error message.
195
The error message is "<tt>timeout</tt>" if a timeout condition was met and
196
<tt><b>nil</b></tt> otherwise. The returned tables are
197
doubly keyed both by integers and also by the sockets
198
themselves, to simplify the test if a specific socket has
203
<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
204
on non-blocking TCP sockets. The function may return a socket as
205
writable even though the socket is <em>not</em> ready for sending.
209
<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
210
<a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
211
Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
212
method or <tt>accept</tt> might block forever.
216
<b>Yet another note</b>: If you close a socket and pass
217
it to <tt>select</tt>, it will be ignored.
220
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
222
<p class=name id=sink>
223
socket.<b>sink(</b>mode, socket<b>)</b>
226
<p class=description>
228
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
229
sink from a stream socket object.
233
<tt>Mode</tt> defines the behavior of the sink. The following
234
options are available:
237
<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
238
<em>chunked transfer coding</em>, closing the socket when done;
239
<li> <tt>"close-when-done"</tt>: sends all received data through the
240
socket, closing the socket when done;
241
<li> <tt>"keep-open"</tt>: sends all received data through the
242
socket, leaving it open when done.
245
<tt>Socket</tt> is the stream socket object used to send the data.
249
The function returns a sink with the appropriate behavior.
252
<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
254
<p class=name id=skip>
255
socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
258
<p class=description>
259
Drops a number of arguments and returns the remaining.
263
<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
264
<tt>ret<sub>N</sub></tt> are the arguments.
268
The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
272
Note: This function is useful to avoid creation of dummy variables:
276
-- get the status code and separator from SMTP server reply
277
local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
280
<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
282
<p class=name id=sleep>
283
socket.<b>sleep(</b>time<b>)</b>
286
<p class=description>
287
Freezes the program execution during a given amount of time.
291
<tt>Time</tt> is the number of seconds to sleep for.
294
<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
296
<p class=name id=source>
297
socket.<b>source(</b>mode, socket [, length]<b>)</b>
300
<p class=description>
302
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
303
source from a stream socket object.
307
<tt>Mode</tt> defines the behavior of the source. The following
308
options are available:
311
<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
312
<em>chunked transfer coding</em> before returning the data;
313
<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
314
socket. This mode requires the extra argument <tt>length</tt>;
315
<li> <tt>"until-closed"</tt>: receives data from a socket until the other
316
side closes the connection.
319
<tt>Socket</tt> is the stream socket object used to receive the data.
323
The function returns a source with the appropriate behavior.
326
<!-- time ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
328
<p class=name id=gettime>
329
socket.<b>gettime()</b>
332
<p class=description>
333
Returns the time in seconds, relative to the origin of the
334
universe. You should subtract the values returned by this function
335
to get meaningful values.
341
print(socket.gettime() - t .. " seconds elapsed")
344
<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
346
<p class=name id=try>
347
socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
350
<p class=description>
351
Throws an exception in case of error. The exception can only be caught
352
by the <a href=#protect><tt>protect</tt></a> function. It does not explode
353
into an error message.
357
<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
358
arguments, but are usually the return values of a function call
359
nested with <tt>try</tt>.
363
The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
364
<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>.
368
-- connects or throws an exception with the appropriate error message
369
c = socket.try(socket.connect("localhost", 80))
372
<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
374
<p class=name id=version>
375
socket.<b>_VERSION</b>
378
<p class=description>
379
This constant has a string describing the current LuaSocket version.
382
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
388
<a href="home.html">home</a> ·
389
<a href="home.html#down">download</a> ·
390
<a href="installation.html">installation</a> ·
391
<a href="introduction.html">introduction</a> ·
392
<a href="reference.html">reference</a>
396
Last modified by Diego Nehab on <br>
397
Thu Apr 20 00:25:54 EDT 2006
added
removed
src/libs/luasocket/doc/socket.html
