aboutsummaryrefslogtreecommitdiff
path: root/docs/socket.html
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
committerCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
commit5c4fc93d5f4137bf4c22ddf1a048c907a4a26727 (patch)
treea9a68e1f6a9c3bfe2b64fa1c3a4098865b7d3b5d /docs/socket.html
parentccef3bc4e2aa6ee5b997a80aabb58f4ff0b0e98f (diff)
parent43a97b7f0053313b43906371dbdc226271e6c8ab (diff)
downloadluasocket-hjelmeland-patch-1.tar.gz
luasocket-hjelmeland-patch-1.tar.bz2
luasocket-hjelmeland-patch-1.zip
Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1
Diffstat (limited to 'docs/socket.html')
-rw-r--r--docs/socket.html481
1 files changed, 481 insertions, 0 deletions
diff --git a/docs/socket.html b/docs/socket.html
new file mode 100644
index 0000000..c148114
--- /dev/null
+++ b/docs/socket.html
@@ -0,0 +1,481 @@
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="https://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="datagramsize">
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 <a href="#setsize">
259<tt>socket._SETSIZE</tt></a>. This
260number may be as high as 1024 or as low as 64 by default,
261depending on the system. It is usually possible to change this
262at compile time. Invoking <tt>select</tt> with a larger
263number of sockets will raise an error.
264</p>
265
266<p class="note">
267<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
268on non-blocking TCP sockets. The function may return a socket as
269writable even though the socket is <em>not</em> ready for sending.
270</p>
271
272<p class="note">
273<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
274<a href="tcp.html#accept"><tt>accept</tt></a> will return immediately.
275Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a>
276method or <tt>accept</tt> might block forever.
277</p>
278
279<p class="note">
280<b>Yet another note</b>: If you close a socket and pass
281it to <tt>select</tt>, it will be ignored.
282</p>
283
284<p class="note">
285<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.
286</p>
287
288<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
289
290<p class="name" id="setsize">
291socket.<b>_SETSIZE</b>
292</p>
293
294<p class="description">
295The maximum number of sockets that the <a
296href="#select"><tt>select</tt></a> function can handle.
297</p>
298
299
300<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
301
302<p class="name" id="sink">
303socket.<b>sink(</b>mode, socket<b>)</b>
304</p>
305
306<p class="description">
307Creates an
308<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
309sink from a stream socket object.
310</p>
311
312<p class="parameters">
313<tt>Mode</tt> defines the behavior of the sink. The following
314options are available:
315</p>
316<ul>
317<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
318<em>chunked transfer coding</em>, closing the socket when done;</li>
319<li> <tt>"close-when-done"</tt>: sends all received data through the
320socket, closing the socket when done;</li>
321<li> <tt>"keep-open"</tt>: sends all received data through the
322socket, leaving it open when done.</li>
323</ul>
324<p>
325<tt>Socket</tt> is the stream socket object used to send the data.
326</p>
327
328<p class="return">
329The function returns a sink with the appropriate behavior.
330</p>
331
332<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
333
334<p class="name" id="skip">
335socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
336</p>
337
338<p class="description">
339Drops a number of arguments and returns the remaining.
340</p>
341
342<p class="parameters">
343<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
344<tt>ret<sub>N</sub></tt> are the arguments.
345</p>
346
347<p class="return">
348The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
349</p>
350
351<p class="note">
352Note: This function is useful to avoid creation of dummy variables:
353</p>
354
355<pre class="example">
356-- get the status code and separator from SMTP server reply
357local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
358</pre>
359
360<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
361
362<p class="name" id="sleep">
363socket.<b>sleep(</b>time<b>)</b>
364</p>
365
366<p class="description">
367Freezes the program execution during a given amount of time.
368</p>
369
370<p class="parameters">
371<tt>Time</tt> is the number of seconds to sleep for. If
372<tt>time</tt> is negative, the function returns immediately.
373</p>
374
375<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
376
377<p class="name" id="source">
378socket.<b>source(</b>mode, socket [, length]<b>)</b>
379</p>
380
381<p class="description">
382Creates an
383<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
384source from a stream socket object.
385</p>
386
387<p class="parameters">
388<tt>Mode</tt> defines the behavior of the source. The following
389options are available:
390</p>
391<ul>
392<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
393<em>chunked transfer coding</em> before returning the data;</li>
394<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
395socket. This mode requires the extra argument <tt>length</tt>;</li>
396<li> <tt>"until-closed"</tt>: receives data from a socket until the other
397side closes the connection.</li>
398</ul>
399<p>
400<tt>Socket</tt> is the stream socket object used to receive the data.
401</p>
402
403<p class="return">
404The function returns a source with the appropriate behavior.
405</p>
406
407<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
408
409<p class="name" id="socketinvalid">
410socket.<b>_SOCKETINVALID</b>
411</p>
412
413<p class="description">
414The OS value for an invalid socket. This can be used with <a href="tcp.html#getfd">
415<tt>tcp:getfd</tt></a> and <a href="tcp.html#setfd"><tt>tcp:setfd</tt></a> methods.
416</p>
417
418<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
419
420<p class="name" id="try">
421socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
422</p>
423
424<p class="description">
425Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using
426<tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught
427by a <a href="#protect"><tt>protect</tt></a>ed function only.
428</p>
429
430<p class="parameters">
431<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
432arguments, but are usually the return values of a function call
433nested with <tt>try</tt>.
434</p>
435
436<p class="return">
437The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
438<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>.
439Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped
440in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to
441distinguish exceptions from runtime errors.
442</p>
443
444<pre class="example">
445-- connects or throws an exception with the appropriate error message
446c = socket.try(socket.connect("localhost", 80))
447</pre>
448
449<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
450
451<p class="name" id="version">
452socket.<b>_VERSION</b>
453</p>
454
455<p class="description">
456This constant has a string describing the current LuaSocket version.
457</p>
458
459<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
460
461<div class="footer">
462<hr>
463<center>
464<p class="bar">
465<a href="index.html">home</a> &middot;
466<a href="index.html#down">download</a> &middot;
467<a href="installation.html">installation</a> &middot;
468<a href="introduction.html">introduction</a> &middot;
469<a href="reference.html">reference</a>
470</p>
471<p>
472<small>
473Last modified by Diego Nehab on <br>
474Thu Apr 20 00:25:54 EDT 2006
475</small>
476</p>
477</center>
478</div>
479
480</body>
481</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-31 04:55:58 +0000