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