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