Mercurial > luasocket

comparison doc/udp.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 UDP support">
7 <meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support">
8 <title>LuaSocket: UDP 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
38 <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40 <h2 id=udp>UDP</h2>
41
42 <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
43
44 <p class="name" id="socket.udp">
45 socket.<b>udp()</b>
46 </p>
47
48 <p class="description">
49 Creates and returns an unconnected UDP object. Unconnected objects support the
50 <a href="#sendto"><tt>sendto</tt></a>,
51 <a href="#receive"><tt>receive</tt></a>,
52 <a href="#receivefrom"><tt>receivefrom</tt></a>,
53 <a href="#getsockname"><tt>getsockname</tt></a>,
54 <a href="#setoption"><tt>setoption</tt></a>,
55 <a href="#settimeout"><tt>settimeout</tt></a>,
56 <a href="#setpeername"><tt>setpeername</tt></a>,
57 <a href="#setsockname"><tt>setsockname</tt></a>, and
58 <a href="#close"><tt>close</tt></a>.
59 The <a href="#setpeername"><tt>setpeername</tt></a>
60 is used to connect the object.
61 </p>
62
63 <p class="return">
64 In case of success, a new unconnected UDP object
65 returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
66 an error message.
67 </p>
68
69 <!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
70
71 <p class="name" id="close">
72 connected:<b>close()</b><br>
73 unconnected:<b>close()</b>
74 </p>
75
76 <p class="description">
77 Closes a UDP object. The internal socket
78 used by the object is closed and the local address to which the
79 object was bound is made available to other applications. No
80 further operations (except for further calls to the <tt>close</tt>
81 method) are allowed on a closed socket.
82 </p>
83
84 <p class="note">
85 Note: It is important to close all used sockets
86 once they are not needed, since, in many systems, each socket uses
87 a file descriptor, which are limited system resources.
88 Garbage-collected objects are automatically closed before
89 destruction, though.
90 </p>
91
92 <!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
93
94 <p class="name" id="getpeername">
95 connected:<b>getpeername()</b>
96 </p>
97
98 <p class="description">
99 Retrieves information about the peer
100 associated with a connected UDP object.
101 </p>
102
103 <p class="return">
104 Returns the IP address and port number of the peer.
105 </p>
106
107 <p class="note">
108 Note: It makes no sense to call this method on unconnected objects.
109 </p>
110
111 <!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
112
113 <p class="name" id="getsockname">
114 connected:<b>getsockname()</b><br>
115 unconnected:<b>getsockname()</b>
116 </p>
117
118 <p class="description">
119 Returns the local address information associated to the object.
120 </p>
121
122 <p class="return">
123 The method returns a string with local IP
124 address and a number with the port. In case of error, the method
125 returns <b><tt>nil</tt></b>.
126 </p>
127
128 <p class="note">
129 Note: UDP sockets are not bound to any address
130 until the <a href="#setsockname"><tt>setsockname</tt></a> or the
131 <a href="#sendto"><tt>sendto</tt></a> method is called for the
132 first time (in which case it is bound to an ephemeral port and the
133 wild-card address).
134 </p>
135
136 <!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
137
138 <p class="name" id="receive">
139 connected:<b>receive(</b>[size]<b>)</b><br>
140 unconnected:<b>receive(</b>[size]<b>)</b>
141 </p>
142
143 <p class="description">
144 Receives a datagram from the UDP object. If
145 the UDP object is connected, only datagrams coming from the peer
146 are accepted. Otherwise, the returned datagram can come from any
147 host.
148 </p>
149
150 <p class="parameters">
151 The optional <tt>size</tt> parameter
152 specifies the maximum size of the datagram to be retrieved. If
153 there are more than <tt>size</tt> bytes available in the datagram,
154 the excess bytes are discarded. If there are less then
155 <tt>size</tt> bytes available in the current datagram, the
156 available bytes are returned. If <tt>size</tt> is omitted, the
157 maximum datagram size is used (which is currently limited by the
158 implementation to 8192 bytes).
159 </p>
160
161 <p class="return">
162 In case of success, the method returns the
163 received datagram. In case of timeout, the method returns
164 <b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
165 </p>
166
167 <!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
168
169 <p class="name" id="receivefrom">
170 unconnected:<b>receivefrom(</b>[size]<b>)</b>
171 </p>
172
173 <p class="description">
174 Works exactly as the <a href="#receive"><tt>receive</tt></a>
175 method, except it returns the IP
176 address and port as extra return values (and is therefore slightly less
177 efficient).
178 </p>
179
180 <!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
181
182 <p class="name" id="send">
183 connected:<b>send(</b>datagram<b>)</b>
184 </p>
185
186 <p class="description">
187 Sends a datagram to the UDP peer of a connected object.
188 </p>
189
190 <p class="parameters">
191 <tt>Datagram</tt> is a string with the datagram contents.
192 The maximum datagram size for UDP is 64K minus IP layer overhead.
193 However datagrams larger than the link layer packet size will be
194 fragmented, which may deteriorate performance and/or reliability.
195 </p>
196
197 <p class="return">
198 If successful, the method returns 1. In case of
199 error, the method returns <b><tt>nil</tt></b> followed by an error message.
200 </p>
201
202 <p class="note">
203 Note: In UDP, the <tt>send</tt> method never blocks
204 and the only way it can fail is if the underlying transport layer
205 refuses to send a message to the specified address (i.e. no
206 interface accepts the address).
207 </p>
208
209 <!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
210
211 <p class="name" id="sendto">
212 unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
213 </p>
214
215 <p class="description">
216 Sends a datagram to the specified IP address and port number.
217 </p>
218
219 <p class="parameters">
220 <tt>Datagram</tt> is a string with the
221 datagram contents.
222 The maximum datagram size for UDP is 64K minus IP layer overhead.
223 However datagrams larger than the link layer packet size will be
224 fragmented, which may deteriorate performance and/or reliability.
225 <tt>Ip</tt> is the IP address of the recipient.
226 Host names are <em>not</em> allowed for performance reasons.
227
228 <tt>Port</tt> is the port number at the recipient.
229 </p>
230
231 <p class="return">
232 If successful, the method returns 1. In case of
233 error, the method returns <b><tt>nil</tt></b> followed by an error message.
234 </p>
235
236 <p class="note">
237 Note: In UDP, the <tt>send</tt> method never blocks
238 and the only way it can fail is if the underlying transport layer
239 refuses to send a message to the specified address (i.e. no
240 interface accepts the address).
241 </p>
242
243 <!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
244
245 <p class="name" id="setpeername">
246 connected:<b>setpeername(</b>'*'<b>)</b><br>
247 unconnected:<b>setpeername(</b>address, port<b>)</b>
248 </p>
249
250 <p class="description">
251 Changes the peer of a UDP object. This
252 method turns an unconnected UDP object into a connected UDP
253 object or vice versa.
254 </p>
255
256 <p class="description">
257 For connected objects, outgoing datagrams
258 will be sent to the specified peer, and datagrams received from
259 other peers will be discarded by the OS. Connected UDP objects must
260 use the <a href="#send"><tt>send</tt></a> and
261 <a href="#receive"><tt>receive</tt></a> methods instead of
262 <a href="#sendto"><tt>sendto</tt></a> and
263 <a href="#receivefrom"><tt>receivefrom</tt></a>.
264 </p>
265
266 <p class="parameters">
267 <tt>Address</tt> can be an IP address or a
268 host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
269 '<tt>*</tt>' and the object is connected, the peer association is
270 removed and the object becomes an unconnected object again. In that
271 case, the <tt>port</tt> argument is ignored.
272 </p>
273
274 <p class="return">
275 In case of error the method returns
276 <b><tt>nil</tt></b> followed by an error message. In case of success, the
277 method returns 1.
278 </p>
279
280 <p class="note">
281 Note: Since the address of the peer does not have
282 to be passed to and from the OS, the use of connected UDP objects
283 is recommended when the same peer is used for several transmissions
284 and can result in up to 30% performance gains.
285 </p>
286
287 <!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
288
289 <p class="name" id="setsockname">
290 unconnected:<b>setsockname(</b>address, port<b>)</b>
291 </p>
292
293 <p class="description">
294 Binds the UDP object to a local address.
295 </p>
296
297 <p class="parameters">
298 <tt>Address</tt> can be an IP address or a
299 host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
300 all local interfaces using the constant <tt>INADDR_ANY</tt>. If
301 <tt>port</tt> is 0, the system chooses an ephemeral port.
302 </p>
303
304 <p class="return">
305 If successful, the method returns 1. In case of
306 error, the method returns <b><tt>nil</tt></b> followed by an error
307 message.
308 </p>
309
310 <p class="note">
311 Note: This method can only be called before any
312 datagram is sent through the UDP object, and only once. Otherwise,
313 the system automatically binds the object to all local interfaces
314 and chooses an ephemeral port as soon as the first datagram is
315 sent. After the local address is set, either automatically by the
316 system or explicitly by <tt>setsockname</tt>, it cannot be
317 changed.
318 </p>
319
320 <!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
321
322 <p class="name" id="setoption">
323 connected:<b>setoption(</b>option [, value]<b>)</b><br>
324 unconnected:<b>setoption(</b>option [, value]<b>)</b>
325 </p>
326
327 <p class="description">
328 Sets options for the UDP object. Options are
329 only needed by low-level or time-critical applications. You should
330 only modify an option if you are sure you need it.</p>
331 <p class="parameters"><tt>Option</tt> is a string with the option
332 name, and <tt>value</tt> depends on the option being set:
333 </p>
334
335 <ul>
336 <li>'<tt>dontroute</tt>': Setting this option to <tt>true</tt>
337 indicates that outgoing messages should bypass the standard routing
338 facilities;</li>
339 <li>'<tt>broadcast</tt>': Setting this option to <tt>true</tt>
340 requests permission to send broadcast datagrams on the
341 socket.</li>
342 </ul>
343
344 <p class="return">
345 The method returns 1 in case of success, or
346 <b><tt>nil</tt></b> followed by an error message otherwise.
347 </p>
348
349 <p class="note">
350 Note: The descriptions above come from the man
351 pages.
352 </p>
353
354 <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
355
356 <p class="name" id="settimeout">
357 connected:<b>settimeout(</b>value<b>)</b><br>
358 unconnected:<b>settimeout(</b>value<b>)</b>
359 </p>
360
361 <p class="description">
362 Changes the timeout values for the object. By default, the
363 <a href="#receive"><tt>receive</tt></a> and
364 <a href="#receivefrom"><tt>receivefrom</tt></a>
365 operations are blocking. That is, any call to the methods will block
366 indefinitely, until data arrives. The <tt>settimeout</tt> function defines
367 a limit on the amount of time the functions can block. When a timeout is
368 set and the specified amount of time has elapsed, the affected methods
369 give up and fail with an error code.
370 </p>
371
372 <p class="parameters">
373 The amount of time to wait is specified as
374 the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
375 <tt>value</tt> allows operations to block indefinitely. Negative
376 timeout values have the same effect.
377 </p>
378
379 <p class="note">
380 Note: In UDP, the <a href="#send"><tt>send</tt></a>
381 and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
382 datagram is just passed to the OS and the call returns
383 immediately). Therefore, the <tt>settimeout</tt> method has no
384 effect on them.
385 </p>
386
387 <p class="note">
388 Note: The old <tt>timeout</tt> method is
389 deprecated. The name has been changed for sake of uniformity, since
390 all other method names already contained verbs making their
391 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#download">download</a> &middot;
402 <a href="installation.html">installation</a> &middot;
403 <a href="introduction.html">introduction</a> &middot;
404 <a href="reference.html">reference</a>
405 </p>
406 <p>
407 <small>
408 Last modified by Diego Nehab on <br>
409 Thu Apr 20 00:26:01 EDT 2006
410 </small>
411 </p>
412 </center>
413 </div>
414
415 </body>
416 </html>