aboutsummaryrefslogtreecommitdiff
path: root/doc/socket.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/socket.html')
-rw-r--r--doc/socket.html456
1 files changed, 0 insertions, 456 deletions
diff --git a/doc/socket.html b/doc/socket.html
deleted file mode 100644
index e6a9bf8..0000000
--- a/doc/socket.html
+++ /dev/null
@@ -1,456 +0,0 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4
5<head>
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">
10</head>
11
12<body>
13
14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15
16<div class=header>
17<hr>
18<center>
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">
22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language
24</td></tr>
25</table>
26<p class=bar>
27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a>
32</p>
33</center>
34<hr>
35</div>
36
37<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id=socket>The socket namespace</h2>
40
41<p>
42The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
43</p>
44
45<p>
46To obtain the <tt>socket</tt> namespace, run:
47</p>
48
49<pre class=example>
50-- loads the socket module
51local socket = require("socket")
52</pre>
53
54<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
55
56<p class=name id=bind>
57socket.<b>bind(</b>address, port [, backlog]<b>)</b>
58</p>
59
60<p class=description>
61This function is a shortcut that creates and returns a TCP server object
62bound to a local <tt>address</tt> and <tt>port</tt>, ready to
63accept client connections. Optionally,
64user can also specify the <tt>backlog</tt> argument to the
65<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32).
66</p>
67
68<p class=note>
69Note: The server object returned will have the option "<tt>reuseaddr</tt>"
70set to <tt><b>true</b></tt>.
71</p>
72
73<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
74
75<p class=name id=connect>
76socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b>
77</p>
78
79<p class=description>
80This function is a shortcut that creates and returns a TCP client object
81connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally,
82the user can also specify the local address and port to bind
83(<tt>locaddr</tt> and <tt>locport</tt>), or restrict the socket family
84to "<tt>inet</tt>" or "<tt>inet6</tt>".
85Without specifying <tt>family</tt> to <tt>connect</tt>, whether a tcp or tcp6
86connection is created depends on your system configuration. Two variations
87of connect are defined as simple helper functions that restrict the
88<tt>family</tt>, <tt>socket.connect4</tt> and <tt>socket.connect6</tt>.
89</p>
90
91<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
92
93<p class=name id=debug>
94socket.<b>_DEBUG</b>
95</p>
96
97<p class=description>
98This constant is set to <tt><b>true</b></tt> if the library was compiled
99with debug support.
100</p>
101
102<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
103
104<p class=name id=gettime>
105socket.<b>gettime()</b>
106</p>
107
108<p class=description>
109Returns the UNIX time in seconds. You should subtract the values returned by this function
110to get meaningful values.
111</p>
112
113<pre class=example>
114t = socket.gettime()
115-- do stuff
116print(socket.gettime() - t .. " seconds elapsed")
117</pre>
118
119<!-- socket.headers ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
120
121<p class=name id="headers.canonic">
122socket.headers.<b>canonic</b></p>
123
124<p> The <tt>socket.headers.canonic</tt> table
125is used by the HTTP and SMTP modules to translate from
126lowercase field names back into their canonic
127capitalization. When a lowercase field name exists as a key
128in this table, the associated value is substituted in
129whenever the field name is sent out.
130</p>
131
132<p>
133You can obtain the <tt>headers</tt> namespace if case run-time
134modifications are required by running:
135</p>
136
137<pre class=example>
138-- loads the headers module
139local headers = require("headers")
140</pre>
141
142<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
143
144<p class=name id=newtry>
145socket.<b>newtry(</b>finalizer<b>)</b>
146</p>
147
148<p class=description>
149Creates and returns a <em>clean</em>
150<a href="#try"><tt>try</tt></a>
151function that allows for cleanup before the exception
152is raised.
153</p>
154
155<p class=parameters>
156<tt>Finalizer</tt> is a function that will be called before
157<tt>try</tt> throws the exception. It will be called
158in <em>protected</em> mode.
159</p>
160
161<p class=return>
162The function returns your customized <tt>try</tt> function.
163</p>
164
165<p class=note>
166Note: This idea saved a <em>lot</em> of work with the
167implementation of protocols in LuaSocket:
168</p>
169
170<pre class=example>
171foo = socket.protect(function()
172 -- connect somewhere
173 local c = socket.try(socket.connect("somewhere", 42))
174 -- create a try function that closes 'c' on error
175 local try = socket.newtry(function() c:close() end)
176 -- do everything reassured c will be closed
177 try(c:send("hello there?\r\n"))
178 local answer = try(c:receive())
179 ...
180 try(c:send("good bye\r\n"))
181 c:close()
182end)
183</pre>
184
185
186<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
187
188<p class=name id=protect>
189socket.<b>protect(</b>func<b>)</b>
190</p>
191
192<p class=description>
193Converts a function that throws exceptions into a safe function. This
194function only catches exceptions thrown by the <a href=#try><tt>try</tt></a>
195and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal
196Lua errors.
197</p>
198
199<p class=parameters>
200<tt>Func</tt> is a function that calls
201<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
202to throw exceptions.
203</p>
204
205<p class=return>
206Returns an equivalent function that instead of throwing exceptions,
207returns <tt><b>nil</b></tt> followed by an error message.
208</p>
209
210<p class=note>
211Note: Beware that if your function performs some illegal operation that
212raises an error, the protected function will catch the error and return it
213as a string. This is because the <a href=#try><tt>try</tt></a> function
214uses errors as the mechanism to throw exceptions.
215</p>
216
217<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
218
219<p class=name id=select>
220socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
221</p>
222
223<p class=description>
224Waits for a number of sockets to change status.
225</p>
226
227<p class=parameters>
228<tt>Recvt</tt> is an array with the sockets to test for characters
229available for reading. Sockets in the <tt>sendt</tt> array are watched to
230see if it is OK to immediately write on them. <tt>Timeout</tt> is the
231maximum amount of time (in seconds) to wait for a change in status. A
232<tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
233function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
234be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
235non-numeric indices) in the arrays will be silently ignored.
236</p>
237
238<p class=return> The function returns a list with the sockets ready for
239reading, a list with the sockets ready for writing and an error message.
240The error message is "<tt>timeout</tt>" if a timeout condition was met and
241<tt><b>nil</b></tt> otherwise. The returned tables are
242doubly keyed both by integers and also by the sockets
243themselves, to simplify the test if a specific socket has
244changed status.
245</p>
246
247<p class=note>
248<b>Note: </b>: <tt>select</tt> can monitor a limited number
249of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This
250number may be as high as 1024 or as low as 64 by default,
251depending on the system. It is usually possible to change this
252at compile time. Invoking <tt>select</tt> with a larger
253number of sockets will raise an error.
254</p>
255
256<p class=note>
257<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
258on non-blocking TCP sockets. The function may return a socket as
259writable even though the socket is <em>not</em> ready for sending.
260</p>
261
262<p class=note>
263<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
264<a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
265Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
266method or <tt>accept</tt> might block forever.
267</p>
268
269<p class=note>
270<b>Yet another note</b>: If you close a socket and pass
271it to <tt>select</tt>, it will be ignored.
272</p>
273
274<p class=note>
275<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.
276</p>
277
278<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
279
280<p class=name id=sink>
281socket.<b>sink(</b>mode, socket<b>)</b>
282</p>
283
284<p class=description>
285Creates an
286<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
287sink from a stream socket object.
288</p>
289
290<p class=parameters>
291<tt>Mode</tt> defines the behavior of the sink. The following
292options are available:
293</p>
294<ul>
295<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
296<em>chunked transfer coding</em>, closing the socket when done;
297<li> <tt>"close-when-done"</tt>: sends all received data through the
298socket, closing the socket when done;
299<li> <tt>"keep-open"</tt>: sends all received data through the
300socket, leaving it open when done.
301</ul>
302<p>
303<tt>Socket</tt> is the stream socket object used to send the data.
304</p>
305
306<p class=return>
307The function returns a sink with the appropriate behavior.
308</p>
309
310<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
311
312<p class=name id=skip>
313socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
314</p>
315
316<p class=description>
317Drops a number of arguments and returns the remaining.
318</p>
319
320<p class=parameters>
321<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
322<tt>ret<sub>N</sub></tt> are the arguments.
323</p>
324
325<p class=return>
326The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
327</p>
328
329<p class=note>
330Note: This function is useful to avoid creation of dummy variables:
331</p>
332
333<pre class=example>
334-- get the status code and separator from SMTP server reply
335local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
336</pre>
337
338<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339
340<p class=name id=sleep>
341socket.<b>sleep(</b>time<b>)</b>
342</p>
343
344<p class=description>
345Freezes the program execution during a given amount of time.
346</p>
347
348<p class=parameters>
349<tt>Time</tt> is the number of seconds to sleep for. If
350<tt>time</tt> is negative, the function returns immediately.
351</p>
352
353<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
354
355<p class=name id=source>
356socket.<b>source(</b>mode, socket [, length]<b>)</b>
357</p>
358
359<p class=description>
360Creates an
361<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
362source from a stream socket object.
363</p>
364
365<p class=parameters>
366<tt>Mode</tt> defines the behavior of the source. The following
367options are available:
368</p>
369<ul>
370<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
371<em>chunked transfer coding</em> before returning the data;
372<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
373socket. This mode requires the extra argument <tt>length</tt>;
374<li> <tt>"until-closed"</tt>: receives data from a socket until the other
375side closes the connection.
376</ul>
377<p>
378<tt>Socket</tt> is the stream socket object used to receive the data.
379</p>
380
381<p class=return>
382The function returns a source with the appropriate behavior.
383</p>
384
385<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
386
387<p class=name id=setsize>
388socket.<b>_SETSIZE</b>
389</p>
390
391<p class=description>
392The maximum number of sockets that the <a
393href=#select><tt>select</tt></a> function can handle.
394</p>
395
396<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
397
398<p class=name id=try>
399socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
400</p>
401
402<p class=description>
403Throws an exception in case of error. The exception can only be caught
404by the <a href=#protect><tt>protect</tt></a> function. It does not explode
405into an error message.
406</p>
407
408<p class=parameters>
409<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
410arguments, but are usually the return values of a function call
411nested with <tt>try</tt>.
412</p>
413
414<p class=return>
415The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
416<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>.
417</p>
418
419<pre class=example>
420-- connects or throws an exception with the appropriate error message
421c = socket.try(socket.connect("localhost", 80))
422</pre>
423
424<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
425
426<p class=name id=version>
427socket.<b>_VERSION</b>
428</p>
429
430<p class=description>
431This constant has a string describing the current LuaSocket version.
432</p>
433
434<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
435
436<div class=footer>
437<hr>
438<center>
439<p class=bar>
440<a href="index.html">home</a> &middot;
441<a href="index.html#down">download</a> &middot;
442<a href="installation.html">installation</a> &middot;
443<a href="introduction.html">introduction</a> &middot;
444<a href="reference.html">reference</a>
445</p>
446<p>
447<small>
448Last modified by Diego Nehab on <br>
449Thu Apr 20 00:25:54 EDT 2006
450</small>
451</p>
452</center>
453</div>
454
455</body>
456</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-04 22:39:14 +0000