aboutsummaryrefslogtreecommitdiff
path: root/doc/tcp.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/tcp.html')
-rw-r--r--doc/tcp.html325
1 files changed, 163 insertions, 162 deletions
diff --git a/doc/tcp.html b/doc/tcp.html
index 6050a5f..2d6e327 100644
--- a/doc/tcp.html
+++ b/doc/tcp.html
@@ -13,17 +13,17 @@
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="http://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;
@@ -40,42 +40,43 @@
40 40
41<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 41<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
42 42
43<p class=name id="accept"> 43<p class="name" id="accept">
44server:<b>accept()</b> 44server:<b>accept()</b>
45</p> 45</p>
46 46
47<p class=description> 47<p class="description">
48Waits for a remote connection on the server 48Waits for a remote connection on the server
49object and returns a client object representing that connection. 49object and returns a client object representing that connection.
50</p> 50</p>
51 51
52<p class=return> 52<p class="return">
53If a connection is successfully initiated, a client object is returned. 53If a connection is successfully initiated, a client object is returned.
54If a timeout condition is met, the method returns <b><tt>nil</tt></b> 54If a timeout condition is met, the method returns <b><tt>nil</tt></b>
55followed by the error string '<tt>timeout</tt>'. Other errors are 55followed by the error string '<tt>timeout</tt>'. Other errors are
56reported by <b><tt>nil</tt></b> followed by a message describing the error. 56reported by <b><tt>nil</tt></b> followed by a message describing the error.
57</p> 57</p>
58 58
59<p class=note> 59<p class="note">
60Note: calling <a href=socket.html#select><tt>socket.select</tt></a> 60Note: calling <a href="socket.html#select"><tt>socket.select</tt></a>
61with a server object in 61with a server object in
62the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does 62the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does
63<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a 63<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
64href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt> 64href="#settimeout"><tt>settimeout</tt></a> method or <tt>accept</tt>
65might block until <em>another</em> client shows up. 65might block until <em>another</em> client shows up.
66</p> 66</p>
67 67
68<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 68<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
69 69
70<p class=name id="bind"> 70<p class="name" id="bind">
71master:<b>bind(</b>address, port<b>)</b> 71master:<b>bind(</b>address, port<b>)</b>
72</p> 72</p>
73 73
74<p class=description> 74<p class="description">
75Binds a master object to <tt>address</tt> and <tt>port</tt> on the 75Binds a master object to <tt>address</tt> and <tt>port</tt> on the
76local host. 76local host.
77</p>
77 78
78<p class=parameters> 79<p class="parameters">
79<tt>Address</tt> can be an IP address or a host name. 80<tt>Address</tt> can be an IP address or a host name.
80<tt>Port</tt> must be an integer number in the range [0..64K). 81<tt>Port</tt> must be an integer number in the range [0..64K).
81If <tt>address</tt> 82If <tt>address</tt>
@@ -86,25 +87,25 @@ If <tt>port</tt> is 0, the system automatically
86chooses an ephemeral port. 87chooses an ephemeral port.
87</p> 88</p>
88 89
89<p class=return> 90<p class="return">
90In case of success, the method returns 1. In case of error, the 91In case of success, the method returns 1. In case of error, the
91method returns <b><tt>nil</tt></b> followed by an error message. 92method returns <b><tt>nil</tt></b> followed by an error message.
92</p> 93</p>
93 94
94<p class=note> 95<p class="note">
95Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a> 96Note: The function <a href="socket.html#bind"><tt>socket.bind</tt></a>
96is available and is a shortcut for the creation of server sockets. 97is available and is a shortcut for the creation of server sockets.
97</p> 98</p>
98 99
99<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 100<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
100 101
101<p class=name id="close"> 102<p class="name" id="close">
102master:<b>close()</b><br> 103master:<b>close()</b><br>
103client:<b>close()</b><br> 104client:<b>close()</b><br>
104server:<b>close()</b> 105server:<b>close()</b>
105</p> 106</p>
106 107
107<p class=description> 108<p class="description">
108Closes a TCP object. The internal socket used by the object is closed 109Closes a TCP object. The internal socket used by the object is closed
109and the local address to which the object was 110and the local address to which the object was
110bound is made available to other applications. No further operations 111bound is made available to other applications. No further operations
@@ -112,7 +113,7 @@ bound is made available to other applications. No further operations
112a closed socket. 113a closed socket.
113</p> 114</p>
114 115
115<p class=note> 116<p class="note">
116Note: It is important to close all used sockets once they are not 117Note: It is important to close all used sockets once they are not
117needed, since, in many systems, each socket uses a file descriptor, 118needed, since, in many systems, each socket uses a file descriptor,
118which are limited system resources. Garbage-collected objects are 119which are limited system resources. Garbage-collected objects are
@@ -121,53 +122,53 @@ automatically closed before destruction, though.
121 122
122<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 123<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
123 124
124<p class=name id="connect"> 125<p class="name" id="connect">
125master:<b>connect(</b>address, port<b>)</b> 126master:<b>connect(</b>address, port<b>)</b>
126</p> 127</p>
127 128
128<p class=description> 129<p class="description">
129Attempts to connect a master object to a remote host, transforming it into a 130Attempts to connect a master object to a remote host, transforming it into a
130client object. 131client object.
131Client objects support methods 132Client objects support methods
132<a href=#send><tt>send</tt></a>, 133<a href="#send"><tt>send</tt></a>,
133<a href=#receive><tt>receive</tt></a>, 134<a href="#receive"><tt>receive</tt></a>,
134<a href=#getsockname><tt>getsockname</tt></a>, 135<a href="#getsockname"><tt>getsockname</tt></a>,
135<a href=#getpeername><tt>getpeername</tt></a>, 136<a href="#getpeername"><tt>getpeername</tt></a>,
136<a href=#settimeout><tt>settimeout</tt></a>, 137<a href="#settimeout"><tt>settimeout</tt></a>,
137and <a href=#close><tt>close</tt></a>. 138and <a href="#close"><tt>close</tt></a>.
138</p> 139</p>
139 140
140<p class=parameters> 141<p class="parameters">
141<tt>Address</tt> can be an IP address or a host name. 142<tt>Address</tt> can be an IP address or a host name.
142<tt>Port</tt> must be an integer number in the range [1..64K). 143<tt>Port</tt> must be an integer number in the range [1..64K).
143</p> 144</p>
144 145
145<p class=return> 146<p class="return">
146In case of error, the method returns <b><tt>nil</tt></b> followed by a string 147In case of error, the method returns <b><tt>nil</tt></b> followed by a string
147describing the error. In case of success, the method returns 1. 148describing the error. In case of success, the method returns 1.
148</p> 149</p>
149 150
150<p class=note> 151<p class="note">
151Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a> 152Note: The function <a href="socket.html#connect"><tt>socket.connect</tt></a>
152is available and is a shortcut for the creation of client sockets. 153is available and is a shortcut for the creation of client sockets.
153</p> 154</p>
154 155
155<p class=note> 156<p class="note">
156Note: Starting with LuaSocket 2.0, 157Note: Starting with LuaSocket 2.0,
157the <a href=#settimeout><tt>settimeout</tt></a> 158the <a href="#settimeout"><tt>settimeout</tt></a>
158method affects the behavior of <tt>connect</tt>, causing it to return 159method affects the behavior of <tt>connect</tt>, causing it to return
159with an error in case of a timeout. If that happens, you can still call <a 160with an error in case of a timeout. If that happens, you can still call <a
160href=socket.html#select><tt>socket.select</tt></a> with the socket in the 161href="socket.html#select"><tt>socket.select</tt></a> with the socket in the
161<tt>sendt</tt> table. The socket will be writable when the connection is 162<tt>sendt</tt> table. The socket will be writable when the connection is
162established. 163established.
163</p> 164</p>
164 165
165<p class=note> 166<p class="note">
166Note: Starting with LuaSocket 3.0, the host name resolution 167Note: Starting with LuaSocket 3.0, the host name resolution
167depends on whether the socket was created by 168depends on whether the socket was created by
168<a href=#socket.tcp><tt>socket.tcp</tt></a>, 169<a href="#socket.tcp"><tt>socket.tcp</tt></a>,
169<a href=#socket.tcp4><tt>socket.tcp4</tt></a> or 170<a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or
170<a href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from 171<a href="#socket.tcp6"><tt>socket.tcp6</tt></a>. Addresses from
171the appropriate family (or both) are tried in the order 172the appropriate family (or both) are tried in the order
172returned by the resolver until the 173returned by the resolver until the
173first success or until the last failure. If the timeout was 174first success or until the last failure. If the timeout was
@@ -176,42 +177,42 @@ set to zero, only the first address is tried.
176 177
177<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 178<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
178 179
179<p class=name id="dirty"> 180<p class="name" id="dirty">
180master:<b>dirty()</b><br> 181master:<b>dirty()</b><br>
181client:<b>dirty()</b><br> 182client:<b>dirty()</b><br>
182server:<b>dirty()</b> 183server:<b>dirty()</b>
183</p> 184</p>
184 185
185<p class=description> 186<p class="description">
186Check the read buffer status. 187Check the read buffer status.
187</p> 188</p>
188 189
189<p class=return> 190<p class="return">
190Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise. 191Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
191</p> 192</p>
192 193
193<p class=note> 194<p class="note">
194Note: <b>This is an internal method, use at your own risk.</b> 195Note: <b>This is an internal method, use at your own risk.</b>
195</p> 196</p>
196 197
197 198
198<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 199<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
199 200
200<p class=name id="getfd"> 201<p class="name" id="getfd">
201master:<b>getfd()</b><br> 202master:<b>getfd()</b><br>
202client:<b>getfd()</b><br> 203client:<b>getfd()</b><br>
203server:<b>getfd()</b> 204server:<b>getfd()</b>
204</p> 205</p>
205 206
206<p class=description> 207<p class="description">
207Returns the underling socket descriptor or handle associated to the object. 208Returns the underling socket descriptor or handle associated to the object.
208</p> 209</p>
209 210
210<p class=return> 211<p class="return">
211The descriptor or handle. In case the object has been closed, the return will be -1. 212The descriptor or handle. In case the object has been closed, the return will be -1.
212</p> 213</p>
213 214
214<p class=note> 215<p class="note">
215Note: <b>This is an internal method. Unlikely to be 216Note: <b>This is an internal method. Unlikely to be
216portable. Use at your own risk. </b> 217portable. Use at your own risk. </b>
217</p> 218</p>
@@ -219,28 +220,27 @@ portable. Use at your own risk. </b>
219 220
220<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 221<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
221 222
222<p class=name id="getoption"> 223<p class="name" id="getoption">
223client:<b>getoption(</b>option)</b><br> 224client:<b>getoption(option)</b><br>
224server:<b>getoption(</b>option)</b> 225server:<b>getoption(option)</b>
225</p> 226</p>
226 227
227<p class=description> 228<p class="description">
228Gets options for the TCP object. 229Gets options for the TCP object.
229See <a href=#setoption><tt>setoption</tt></a> for description of the 230See <a href="#setoption"><tt>setoption</tt></a> for description of the
230option names and values. 231option names and values.
231</p> 232</p>
232 233
233<p class=parameters> 234<p class="parameters">
234<tt>Option</tt> is a string with the option name. 235<tt>Option</tt> is a string with the option name.</p>
235<ul> 236<ul>
236 237<li> '<tt>keepalive</tt>'</li>
237<li> '<tt>keepalive</tt>' 238<li> '<tt>linger</tt>'</li>
238<li> '<tt>linger</tt>' 239<li> '<tt>reuseaddr</tt>'</li>
239<li> '<tt>reuseaddr</tt>' 240<li> '<tt>tcp-nodelay</tt>'</li>
240<li> '<tt>tcp-nodelay</tt>'
241</ul> 241</ul>
242 242
243<p class=return> 243<p class="return">
244The method returns the option <tt>value</tt> in case of success, or 244The method returns the option <tt>value</tt> in case of success, or
245<b><tt>nil</tt></b> followed by an error message otherwise. 245<b><tt>nil</tt></b> followed by an error message otherwise.
246</p> 246</p>
@@ -248,38 +248,38 @@ The method returns the option <tt>value</tt> in case of success, or
248 248
249<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 249<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
250 250
251<p class=name id="getpeername"> 251<p class="name" id="getpeername">
252client:<b>getpeername()</b> 252client:<b>getpeername()</b>
253</p> 253</p>
254 254
255<p class=description> 255<p class="description">
256Returns information about the remote side of a connected client object. 256Returns information about the remote side of a connected client object.
257</p> 257</p>
258 258
259<p class=return> 259<p class="return">
260Returns a string with the IP address of the peer, the 260Returns a string with the IP address of the peer, the
261port number that peer is using for the connection, 261port number that peer is using for the connection,
262and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). 262and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
263In case of error, the method returns <b><tt>nil</tt></b>. 263In case of error, the method returns <b><tt>nil</tt></b>.
264</p> 264</p>
265 265
266<p class=note> 266<p class="note">
267Note: It makes no sense to call this method on server objects. 267Note: It makes no sense to call this method on server objects.
268</p> 268</p>
269 269
270<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 270<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
271 271
272<p class=name id="getsockname"> 272<p class="name" id="getsockname">
273master:<b>getsockname()</b><br> 273master:<b>getsockname()</b><br>
274client:<b>getsockname()</b><br> 274client:<b>getsockname()</b><br>
275server:<b>getsockname()</b> 275server:<b>getsockname()</b>
276</p> 276</p>
277 277
278<p class=description> 278<p class="description">
279Returns the local address information associated to the object. 279Returns the local address information associated to the object.
280</p> 280</p>
281 281
282<p class=return> 282<p class="return">
283The method returns a string with local IP address, a number with 283The method returns a string with local IP address, a number with
284the local port, 284the local port,
285and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). 285and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
@@ -288,31 +288,31 @@ In case of error, the method returns <b><tt>nil</tt></b>.
288 288
289<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 289<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
290 290
291<p class=name id="getstats"> 291<p class="name" id="getstats">
292master:<b>getstats()</b><br> 292master:<b>getstats()</b><br>
293client:<b>getstats()</b><br> 293client:<b>getstats()</b><br>
294server:<b>getstats()</b><br> 294server:<b>getstats()</b><br>
295</p> 295</p>
296 296
297<p class=description> 297<p class="description">
298Returns accounting information on the socket, useful for throttling 298Returns accounting information on the socket, useful for throttling
299of bandwidth. 299of bandwidth.
300</p> 300</p>
301 301
302<p class=return> 302<p class="return">
303The method returns the number of bytes received, the number of bytes sent, 303The method returns the number of bytes received, the number of bytes sent,
304and the age of the socket object in seconds. 304and the age of the socket object in seconds.
305</p> 305</p>
306 306
307<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 307<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
308 308
309<p class=name id="gettimeout"> 309<p class="name" id="gettimeout">
310master:<b>gettimeout()</b><br> 310master:<b>gettimeout()</b><br>
311client:<b>gettimeout()</b><br> 311client:<b>gettimeout()</b><br>
312server:<b>gettimeout()</b> 312server:<b>gettimeout()</b>
313</p> 313</p>
314 314
315<p class=description> 315<p class="description">
316Returns the current block timeout followed by the curent 316Returns the current block timeout followed by the curent
317total timeout. 317total timeout.
318</p> 318</p>
@@ -320,65 +320,65 @@ total timeout.
320 320
321<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 321<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
322 322
323<p class=name id="listen"> 323<p class="name" id="listen">
324master:<b>listen(</b>backlog<b>)</b> 324master:<b>listen(</b>backlog<b>)</b>
325</p> 325</p>
326 326
327<p class=description> 327<p class="description">
328Specifies the socket is willing to receive connections, transforming the 328Specifies the socket is willing to receive connections, transforming the
329object into a server object. Server objects support the 329object into a server object. Server objects support the
330<a href=#accept><tt>accept</tt></a>, 330<a href="#accept"><tt>accept</tt></a>,
331<a href=#getsockname><tt>getsockname</tt></a>, 331<a href="#getsockname"><tt>getsockname</tt></a>,
332<a href=#setoption><tt>setoption</tt></a>, 332<a href="#setoption"><tt>setoption</tt></a>,
333<a href=#settimeout><tt>settimeout</tt></a>, 333<a href="#settimeout"><tt>settimeout</tt></a>,
334and <a href=#close><tt>close</tt></a> methods. 334and <a href="#close"><tt>close</tt></a> methods.
335</p> 335</p>
336 336
337<p class=parameters> 337<p class="parameters">
338The parameter <tt>backlog</tt> specifies the number of client 338The parameter <tt>backlog</tt> specifies the number of client
339connections that can 339connections that can
340be queued waiting for service. If the queue is full and another client 340be queued waiting for service. If the queue is full and another client
341attempts connection, the connection is refused. 341attempts connection, the connection is refused.
342</p> 342</p>
343 343
344<p class=return> 344<p class="return">
345In case of success, the method returns 1. In case of error, the 345In case of success, the method returns 1. In case of error, the
346method returns <b><tt>nil</tt></b> followed by an error message. 346method returns <b><tt>nil</tt></b> followed by an error message.
347</p> 347</p>
348 348
349<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 349<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
350 350
351<p class=name id="receive"> 351<p class="name" id="receive">
352client:<b>receive(</b>[pattern [, prefix]]<b>)</b> 352client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
353</p> 353</p>
354 354
355<p class=description> 355<p class="description">
356Reads data from a client object, according to the specified <em>read 356Reads data from a client object, according to the specified <em>read
357pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. 357pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
358</p> 358</p>
359 359
360<p class=parameters> 360<p class="parameters">
361<tt>Pattern</tt> can be any of the following: 361<tt>Pattern</tt> can be any of the following:
362</p> 362</p>
363 363
364<ul> 364<ul>
365<li> '<tt>*a</tt>': reads from the socket until the connection is 365<li> '<tt>*a</tt>': reads from the socket until the connection is
366closed. No end-of-line translation is performed; 366closed. No end-of-line translation is performed;</li>
367<li> '<tt>*l</tt>': reads a line of text from the socket. The line is 367<li> '<tt>*l</tt>': reads a line of text from the socket. The line is
368terminated by a LF character (ASCII&nbsp;10), optionally preceded by a 368terminated by a LF character (ASCII&nbsp;10), optionally preceded by a
369CR character (ASCII&nbsp;13). The CR and LF characters are not included in 369CR character (ASCII&nbsp;13). The CR and LF characters are not included in
370the returned line. In fact, <em>all</em> CR characters are 370the returned line. In fact, <em>all</em> CR characters are
371ignored by the pattern. This is the default pattern; 371ignored by the pattern. This is the default pattern;</li>
372<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> 372<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt>
373of bytes from the socket. 373of bytes from the socket.</li>
374</ul> 374</ul>
375 375
376<p class=parameters> 376<p class="parameters">
377<tt>Prefix</tt> is an optional string to be concatenated to the beginning 377<tt>Prefix</tt> is an optional string to be concatenated to the beginning
378of any received data before return. 378of any received data before return.
379</p> 379</p>
380 380
381<p class=return> 381<p class="return">
382If successful, the method returns the received pattern. In case of error, 382If successful, the method returns the received pattern. In case of error,
383the method returns <tt><b>nil</b></tt> followed by an error 383the method returns <tt><b>nil</b></tt> followed by an error
384message, followed by a (possibly empty) string containing 384message, followed by a (possibly empty) string containing
@@ -388,7 +388,7 @@ closed before the transmission was completed or the string
388'<tt>timeout</tt>' in case there was a timeout during the operation. 388'<tt>timeout</tt>' in case there was a timeout during the operation.
389</p> 389</p>
390 390
391<p class=note> 391<p class="note">
392<b>Important note</b>: This function was changed <em>severely</em>. It used 392<b>Important note</b>: This function was changed <em>severely</em>. It used
393to support multiple patterns (but I have never seen this feature used) and 393to support multiple patterns (but I have never seen this feature used) and
394now it doesn't anymore. Partial results used to be returned in the same 394now it doesn't anymore. Partial results used to be returned in the same
@@ -399,22 +399,22 @@ too.
399 399
400<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 400<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
401 401
402<p class=name id="send"> 402<p class="name" id="send">
403client:<b>send(</b>data [, i [, j]]<b>)</b> 403client:<b>send(</b>data [, i [, j]]<b>)</b>
404</p> 404</p>
405 405
406<p class=description> 406<p class="description">
407Sends <tt>data</tt> through client object. 407Sends <tt>data</tt> through client object.
408</p> 408</p>
409 409
410<p class=parameters> 410<p class="parameters">
411<tt>Data</tt> is the string to be sent. The optional arguments 411<tt>Data</tt> is the string to be sent. The optional arguments
412<tt>i</tt> and <tt>j</tt> work exactly like the standard 412<tt>i</tt> and <tt>j</tt> work exactly like the standard
413<tt>string.sub</tt> Lua function to allow the selection of a 413<tt>string.sub</tt> Lua function to allow the selection of a
414substring to be sent. 414substring to be sent.
415</p> 415</p>
416 416
417<p class=return> 417<p class="return">
418If successful, the method returns the index of the last byte 418If successful, the method returns the index of the last byte
419within <tt>[i, j]</tt> that has been sent. Notice that, if 419within <tt>[i, j]</tt> that has been sent. Notice that, if
420<tt>i</tt> is 1 or absent, this is effectively the total 420<tt>i</tt> is 1 or absent, this is effectively the total
@@ -428,7 +428,7 @@ was completed or the string '<tt>timeout</tt>' in case
428there was a timeout during the operation. 428there was a timeout during the operation.
429</p> 429</p>
430 430
431<p class=note> 431<p class="note">
432Note: Output is <em>not</em> buffered. For small strings, 432Note: Output is <em>not</em> buffered. For small strings,
433it is always better to concatenate them in Lua 433it is always better to concatenate them in Lua
434(with the '<tt>..</tt>' operator) and send the result in one call 434(with the '<tt>..</tt>' operator) and send the result in one call
@@ -437,27 +437,27 @@ instead of calling the method several times.
437 437
438<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 438<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
439 439
440<p class=name id="setoption"> 440<p class="name" id="setoption">
441client:<b>setoption(</b>option [, value]<b>)</b><br> 441client:<b>setoption(</b>option [, value]<b>)</b><br>
442server:<b>setoption(</b>option [, value]<b>)</b> 442server:<b>setoption(</b>option [, value]<b>)</b>
443</p> 443</p>
444 444
445<p class=description> 445<p class="description">
446Sets options for the TCP object. Options are only needed by low-level or 446Sets options for the TCP object. Options are only needed by low-level or
447time-critical applications. You should only modify an option if you 447time-critical applications. You should only modify an option if you
448are sure you need it. 448are sure you need it.
449</p> 449</p>
450 450
451<p class=parameters> 451<p class="parameters">
452<tt>Option</tt> is a string with the option name, and <tt>value</tt> 452<tt>Option</tt> is a string with the option name, and <tt>value</tt>
453depends on the option being set: 453depends on the option being set:</p>
454 454
455<ul> 455<ul>
456 456
457<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables 457<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
458the periodic transmission of messages on a connected socket. Should the 458the periodic transmission of messages on a connected socket. Should the
459connected party fail to respond to these messages, the connection is 459connected party fail to respond to these messages, the connection is
460considered broken and processes using the socket are notified; 460considered broken and processes using the socket are notified;</li>
461 461
462<li> '<tt>linger</tt>': Controls the action taken when unsent data are 462<li> '<tt>linger</tt>': Controls the action taken when unsent data are
463queued on a socket and a close is performed. The value is a table with a 463queued on a socket and a close is performed. The value is a table with a
@@ -468,79 +468,79 @@ it is able to transmit the data or until '<tt>timeout</tt>' has passed. If
468'<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will 468'<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will
469process the close in a manner that allows the process to continue as 469process the close in a manner that allows the process to continue as
470quickly as possible. I do not advise you to set this to anything other than 470quickly as possible. I do not advise you to set this to anything other than
471zero; 471zero;</li>
472 472
473<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules 473<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
474used in validating addresses supplied in a call to 474used in validating addresses supplied in a call to
475<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses; 475<a href="#bind"><tt>bind</tt></a> should allow reuse of local addresses;</li>
476 476
477<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> 477<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
478disables the Nagle's algorithm for the connection; 478disables the Nagle's algorithm for the connection;</li>
479 479
480<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!! 480<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!</li>
481 481
482<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!! 482<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!</li>
483 483
484<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!! 484<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!</li>
485 485
486<li> '<tt>ipv6-v6only</tt>': 486<li> '<tt>ipv6-v6only</tt>':
487Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to 487Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to
488sending and receiving only IPv6 packets. 488sending and receiving only IPv6 packets.</li>
489</ul> 489</ul>
490 490
491<p class=return> 491<p class="return">
492The method returns 1 in case of success, or <b><tt>nil</tt></b> 492The method returns 1 in case of success, or <b><tt>nil</tt></b>
493followed by an error message otherwise. 493followed by an error message otherwise.
494</p> 494</p>
495 495
496<p class=note> 496<p class="note">
497Note: The descriptions above come from the man pages. 497Note: The descriptions above come from the man pages.
498</p> 498</p>
499 499
500<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 500<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
501 501
502<p class=name id="setstats"> 502<p class="name" id="setstats">
503master:<b>setstats(</b>received, sent, age<b>)</b><br> 503master:<b>setstats(</b>received, sent, age<b>)</b><br>
504client:<b>setstats(</b>received, sent, age<b>)</b><br> 504client:<b>setstats(</b>received, sent, age<b>)</b><br>
505server:<b>setstats(</b>received, sent, age<b>)</b><br> 505server:<b>setstats(</b>received, sent, age<b>)</b><br>
506</p> 506</p>
507 507
508<p class=description> 508<p class="description">
509Resets accounting information on the socket, useful for throttling 509Resets accounting information on the socket, useful for throttling
510of bandwidth. 510of bandwidth.
511</p> 511</p>
512 512
513<p class=parameters> 513<p class="parameters">
514<tt>Received</tt> is a number with the new number of bytes received. 514<tt>Received</tt> is a number with the new number of bytes received.
515<tt>Sent</tt> is a number with the new number of bytes sent. 515<tt>Sent</tt> is a number with the new number of bytes sent.
516<tt>Age</tt> is the new age in seconds. 516<tt>Age</tt> is the new age in seconds.
517</p> 517</p>
518 518
519<p class=return> 519<p class="return">
520The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise. 520The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
521</p> 521</p>
522 522
523<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 523<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
524 524
525<p class=name id="settimeout"> 525<p class="name" id="settimeout">
526master:<b>settimeout(</b>value [, mode]<b>)</b><br> 526master:<b>settimeout(</b>value [, mode]<b>)</b><br>
527client:<b>settimeout(</b>value [, mode]<b>)</b><br> 527client:<b>settimeout(</b>value [, mode]<b>)</b><br>
528server:<b>settimeout(</b>value [, mode]<b>)</b> 528server:<b>settimeout(</b>value [, mode]<b>)</b>
529</p> 529</p>
530 530
531<p class=description> 531<p class="description">
532Changes the timeout values for the object. By default, 532Changes the timeout values for the object. By default,
533all I/O operations are blocking. That is, any call to the methods 533all I/O operations are blocking. That is, any call to the methods
534<a href=#send><tt>send</tt></a>, 534<a href="#send"><tt>send</tt></a>,
535<a href=#receive><tt>receive</tt></a>, and 535<a href="#receive"><tt>receive</tt></a>, and
536<a href=#accept><tt>accept</tt></a> 536<a href="#accept"><tt>accept</tt></a>
537will block indefinitely, until the operation completes. The 537will block indefinitely, until the operation completes. The
538<tt>settimeout</tt> method defines a limit on the amount of time the 538<tt>settimeout</tt> method defines a limit on the amount of time the
539I/O methods can block. When a timeout is set and the specified amount of 539I/O methods can block. When a timeout is set and the specified amount of
540time has elapsed, the affected methods give up and fail with an error code. 540time has elapsed, the affected methods give up and fail with an error code.
541</p> 541</p>
542 542
543<p class=parameters> 543<p class="parameters">
544The amount of time to wait is specified as the 544The amount of time to wait is specified as the
545<tt>value</tt> parameter, in seconds. There are two timeout modes and 545<tt>value</tt> parameter, in seconds. There are two timeout modes and
546both can be used together for fine tuning: 546both can be used together for fine tuning:
@@ -557,12 +557,12 @@ the amount of time LuaSocket can block a Lua script before returning from
557a call.</li> 557a call.</li>
558</ul> 558</ul>
559 559
560<p class=parameters> 560<p class="parameters">
561The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block 561The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block
562indefinitely. Negative timeout values have the same effect. 562indefinitely. Negative timeout values have the same effect.
563</p> 563</p>
564 564
565<p class=note> 565<p class="note">
566Note: although timeout values have millisecond precision in LuaSocket, 566Note: although timeout values have millisecond precision in LuaSocket,
567large blocks can cause I/O functions not to respect timeout values due 567large blocks can cause I/O functions not to respect timeout values due
568to the time the library takes to transfer blocks to and from the OS 568to the time the library takes to transfer blocks to and from the OS
@@ -571,7 +571,7 @@ and perform automatic name resolution might be blocked by the resolver for
571longer than the specified timeout value. 571longer than the specified timeout value.
572</p> 572</p>
573 573
574<p class=note> 574<p class="note">
575Note: The old <tt>timeout</tt> method is deprecated. The name has been 575Note: The old <tt>timeout</tt> method is deprecated. The name has been
576changed for sake of uniformity, since all other method names already 576changed for sake of uniformity, since all other method names already
577contained verbs making their imperative nature obvious. 577contained verbs making their imperative nature obvious.
@@ -579,123 +579,124 @@ contained verbs making their imperative nature obvious.
579 579
580<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 580<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
581 581
582<p class=name id="shutdown"> 582<p class="name" id="shutdown">
583client:<b>shutdown(</b>mode<b>)</b><br> 583client:<b>shutdown(</b>mode<b>)</b><br>
584</p> 584</p>
585 585
586<p class=description> 586<p class="description">
587Shuts down part of a full-duplex connection. 587Shuts down part of a full-duplex connection.
588</p> 588</p>
589 589
590<p class=parameters> 590<p class="parameters">
591Mode tells which way of the connection should be shut down and can 591Mode tells which way of the connection should be shut down and can
592take the value: 592take the value:
593<ul> 593<ul>
594<li>"<tt>both</tt>": disallow further sends and receives on the object. 594<li>"<tt>both</tt>": disallow further sends and receives on the object.
595This is the default mode; 595This is the default mode;</li>
596<li>"<tt>send</tt>": disallow further sends on the object; 596<li>"<tt>send</tt>": disallow further sends on the object;</li>
597<li>"<tt>receive</tt>": disallow further receives on the object. 597<li>"<tt>receive</tt>": disallow further receives on the object.</li>
598</ul> 598</ul>
599</p>
599 600
600<p class=return> 601<p class="return">
601This function returns 1. 602This function returns 1.
602</p> 603</p>
603 604
604<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 605<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
605 606
606<p class=name id="setfd"> 607<p class="name" id="setfd">
607master:<b>setfd(</b>fd<b>)</b><br> 608master:<b>setfd(</b>fd<b>)</b><br>
608client:<b>setfd(</b>fd<b>)</b><br> 609client:<b>setfd(</b>fd<b>)</b><br>
609server:<b>setfd(</b>fd<b>)</b> 610server:<b>setfd(</b>fd<b>)</b>
610</p> 611</p>
611 612
612<p class=description> 613<p class="description">
613Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made. 614Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made.
614</p> 615</p>
615 616
616<p class=return> 617<p class="return">
617No return value. 618No return value.
618</p> 619</p>
619 620
620<p class=note> 621<p class="note">
621Note: <b>This is an internal method. Unlikely to be 622Note: <b>This is an internal method. Unlikely to be
622portable. Use at your own risk. </b> 623portable. Use at your own risk. </b>
623</p> 624</p>
624 625
625<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 626<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
626 627
627<p class=name id="socket.tcp"> 628<p class="name" id="socket.tcp">
628socket.<b>tcp()</b> 629socket.<b>tcp()</b>
629</p> 630</p>
630 631
631<p class=description> 632<p class="description">
632Creates and returns an TCP master object. A master object can 633Creates and returns an TCP master object. A master object can
633be transformed into a server object with the method 634be transformed into a server object with the method
634<a href=#listen><tt>listen</tt></a> (after a call to <a 635<a href="#listen"><tt>listen</tt></a> (after a call to <a
635href=#bind><tt>bind</tt></a>) or into a client object with 636href="#bind"><tt>bind</tt></a>) or into a client object with
636the method <a href=#connect><tt>connect</tt></a>. The only other 637the method <a href="#connect"><tt>connect</tt></a>. The only other
637method supported by a master object is the 638method supported by a master object is the
638<a href=#close><tt>close</tt></a> method.</p> 639<a href="#close"><tt>close</tt></a> method.</p>
639 640
640<p class=return> 641<p class="return">
641In case of success, a new master object is returned. In case of error, 642In case of success, a new master object is returned. In case of error,
642<b><tt>nil</tt></b> is returned, followed by an error message. 643<b><tt>nil</tt></b> is returned, followed by an error message.
643</p> 644</p>
644 645
645<p class=note> 646<p class="note">
646Note: The choice between IPv4 and IPv6 happens during a call to 647Note: The choice between IPv4 and IPv6 happens during a call to
647<a href=#bind><tt>bind</tt></a> or <a 648<a href="#bind"><tt>bind</tt></a> or <a
648href=#bind><tt>connect</tt></a>, depending on the address 649href="#bind"><tt>connect</tt></a>, depending on the address
649family obtained from the resolver. 650family obtained from the resolver.
650</p> 651</p>
651 652
652<p class=note> 653<p class="note">
653Note: Before the choice between IPv4 and IPv6 happens, 654Note: Before the choice between IPv4 and IPv6 happens,
654the internal socket object is invalid and therefore <a 655the internal socket object is invalid and therefore <a
655href=#setoption><tt>setoption</tt></a> will fail. 656href="#setoption"><tt>setoption</tt></a> will fail.
656</p> 657</p>
657 658
658<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 659<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
659 660
660<p class=name id="socket.tcp4"> 661<p class="name" id="socket.tcp4">
661socket.<b>tcp4()</b> 662socket.<b>tcp4()</b>
662</p> 663</p>
663 664
664<p class=description> 665<p class="description">
665Creates and returns an IPv4 TCP master object. A master object can 666Creates and returns an IPv4 TCP master object. A master object can
666be transformed into a server object with the method 667be transformed into a server object with the method
667<a href=#listen><tt>listen</tt></a> (after a call to <a 668<a href="#listen"><tt>listen</tt></a> (after a call to <a
668href=#bind><tt>bind</tt></a>) or into a client object with 669href="#bind"><tt>bind</tt></a>) or into a client object with
669the method <a href=#connect><tt>connect</tt></a>. The only other 670the method <a href="#connect"><tt>connect</tt></a>. The only other
670method supported by a master object is the 671method supported by a master object is the
671<a href=#close><tt>close</tt></a> method.</p> 672<a href="#close"><tt>close</tt></a> method.</p>
672 673
673<p class=return> 674<p class="return">
674In case of success, a new master object is returned. In case of error, 675In case of success, a new master object is returned. In case of error,
675<b><tt>nil</tt></b> is returned, followed by an error message. 676<b><tt>nil</tt></b> is returned, followed by an error message.
676</p> 677</p>
677 678
678<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 679<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
679 680
680<p class=name id="socket.tcp6"> 681<p class="name" id="socket.tcp6">
681socket.<b>tcp6()</b> 682socket.<b>tcp6()</b>
682</p> 683</p>
683 684
684<p class=description> 685<p class="description">
685Creates and returns an IPv6 TCP master object. A master object can 686Creates and returns an IPv6 TCP master object. A master object can
686be transformed into a server object with the method 687be transformed into a server object with the method
687<a href=#listen><tt>listen</tt></a> (after a call to <a 688<a href="#listen"><tt>listen</tt></a> (after a call to <a
688href=#bind><tt>bind</tt></a>) or into a client object with 689href="#bind"><tt>bind</tt></a>) or into a client object with
689the method <a href=#connect><tt>connect</tt></a>. The only other 690the method <a href="#connect"><tt>connect</tt></a>. The only other
690method supported by a master object is the 691method supported by a master object is the
691<a href=#close><tt>close</tt></a> method.</p> 692<a href="#close"><tt>close</tt></a> method.</p>
692 693
693<p class=return> 694<p class="return">
694In case of success, a new master object is returned. In case of error, 695In case of success, a new master object is returned. In case of error,
695<b><tt>nil</tt></b> is returned, followed by an error message. 696<b><tt>nil</tt></b> is returned, followed by an error message.
696</p> 697</p>
697 698
698<p class=note> 699<p class="note">
699Note: The TCP object returned will have the option 700Note: The TCP object returned will have the option
700"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. 701"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
701</p> 702</p>
@@ -704,10 +705,10 @@ Note: The TCP object returned will have the option
704 705
705<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 706<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
706 707
707<div class=footer> 708<div class="footer">
708<hr> 709<hr>
709<center> 710<center>
710<p class=bar> 711<p class="bar">
711<a href="index.html">home</a> &middot; 712<a href="index.html">home</a> &middot;
712<a href="index.html#down">download</a> &middot; 713<a href="index.html#down">download</a> &middot;
713<a href="installation.html">installation</a> &middot; 714<a href="installation.html">installation</a> &middot;