aboutsummaryrefslogtreecommitdiff
path: root/docs/unix.html
diff options
context:
space:
mode:
authorThijs Schreijer <thijs@thijsschreijer.nl>2026-09-01 10:00:21 +0200
committerThijs Schreijer <thijs@thijsschreijer.nl>2026-09-01 10:48:40 +0200
commit70f7800986812ad0d1a5dd6f280f66fd2bf1dd12 (patch)
tree36051874b3ce036307d4bb69b3c4058458b6255d /docs/unix.html
parentfa9b35a0cf11bc856cbd8bffbef5ad6fb3e62a93 (diff)
downloadluasocket-docs/pre-release-audit.tar.gz
luasocket-docs/pre-release-audit.tar.bz2
luasocket-docs/pre-release-audit.zip
docs: document socket.unix and socket.serial, fix stale/missing API referencesdocs/pre-release-audit
Pre-release documentation audit against master. Adds the two fully undocumented modules and closes gaps found by diffing every docs/*.html page against its corresponding source: - New docs/unix.html and docs/serial.html (socket.unix stream/dgram and socket.serial were never documented), linked from index.html, introduction.html, socket.html and reference.html. serial.html notes the current lack of a baud/parity/flow-control API and includes an os.execute+stty workaround example. Both note Windows is unsupported. - socket.html: document headers.setcanonic, point to unix/serial modules. - tcp.html: document getfamily, setpeername/setsockname aliases. - udp.html: document getfamily, getfd/setfd, dirty; document the ipv6-multicast-hops/ipv6-unicast-hops aliasing as current (known-buggy) behavior rather than the originally intended semantics. - http.html: correct redirect text (301/302/303/307/308, was 301/302 only); document MAXHEADERLINE/MAXHEADERSIZE. - dns.html: document getnameinfo. - ltn12.html: document source.rewind and BLOCKSIZE. - installation.html: fix stale "LuaSocket 3.0" sample output to 3.1.0. - reference.html: index every anchor added above plus new Unix/Serial blocks.
Diffstat (limited to 'docs/unix.html')
-rw-r--r--docs/unix.html795
1 files changed, 795 insertions, 0 deletions
diff --git a/docs/unix.html b/docs/unix.html
new file mode 100644
index 0000000..de71925
--- /dev/null
+++ b/docs/unix.html
@@ -0,0 +1,795 @@
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: Unix domain socket support">
7<meta name="keywords" content="Lua, LuaSocket, Socket, Unix, Domain, IPC, Library, Support">
8<title>LuaSocket: Unix domain socket 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<!-- unix ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id="unix">Unix domain sockets</h2>
40
41<p>
42Unix domain sockets provide inter-process communication between processes
43on the same host, addressed by a path in the file system rather than by an
44IP address and port. LuaSocket supports both the stream (connection
45oriented, like TCP) and datagram (connectionless, like UDP) flavors.
46</p>
47
48<p class="note">
49Note: This module is only built on Unix-like platforms (Linux, macOS,
50BSD, Haiku). It is not available on Windows.
51</p>
52
53<p>
54Unlike the core <tt>socket</tt> namespace, Unix domain socket support is a
55separate module that must be required explicitly:
56</p>
57
58<pre class="example">
59-- loads the socket.unix module
60local unix = require("socket.unix")
61</pre>
62
63<p>
64The module table returned by <tt>require("socket.unix")</tt> exposes two
65constructors, <a href="#socket.unix.stream"><tt>unix.stream()</tt></a> and
66<a href="#socket.unix.dgram"><tt>unix.dgram()</tt></a>. For backwards
67compatibility, <tt>unix.tcp</tt> and <tt>unix.udp</tt> are aliases for
68<tt>stream</tt> and <tt>dgram</tt> respectively, and the module table
69itself can be called directly as a shortcut for <tt>unix.stream()</tt>
70(i.e. <tt>unix()</tt> is the same as <tt>unix.stream()</tt>).
71</p>
72
73<p class="note">
74Note: Paths passed to <a href="#stream.bind"><tt>bind</tt></a>,
75<a href="#stream.connect"><tt>connect</tt></a> and their datagram
76equivalents are limited by the platform's <tt>sun_path</tt> buffer size
77(commonly around 100&ndash;108 bytes). A path that does not fit returns
78<b><tt>nil</tt></b> followed by the error message '<tt>path too
79long</tt>'.
80</p>
81
82<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
83
84<h3 id="stream">Stream (<tt>socket.unix.stream</tt>)</h3>
85
86<p>
87Stream Unix domain sockets behave like TCP sockets (see
88<a href="tcp.html">TCP</a>): a freshly created object is a <em>master</em>
89object, which becomes a <em>client</em> object after a successful
90<a href="#stream.connect"><tt>connect</tt></a>, or a <em>server</em>
91object after a successful <a href="#stream.listen"><tt>listen</tt></a>
92(itself normally preceded by <a href="#stream.bind"><tt>bind</tt></a>).
93Server objects produce client objects via
94<a href="#stream.accept"><tt>accept</tt></a>. Most methods below work the
95same way as their TCP counterparts, just addressed by path instead of
96IP/port.
97</p>
98
99<!-- stream.accept ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
100
101<p class="name" id="stream.accept">
102server:<b>accept()</b>
103</p>
104
105<p class="description">
106Waits for a remote connection on the server object and returns a client
107object representing that connection. Works exactly like
108<a href="tcp.html#accept"><tt>tcp:accept</tt></a>.
109</p>
110
111<p class="return">
112If a connection is successfully accepted, a client object is returned. If a
113timeout condition is met, the method returns <b><tt>nil</tt></b> followed
114by the error string '<tt>timeout</tt>'. Other errors are reported by
115<b><tt>nil</tt></b> followed by a message describing the error.
116</p>
117
118<!-- stream.bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
119
120<p class="name" id="stream.bind">
121master:<b>bind(</b>path<b>)</b><br>
122master:<b>setsockname(</b>path<b>)</b>
123</p>
124
125<p class="description">
126Binds a master object to a file system <tt>path</tt>. <tt>setsockname</tt>
127is an alias for <tt>bind</tt>.
128</p>
129
130<p class="parameters">
131<tt>Path</tt> is a string with the file system path to bind to. The path
132must not already exist as a socket file &mdash; remove any stale socket
133file left over from a previous run before binding.
134</p>
135
136<p class="return">
137In case of success, the method returns 1. In case of error, the method
138returns <b><tt>nil</tt></b> followed by an error message.
139</p>
140
141<!-- stream.close +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
142
143<p class="name" id="stream.close">
144master:<b>close()</b><br>
145client:<b>close()</b><br>
146server:<b>close()</b>
147</p>
148
149<p class="description">
150Closes a stream Unix domain object. The internal socket used by the object
151is closed. No further operations (except further calls to
152<tt>close</tt>) are allowed on a closed socket.
153</p>
154
155<p class="note">
156Note: Closing a socket does not remove the bound path from the file
157system. Delete the socket file yourself (e.g. <tt>os.remove(path)</tt>)
158once the server is done with it.
159</p>
160
161<p class="note">
162Note: Garbage-collected objects are automatically closed before
163destruction.
164</p>
165
166<!-- stream.connect +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
167
168<p class="name" id="stream.connect">
169master:<b>connect(</b>path<b>)</b><br>
170master:<b>setpeername(</b>path<b>)</b>
171</p>
172
173<p class="description">
174Attempts to connect a master object to <tt>path</tt>, transforming it
175into a client object. <tt>setpeername</tt> is an alias for
176<tt>connect</tt>. Client objects support
177<a href="#stream.send"><tt>send</tt></a>,
178<a href="#stream.receive"><tt>receive</tt></a>,
179<a href="#stream.getsockname"><tt>getsockname</tt></a>,
180<a href="#stream.settimeout"><tt>settimeout</tt></a>,
181<a href="#stream.shutdown"><tt>shutdown</tt></a>, and
182<a href="#stream.close"><tt>close</tt></a>.
183</p>
184
185<p class="parameters">
186<tt>Path</tt> is a string with the file system path of a listening server
187object.
188</p>
189
190<p class="return">
191In case of error, the method returns <b><tt>nil</tt></b> followed by a
192string describing the error. In case of success, the method returns 1.
193</p>
194
195<!-- stream.dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
196
197<p class="name" id="stream.dirty">
198master:<b>dirty()</b><br>
199client:<b>dirty()</b><br>
200server:<b>dirty()</b>
201</p>
202
203<p class="description">
204Check the read buffer status.
205</p>
206
207<p class="return">
208Returns <tt>true</tt> if there is any data in the read buffer,
209<tt>false</tt> otherwise.
210</p>
211
212<p class="note">
213Note: <b>This is an internal method, use at your own risk.</b>
214</p>
215
216<!-- stream.getfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
217
218<p class="name" id="stream.getfd">
219master:<b>getfd()</b><br>
220client:<b>getfd()</b><br>
221server:<b>getfd()</b>
222</p>
223
224<p class="description">
225Returns the underlying socket descriptor or handle associated to the
226object.
227</p>
228
229<p class="return">
230The descriptor or handle.
231</p>
232
233<p class="note">
234Note: <b>This is an internal method. Unlikely to be portable. Use at your
235own risk.</b>
236</p>
237
238<!-- stream.getsockname +++++++++++++++++++++++++++++++++++++++++++++++++ -->
239
240<p class="name" id="stream.getsockname">
241master:<b>getsockname()</b><br>
242client:<b>getsockname()</b><br>
243server:<b>getsockname()</b>
244</p>
245
246<p class="description">
247Returns the local path the object is bound to.
248</p>
249
250<p class="return">
251The method returns a string with the local path. In case of error, the
252method returns <b><tt>nil</tt></b>.
253</p>
254
255<!-- stream.getstats +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
256
257<p class="name" id="stream.getstats">
258master:<b>getstats()</b><br>
259client:<b>getstats()</b><br>
260server:<b>getstats()</b>
261</p>
262
263<p class="description">
264Returns accounting information on the socket, useful for throttling of
265bandwidth. Works exactly like <a href="tcp.html#getstats"><tt>tcp:getstats</tt></a>.
266</p>
267
268<p class="return">
269The method returns the number of bytes received, the number of bytes
270sent, and the age of the socket object in seconds.
271</p>
272
273<!-- stream.listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
274
275<p class="name" id="stream.listen">
276master:<b>listen(</b>[backlog]<b>)</b>
277</p>
278
279<p class="description">
280Specifies the socket is willing to receive connections, transforming the
281object into a server object. Server objects support
282<a href="#stream.accept"><tt>accept</tt></a>,
283<a href="#stream.getsockname"><tt>getsockname</tt></a>,
284<a href="#stream.setoption"><tt>setoption</tt></a>,
285<a href="#stream.settimeout"><tt>settimeout</tt></a>, and
286<a href="#stream.close"><tt>close</tt></a>.
287</p>
288
289<p class="parameters">
290The optional <tt>backlog</tt> parameter specifies the number of client
291connections that can be queued waiting for service. Defaults to 32.
292</p>
293
294<p class="return">
295In case of success, the method returns 1. In case of error, the method
296returns <b><tt>nil</tt></b> followed by an error message.
297</p>
298
299<!-- stream.receive +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
300
301<p class="name" id="stream.receive">
302client:<b>receive(</b>[pattern [, prefix [, maxsize]]]<b>)</b>
303</p>
304
305<p class="description">
306Reads data from a client object. Works exactly like
307<a href="tcp.html#receive"><tt>tcp:receive</tt></a>, including the
308<tt>*a</tt>/<tt>*l</tt>/<tt>number</tt> patterns and the
309<tt>prefix</tt>/<tt>maxsize</tt> parameters.
310</p>
311
312<!-- stream.send +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
313
314<p class="name" id="stream.send">
315client:<b>send(</b>data [, i [, j]]<b>)</b>
316</p>
317
318<p class="description">
319Sends <tt>data</tt> through a client object. Works exactly like
320<a href="tcp.html#send"><tt>tcp:send</tt></a>, including the optional
321<tt>i</tt>/<tt>j</tt> substring selection.
322</p>
323
324<!-- stream.setfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
325
326<p class="name" id="stream.setfd">
327master:<b>setfd(</b>fd<b>)</b><br>
328client:<b>setfd(</b>fd<b>)</b><br>
329server:<b>setfd(</b>fd<b>)</b>
330</p>
331
332<p class="description">
333Sets the underlying socket descriptor or handle associated to the object.
334The current one is simply replaced, not closed, and no other change to
335the object state is made.
336</p>
337
338<p class="return">
339No return value.
340</p>
341
342<p class="note">
343Note: <b>This is an internal method. Unlikely to be portable. Use at your
344own risk.</b>
345</p>
346
347<!-- stream.setoption +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
348
349<p class="name" id="stream.setoption">
350client:<b>setoption(</b>option [, value]<b>)</b><br>
351server:<b>setoption(</b>option [, value]<b>)</b>
352</p>
353
354<p class="description">
355Sets options for the stream object. Options are only needed by low-level
356or time-critical applications. You should only modify an option if you
357are sure you need it.
358</p>
359
360<p class="parameters">
361<tt>Option</tt> is a string with the option name, and <tt>value</tt>
362depends on the option being set:
363</p>
364
365<ul>
366<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
367the periodic transmission of messages on a connected socket. See
368<a href="tcp.html#setoption"><tt>tcp:setoption</tt></a> for details;</li>
369<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
370used in validating addresses supplied in a call to
371<a href="#stream.bind"><tt>bind</tt></a> should allow reuse of local
372addresses;</li>
373<li> '<tt>linger</tt>': Controls the action taken when unsent data are
374queued on a socket and a close is performed. See
375<a href="tcp.html#setoption"><tt>tcp:setoption</tt></a> for the full
376description of the <tt>on</tt>/<tt>timeout</tt> value table.</li>
377</ul>
378
379<p class="return">
380The method returns 1 in case of success, or <b><tt>nil</tt></b> followed
381by an error message otherwise.
382</p>
383
384<!-- stream.setstats +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
385
386<p class="name" id="stream.setstats">
387master:<b>setstats(</b>received, sent, age<b>)</b><br>
388client:<b>setstats(</b>received, sent, age<b>)</b><br>
389server:<b>setstats(</b>received, sent, age<b>)</b>
390</p>
391
392<p class="description">
393Resets accounting information on the socket, useful for throttling of
394bandwidth. Works exactly like
395<a href="tcp.html#setstats"><tt>tcp:setstats</tt></a>.
396</p>
397
398<p class="return">
399The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
400</p>
401
402<!-- stream.settimeout +++++++++++++++++++++++++++++++++++++++++++++++++ -->
403
404<p class="name" id="stream.settimeout">
405master:<b>settimeout(</b>value [, mode]<b>)</b><br>
406client:<b>settimeout(</b>value [, mode]<b>)</b><br>
407server:<b>settimeout(</b>value [, mode]<b>)</b>
408</p>
409
410<p class="description">
411Changes the timeout values for the object. Works exactly like
412<a href="tcp.html#settimeout"><tt>tcp:settimeout</tt></a>, including the
413'<tt>b</tt>' (block) and '<tt>t</tt>' (total) modes.
414</p>
415
416<!-- stream.shutdown ++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
417
418<p class="name" id="stream.shutdown">
419client:<b>shutdown(</b>[mode]<b>)</b>
420</p>
421
422<p class="description">
423Shuts down part of a full-duplex connection. Works exactly like
424<a href="tcp.html#shutdown"><tt>tcp:shutdown</tt></a>.
425</p>
426
427<p class="parameters">
428<tt>Mode</tt> can be "<tt>both</tt>" (default), "<tt>send</tt>" or
429"<tt>receive</tt>".
430</p>
431
432<p class="return">
433This function returns 1.
434</p>
435
436<!-- socket.unix.stream +++++++++++++++++++++++++++++++++++++++++++++++++ -->
437
438<p class="name" id="socket.unix.stream">
439unix.<b>stream()</b>
440</p>
441
442<p class="description">
443Creates and returns a stream Unix domain master object. A master object
444can be transformed into a server object with
445<a href="#stream.listen"><tt>listen</tt></a> (after a call to
446<a href="#stream.bind"><tt>bind</tt></a>) or into a client object with
447<a href="#stream.connect"><tt>connect</tt></a>. The only other method
448supported by a master object is <a href="#stream.close"><tt>close</tt></a>.
449</p>
450
451<p class="return">
452In case of success, a new master object is returned. In case of error,
453<b><tt>nil</tt></b> is returned, followed by an error message.
454</p>
455
456<!-- dgram +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
457
458<h3 id="dgram">Datagram (<tt>socket.unix.dgram</tt>)</h3>
459
460<p>
461Datagram Unix domain sockets behave like UDP sockets (see
462<a href="udp.html">UDP</a>): a socket starts out unconnected, and can
463optionally be turned into a connected socket with
464<a href="#dgram.connect"><tt>connect</tt></a> for repeated exchanges with
465a single peer.
466</p>
467
468<!-- dgram.bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
469
470<p class="name" id="dgram.bind">
471unconnected:<b>bind(</b>path<b>)</b><br>
472unconnected:<b>setsockname(</b>path<b>)</b>
473</p>
474
475<p class="description">
476Binds the datagram object to a local file system <tt>path</tt>.
477<tt>setsockname</tt> is an alias for <tt>bind</tt>. Binding is only
478required if you want other processes to be able to
479<a href="#dgram.sendto"><tt>sendto</tt></a> this object; it is not
480required to <a href="#dgram.sendto"><tt>sendto</tt></a> or
481<a href="#dgram.connect"><tt>connect</tt></a> from it.
482</p>
483
484<p class="return">
485In case of success, the method returns 1. In case of error, the method
486returns <b><tt>nil</tt></b> followed by an error message.
487</p>
488
489<!-- dgram.close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
490
491<p class="name" id="dgram.close">
492connected:<b>close()</b><br>
493unconnected:<b>close()</b>
494</p>
495
496<p class="description">
497Closes a datagram Unix domain object.
498</p>
499
500<p class="note">
501Note: Closing a socket does not remove the bound path from the file
502system. Delete the socket file yourself (e.g. <tt>os.remove(path)</tt>)
503once you are done with it.
504</p>
505
506<p class="note">
507Note: Garbage-collected objects are automatically closed before
508destruction.
509</p>
510
511<!-- dgram.connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
512
513<p class="name" id="dgram.connect">
514connected:<b>connect(</b>path<b>)</b><br>
515unconnected:<b>connect(</b>path<b>)</b><br>
516connected:<b>setpeername(</b>path<b>)</b><br>
517unconnected:<b>setpeername(</b>path<b>)</b>
518</p>
519
520<p class="description">
521Sets (or changes) the peer of a datagram object, turning an unconnected
522object into a connected one. <tt>setpeername</tt> is an alias for
523<tt>connect</tt>.
524</p>
525
526<p class="parameters">
527<tt>Path</tt> is a string with the file system path of the peer.
528</p>
529
530<p class="return">
531In case of error, the method returns <b><tt>nil</tt></b> followed by an
532error message. In case of success, the method returns 1.
533</p>
534
535<p class="note">
536Note: Unlike <a href="udp.html#setpeername"><tt>udp:setpeername</tt></a>,
537there is no '<tt>*</tt>' path to dissolve the peer association back to an
538unconnected socket.
539</p>
540
541<!-- dgram.dirty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
542
543<p class="name" id="dgram.dirty">
544connected:<b>dirty()</b><br>
545unconnected:<b>dirty()</b>
546</p>
547
548<p class="description">
549Check the read buffer status.
550</p>
551
552<p class="return">
553Always returns <tt>false</tt>. Datagram objects do not keep a read
554buffer.
555</p>
556
557<p class="note">
558Note: <b>This is an internal method, use at your own risk.</b>
559</p>
560
561<!-- dgram.getfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
562
563<p class="name" id="dgram.getfd">
564connected:<b>getfd()</b><br>
565unconnected:<b>getfd()</b>
566</p>
567
568<p class="description">
569Returns the underlying socket descriptor or handle associated to the
570object.
571</p>
572
573<p class="return">
574The descriptor or handle.
575</p>
576
577<p class="note">
578Note: <b>This is an internal method. Unlikely to be portable. Use at your
579own risk.</b>
580</p>
581
582<!-- dgram.getsockname +++++++++++++++++++++++++++++++++++++++++++++++++ -->
583
584<p class="name" id="dgram.getsockname">
585connected:<b>getsockname()</b><br>
586unconnected:<b>getsockname()</b>
587</p>
588
589<p class="description">
590Returns the local path the object is bound to.
591</p>
592
593<p class="return">
594The method returns a string with the local path. In case of error, the
595method returns <b><tt>nil</tt></b>.
596</p>
597
598<!-- dgram.gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
599
600<p class="name" id="dgram.gettimeout">
601connected:<b>gettimeout()</b><br>
602unconnected:<b>gettimeout()</b>
603</p>
604
605<p class="description">
606Returns the current timeout value.
607</p>
608
609<!-- dgram.receive +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
610
611<p class="name" id="dgram.receive">
612connected:<b>receive(</b>[size]<b>)</b><br>
613unconnected:<b>receive(</b>[size]<b>)</b>
614</p>
615
616<p class="description">
617Receives a datagram from the object. If the object is connected, only
618datagrams coming from the peer are accepted.
619</p>
620
621<p class="parameters">
622The optional <tt>size</tt> parameter specifies the maximum size of the
623datagram to be retrieved (defaults to 8192 bytes).
624</p>
625
626<p class="return">
627In case of success, the method returns the received datagram, which may
628be the empty string (a valid zero-length datagram, not end-of-stream). In
629case of timeout, the method returns <b><tt>nil</tt></b> followed by the
630string '<tt>timeout</tt>'.
631</p>
632
633<!-- dgram.receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++ -->
634
635<p class="name" id="dgram.receivefrom">
636unconnected:<b>receivefrom(</b>[size]<b>)</b>
637</p>
638
639<p class="description">
640Works exactly as <a href="#dgram.receive"><tt>receive</tt></a>, except it
641also returns the sender's path as a second return value.
642</p>
643
644<p class="return">
645In case of success, the method returns the received datagram followed by
646the sender's path (the empty string if the sender's socket was not
647bound). In case of timeout, the method returns <b><tt>nil</tt></b>
648followed by the string '<tt>timeout</tt>'.
649</p>
650
651<!-- dgram.send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
652
653<p class="name" id="dgram.send">
654connected:<b>send(</b>datagram<b>)</b>
655</p>
656
657<p class="description">
658Sends a datagram to the peer of a connected object.
659</p>
660
661<p class="return">
662If successful, the method returns the number of bytes sent. In case of
663error, the method returns <b><tt>nil</tt></b> followed by an error
664message (the string '<tt>refused</tt>' if the peer's socket is not
665accepting datagrams).
666</p>
667
668<!-- dgram.sendto +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
669
670<p class="name" id="dgram.sendto">
671unconnected:<b>sendto(</b>datagram, path<b>)</b>
672</p>
673
674<p class="description">
675Sends a datagram to the object bound to <tt>path</tt>.
676</p>
677
678<p class="parameters">
679<tt>Datagram</tt> is a string with the datagram contents. <tt>Path</tt>
680is the file system path of the recipient.
681</p>
682
683<p class="return">
684If successful, the method returns the number of bytes sent. In case of
685error, the method returns <b><tt>nil</tt></b> followed by an error
686message (the string '<tt>refused</tt>' if the recipient's socket is not
687accepting datagrams).
688</p>
689
690<!-- dgram.setfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
691
692<p class="name" id="dgram.setfd">
693connected:<b>setfd(</b>fd<b>)</b><br>
694unconnected:<b>setfd(</b>fd<b>)</b>
695</p>
696
697<p class="description">
698Sets the underlying socket descriptor or handle associated to the object.
699</p>
700
701<p class="return">
702No return value.
703</p>
704
705<p class="note">
706Note: <b>This is an internal method. Unlikely to be portable. Use at your
707own risk.</b>
708</p>
709
710<!-- dgram.setoption +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
711
712<p class="name" id="dgram.setoption">
713connected:<b>setoption(</b>option [, value]<b>)</b><br>
714unconnected:<b>setoption(</b>option [, value]<b>)</b>
715</p>
716
717<p class="description">
718Sets options for the datagram object.
719</p>
720
721<p class="parameters">
722<tt>Option</tt> is a string with the option name:
723</p>
724
725<ul>
726<li> '<tt>reuseaddr</tt>': Indicates that the rules used in validating
727addresses supplied in a <a href="#dgram.bind"><tt>bind</tt></a> call
728should allow reuse of local addresses. Receives a boolean value.</li>
729</ul>
730
731<p class="return">
732The method returns 1 in case of success, or <b><tt>nil</tt></b> followed
733by an error message otherwise.
734</p>
735
736<!-- dgram.settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
737
738<p class="name" id="dgram.settimeout">
739connected:<b>settimeout(</b>value<b>)</b><br>
740unconnected:<b>settimeout(</b>value<b>)</b>
741</p>
742
743<p class="description">
744Changes the timeout value for the object. Works like
745<a href="udp.html#settimeout"><tt>udp:settimeout</tt></a>: since
746<a href="#dgram.send"><tt>send</tt></a> and
747<a href="#dgram.sendto"><tt>sendto</tt></a> never block, this only
748affects <a href="#dgram.receive"><tt>receive</tt></a> and
749<a href="#dgram.receivefrom"><tt>receivefrom</tt></a>.
750</p>
751
752<!-- socket.unix.dgram +++++++++++++++++++++++++++++++++++++++++++++++++ -->
753
754<p class="name" id="socket.unix.dgram">
755unix.<b>dgram()</b>
756</p>
757
758<p class="description">
759Creates and returns an unconnected datagram Unix domain object.
760Unconnected objects support
761<a href="#dgram.sendto"><tt>sendto</tt></a>,
762<a href="#dgram.receive"><tt>receive</tt></a>,
763<a href="#dgram.receivefrom"><tt>receivefrom</tt></a>,
764<a href="#dgram.getsockname"><tt>getsockname</tt></a>,
765<a href="#dgram.setoption"><tt>setoption</tt></a>,
766<a href="#dgram.settimeout"><tt>settimeout</tt></a>,
767<a href="#dgram.connect"><tt>connect</tt></a>, and
768<a href="#dgram.close"><tt>close</tt></a>. Use
769<a href="#dgram.connect"><tt>connect</tt></a> to turn the object into a
770connected object.
771</p>
772
773<p class="return">
774In case of success, a new unconnected datagram object is returned. In
775case of error, <b><tt>nil</tt></b> is returned, followed by an error
776message.
777</p>
778
779<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
780
781<div class="footer">
782<hr>
783<center>
784<p class="bar">
785<a href="index.html">home</a> &middot;
786<a href="index.html#download">download</a> &middot;
787<a href="installation.html">installation</a> &middot;
788<a href="introduction.html">introduction</a> &middot;
789<a href="reference.html">reference</a>
790</p>
791</center>
792</div>
793
794</body>
795</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-09-03 12:00:37 +0000