aboutsummaryrefslogtreecommitdiff
path: root/doc/udp.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/udp.html')
-rw-r--r--doc/udp.html578
1 files changed, 0 insertions, 578 deletions
diff --git a/doc/udp.html b/doc/udp.html
deleted file mode 100644
index a300f2f..0000000
--- a/doc/udp.html
+++ /dev/null
@@ -1,578 +0,0 @@
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="index.html">home</a> &middot;
28<a href="index.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">
45socket.<b>udp()</b>
46</p>
47
48<p class="description">
49Creates and returns an unconnected UDP object.
50Unconnected objects support the
51<a href="#sendto"><tt>sendto</tt></a>,
52<a href="#receive"><tt>receive</tt></a>,
53<a href="#receivefrom"><tt>receivefrom</tt></a>,
54<a href="#getoption"><tt>getoption</tt></a>,
55<a href="#getsockname"><tt>getsockname</tt></a>,
56<a href="#setoption"><tt>setoption</tt></a>,
57<a href="#settimeout"><tt>settimeout</tt></a>,
58<a href="#setpeername"><tt>setpeername</tt></a>,
59<a href="#setsockname"><tt>setsockname</tt></a>, and
60<a href="#close"><tt>close</tt></a>.
61The <a href="#setpeername"><tt>setpeername</tt></a>
62is used to connect the object.
63</p>
64
65<p class="return">
66In case of success, a new unconnected UDP object
67returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
68an error message.
69</p>
70
71<p class=note>
72Note: The choice between IPv4 and IPv6 happens during a call to
73<a href=#sendto><tt>sendto</tt></a>, <a
74href=#setpeername><tt>setpeername</tt></a>, or <a
75href=#setsockname><tt>sockname</tt></a>, depending on the address
76family obtained from the resolver.
77</p>
78
79<p class=note>
80Note: Before the choice between IPv4 and IPv6 happens,
81the internal socket object is invalid and therefore <a
82href=#setoption><tt>setoption</tt></a> will fail.
83</p>
84
85<!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
86
87<p class="name" id="socket.udp">
88socket.<b>udp4()</b>
89</p>
90
91<p class="description">
92Creates and returns an unconnected IPv4 UDP object.
93Unconnected objects support the
94<a href="#sendto"><tt>sendto</tt></a>,
95<a href="#receive"><tt>receive</tt></a>,
96<a href="#receivefrom"><tt>receivefrom</tt></a>,
97<a href="#getoption"><tt>getoption</tt></a>,
98<a href="#getsockname"><tt>getsockname</tt></a>,
99<a href="#setoption"><tt>setoption</tt></a>,
100<a href="#settimeout"><tt>settimeout</tt></a>,
101<a href="#setpeername"><tt>setpeername</tt></a>,
102<a href="#setsockname"><tt>setsockname</tt></a>, and
103<a href="#close"><tt>close</tt></a>.
104The <a href="#setpeername"><tt>setpeername</tt></a>
105is used to connect the object.
106</p>
107
108<p class="return">
109In case of success, a new unconnected UDP object
110returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
111an error message.
112</p>
113
114<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
115
116<p class="name" id="socket.udp6">
117socket.<b>udp6()</b>
118</p>
119
120<p class="description">
121Creates and returns an unconnected IPv6 UDP object.
122Unconnected objects support the
123<a href="#sendto"><tt>sendto</tt></a>,
124<a href="#receive"><tt>receive</tt></a>,
125<a href="#receivefrom"><tt>receivefrom</tt></a>,
126<a href="#getoption"><tt>getoption</tt></a>,
127<a href="#getsockname"><tt>getsockname</tt></a>,
128<a href="#setoption"><tt>setoption</tt></a>,
129<a href="#settimeout"><tt>settimeout</tt></a>,
130<a href="#setpeername"><tt>setpeername</tt></a>,
131<a href="#setsockname"><tt>setsockname</tt></a>, and
132<a href="#close"><tt>close</tt></a>.
133The <a href="#setpeername"><tt>setpeername</tt></a>
134is used to connect the object.
135</p>
136
137<p class="return">
138In case of success, a new unconnected UDP object
139returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
140an error message.
141</p>
142
143<p class=note>
144Note: The TCP object returned will have the option
145"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
146</p>
147
148<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
149
150<p class="name" id="close">
151connected:<b>close()</b><br>
152unconnected:<b>close()</b>
153</p>
154
155<p class="description">
156Closes a UDP object. The internal socket
157used by the object is closed and the local address to which the
158object was bound is made available to other applications. No
159further operations (except for further calls to the <tt>close</tt>
160method) are allowed on a closed socket.
161</p>
162
163<p class="note">
164Note: It is important to close all used sockets
165once they are not needed, since, in many systems, each socket uses
166a file descriptor, which are limited system resources.
167Garbage-collected objects are automatically closed before
168destruction, though.
169</p>
170
171<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
172
173<p class="name" id="getpeername">
174connected:<b>getpeername()</b>
175</p>
176
177<p class="description">
178Retrieves information about the peer
179associated with a connected UDP object.
180</p>
181
182
183<p class=return>
184Returns a string with the IP address of the peer, the
185port number that peer is using for the connection,
186and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
187In case of error, the method returns <b><tt>nil</tt></b>.
188</p>
189
190<p class="note">
191Note: It makes no sense to call this method on unconnected objects.
192</p>
193
194<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
195
196<p class="name" id="getsockname">
197connected:<b>getsockname()</b><br>
198unconnected:<b>getsockname()</b>
199</p>
200
201<p class="description">
202Returns the local address information associated to the object.
203</p>
204
205
206<p class=return>
207The method returns a string with local IP address, a number with
208the local port,
209and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
210In case of error, the method returns <b><tt>nil</tt></b>.
211</p>
212
213<p class="note">
214Note: UDP sockets are not bound to any address
215until the <a href="#setsockname"><tt>setsockname</tt></a> or the
216<a href="#sendto"><tt>sendto</tt></a> method is called for the
217first time (in which case it is bound to an ephemeral port and the
218wild-card address).
219</p>
220
221<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
222
223<p class="name" id="receive">
224connected:<b>receive(</b>[size]<b>)</b><br>
225unconnected:<b>receive(</b>[size]<b>)</b>
226</p>
227
228<p class="description">
229Receives a datagram from the UDP object. If
230the UDP object is connected, only datagrams coming from the peer
231are accepted. Otherwise, the returned datagram can come from any
232host.
233</p>
234
235<p class="parameters">
236The optional <tt>size</tt> parameter
237specifies the maximum size of the datagram to be retrieved. If
238there are more than <tt>size</tt> bytes available in the datagram,
239the excess bytes are discarded. If there are less then
240<tt>size</tt> bytes available in the current datagram, the
241available bytes are returned. If <tt>size</tt> is omitted, the
242maximum datagram size is used (which is currently limited by the
243implementation to 8192 bytes).
244</p>
245
246<p class="return">
247In case of success, the method returns the
248received datagram. In case of timeout, the method returns
249<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
250</p>
251
252<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253
254<p class="name" id="receivefrom">
255unconnected:<b>receivefrom(</b>[size]<b>)</b>
256</p>
257
258<p class="description">
259Works exactly as the <a href="#receive"><tt>receive</tt></a>
260method, except it returns the IP
261address and port as extra return values (and is therefore slightly less
262efficient).
263</p>
264
265<!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
266
267<p class="name" id="getoption">
268connected:<b>getoption()</b><br>
269unconnected:<b>getoption()</b>
270</p>
271
272<p class="description">
273Gets an option value from the UDP object.
274See <a href=#setoption><tt>setoption</tt></a> for
275description of the option names and values.
276</p>
277
278<p class="parameters"><tt>Option</tt> is a string with the option name.
279<ul>
280<li> '<tt>dontroute</tt>'
281<li> '<tt>broadcast</tt>'
282<li> '<tt>reuseaddr</tt>'
283<li> '<tt>reuseport</tt>'
284<li> '<tt>ip-multicast-loop</tt>'
285<li> '<tt>ipv6-v6only</tt>'
286<li> '<tt>ip-multicast-if</tt>'
287<li> '<tt>ip-multicast-ttl</tt>'
288<li> '<tt>ip-add-membership</tt>'
289<li> '<tt>ip-drop-membership</tt>'
290</ul>
291</p>
292
293<p class=return>
294The method returns the option <tt>value</tt> in case of
295success, or
296<b><tt>nil</tt></b> followed by an error message otherwise.
297</p>
298
299<!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
300
301<p class="name" id="send">
302connected:<b>send(</b>datagram<b>)</b>
303</p>
304
305<p class="description">
306Sends a datagram to the UDP peer of a connected object.
307</p>
308
309<p class="parameters">
310<tt>Datagram</tt> is a string with the datagram contents.
311The maximum datagram size for UDP is 64K minus IP layer overhead.
312However datagrams larger than the link layer packet size will be
313fragmented, which may deteriorate performance and/or reliability.
314</p>
315
316<p class="return">
317If successful, the method returns 1. In case of
318error, the method returns <b><tt>nil</tt></b> followed by an error message.
319</p>
320
321<p class="note">
322Note: In UDP, the <tt>send</tt> method never blocks
323and the only way it can fail is if the underlying transport layer
324refuses to send a message to the specified address (i.e. no
325interface accepts the address).
326</p>
327
328<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
329
330<p class="name" id="sendto">
331unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
332</p>
333
334<p class="description">
335Sends a datagram to the specified IP address and port number.
336</p>
337
338<p class="parameters">
339<tt>Datagram</tt> is a string with the
340datagram contents.
341The maximum datagram size for UDP is 64K minus IP layer overhead.
342However datagrams larger than the link layer packet size will be
343fragmented, which may deteriorate performance and/or reliability.
344<tt>Ip</tt> is the IP address of the recipient.
345Host names are <em>not</em> allowed for performance reasons.
346
347<tt>Port</tt> is the port number at the recipient.
348</p>
349
350<p class="return">
351If successful, the method returns 1. In case of
352error, the method returns <b><tt>nil</tt></b> followed by an error message.
353</p>
354
355<p class="note">
356Note: In UDP, the <tt>send</tt> method never blocks
357and the only way it can fail is if the underlying transport layer
358refuses to send a message to the specified address (i.e. no
359interface accepts the address).
360</p>
361
362<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
363
364<p class="name" id="setpeername">
365connected:<b>setpeername(</b>'*'<b>)</b><br>
366unconnected:<b>setpeername(</b>address, port<b>)</b>
367</p>
368
369<p class="description">
370Changes the peer of a UDP object. This
371method turns an unconnected UDP object into a connected UDP
372object or vice versa.
373</p>
374
375<p class="description">
376For connected objects, outgoing datagrams
377will be sent to the specified peer, and datagrams received from
378other peers will be discarded by the OS. Connected UDP objects must
379use the <a href="#send"><tt>send</tt></a> and
380<a href="#receive"><tt>receive</tt></a> methods instead of
381<a href="#sendto"><tt>sendto</tt></a> and
382<a href="#receivefrom"><tt>receivefrom</tt></a>.
383</p>
384
385<p class="parameters">
386<tt>Address</tt> can be an IP address or a
387host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
388'<tt>*</tt>' and the object is connected, the peer association is
389removed and the object becomes an unconnected object again. In that
390case, the <tt>port</tt> argument is ignored.
391</p>
392
393<p class="return">
394In case of error the method returns
395<b><tt>nil</tt></b> followed by an error message. In case of success, the
396method returns 1.
397</p>
398
399<p class="note">
400Note: Since the address of the peer does not have
401to be passed to and from the OS, the use of connected UDP objects
402is recommended when the same peer is used for several transmissions
403and can result in up to 30% performance gains.
404</p>
405
406<p class=note>
407Note: Starting with LuaSocket 3.0, the host name resolution
408depends on whether the socket was created by <a
409href=#socket.udp><tt>socket.udp</tt></a> or <a
410href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
411the appropriate family are tried in succession until the
412first success or until the last failure.
413</p>
414
415<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
416
417<p class="name" id="setsockname">
418unconnected:<b>setsockname(</b>address, port<b>)</b>
419</p>
420
421<p class="description">
422Binds the UDP object to a local address.
423</p>
424
425<p class="parameters">
426<tt>Address</tt> can be an IP address or a
427host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
428all local interfaces using the constant <tt>INADDR_ANY</tt>. If
429<tt>port</tt> is 0, the system chooses an ephemeral port.
430</p>
431
432<p class="return">
433If successful, the method returns 1. In case of
434error, the method returns <b><tt>nil</tt></b> followed by an error
435message.
436</p>
437
438<p class="note">
439Note: This method can only be called before any
440datagram is sent through the UDP object, and only once. Otherwise,
441the system automatically binds the object to all local interfaces
442and chooses an ephemeral port as soon as the first datagram is
443sent. After the local address is set, either automatically by the
444system or explicitly by <tt>setsockname</tt>, it cannot be
445changed.
446</p>
447
448<!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
449
450<p class="name" id="setoption">
451connected:<b>setoption(</b>option [, value]<b>)</b><br>
452unconnected:<b>setoption(</b>option [, value]<b>)</b>
453</p>
454
455<p class="description">
456Sets options for the UDP object. Options are
457only needed by low-level or time-critical applications. You should
458only modify an option if you are sure you need it.</p>
459<p class="parameters"><tt>Option</tt> is a string with the option
460name, and <tt>value</tt> depends on the option being set:
461</p>
462
463<ul>
464<li> '<tt>dontroute</tt>': Indicates that outgoing
465messages should bypass the standard routing facilities.
466Receives a boolean value;
467<li> '<tt>broadcast</tt>': Requests permission to send
468broadcast datagrams on the socket.
469Receives a boolean value;
470<li> '<tt>reuseaddr</tt>': Indicates that the rules used in
471validating addresses supplied in a <tt>bind()</tt> call
472should allow reuse of local addresses.
473Receives a boolean value;
474<li> '<tt>reuseport</tt>': Allows completely duplicate
475bindings by multiple processes if they all set
476'<tt>reuseport</tt>' before binding the port.
477Receives a boolean value;
478<li> '<tt>ip-multicast-loop</tt>':
479Specifies whether or not a copy of an outgoing multicast
480datagram is delivered to the sending host as long as it is a
481member of the multicast group.
482Receives a boolean value;
483<li> '<tt>ipv6-v6only</tt>':
484Specifies whether to restrict <tt>inet6</tt> sockets to
485sending and receiving only IPv6 packets.
486Receive a boolean value;
487<li> '<tt>ip-multicast-if</tt>':
488Sets the interface over which outgoing multicast datagrams
489are sent.
490Receives an IP address;
491<li> '<tt>ip-multicast-ttl</tt>':
492Sets the Time To Live in the IP header for outgoing
493multicast datagrams.
494Receives a number;
495<li> '<tt>ip-add-membership</tt>':
496Joins the multicast group specified.
497Receives a table with fields
498<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
499IP address;
500<li> '<tt>ip-drop-membership</tt>': Leaves the multicast
501group specified.
502Receives a table with fields
503<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
504IP address.
505</ul>
506
507<p class="return">
508The method returns 1 in case of success, or
509<b><tt>nil</tt></b> followed by an error message otherwise.
510</p>
511
512<p class=note>
513Note: The descriptions above come from the man pages.
514</p>
515
516<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
517
518<p class="name" id="settimeout">
519connected:<b>settimeout(</b>value<b>)</b><br>
520unconnected:<b>settimeout(</b>value<b>)</b>
521</p>
522
523<p class="description">
524Changes the timeout values for the object. By default, the
525<a href="#receive"><tt>receive</tt></a> and
526<a href="#receivefrom"><tt>receivefrom</tt></a>
527operations are blocking. That is, any call to the methods will block
528indefinitely, until data arrives. The <tt>settimeout</tt> function defines
529a limit on the amount of time the functions can block. When a timeout is
530set and the specified amount of time has elapsed, the affected methods
531give up and fail with an error code.
532</p>
533
534<p class="parameters">
535The amount of time to wait is specified as
536the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
537<tt>value</tt> allows operations to block indefinitely. Negative
538timeout values have the same effect.
539</p>
540
541<p class="note">
542Note: In UDP, the <a href="#send"><tt>send</tt></a>
543and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
544datagram is just passed to the OS and the call returns
545immediately). Therefore, the <tt>settimeout</tt> method has no
546effect on them.
547</p>
548
549<p class="note">
550Note: The old <tt>timeout</tt> method is
551deprecated. The name has been changed for sake of uniformity, since
552all other method names already contained verbs making their
553imperative nature obvious.
554</p>
555
556<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
557
558<div class=footer>
559<hr>
560<center>
561<p class=bar>
562<a href="index.html">home</a> &middot;
563<a href="index.html#download">download</a> &middot;
564<a href="installation.html">installation</a> &middot;
565<a href="introduction.html">introduction</a> &middot;
566<a href="reference.html">reference</a>
567</p>
568<p>
569<small>
570Last modified by Diego Nehab on <br>
571Thu Apr 20 00:26:01 EDT 2006
572</small>
573</p>
574</center>
575</div>
576
577</body>
578</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-04 22:35:35 +0000