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