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