Mercurial > luasocket

comparison doc/tcp.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaSocket 2.0.2 + CMake build description.
author Eric Wing <ewing . public |-at-| gmail . com>
date Tue, 26 Aug 2008 18:40:01 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4b915342e2a8
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3 <html>
4
5 <head>
6 <meta name="description" content="LuaSocket: The TCP/IP support">
7 <meta name="keywords" content="Lua, LuaSocket, Socket, TCP, Library, Network, Support">
8 <title>LuaSocket: TCP/IP support</title>
9 <link rel="stylesheet" href="reference.css" type="text/css">
10 </head>
11
12 <body>
13
14 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15
16 <div class=header>
17 <hr>
18 <center>
19 <table summary="LuaSocket logo">
20 <tr><td align=center><a href="http://www.lua.org">
21 <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
22 </a></td></tr>
23 <tr><td align=center valign=top>Network support for the Lua language
24 </td></tr>
25 </table>
26 <p class=bar>
27 <a href="home.html">home</a> &middot;
28 <a href="home.html#download">download</a> &middot;
29 <a href="installation.html">installation</a> &middot;
30 <a href="introduction.html">introduction</a> &middot;
31 <a href="reference.html">reference</a>
32 </p>
33 </center>
34 <hr>
35 </div>
36
37 <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39 <h2 id=tcp>TCP</h2>
40
41 <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
42
43 <p class=name id=socket.tcp>
44 socket.<b>tcp()</b>
45 </p>
46
47 <p class=description>
48 Creates and returns a TCP master object. A master object can
49 be transformed into a server object with the method
50 <a href=#listen><tt>listen</tt></a> (after a call to <a
51 href=#bind><tt>bind</tt></a>) or into a client object with
52 the method <a href=#connect><tt>connect</tt></a>. The only other
53 method supported by a master object is the
54 <a href=#close><tt>close</tt></a> method.</p>
55
56 <p class=return>
57 In case of success, a new master object is returned. In case of error,
58 <b><tt>nil</tt></b> is returned, followed by an error message.
59 </p>
60
61 <!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
62
63 <p class=name id=accept>
64 server:<b>accept()</b>
65 </p>
66
67 <p class=description>
68 Waits for a remote connection on the server
69 object and returns a client object representing that connection.
70 </p>
71
72 <p class=return>
73 If a connection is successfully initiated, a client object is returned.
74 If a timeout condition is met, the method returns <b><tt>nil</tt></b>
75 followed by the error string '<tt>timeout</tt>'. Other errors are
76 reported by <b><tt>nil</tt></b> followed by a message describing the error.
77 </p>
78
79 <p class=note>
80 Note: calling <a href=socket.html#select><tt>socket.select</tt></a>
81 with a server object in
82 the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does
83 <em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
84 href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
85 might block until <em>another</em> client shows up.
86 </p>
87
88 <!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
89
90 <p class=name id=bind>
91 master:<b>bind(</b>address, port<b>)</b>
92 </p>
93
94 <p class=description>
95 Binds a master object to <tt>address</tt> and <tt>port</tt> on the
96 local host.
97
98 <p class=parameters>
99 <tt>Address</tt> can be an IP address or a host name.
100 <tt>Port</tt> must be an integer number in the range [0..64K).
101 If <tt>address</tt>
102 is '<tt>*</tt>', the system binds to all local interfaces
103 using the <tt>INADDR_ANY</tt> constant. If <tt>port</tt> is 0, the system automatically
104 chooses an ephemeral port.
105 </p>
106
107 <p class=return>
108 In case of success, the method returns 1. In case of error, the
109 method returns <b><tt>nil</tt></b> followed by an error message.
110 </p>
111
112 <p class=note>
113 Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a>
114 is available and is a shortcut for the creation of server sockets.
115 </p>
116
117 <!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
118
119 <p class=name id=close>
120 master:<b>close()</b><br>
121 client:<b>close()</b><br>
122 server:<b>close()</b>
123 </p>
124
125 <p class=description>
126 Closes a TCP object. The internal socket used by the object is closed
127 and the local address to which the object was
128 bound is made available to other applications. No further operations
129 (except for further calls to the <tt>close</tt> method) are allowed on
130 a closed socket.
131 </p>
132
133 <p class=note>
134 Note: It is important to close all used sockets once they are not
135 needed, since, in many systems, each socket uses a file descriptor,
136 which are limited system resources. Garbage-collected objects are
137 automatically closed before destruction, though.
138 </p>
139
140 <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
141
142 <p class=name id=connect>
143 master:<b>connect(</b>address, port<b>)</b>
144 </p>
145
146 <p class=description>
147 Attempts to connect a master object to a remote host, transforming it into a
148 client object.
149 Client objects support methods
150 <a href=#send><tt>send</tt></a>,
151 <a href=#receive><tt>receive</tt></a>,
152 <a href=#getsockname><tt>getsockname</tt></a>,
153 <a href=#getpeername><tt>getpeername</tt></a>,
154 <a href=#settimeout><tt>settimeout</tt></a>,
155 and <a href=#close><tt>close</tt></a>.
156 </p>
157
158 <p class=parameters>
159 <tt>Address</tt> can be an IP address or a host name.
160 <tt>Port</tt> must be an integer number in the range [1..64K).
161 </p>
162
163 <p class=return>
164 In case of error, the method returns <b><tt>nil</tt></b> followed by a string
165 describing the error. In case of success, the method returns 1.
166 </p>
167
168 <p class=note>
169 Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a>
170 is available and is a shortcut for the creation of client sockets.
171 </p>
172
173 <p class=note>
174 Note: Starting with LuaSocket 2.0,
175 the <a href=#settimeout><tt>settimeout</tt></a>
176 method affects the behavior of <tt>connect</tt>, causing it to return
177 with an error in case of a timeout. If that happens, you can still call <a
178 href=socket.html#select><tt>socket.select</tt></a> with the socket in the
179 <tt>sendt</tt> table. The socket will be writable when the connection is
180 established.
181 </p>
182
183 <!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
184
185 <p class=name id=getpeername>
186 client:<b>getpeername()</b>
187 </p>
188
189 <p class=description>
190 Returns information about the remote side of a connected client object.
191 </p>
192
193 <p class=return>
194 Returns a string with the IP address of the peer, followed by the
195 port number that peer is using for the connection.
196 In case of error, the method returns <b><tt>nil</tt></b>.
197 </p>
198
199 <p class=note>
200 Note: It makes no sense to call this method on server objects.
201 </p>
202
203 <!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
204
205 <p class=name id=getsockname>
206 master:<b>getsockname()</b><br>
207 client:<b>getsockname()</b><br>
208 server:<b>getsockname()</b>
209 </p>
210
211 <p class=description>
212 Returns the local address information associated to the object.
213 </p>
214
215 <p class=return>
216 The method returns a string with local IP address and a number with
217 the port. In case of error, the method returns <b><tt>nil</tt></b>.
218 </p>
219
220 <!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
221
222 <p class=name id=getstats>
223 master:<b>getstats()</b><br>
224 client:<b>getstats()</b><br>
225 server:<b>getstats()</b><br>
226 </p>
227
228 <p class=description>
229 Returns accounting information on the socket, useful for throttling
230 of bandwidth.
231 </p>
232
233 <p class=return>
234 The method returns the number of bytes received, the number of bytes sent,
235 and the age of the socket object in seconds.
236 </p>
237
238 <!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
239
240 <p class=name id=listen>
241 master:<b>listen(</b>backlog<b>)</b>
242 </p>
243
244 <p class=description>
245 Specifies the socket is willing to receive connections, transforming the
246 object into a server object. Server objects support the
247 <a href=#accept><tt>accept</tt></a>,
248 <a href=#getsockname><tt>getsockname</tt></a>,
249 <a href=#setoption><tt>setoption</tt></a>,
250 <a href=#settimeout><tt>settimeout</tt></a>,
251 and <a href=#close><tt>close</tt></a> methods.
252 </p>
253
254 <p class=parameters>
255 The parameter <tt>backlog</tt> specifies the number of client
256 connections that can
257 be queued waiting for service. If the queue is full and another client
258 attempts connection, the connection is refused.
259 </p>
260
261 <p class=return>
262 In case of success, the method returns 1. In case of error, the
263 method returns <b><tt>nil</tt></b> followed by an error message.
264 </p>
265
266 <!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
267
268 <p class=name id=receive>
269 client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
270 </p>
271
272 <p class=description>
273 Reads data from a client object, according to the specified <em>read
274 pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
275 </p>
276
277 <p class=parameters>
278 <tt>Pattern</tt> can be any of the following:
279 </p>
280
281 <ul>
282 <li> '<tt>*a</tt>': reads from the socket until the connection is
283 closed. No end-of-line translation is performed;
284 <li> '<tt>*l</tt>': reads a line of text from the socket. The line is
285 terminated by a LF character (ASCII&nbsp;10), optionally preceded by a
286 CR character (ASCII&nbsp;13). The CR and LF characters are not included in
287 the returned line. In fact, <em>all</em> CR characters are
288 ignored by the pattern. This is the default pattern;
289 <li> <tt>number</tt>: causes the method to read a specified <tt>number</tt>
290 of bytes from the socket.
291 </ul>
292
293 <p class=parameters>
294 <tt>Prefix</tt> is an optional string to be concatenated to the beginning
295 of any received data before return.
296 </p>
297
298 <p class=return>
299 If successful, the method returns the received pattern. In case of error,
300 the method returns <tt><b>nil</b></tt> followed by an error message which
301 can be the string '<tt>closed</tt>' in case the connection was
302 closed before the transmission was completed or the string
303 '<tt>timeout</tt>' in case there was a timeout during the operation.
304 Also, after the error message, the function returns the partial result of
305 the transmission.
306 </p>
307
308 <p class=note>
309 <b>Important note</b>: This function was changed <em>severely</em>. It used
310 to support multiple patterns (but I have never seen this feature used) and
311 now it doesn't anymore. Partial results used to be returned in the same
312 way as successful results. This last feature violated the idea that all
313 functions should return <tt><b>nil</b></tt> on error. Thus it was changed
314 too.
315 </p>
316
317 <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
318
319 <p class=name id=send>
320 client:<b>send(</b>data [, i [, j]]<b>)</b>
321 </p>
322
323 <p class=description>
324 Sends <tt>data</tt> through client object.
325 </p>
326
327 <p class=parameters>
328 <tt>Data</tt> is the string to be sent. The optional arguments
329 <tt>i</tt> and <tt>j</tt> work exactly like the standard
330 <tt>string.sub</tt> Lua function to allow the selection of a
331 substring to be sent.
332 </p>
333
334 <p class=return>
335 If successful, the method returns the index of the last byte
336 within <tt>[i, j]</tt> that has been sent. Notice that, if
337 <tt>i</tt> is 1 or absent, this is effectively the total
338 number of bytes sent. In case of error, the method returns
339 <b><tt>nil</tt></b>, followed by an error message, followed
340 by the index of the last byte within <tt>[i, j]</tt> that
341 has been sent. You might want to try again from the byte
342 following that. The error message can be '<tt>closed</tt>'
343 in case the connection was closed before the transmission
344 was completed or the string '<tt>timeout</tt>' in case
345 there was a timeout during the operation.
346 </p>
347
348 <p class=note>
349 Note: Output is <em>not</em> buffered. For small strings,
350 it is always better to concatenate them in Lua
351 (with the '<tt>..</tt>' operator) and send the result in one call
352 instead of calling the method several times.
353 </p>
354
355 <!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
356
357 <p class=name id=setoption>
358 client:<b>setoption(</b>option [, value]<b>)</b><br>
359 server:<b>setoption(</b>option [, value]<b>)</b>
360 </p>
361
362 <p class=description>
363 Sets options for the TCP object. Options are only needed by low-level or
364 time-critical applications. You should only modify an option if you
365 are sure you need it.
366 </p>
367
368 <p class=parameters>
369 <tt>Option</tt> is a string with the option name, and <tt>value</tt>
370 depends on the option being set:
371
372 <ul>
373
374 <li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
375 the periodic transmission of messages on a connected socket. Should the
376 connected party fail to respond to these messages, the connection is
377 considered broken and processes using the socket are notified;
378
379 <li> '<tt>linger</tt>': Controls the action taken when unsent data are
380 queued on a socket and a close is performed. The value is a table with a
381 boolean entry '<tt>on</tt>' and a numeric entry for the time interval
382 '<tt>timeout</tt>' in seconds. If the '<tt>on</tt>' field is set to
383 <tt>true</tt>, the system will block the process on the close attempt until
384 it is able to transmit the data or until '<tt>timeout</tt>' has passed. If
385 '<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will
386 process the close in a manner that allows the process to continue as
387 quickly as possible. I do not advise you to set this to anything other than
388 zero;
389
390 <li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
391 used in validating addresses supplied in a call to
392 <a href=#bind><tt>bind</tt></a> should allow reuse of local addresses;
393
394 <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
395 disables the Nagle's algorithm for the connection.
396
397 </ul>
398
399 <p class=return>
400 The method returns 1 in case of success, or <b><tt>nil</tt></b> otherwise.
401 </p>
402
403 <p class=note>
404 Note: The descriptions above come from the man pages.
405 </p>
406
407 <!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
408
409 <p class=name id=setstats>
410 master:<b>setstats(</b>received, sent, age<b>)</b><br>
411 client:<b>setstats(</b>received, sent, age<b>)</b><br>
412 server:<b>setstats(</b>received, sent, age<b>)</b><br>
413 </p>
414
415 <p class=description>
416 Resets accounting information on the socket, useful for throttling
417 of bandwidth.
418 </p>
419
420 <p class=parameters>
421 <tt>Received</tt> is a number with the new number of bytes received.
422 <tt>Sent</tt> is a number with the new number of bytes sent.
423 <tt>Age</tt> is the new age in seconds.
424 </p>
425
426 <p class=return>
427 The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
428 </p>
429
430 <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
431
432 <p class=name id=settimeout>
433 master:<b>settimeout(</b>value [, mode]<b>)</b><br>
434 client:<b>settimeout(</b>value [, mode]<b>)</b><br>
435 server:<b>settimeout(</b>value [, mode]<b>)</b>
436 </p>
437
438 <p class=description>
439 Changes the timeout values for the object. By default,
440 all I/O operations are blocking. That is, any call to the methods
441 <a href=#send><tt>send</tt></a>,
442 <a href=#receive><tt>receive</tt></a>, and
443 <a href=#accept><tt>accept</tt></a>
444 will block indefinitely, until the operation completes. The
445 <tt>settimeout</tt> method defines a limit on the amount of time the
446 I/O methods can block. When a timeout is set and the specified amount of
447 time has elapsed, the affected methods give up and fail with an error code.
448 </p>
449
450 <p class=parameters>
451 The amount of time to wait is specified as the
452 <tt>value</tt> parameter, in seconds. There are two timeout modes and
453 both can be used together for fine tuning:
454 </p>
455
456 <ul>
457 <li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on
458 the amount of time LuaSocket can be blocked by the operating system
459 while waiting for completion of any single I/O operation. This is the
460 default mode;</li>
461
462 <li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on
463 the amount of time LuaSocket can block a Lua script before returning from
464 a call.</li>
465 </ul>
466
467 <p class=parameters>
468 The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block
469 indefinitely. Negative timeout values have the same effect.
470 </p>
471
472 <p class=note>
473 Note: although timeout values have millisecond precision in LuaSocket,
474 large blocks can cause I/O functions not to respect timeout values due
475 to the time the library takes to transfer blocks to and from the OS
476 and to and from the Lua interpreter. Also, function that accept host names
477 and perform automatic name resolution might be blocked by the resolver for
478 longer than the specified timeout value.
479 </p>
480
481 <p class=note>
482 Note: The old <tt>timeout</tt> method is deprecated. The name has been
483 changed for sake of uniformity, since all other method names already
484 contained verbs making their imperative nature obvious.
485 </p>
486
487 <!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
488
489 <p class=name id=shutdown>
490 client:<b>shutdown(</b>mode<b>)</b><br>
491 </p>
492
493 <p class=description>
494 Shuts down part of a full-duplex connection.
495 </p>
496
497 <p class=parameters>
498 Mode tells which way of the connection should be shut down and can
499 take the value:
500 <ul>
501 <li>"<tt>both</tt>": disallow further sends and receives on the object.
502 This is the default mode;
503 <li>"<tt>send</tt>": disallow further sends on the object;
504 <li>"<tt>receive</tt>": disallow further receives on the object.
505 </ul>
506
507 <p class=return>
508 This function returns 1.
509 </p>
510
511 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
512
513 <div class=footer>
514 <hr>
515 <center>
516 <p class=bar>
517 <a href="home.html">home</a> &middot;
518 <a href="home.html#down">download</a> &middot;
519 <a href="installation.html">installation</a> &middot;
520 <a href="introduction.html">introduction</a> &middot;
521 <a href="reference.html">reference</a>
522 </p>
523 <p>
524 <small>
525 Last modified by Diego Nehab on <br>
526 Thu Apr 20 00:25:57 EDT 2006
527 </small>
528 </p>
529 </center>
530 </div>
531
532 </body>
533 </html>