aboutsummaryrefslogtreecommitdiff
path: root/docs/socket.html
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/socket.html (renamed from doc/socket.html)337
1 files changed, 181 insertions, 156 deletions
diff --git a/doc/socket.html b/docs/socket.html
index e6a9bf8..c148114 100644
--- a/doc/socket.html
+++ b/docs/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,47 +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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
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
54<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 78<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
55 79
56<p class=name id=bind> 80<p class="name" id="bind">
57socket.<b>bind(</b>address, port [, backlog]<b>)</b> 81socket.<b>bind(</b>address, port [, backlog]<b>)</b>
58</p> 82</p>
59 83
60<p class=description> 84<p class="description">
61This 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
62bound 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
63accept client connections. Optionally, 87accept client connections. Optionally,
64user can also specify the <tt>backlog</tt> argument to the 88user can also specify the <tt>backlog</tt> argument to the
65<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).
66</p> 90</p>
67 91
68<p class=note> 92<p class="note">
69Note: The server object returned will have the option "<tt>reuseaddr</tt>" 93Note: The server object returned will have the option "<tt>reuseaddr</tt>"
70set to <tt><b>true</b></tt>. 94set to <tt><b>true</b></tt>.
71</p> 95</p>
72 96
73<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 97<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
74 98
75<p class=name id=connect> 99<p class="name" id="connect">
76socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> 100socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b>
77</p> 101</p>
78 102
79<p class=description> 103<p class="description">
80This 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
81connected 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,
82the user can also specify the local address and port to bind 106the user can also specify the local address and port to bind
@@ -90,90 +114,79 @@ of connect are defined as simple helper functions that restrict the
90 114
91<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 115<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
92 116
93<p class=name id=debug> 117<p class="name" id="debug">
94socket.<b>_DEBUG</b> 118socket.<b>_DEBUG</b>
95</p> 119</p>
96 120
97<p class=description> 121<p class="description">
98This 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
99with debug support. 123with debug support.
100</p> 124</p>
101 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
102<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 139<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
103 140
104<p class=name id=gettime> 141<p class="name" id="gettime">
105socket.<b>gettime()</b> 142socket.<b>gettime()</b>
106</p> 143</p>
107 144
108<p class=description> 145<p class="description">
109Returns 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
110to get meaningful values. 147to get meaningful values.
111</p> 148</p>
112 149
113<pre class=example> 150<pre class="example">
114t = socket.gettime() 151t = socket.gettime()
115-- do stuff 152-- do stuff
116print(socket.gettime() - t .. " seconds elapsed") 153print(socket.gettime() - t .. " seconds elapsed")
117</pre> 154</pre>
118 155
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 156<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
143 157
144<p class=name id=newtry> 158<p class="name" id="newtry">
145socket.<b>newtry(</b>finalizer<b>)</b> 159socket.<b>newtry(</b>finalizer<b>)</b>
146</p> 160</p>
147 161
148<p class=description> 162<p class="description">
149Creates and returns a <em>clean</em> 163Creates and returns a <em>clean</em>
150<a href="#try"><tt>try</tt></a> 164<a href="#try"><tt>try</tt></a>
151function that allows for cleanup before the exception 165function that allows for cleanup before the exception
152is raised. 166is raised.
153</p> 167</p>
154 168
155<p class=parameters> 169<p class="parameters">
156<tt>Finalizer</tt> is a function that will be called before 170<tt>Finalizer</tt> is a function that will be called before
157<tt>try</tt> throws the exception. It will be called 171<tt>try</tt> throws the exception.
158in <em>protected</em> mode.
159</p> 172</p>
160 173
161<p class=return> 174<p class="return">
162The function returns your customized <tt>try</tt> function. 175The function returns your customized <tt>try</tt> function.
163</p> 176</p>
164 177
165<p class=note> 178<p class="note">
166Note: This idea saved a <em>lot</em> of work with the 179Note: This idea saved a <em>lot</em> of work with the
167implementation of protocols in LuaSocket: 180implementation of protocols in LuaSocket:
168</p> 181</p>
169 182
170<pre class=example> 183<pre class="example">
171foo = socket.protect(function() 184foo = socket.protect(function()
172 -- connect somewhere 185 -- connect somewhere
173 local c = socket.try(socket.connect("somewhere", 42)) 186 local c = socket.try(socket.connect("somewhere", 42))
174 -- create a try function that closes 'c' on error 187 -- create a try function that closes 'c' on error
175 local try = socket.newtry(function() c:close() end) 188 local try = socket.newtry(function() c:close() end)
176 -- do everything reassured c will be closed 189 -- do everything reassured c will be closed
177 try(c:send("hello there?\r\n")) 190 try(c:send("hello there?\r\n"))
178 local answer = try(c:receive()) 191 local answer = try(c:receive())
179 ... 192 ...
@@ -185,46 +198,40 @@ end)
185 198
186<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 199<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
187 200
188<p class=name id=protect> 201<p class="name" id="protect">
189socket.<b>protect(</b>func<b>)</b> 202socket.<b>protect(</b>func<b>)</b>
190</p> 203</p>
191 204
192<p class=description> 205<p class="description">
193Converts a function that throws exceptions into a safe function. This 206Converts a function that throws exceptions into a safe function. This
194function 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>
195and <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
196Lua errors. 209Lua errors.
197</p> 210</p>
198 211
199<p class=parameters> 212<p class="parameters">
200<tt>Func</tt> is a function that calls 213<tt>Func</tt> is a function that calls
201<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>)
202to throw exceptions. 215to 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> 216</p>
209 217
210<p class=note> 218<p class="return">
211Note: Beware that if your function performs some illegal operation that 219Returns an equivalent function that instead of throwing exceptions in case of
212raises an error, the protected function will catch the error and return it 220a failed <a href="#try"><tt>try</tt></a> call, returns <tt><b>nil</b></tt>
213as a string. This is because the <a href=#try><tt>try</tt></a> function 221followed by an error message.
214uses errors as the mechanism to throw exceptions.
215</p> 222</p>
216 223
217<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 224<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
218 225
219<p class=name id=select> 226<p class="name" id="select">
220socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> 227socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
221</p> 228</p>
222 229
223<p class=description> 230<p class="description">
224Waits for a number of sockets to change status. 231Waits for a number of sockets to change status.
225</p> 232</p>
226 233
227<p class=parameters> 234<p class="parameters">
228<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
229available 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
230see 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
@@ -235,208 +242,226 @@ be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
235non-numeric indices) in the arrays will be silently ignored. 242non-numeric indices) in the arrays will be silently ignored.
236</p> 243</p>
237 244
238<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
239reading, 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.
240The error message is "<tt>timeout</tt>" if a timeout condition was met and 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
241<tt><b>nil</b></tt> otherwise. The returned tables are 250<tt><b>nil</b></tt> otherwise. The returned tables are
242doubly keyed both by integers and also by the sockets 251doubly keyed both by integers and also by the sockets
243themselves, to simplify the test if a specific socket has 252themselves, to simplify the test if a specific socket has
244changed status. 253changed status.
245</p> 254</p>
246 255
247<p class=note> 256<p class="note">
248<b>Note: </b>: <tt>select</tt> can monitor a limited number 257<b>Note:</b> <tt>select</tt> can monitor a limited number
249of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This 258of sockets, as defined by the constant <a href="#setsize">
259<tt>socket._SETSIZE</tt></a>. This
250number may be as high as 1024 or as low as 64 by default, 260number may be as high as 1024 or as low as 64 by default,
251depending on the system. It is usually possible to change this 261depending on the system. It is usually possible to change this
252at compile time. Invoking <tt>select</tt> with a larger 262at compile time. Invoking <tt>select</tt> with a larger
253number of sockets will raise an error. 263number of sockets will raise an error.
254</p> 264</p>
255 265
256<p class=note> 266<p class="note">
257<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail 267<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 268on non-blocking TCP sockets. The function may return a socket as
259writable even though the socket is <em>not</em> ready for sending. 269writable even though the socket is <em>not</em> ready for sending.
260</p> 270</p>
261 271
262<p class=note> 272<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 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
264<a href=tcp.html#accept><tt>accept</tt></a> will return immediately. 274<a href="tcp.html#accept"><tt>accept</tt></a> will return immediately.
265Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a> 275Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a>
266method or <tt>accept</tt> might block forever. 276method or <tt>accept</tt> might block forever.
267</p> 277</p>
268 278
269<p class=note> 279<p class="note">
270<b>Yet another note</b>: If you close a socket and pass 280<b>Yet another note</b>: If you close a socket and pass
271it to <tt>select</tt>, it will be ignored. 281it to <tt>select</tt>, it will be ignored.
272</p> 282</p>
273 283
274<p class=note> 284<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. 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.
276</p> 286</p>
277 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
278<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 300<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
279 301
280<p class=name id=sink> 302<p class="name" id="sink">
281socket.<b>sink(</b>mode, socket<b>)</b> 303socket.<b>sink(</b>mode, socket<b>)</b>
282</p> 304</p>
283 305
284<p class=description> 306<p class="description">
285Creates an 307Creates an
286<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 308<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
287sink from a stream socket object. 309sink from a stream socket object.
288</p> 310</p>
289 311
290<p class=parameters> 312<p class="parameters">
291<tt>Mode</tt> defines the behavior of the sink. The following 313<tt>Mode</tt> defines the behavior of the sink. The following
292options are available: 314options are available:
293</p> 315</p>
294<ul> 316<ul>
295<li> <tt>"http-chunked"</tt>: sends data through socket after applying the 317<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
296<em>chunked transfer coding</em>, closing the socket when done; 318<em>chunked transfer coding</em>, closing the socket when done;</li>
297<li> <tt>"close-when-done"</tt>: sends all received data through the 319<li> <tt>"close-when-done"</tt>: sends all received data through the
298socket, closing the socket when done; 320socket, closing the socket when done;</li>
299<li> <tt>"keep-open"</tt>: sends all received data through the 321<li> <tt>"keep-open"</tt>: sends all received data through the
300socket, leaving it open when done. 322socket, leaving it open when done.</li>
301</ul> 323</ul>
302<p> 324<p>
303<tt>Socket</tt> is the stream socket object used to send the data. 325<tt>Socket</tt> is the stream socket object used to send the data.
304</p> 326</p>
305 327
306<p class=return> 328<p class="return">
307The function returns a sink with the appropriate behavior. 329The function returns a sink with the appropriate behavior.
308</p> 330</p>
309 331
310<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 332<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
311 333
312<p class=name id=skip> 334<p class="name" id="skip">
313socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> 335socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
314</p> 336</p>
315 337
316<p class=description> 338<p class="description">
317Drops a number of arguments and returns the remaining. 339Drops a number of arguments and returns the remaining.
318</p> 340</p>
319 341
320<p class=parameters> 342<p class="parameters">
321<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to 343<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. 344<tt>ret<sub>N</sub></tt> are the arguments.
323</p> 345</p>
324 346
325<p class=return> 347<p class="return">
326The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. 348The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
327</p> 349</p>
328 350
329<p class=note> 351<p class="note">
330Note: This function is useful to avoid creation of dummy variables: 352Note: This function is useful to avoid creation of dummy variables:
331</p> 353</p>
332 354
333<pre class=example> 355<pre class="example">
334-- get the status code and separator from SMTP server reply 356-- get the status code and separator from SMTP server reply
335local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) 357local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
336</pre> 358</pre>
337 359
338<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 360<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339 361
340<p class=name id=sleep> 362<p class="name" id="sleep">
341socket.<b>sleep(</b>time<b>)</b> 363socket.<b>sleep(</b>time<b>)</b>
342</p> 364</p>
343 365
344<p class=description> 366<p class="description">
345Freezes the program execution during a given amount of time. 367Freezes the program execution during a given amount of time.
346</p> 368</p>
347 369
348<p class=parameters> 370<p class="parameters">
349<tt>Time</tt> is the number of seconds to sleep for. If 371<tt>Time</tt> is the number of seconds to sleep for. If
350<tt>time</tt> is negative, the function returns immediately. 372<tt>time</tt> is negative, the function returns immediately.
351</p> 373</p>
352 374
353<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 375<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
354 376
355<p class=name id=source> 377<p class="name" id="source">
356socket.<b>source(</b>mode, socket [, length]<b>)</b> 378socket.<b>source(</b>mode, socket [, length]<b>)</b>
357</p> 379</p>
358 380
359<p class=description> 381<p class="description">
360Creates an 382Creates an
361<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 383<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
362source from a stream socket object. 384source from a stream socket object.
363</p> 385</p>
364 386
365<p class=parameters> 387<p class="parameters">
366<tt>Mode</tt> defines the behavior of the source. The following 388<tt>Mode</tt> defines the behavior of the source. The following
367options are available: 389options are available:
368</p> 390</p>
369<ul> 391<ul>
370<li> <tt>"http-chunked"</tt>: receives data from socket and removes the 392<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
371<em>chunked transfer coding</em> before returning the data; 393<em>chunked transfer coding</em> before returning the data;</li>
372<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the 394<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
373socket. This mode requires the extra argument <tt>length</tt>; 395socket. This mode requires the extra argument <tt>length</tt>;</li>
374<li> <tt>"until-closed"</tt>: receives data from a socket until the other 396<li> <tt>"until-closed"</tt>: receives data from a socket until the other
375side closes the connection. 397side closes the connection.</li>
376</ul> 398</ul>
377<p> 399<p>
378<tt>Socket</tt> is the stream socket object used to receive the data. 400<tt>Socket</tt> is the stream socket object used to receive the data.
379</p> 401</p>
380 402
381<p class=return> 403<p class="return">
382The function returns a source with the appropriate behavior. 404The function returns a source with the appropriate behavior.
383</p> 405</p>
384 406
385<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 407<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
386 408
387<p class=name id=setsize> 409<p class="name" id="socketinvalid">
388socket.<b>_SETSIZE</b> 410socket.<b>_SOCKETINVALID</b>
389</p> 411</p>
390 412
391<p class=description> 413<p class="description">
392The maximum number of sockets that the <a 414The OS value for an invalid socket. This can be used with <a href="tcp.html#getfd">
393href=#select><tt>select</tt></a> function can handle. 415<tt>tcp:getfd</tt></a> and <a href="tcp.html#setfd"><tt>tcp:setfd</tt></a> methods.
394</p> 416</p>
395 417
396<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 418<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
397 419
398<p class=name id=try> 420<p class="name" id="try">
399socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> 421socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
400</p> 422</p>
401 423
402<p class=description> 424<p class="description">
403Throws an exception in case of error. The exception can only be caught 425Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using
404by the <a href=#protect><tt>protect</tt></a> function. It does not explode 426<tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught
405into an error message. 427by a <a href="#protect"><tt>protect</tt></a>ed function only.
406</p> 428</p>
407 429
408<p class=parameters> 430<p class="parameters">
409<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary 431<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 432arguments, but are usually the return values of a function call
411nested with <tt>try</tt>. 433nested with <tt>try</tt>.
412</p> 434</p>
413 435
414<p class=return> 436<p class="return">
415The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if 437The 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>. 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.
417</p> 442</p>
418 443
419<pre class=example> 444<pre class="example">
420-- connects or throws an exception with the appropriate error message 445-- connects or throws an exception with the appropriate error message
421c = socket.try(socket.connect("localhost", 80)) 446c = socket.try(socket.connect("localhost", 80))
422</pre> 447</pre>
423 448
424<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 449<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
425 450
426<p class=name id=version> 451<p class="name" id="version">
427socket.<b>_VERSION</b> 452socket.<b>_VERSION</b>
428</p> 453</p>
429 454
430<p class=description> 455<p class="description">
431This constant has a string describing the current LuaSocket version. 456This constant has a string describing the current LuaSocket version.
432</p> 457</p>
433 458
434<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 459<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
435 460
436<div class=footer> 461<div class="footer">
437<hr> 462<hr>
438<center> 463<center>
439<p class=bar> 464<p class="bar">
440<a href="index.html">home</a> &middot; 465<a href="index.html">home</a> &middot;
441<a href="index.html#down">download</a> &middot; 466<a href="index.html#down">download</a> &middot;
442<a href="installation.html">installation</a> &middot; 467<a href="installation.html">installation</a> &middot;
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-21 03:51:37 +0000