Mercurial > luasocket

comparison doc/socket.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 core namespace">
7 <meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
8 <title>LuaSocket: The socket namespace</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 <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39 <h2 id=socket>The socket namespace</h2>
40
41 <p>
42 The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
43 </p>
44
45 <p>
46 To obtain the <tt>socket</tt> namespace, run:
47 </p>
48
49 <pre class=example>
50 -- loads the socket module
51 local socket = require("socket")
52 </pre>
53
54 <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
55
56 <p class=name id=bind>
57 socket.<b>bind(</b>address, port [, backlog]<b>)</b>
58 </p>
59
60 <p class=description>
61 This function is a shortcut that creates and returns a TCP server object
62 bound to a local <tt>address</tt> and <tt>port</tt>, ready to
63 accept client connections. Optionally,
64 user can also specify the <tt>backlog</tt> argument to the
65 <a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32).
66 </p>
67
68 <p class=note>
69 Note: The server object returned will have the option "<tt>reuseaddr</tt>"
70 set to <tt><b>true</b></tt>.
71 </p>
72
73 <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
74
75 <p class=name id=connect>
76 socket.<b>connect(</b>address, port [, locaddr, locport]<b>)</b>
77 </p>
78
79 <p class=description>
80 This function is a shortcut that creates and returns a TCP client object
81 connected to a remote <tt>host</tt> at a given <tt>port</tt>. Optionally,
82 the user can also specify the local address and port to bind
83 (<tt>locaddr</tt> and <tt>locport</tt>).
84 </p>
85
86 <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
87
88 <p class=name id=debug>
89 socket.<b>_DEBUG</b>
90 </p>
91
92 <p class=description>
93 This constant is set to <tt><b>true</b></tt> if the library was compiled
94 with debug support.
95 </p>
96
97 <!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
98
99 <p class=name id=newtry>
100 socket.<b>newtry(</b>finalizer<b>)</b>
101 </p>
102
103 <p class=description>
104 Creates and returns a <em>clean</em>
105 <a href="#try"><tt>try</tt></a>
106 function that allows for cleanup before the exception
107 is raised.
108 </p>
109
110 <p class=parameters>
111 <tt>Finalizer</tt> is a function that will be called before
112 <tt>try</tt> throws the exception. It will be called
113 in <em>protected</em> mode.
114 </p>
115
116 <p class=return>
117 The function returns your customized <tt>try</tt> function.
118 </p>
119
120 <p class=note>
121 Note: This idea saved a <em>lot</em> of work with the
122 implementation of protocols in LuaSocket:
123 </p>
124
125 <pre class=example>
126 foo = socket.protect(function()
127 -- connect somewhere
128 local c = socket.try(socket.connect("somewhere", 42))
129 -- create a try function that closes 'c' on error
130 local try = socket.newtry(function() c:close() end)
131 -- do everything reassured c will be closed
132 try(c:send("hello there?\r\n"))
133 local answer = try(c:receive())
134 ...
135 try(c:send("good bye\r\n"))
136 c:close()
137 end)
138 </pre>
139
140
141 <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
142
143 <p class=name id=protect>
144 socket.<b>protect(</b>func<b>)</b>
145 </p>
146
147 <p class=description>
148 Converts a function that throws exceptions into a safe function. This
149 function only catches exceptions thrown by the <a href=#try><tt>try</tt></a>
150 and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal
151 Lua errors.
152 </p>
153
154 <p class=parameters>
155 <tt>Func</tt> is a function that calls
156 <a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
157 to throw exceptions.
158 </p>
159
160 <p class=return>
161 Returns an equivalent function that instead of throwing exceptions,
162 returns <tt><b>nil</b></tt> followed by an error message.
163 </p>
164
165 <p class=note>
166 Note: Beware that if your function performs some illegal operation that
167 raises an error, the protected function will catch the error and return it
168 as a string. This is because the <a href=#try><tt>try</tt></a> function
169 uses errors as the mechanism to throw exceptions.
170 </p>
171
172 <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
173
174 <p class=name id=select>
175 socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
176 </p>
177
178 <p class=description>
179 Waits for a number of sockets to change status.
180 </p>
181
182 <p class=parameters>
183 <tt>Recvt</tt> is an array with the sockets to test for characters
184 available for reading. Sockets in the <tt>sendt</tt> array are watched to
185 see if it is OK to immediately write on them. <tt>Timeout</tt> is the
186 maximum amount of time (in seconds) to wait for a change in status. A
187 <tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
188 function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
189 be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
190 non-numeric indices) in the arrays will be silently ignored.
191 </p>
192
193 <p class=return> The function returns a list with the sockets ready for
194 reading, a list with the sockets ready for writing and an error message.
195 The error message is "<tt>timeout</tt>" if a timeout condition was met and
196 <tt><b>nil</b></tt> otherwise. The returned tables are
197 doubly keyed both by integers and also by the sockets
198 themselves, to simplify the test if a specific socket has
199 changed status.
200 </p>
201
202 <p class=note>
203 <b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
204 on non-blocking TCP sockets. The function may return a socket as
205 writable even though the socket is <em>not</em> ready for sending.
206 </p>
207
208 <p class=note>
209 <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
210 <a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
211 Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
212 method or <tt>accept</tt> might block forever.
213 </p>
214
215 <p class=note>
216 <b>Yet another note</b>: If you close a socket and pass
217 it to <tt>select</tt>, it will be ignored.
218 </p>
219
220 <!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
221
222 <p class=name id=sink>
223 socket.<b>sink(</b>mode, socket<b>)</b>
224 </p>
225
226 <p class=description>
227 Creates an
228 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
229 sink from a stream socket object.
230 </p>
231
232 <p class=parameters>
233 <tt>Mode</tt> defines the behavior of the sink. The following
234 options are available:
235 </p>
236 <ul>
237 <li> <tt>"http-chunked"</tt>: sends data through socket after applying the
238 <em>chunked transfer coding</em>, closing the socket when done;
239 <li> <tt>"close-when-done"</tt>: sends all received data through the
240 socket, closing the socket when done;
241 <li> <tt>"keep-open"</tt>: sends all received data through the
242 socket, leaving it open when done.
243 </ul>
244 <p>
245 <tt>Socket</tt> is the stream socket object used to send the data.
246 </p>
247
248 <p class=return>
249 The function returns a sink with the appropriate behavior.
250 </p>
251
252 <!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253
254 <p class=name id=skip>
255 socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
256 </p>
257
258 <p class=description>
259 Drops a number of arguments and returns the remaining.
260 </p>
261
262 <p class=parameters>
263 <tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
264 <tt>ret<sub>N</sub></tt> are the arguments.
265 </p>
266
267 <p class=return>
268 The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
269 </p>
270
271 <p class=note>
272 Note: This function is useful to avoid creation of dummy variables:
273 </p>
274
275 <pre class=example>
276 -- get the status code and separator from SMTP server reply
277 local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
278 </pre>
279
280 <!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
281
282 <p class=name id=sleep>
283 socket.<b>sleep(</b>time<b>)</b>
284 </p>
285
286 <p class=description>
287 Freezes the program execution during a given amount of time.
288 </p>
289
290 <p class=parameters>
291 <tt>Time</tt> is the number of seconds to sleep for.
292 </p>
293
294 <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
295
296 <p class=name id=source>
297 socket.<b>source(</b>mode, socket [, length]<b>)</b>
298 </p>
299
300 <p class=description>
301 Creates an
302 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
303 source from a stream socket object.
304 </p>
305
306 <p class=parameters>
307 <tt>Mode</tt> defines the behavior of the source. The following
308 options are available:
309 </p>
310 <ul>
311 <li> <tt>"http-chunked"</tt>: receives data from socket and removes the
312 <em>chunked transfer coding</em> before returning the data;
313 <li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
314 socket. This mode requires the extra argument <tt>length</tt>;
315 <li> <tt>"until-closed"</tt>: receives data from a socket until the other
316 side closes the connection.
317 </ul>
318 <p>
319 <tt>Socket</tt> is the stream socket object used to receive the data.
320 </p>
321
322 <p class=return>
323 The function returns a source with the appropriate behavior.
324 </p>
325
326 <!-- time ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
327
328 <p class=name id=gettime>
329 socket.<b>gettime()</b>
330 </p>
331
332 <p class=description>
333 Returns the time in seconds, relative to the origin of the
334 universe. You should subtract the values returned by this function
335 to get meaningful values.
336 </p>
337
338 <pre class=example>
339 t = socket.gettime()
340 -- do stuff
341 print(socket.gettime() - t .. " seconds elapsed")
342 </pre>
343
344 <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
345
346 <p class=name id=try>
347 socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
348 </p>
349
350 <p class=description>
351 Throws an exception in case of error. The exception can only be caught
352 by the <a href=#protect><tt>protect</tt></a> function. It does not explode
353 into an error message.
354 </p>
355
356 <p class=parameters>
357 <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
358 arguments, but are usually the return values of a function call
359 nested with <tt>try</tt>.
360 </p>
361
362 <p class=return>
363 The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
364 <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>.
365 </p>
366
367 <pre class=example>
368 -- connects or throws an exception with the appropriate error message
369 c = socket.try(socket.connect("localhost", 80))
370 </pre>
371
372 <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
373
374 <p class=name id=version>
375 socket.<b>_VERSION</b>
376 </p>
377
378 <p class=description>
379 This constant has a string describing the current LuaSocket version.
380 </p>
381
382 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
383
384 <div class=footer>
385 <hr>
386 <center>
387 <p class=bar>
388 <a href="home.html">home</a> &middot;
389 <a href="home.html#down">download</a> &middot;
390 <a href="installation.html">installation</a> &middot;
391 <a href="introduction.html">introduction</a> &middot;
392 <a href="reference.html">reference</a>
393 </p>
394 <p>
395 <small>
396 Last modified by Diego Nehab on <br>
397 Thu Apr 20 00:25:54 EDT 2006
398 </small>
399 </p>
400 </center>
401 </div>
402
403 </body>
404 </html>