aboutsummaryrefslogtreecommitdiff
path: root/doc/tcp.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
commit982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch)
tree8f96f9e9fa1e6bef8b8356037986ddc18673cade /doc/tcp.html
parent6789b83ff5c15296267f880d3b98cf8a1800c30a (diff)
downloadluasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.gz
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.bz2
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.zip
LuaSocket 2.0 User's Manual.
Diffstat (limited to 'doc/tcp.html')
-rw-r--r--doc/tcp.html415
1 files changed, 415 insertions, 0 deletions
diff --git a/doc/tcp.html b/doc/tcp.html
new file mode 100644
index 0000000..ecbedaa
--- /dev/null
+++ b/doc/tcp.html
@@ -0,0 +1,415 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=tcp>TCP</h2>
37
38<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<p class=name id=socket.tcp>
41socket.<b>tcp()</b>
42</p>
43
44<p class=description>
45Creates and returns a TCP master object. A master object can
46be transformed into a server object with the method
47<a href=#bind><tt>bind</tt></a> or into a client object with the method
48<a href=#connect><tt>connect</tt></a>. The only other method
49supported by a master object is the <a href=#close><tt>close</tt></a>
50method.</p>
51
52<p class=return>
53In case of success, a new master object is returned. In case of error,
54<tt>nil</tt> is returned, followed by an error message.
55</p>
56
57<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
58
59<p class=name id=accept>
60server:<b>accept()</b>
61</p>
62
63<p class=description>
64Waits for a remote connection on the server
65object and returns a client object representing that connection.
66</p>
67
68<p class=return>
69If a connection is successfully initiated, a client object is returned.
70If a timeout condition is met, the method returns <tt>nil</tt> followed
71by the error string '<tt>timeout</tt>'.
72</p>
73
74<p class=note>
75Note: calling <a href=misc.html#socket.select><tt>socket.select</tt></a>
76with a server object in
77the <tt>receive</tt> parameter before a call to <tt>accept</tt> does
78<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
79href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
80might block until <em>another</em> client shows up.
81</p>
82
83<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
84
85<p class=name id=bind>
86master:<b>bind(</b>address, port [, backlog]<b>)</b>
87</p>
88
89<p class=description>
90Binds a master object to <tt>address</tt> and <tt>port</tt> on the
91local host, transforming it into a server object. Server
92objects support the
93<a href=#accept><tt>accept</tt></a>,
94<a href=#getsockname><tt>getsockname</tt></a>,
95<a href=#setoption><tt>setoption</tt></a>,
96<a href=#settimeout><tt>settimeout</tt></a>,
97and <a href=#close><tt>close</tt></a> methods.
98</p>
99
100<p class=parameters>
101<tt>Address</tt> can be an IP address or a host name.
102<tt>Port</tt> must be an integer number in the range [0..64K].
103If <tt>address</tt>
104is '<tt>*</tt>', the system binds to all local interfaces
105using the <tt>INADDR_ANY</tt> constant. If <tt>port</tt> is 0, the system automatically
106chooses an ephemeral port. The optional parameter <tt>backlog</tt>, which
107defaults to 1, specifies the number of client connections that can
108be queued waiting for service. If the queue is full and another client
109attempts connection, the connection is refused.
110</p>
111
112<p class=return>
113In case of success, the method returns 1. In case of error, the
114method returns <tt>nil</tt> followed by an error message.
115</p>
116
117<p class=note>
118Note: The function <tt>socket.bind</tt> is available and is a short
119for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>bind</tt> method.
120</p>
121
122<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
123
124<p class=name id=close>
125master:<b>close()</b><br>
126client:<b>close()</b><br>
127server:<b>close()</b>
128</p>
129
130<p class=description>
131Closes a TCP object. The internal socket used by the object is closed
132and the local address to which the object was
133bound is made available to other applications. No further operations
134(except for further calls to the <tt>close</tt> method) are allowed on
135a closed socket.
136</p>
137
138<p class=note>
139Note: It is important to close all used sockets once they are not
140needed, since, in many systems, each socket uses a file descriptor,
141which are limited system resources. Garbage-collected objects are
142automatically closed before destruction, though.
143</p>
144
145<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
146
147<p class=name id=connect>
148master:<b>connect(</b>address, port<b>)</b>
149</p>
150
151<p class=description>
152Attempts to connect a master object to a remote host, transforming it into a
153client object. Client objects support methods
154<a href=#send><tt>send</tt></a>,
155<a href=#receive><tt>receive</tt></a>,
156<a href=#getsockname><tt>getsockname</tt></a>,
157<a href=#getpeername><tt>getpeername</tt></a>,
158<a href=#settimeout><tt>settimeout</tt></a>,
159and <a href=#close><tt>close</tt></a>.
160</p>
161
162<p class=parameters>
163<tt>Address</tt> can be an IP address or a host name.
164<tt>Port</tt> must be an integer number in the range [1..64K].
165</p>
166
167<p class=return>
168In case of error, the method returns <tt>nil</tt> followed by a string
169describing the error. In case of success, the method returns 1.
170</p>
171
172<p class=note>
173Note: The function <tt>socket.connect</tt> is available and is a short
174for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>connect</tt> method.
175</p>
176
177<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
178
179<p class=name id=getpeername>
180client:<b>getpeername()</b>
181</p>
182
183<p class=description>
184Returns information about the remote side of a connected client object.
185</p>
186
187<p class=return>
188Returns a string with the IP address of the peer, followed by the
189port number that peer is using for the connection.
190In case of error, the method returns <tt>nil</tt>.
191</p>
192
193<p class=note>
194Note: It makes no sense to call this method on server objects.
195</p>
196
197<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
198
199<p class=name id=getsockname>
200client:<b>getsockname()</b><br>
201server:<b>getsockname()</b>
202</p>
203
204<p class=description>
205Returns the local address information associated to the object.
206</p>
207
208<p class=return>
209The method returns a string with local IP address and a number with
210the port. In case of error, the method returns <tt>nil</tt>.
211</p>
212
213<p class=note>
214Note: Naturally, for a server object, the address and port returned are
215those passed to the <a href=#bind>bind</a> method. If the port value
216passed to bind was 0, the OS assigned ephemeral port is returned. For
217client objects, both the address and port are ephemeral and these are the
218values returned.
219</p>
220
221<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
222
223<p class=name id=receive>
224client:<b>receive(</b>[pattern<sub>1</sub>, pattern<sub>2</sub>,
225... pattern<sub>N</sub>]<b>)</b>
226</p>
227
228<p class=description>
229Reads data from a client object, according to the specified <em>read
230patterns</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
231</p>
232
233<p class=parameters>
234The parameters <tt>pattern</tt><sub>1</sub>, <tt>pattern</tt><sub>2</sub>, ...
235<tt>pattern</tt><sub>N</sub> can be any of the following:
236</p>
237
238<ul>
239<li> '<tt>*a</tt>': reads from the socket until the connection is
240closed. No end-of-line translation is performed;
241<li> '<tt>*l</tt>': reads a line of text from the socket. The line is
242terminated by a LF character (ASCII&nbsp;10), optionally preceded by a
243CR character (ASCII&nbsp;13). The CR and LF characters are not included in
244the returned line. This is the default pattern;
245<li> <tt>number</tt>: causes the method to read <tt>number</tt> raw
246bytes from the socket.
247</ul>
248
249<p class=return>
250The method returns one value for each pattern, followed by a single
251error code that can be <tt>nil</tt> in case of success, the string
252'<tt>closed</tt>' in case the connection was closed before the
253transmission was completed or the string '<tt>timeout</tt>' in case
254there was a timeout during the operation.
255</p>
256
257<p class=note>
258Note: In case of error, the method always return everything it managed
259to download before the error condition was met.
260</p>
261
262<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
263
264<p class=name id=send>
265client:<b>send(</b>string<sub>1</sub> [,
266string<sub>2</sub>, ... string<sub>N</sub>]<b>)</b>
267</p>
268
269<p class=description>
270Sends data through client object.
271</p>
272
273<p class=parameters>
274All parameters should be strings. For small strings, it is always better to
275concatenate them in Lua (with the '<tt>..</tt>' operator) and pass the
276result to LuaSocket instead of passing several independent strings.
277</p>
278
279<p class=return>
280The method returns the number of bytes accepted by the transport layer,
281followed by an error code. The error code is <tt>nil</tt> if the operation
282completed with no errors, the string '<tt>closed</tt>' in case
283the connection was closed before the transmission was completed or the
284string '<tt>timeout</tt>' in case there was a timeout during the
285operation.
286</p>
287
288<p class=note>
289Note: The return values for the <tt>send</tt> method have been changed in
290LuaSocket 2.0! In previous versions, the method returned only the
291error message. Since returning <tt>nil</tt> in case of success goes
292against all other LuaSocket methods and functions, the
293<tt>send</tt> method been changed for the sake of uniformity.
294</p>
295
296<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
297
298<p class=name id=setoption>
299client:<b>setoption(</b>option [, value]<b>)</b><br>
300server:<b>setoption(</b>option [, value]<b>)</b>
301</p>
302
303<p class=description>
304Sets options for the TCP object. Options are only needed by low-level or
305time-critical applications. You should only modify a an option if you
306are sure you need it.
307</p>
308
309<p class=parameters>
310<tt>Option</tt> is a string with the option name, and <tt>value</tt>
311depends on the option being set:
312
313<ul>
314<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> disables the
315Nagle's algorithm for the connection;
316<li> '<tt>linger</tt>': Controls the action taken when unsent data are
317queued on socket and a close is performed. The value is a table with a
318boolean entry '<tt>on</tt>' and a numeric entry for the time interval
319'<tt>timeout</tt>' in seconds.
320 If the '<tt>on</tt>' field is set to <tt>true</tt>,
321the system will block the process on the close attempt until it is able to
322transmit the data or until '<tt>timeout</tt>' has passed. If '<tt>on</tt>'
323is <tt>false</tt> and a close is issued, the system will process the close
324in a manner that allows the process to continue as quickly as possible. I
325do not advise you to set this to anything other than zero.
326<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
327the periodic transmission of messages on a connected socket. Should the
328 connected party fail to respond to these messages, the connection is
329considered broken and processes using the socket are notified.
330</ul>
331
332<p class=return>
333The method returns 1 in case of success, or <tt>nil</tt> otherwise.
334</p>
335
336<p class=note>
337Note: The descriptions above come from the man pages.
338</p>
339
340<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
341
342<p class=name id=settimeout>
343client:<b>settimeout(</b>value [, mode]<b>)</b><br>
344server:<b>settimeout(</b>value [, mode]<b>)</b>
345</p>
346
347<p class=description>
348Changes the timeout values for the object. By default,
349all I/O operations are blocking. That is, any call to the methods
350<a href=#send><tt>send</tt></a>,
351<a href=#receive><tt>receive</tt></a>, and
352<a href=#accept><tt>accept</tt></a>
353will block indefinitely, until the operation completes. The
354<tt>settimeout</tt> method defines a limit on the amount of time the
355I/O methods can block. When a timeout is set and the specified amount of
356time has elapsed, the affected methods give up and fail with an error code.
357</p>
358
359<p class=parameters>
360The amount of time to wait is specified as the
361<tt>value</tt> parameter, in seconds. There are two timeout modes and
362both can be used together for fine tuning:
363</p>
364
365<ul>
366<li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on
367the amount of time LuaSocket can be blocked by the operating system
368while waiting for completion of any single I/O operation. This is the
369default mode;</li>
370
371<li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on
372the amount of time LuaSocket can block a Lua script before returning from
373a call.</li>
374</ul>
375
376<p class=parameters>
377The <tt>nil</tt> timeout <tt>value</tt> allows operations to block
378indefinitely. Negative timeout values have the same effect.
379</p>
380
381<p class=note>
382Note: although timeout values have millisecond precision in LuaSocket,
383large blocks can cause I/O functions not to respect timeout values due
384to the time the library takes to transfer blocks to and from the OS
385and to and from the Lua interpreter.
386</p>
387
388<p class=note>
389Note: The old <tt>timeout</tt> method is deprecated. The name has been
390changed for sake of uniformity, since all other method names already
391contained verbs making their imperative nature obvious.
392</p>
393
394<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
395
396<div class=footer>
397<hr>
398<center>
399<p class=bar>
400<a href="home.html">home</a> &middot;
401<a href="home.html#down">download</a> &middot;
402<a href="introduction.html">introduction</a> &middot;
403<a href="reference.html">reference</a>
404</p>
405<p>
406<small>
407Last modified by Diego Nehab on <br>
408Sat Aug 9 01:00:41 PDT 2003
409</small>
410</p>
411</center>
412</div>
413
414</body>
415</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-15 05:11:20 +0000