LuaSocket: Serial port support

From 70f7800986812ad0d1a5dd6f280f66fd2bf1dd12 Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Tue, 1 Sep 2026 10:00:21 +0200 Subject: docs: document socket.unix and socket.serial, fix stale/missing API references 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. --- docs/dns.html | 26 ++ docs/http.html | 9 +- docs/index.html | 2 + docs/installation.html | 2 +- docs/introduction.html | 5 +- docs/ltn12.html | 38 +++ docs/reference.html | 72 +++++ docs/serial.html | 308 +++++++++++++++++++ docs/socket.html | 29 ++ docs/tcp.html | 43 +++ docs/udp.html | 88 +++++- docs/unix.html | 795 +++++++++++++++++++++++++++++++++++++++++++++++++ 12 files changed, 1411 insertions(+), 6 deletions(-) create mode 100644 docs/serial.html create mode 100644 docs/unix.html (limited to 'docs') diff --git a/docs/dns.html b/docs/dns.html index 56ce3ba..e8320e8 100644 --- a/docs/dns.html +++ b/docs/dns.html @@ -106,6 +106,32 @@ the resolver. In case of error, the function returns nil followed by an error message.

+ + +

+socket.dns.getnameinfo([host] [, service]) +

+ +

+Resolves a host and/or a service name through the system resolver and +returns their canonical name form. At least one of host or +service must be given. +

+ +

+Host is an optional string with a host name or IP address. +Service is an optional string with a service name or port number. +

+ +

+If host was given, returns a numerically-indexed table with the +canonical host name found for each address the resolver returns for +host. If service was also given, the canonical service +name is returned as an additional value; if only service was +given, its canonical name is returned by itself. In case of error, the +function returns nil followed by an error message. +

diff --git a/docs/http.html b/docs/http.html index c6423ba..316cd2e 100644 --- a/docs/http.html +++ b/docs/http.html @@ -114,7 +114,11 @@ the HTTP module:

PROXY: default proxy used for connections;
TIMEOUT: sets the timeout for all I/O operations;
USERAGENT: default user agent reported to server.
USERAGENT: default user agent reported to server;
MAXHEADERLINE: maximum length, in bytes, of a single response +header line. Defaults to 8192;
MAXHEADERSIZE: maximum total size, in bytes, of all response +header lines combined. Defaults to 65536.

@@ -183,7 +187,8 @@ pump step function used to move data. Defaults to the LTN12 pump.step function.

proxy: The URL of a proxy server to use. Defaults to no proxy;

redirect: Set to false to prevent the -function from automatically following 301 or 302 server redirect messages;

+function from automatically following 301, 302, 303, 307 or 308 server +redirect messages;

create: An optional function to be used instead of socket.tcp when the communications socket is created.

maxredirects: An optional number specifying the maximum number of diff --git a/docs/index.html b/docs/index.html index 3341f8d..7a22dd6 100644 --- a/docs/index.html +++ b/docs/index.html @@ -67,6 +67,8 @@ In addition, you will find that the (anything you could possible want to do with one) and LTN12 (filters, sinks, sources and pumps) modules can be very handy. +On Unix-like platforms, dedicated Unix domain socket +and serial port modules are also available.

diff --git a/docs/installation.html b/docs/installation.html index b56f50f..bdc8b1d 100644 --- a/docs/installation.html +++ b/docs/installation.html @@ -57,7 +57,7 @@ luarocks install luasocket print(socket._VERSION) -

If you see output like LuaSocket 3.0, the installation was successful.

If you see output like LuaSocket 3.1.0, the installation was successful.

More Information

For more details, visit the LuaSocket GitHub repository.

diff --git a/docs/introduction.html b/docs/introduction.html index 51443a0..bc0d535 100644 --- a/docs/introduction.html +++ b/docs/introduction.html @@ -304,7 +304,10 @@ io.write(assert(udp:receive()))

Although not covered in the introduction, LuaSocket offers much more than TCP and UDP functionality. As the library evolved, support for HTTP, FTP, -and SMTP were built on top of these. These modules +and SMTP were built on top of these. On Unix-like +platforms, the library also ships separate Unix domain +socket and serial port modules, requirable as +socket.unix and socket.serial. These modules and many others are covered by the reference manual.

diff --git a/docs/ltn12.html b/docs/ltn12.html index 30bc564..76b3984 100644 --- a/docs/ltn12.html +++ b/docs/ltn12.html @@ -55,6 +55,20 @@ To obtain the ltn12 namespace, run: local ltn12 = require("ltn12") + + +

+ltn12.BLOCKSIZE +

+ +

+The default chunk size, in bytes, used internally by the built-in sources +and sinks (e.g. source.string, +source.file) when they have no more +natural chunk size of their own. Defaults to 2048. Changing it affects +only sources/sinks created after the change. +

Filters

@@ -415,6 +429,30 @@ ltn12.source.table(table) Creates and returns a source that produces the numerically-indexed values of a table successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless.

+ + +

+ltn12.source.rewind(source) +

+ +

+Wraps a fancy source to add chunk pushback, so previously +produced chunks can be fed back in for a later read to consume again. +

+ +

+Source is the fancy source being wrapped. +

+ +

+The function returns a new fancy source. Calling it with no arguments reads +the next chunk as usual: any chunks previously pushed back are returned +first (most recently pushed back, first), and once none remain it falls +through to source. Calling it with a chunk argument does +not read anything: it pushes that chunk back onto the internal stack for a +future no-argument call to return. +

diff --git a/docs/reference.html b/docs/reference.html index 2bc5f78..7425716 100644 --- a/docs/reference.html +++ b/docs/reference.html @@ -43,6 +43,7 @@ Support, Manual"> DNS (in socket)

getaddrinfo, +getnameinfo, gethostname, tohostname, toip. @@ -73,6 +74,9 @@ Support, Manual">
LTN12
+BLOCKSIZE. +
+
filter: chain, cycle. @@ -98,6 +102,7 @@ Support, Manual"> empty, error, file, +rewind, simplify, string, table. @@ -129,6 +134,23 @@ Support, Manual">

+ + +
+Serial +
+close, +getfd, +getstats, +receive, +send, +setfd, +setstats, +settimeout, +socket.serial. +
+
+
@@ -153,6 +175,7 @@ Support, Manual"> dns, gettime, headers.canonic, +headers.setcanonic, newtry, protect, select, @@ -183,6 +206,7 @@ Support, Manual"> close, connect, dirty, +getfamily, getfd, getoption, getpeername, @@ -194,6 +218,8 @@ Support, Manual"> send, setfd, setoption, +setpeername, +setsockname, setstats, settimeout, shutdown. @@ -206,6 +232,9 @@ Support, Manual"> UDP (in socket)
close, +dirty, +getfamily, +getfd, getoption, getpeername, getsockname, @@ -214,6 +243,7 @@ Support, Manual"> receivefrom, send, sendto, +setfd, setpeername, setsockname, setoption, @@ -221,6 +251,48 @@ Support, Manual">

+ + +
+Unix +
+socket.unix.stream: +accept, +bind, +close, +connect, +dirty, +getfd, +getsockname, +getstats, +listen, +receive, +send, +setfd, +setoption, +setstats, +settimeout, +shutdown. +
+
+socket.unix.dgram: +bind, +close, +connect, +dirty, +getfd, +getsockname, +gettimeout, +receive, +receivefrom, +send, +sendto, +setfd, +setoption, +settimeout. +
+
+
diff --git a/docs/serial.html b/docs/serial.html new file mode 100644 index 0000000..8e123b0 --- /dev/null +++ b/docs/serial.html @@ -0,0 +1,308 @@ + + + + + + +LuaSocket: Serial port support + + + + + + + +
+
+ + + + +
+ +
Network support for the Lua language +
+
+home · +download · +installation · +introduction · +reference +
+ +
+
+ + + +
Serial port support
+ +
+The socket.serial module opens a serial device (e.g. +/dev/ttyUSB0) and exposes it through the same buffered, +timeout-aware send/receive interface used by +TCP and Unix domain +stream objects. +
+ +
+Note: This module is only built on Unix-like platforms (Linux, macOS, +BSD, Haiku). It is not available on Windows. +
+ +
+Serial port support is a separate module that must be required +explicitly. Unlike most other LuaSocket modules, it returns a +function directly — the constructor — rather than a +table of functions: +
+ +
+-- loads the socket.serial module; note this is the constructor itself
+local serial_open = require("socket.serial")
+
+-- open the device
+local port = assert(serial_open("/dev/ttyUSB0"))
+port:settimeout(1)
+assert(port:send("AT\r\n"))
+print(port:receive())
+port:close()
+
+ +
+Note: There is currently no API to configure the serial line itself +— baud rate, parity, data/stop bits or flow control. The device +is opened non-blocking with whatever settings the OS driver or a prior +external configuration (e.g. stty) left it in. This is a known +current limitation of the module, not a deliberate protection against +misuse; a future version may add a setoption-style API for these +settings the way tcp:setoption +does for TCP. +
+ +
+Until such an API exists, the workaround is to configure the line with +the platform's own stty utility (via os.execute) +before opening the device with socket.serial: +
+ +
+local serial_open = require("socket.serial")
+
+local dev = "/dev/ttyUSB0"
+
+-- Linux: stty -F <device> ...
+local ok = os.execute(string.format(
+    "stty -F %s 115200 cs8 -cstopb -parenb raw -echo", dev))
+
+-- macOS/BSD use -f instead of -F:
+-- os.execute(string.format("stty -f %s 115200 cs8 -cstopb -parenb raw -echo", dev))
+
+assert(ok, "failed to configure serial line with stty")
+
+local port = assert(serial_open(dev))
+port:settimeout(1)
+assert(port:send("AT\r\n"))
+print(port:receive())
+port:close()
+
+ +
+Note: raw -echo puts the line in raw mode, which matters for +LuaSocket's framing: without it, the TTY driver applies its own line +editing/echo, which can interfere with receive +patterns and send content. Adjust the +stty flags (baud rate, parity, stop bits, flow control) to match +your device; consult man stty for the full option set on your +platform, since flag names and defaults vary between Linux, macOS and the +BSDs. +
+ + + +
+port:close() +
+ +
+Closes a serial object. No further operations (except further calls to +close) are allowed on a closed object. +
+ +
+Note: Garbage-collected objects are automatically closed before +destruction. +
+ + + +
+port:dirty() +
+ +
+Check the read buffer status. +
+ +
+Returns true if there is any data in the read buffer, +false otherwise. +
+ +
+Note: This is an internal method, use at your own risk. +
+ + + +
+port:getfd() +
+ +
+Returns the underlying file descriptor associated to the object. +
+ +
+The descriptor. +
+ +
+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +
+ + + +
+port:getstats() +
+ +
+Returns accounting information on the port, useful for throttling of +bandwidth. Works exactly like +tcp:getstats. +
+ +
+The method returns the number of bytes received, the number of bytes +sent, and the age of the object in seconds. +
+ + + +
+port:receive([pattern [, prefix [, maxsize]]]) +
+ +
+Reads data from the serial port, according to the specified read +pattern. Works exactly like +tcp:receive, including the +*a/*l/number patterns and the +prefix/maxsize parameters. +
+ + + +
+port:send(data [, i [, j]]) +
+ +
+Sends data through the serial port. Works exactly like +tcp:send, including the optional +i/j substring selection. +
+ + + +
+port:setfd(fd) +
+ +
+Sets the underlying file descriptor associated to the object. The current +one is simply replaced, not closed, and no other change to the object +state is made. +
+ +
+No return value. +
+ +
+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +
+ + + +
+port:setstats(received, sent, age) +
+ +
+Resets accounting information on the port, useful for throttling of +bandwidth. Works exactly like +tcp:setstats. +
+ +
+The method returns 1 in case of success and nil otherwise. +
+ + + +
+port:settimeout(value [, mode]) +
+ +
+Changes the timeout values for the object. Works exactly like +tcp:settimeout, including the +'b' (block) and 't' (total) modes. +
+ + + +
+serial_open(path) +
+ +
+Opens the serial device at path and returns a serial object. +This is the value returned directly by require("socket.serial") +— there is no separate module table to index into, unlike +socket.unix.stream() or socket.tcp(). +
+ +
+Path is a string with the device path (e.g. +"/dev/ttyUSB0" or "/dev/ttyS0"). +
+ +
+In case of success, a new serial object is returned. In case of error, +the function returns nil, followed by an error message, +followed by the numeric errno value. +
+ + + +
+
+ +
+home · +download · +installation · +introduction · +reference +
+ +
+ + + diff --git a/docs/socket.html b/docs/socket.html index 570f6d5..de43135 100644 --- a/docs/socket.html +++ b/docs/socket.html @@ -51,6 +51,14 @@ To obtain the socket namespace, run: local socket = require("socket") +
+Two related transports are shipped as separate modules, loaded on demand +with their own require call: Unix domain +sockets (require("socket.unix")) and +serial ports (require("socket.serial")). +Both are only built on Unix-like platforms. +
+
@@ -94,6 +102,27 @@ local headers = require("socket.headers") headers.setcanonic("X-Request-ID") + + +
+socket.headers.setcanonic(name) +
+ +
+Registers a custom canonic capitalization for a header field name in +socket.headers.canonic, for use +when the automatic capitalize-first-letter-of-each-word rule would not +reproduce it (e.g. an all-caps acronym). +
+ +
+Name is a string with the header field name in its desired +canonic capitalization (e.g. "X-Request-ID"). +
+ +
+No return value. +
diff --git a/docs/tcp.html b/docs/tcp.html index 715d28f..580bdcf 100644 --- a/docs/tcp.html +++ b/docs/tcp.html @@ -196,6 +196,25 @@ Note: This is an internal method, use at your own risk.
+ + +
+master:getfamily()
+client:getfamily()
+server:getfamily() +
+ +
+Returns the family of the underlying socket, as chosen when the object was +created by socket.tcp, +socket.tcp4 or +socket.tcp6. +
+ +
+The string "inet4" or "inet6". +
+
@@ -651,6 +670,30 @@ This is the default mode;

This function returns 1.

+ + +

+master:setpeername(address, port) +

+ +

+Alias for connect, kept for naming symmetry +with udp:setpeername and with +getpeername. +

+ + + +

+master:setsockname(address, port) +

+ +

+Alias for bind, kept for naming symmetry +with udp:setsockname and with +getsockname. +

diff --git a/docs/udp.html b/docs/udp.html index 8d807a4..d2c169a 100644 --- a/docs/udp.html +++ b/docs/udp.html @@ -62,6 +62,66 @@ Garbage-collected objects are automatically closed before destruction, though.

+ + +

+connected:dirty()
+unconnected:dirty() +

+ +

+Check the read buffer status. +

+ +

+Returns false. UDP objects do not keep a read buffer, so this +always reports no buffered data. +

+ +

+Note: This is an internal method, use at your own risk. +

+ + + +

+connected:getfamily()
+unconnected:getfamily() +

+ +

+Returns the family of the underlying socket, as chosen when the object was +created by socket.udp, +socket.udp4 or +socket.udp6. +

+ +

+The string "inet4" or "inet6". +

+ + + +

+connected:getfd()
+unconnected:getfd() +

+ +

+Returns the underling socket descriptor or handle associated to the object. +

+ +

+The descriptor or handle. In case the object has been closed, the return value +will be -1. For an invalid socket it will be +_SOCKETINVALID. +

+ +

+Note: This is an internal method. Unlikely to be +portable. Use at your own risk. +

@@ -321,8 +381,10 @@ Sets the unicast hop limit (the IPv6 equivalent of the IPv4 TTL) for outgoing packets. Receives a number;

'ipv6-multicast-hops': -Sets the hop limit for outgoing IPv6 multicast datagrams. -Receives a number;

+Known limitation: this option is currently wired to the same +underlying setting as ipv6-unicast-hops instead of a separate +multicast hop limit, so getting or setting one also gets or sets the +other. Receives a number;

'ipv6-multicast-loop': Specifies whether or not a copy of an outgoing IPv6 multicast datagram is delivered to the sending host as long as it is a @@ -374,6 +436,28 @@ Note: The descriptions above come from the man pages.

+ + +

+connected:setfd(fd)
+unconnected:setfd(fd) +

+ +

+Sets the underling socket descriptor or handle associated to the object. The current one +is simply replaced, not closed, and no other change to the object state is made. +To set it as invalid use _SOCKETINVALID. +

+ +

+No return value. +

+ +

+Note: This is an internal method. Unlikely to be +portable. Use at your own risk. +

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 @@ + + + + + + +LuaSocket: Unix domain socket support + + + + + + + +

+ + + +

Unix domain sockets

+ +

+Unix domain sockets provide inter-process communication between processes +on the same host, addressed by a path in the file system rather than by an +IP address and port. LuaSocket supports both the stream (connection +oriented, like TCP) and datagram (connectionless, like UDP) flavors. +

+ +

+Note: This module is only built on Unix-like platforms (Linux, macOS, +BSD, Haiku). It is not available on Windows. +

+ +

+Unlike the core socket namespace, Unix domain socket support is a +separate module that must be required explicitly: +

+ +

+-- loads the socket.unix module
+local unix = require("socket.unix")
+

+ +

+The module table returned by require("socket.unix") exposes two +constructors, unix.stream() and +unix.dgram(). For backwards +compatibility, unix.tcp and unix.udp are aliases for +stream and dgram respectively, and the module table +itself can be called directly as a shortcut for unix.stream() +(i.e. unix() is the same as unix.stream()). +

+ +

+Note: Paths passed to bind, +connect and their datagram +equivalents are limited by the platform's sun_path buffer size +(commonly around 100–108 bytes). A path that does not fit returns +nil followed by the error message 'path too +long'. +

+ + + +

Stream (`socket.unix.stream`)

+ +

+Stream Unix domain sockets behave like TCP sockets (see +TCP): a freshly created object is a master +object, which becomes a client object after a successful +connect, or a server +object after a successful listen +(itself normally preceded by bind). +Server objects produce client objects via +accept. Most methods below work the +same way as their TCP counterparts, just addressed by path instead of +IP/port. +

+ + + +

+server:accept() +

+ +

+Waits for a remote connection on the server object and returns a client +object representing that connection. Works exactly like +tcp:accept. +

+ +

+If a connection is successfully accepted, a client object is returned. If a +timeout condition is met, the method returns nil followed +by the error string 'timeout'. Other errors are reported by +nil followed by a message describing the error. +

+ + + +

+master:bind(path)
+master:setsockname(path) +

+ +

+Binds a master object to a file system path. setsockname +is an alias for bind. +

+ +

+Path is a string with the file system path to bind to. The path +must not already exist as a socket file — remove any stale socket +file left over from a previous run before binding. +

+ +

+In case of success, the method returns 1. In case of error, the method +returns nil followed by an error message. +

+ + + +

+master:close()
+client:close()
+server:close() +

+ +

+Closes a stream Unix domain object. The internal socket used by the object +is closed. No further operations (except further calls to +close) are allowed on a closed socket. +

+ +

+Note: Closing a socket does not remove the bound path from the file +system. Delete the socket file yourself (e.g. os.remove(path)) +once the server is done with it. +

+ +

+Note: Garbage-collected objects are automatically closed before +destruction. +

+ + + +

+master:connect(path)
+master:setpeername(path) +

+ +

+Attempts to connect a master object to path, transforming it +into a client object. setpeername is an alias for +connect. Client objects support +send, +receive, +getsockname, +settimeout, +shutdown, and +close. +

+ +

+Path is a string with the file system path of a listening server +object. +

+ +

+In case of error, the method returns nil followed by a +string describing the error. In case of success, the method returns 1. +

+ + + +

+master:dirty()
+client:dirty()
+server:dirty() +

+ +

+Check the read buffer status. +

+ +

+Returns true if there is any data in the read buffer, +false otherwise. +

+ +

+Note: This is an internal method, use at your own risk. +

+ + + +

+master:getfd()
+client:getfd()
+server:getfd() +

+ +

+Returns the underlying socket descriptor or handle associated to the +object. +

+ +

+The descriptor or handle. +

+ +

+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +

+ + + +

+master:getsockname()
+client:getsockname()
+server:getsockname() +

+ +

+Returns the local path the object is bound to. +

+ +

+The method returns a string with the local path. In case of error, the +method returns nil. +

+ + + +

+master:getstats()
+client:getstats()
+server:getstats() +

+ +

+Returns accounting information on the socket, useful for throttling of +bandwidth. Works exactly like tcp:getstats. +

+ +

+The method returns the number of bytes received, the number of bytes +sent, and the age of the socket object in seconds. +

+ + + +

+master:listen([backlog]) +

+ +

+Specifies the socket is willing to receive connections, transforming the +object into a server object. Server objects support +accept, +getsockname, +setoption, +settimeout, and +close. +

+ +

+The optional backlog parameter specifies the number of client +connections that can be queued waiting for service. Defaults to 32. +

+ +

+In case of success, the method returns 1. In case of error, the method +returns nil followed by an error message. +

+ + + +

+client:receive([pattern [, prefix [, maxsize]]]) +

+ +

+Reads data from a client object. Works exactly like +tcp:receive, including the +*a/*l/number patterns and the +prefix/maxsize parameters. +

+ + + +

+client:send(data [, i [, j]]) +

+ +

+Sends data through a client object. Works exactly like +tcp:send, including the optional +i/j substring selection. +

+ + + +

+master:setfd(fd)
+client:setfd(fd)
+server:setfd(fd) +

+ +

+Sets the underlying socket descriptor or handle associated to the object. +The current one is simply replaced, not closed, and no other change to +the object state is made. +

+ +

+No return value. +

+ +

+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +

+ + + +

+client:setoption(option [, value])
+server:setoption(option [, value]) +

+ +

+Sets options for the stream object. Options are only needed by low-level +or time-critical applications. You should only modify an option if you +are sure you need it. +

+ +

+Option is a string with the option name, and value +depends on the option being set: +

+ +

'keepalive': Setting this option to true enables +the periodic transmission of messages on a connected socket. See +tcp:setoption for details;
'reuseaddr': Setting this option indicates that the rules +used in validating addresses supplied in a call to +bind should allow reuse of local +addresses;
'linger': Controls the action taken when unsent data are +queued on a socket and a close is performed. See +tcp:setoption for the full +description of the on/timeout value table.

+ +

+The method returns 1 in case of success, or nil followed +by an error message otherwise. +

+ + + +

+master:setstats(received, sent, age)
+client:setstats(received, sent, age)
+server:setstats(received, sent, age) +

+ +

+Resets accounting information on the socket, useful for throttling of +bandwidth. Works exactly like +tcp:setstats. +

+ +

+The method returns 1 in case of success and nil otherwise. +

+ + + +

+master:settimeout(value [, mode])
+client:settimeout(value [, mode])
+server:settimeout(value [, mode]) +

+ +

+Changes the timeout values for the object. Works exactly like +tcp:settimeout, including the +'b' (block) and 't' (total) modes. +

+ + + +

+client:shutdown([mode]) +

+ +

+Shuts down part of a full-duplex connection. Works exactly like +tcp:shutdown. +

+ +

+Mode can be "both" (default), "send" or +"receive". +

+ +

+This function returns 1. +

+ + + +

+unix.stream() +

+ +

+Creates and returns a stream Unix domain master object. A master object +can be transformed into a server object with +listen (after a call to +bind) or into a client object with +connect. The only other method +supported by a master object is close. +

+ +

+In case of success, a new master object is returned. In case of error, +nil is returned, followed by an error message. +

+ + + +

Datagram (`socket.unix.dgram`)

+ +

+Datagram Unix domain sockets behave like UDP sockets (see +UDP): a socket starts out unconnected, and can +optionally be turned into a connected socket with +connect for repeated exchanges with +a single peer. +

+ + + +

+unconnected:bind(path)
+unconnected:setsockname(path) +

+ +

+Binds the datagram object to a local file system path. +setsockname is an alias for bind. Binding is only +required if you want other processes to be able to +sendto this object; it is not +required to sendto or +connect from it. +

+ +

+In case of success, the method returns 1. In case of error, the method +returns nil followed by an error message. +

+ + + +

+connected:close()
+unconnected:close() +

+ +

+Closes a datagram Unix domain object. +

+ +

+Note: Closing a socket does not remove the bound path from the file +system. Delete the socket file yourself (e.g. os.remove(path)) +once you are done with it. +

+ +

+Note: Garbage-collected objects are automatically closed before +destruction. +

+ + + +

+connected:connect(path)
+unconnected:connect(path)
+connected:setpeername(path)
+unconnected:setpeername(path) +

+ +

+Sets (or changes) the peer of a datagram object, turning an unconnected +object into a connected one. setpeername is an alias for +connect. +

+ +

+Path is a string with the file system path of the peer. +

+ +

+In case of error, the method returns nil followed by an +error message. In case of success, the method returns 1. +

+ +

+Note: Unlike udp:setpeername, +there is no '*' path to dissolve the peer association back to an +unconnected socket. +

+ + + +

+connected:dirty()
+unconnected:dirty() +

+ +

+Check the read buffer status. +

+ +

+Always returns false. Datagram objects do not keep a read +buffer. +

+ +

+Note: This is an internal method, use at your own risk. +

+ + + +

+connected:getfd()
+unconnected:getfd() +

+ +

+Returns the underlying socket descriptor or handle associated to the +object. +

+ +

+The descriptor or handle. +

+ +

+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +

+ + + +

+connected:getsockname()
+unconnected:getsockname() +

+ +

+Returns the local path the object is bound to. +

+ +

+The method returns a string with the local path. In case of error, the +method returns nil. +

+ + + +

+connected:gettimeout()
+unconnected:gettimeout() +

+ +

+Returns the current timeout value. +

+ + + +

+connected:receive([size])
+unconnected:receive([size]) +

+ +

+Receives a datagram from the object. If the object is connected, only +datagrams coming from the peer are accepted. +

+ +

+The optional size parameter specifies the maximum size of the +datagram to be retrieved (defaults to 8192 bytes). +

+ +

+In case of success, the method returns the received datagram, which may +be the empty string (a valid zero-length datagram, not end-of-stream). In +case of timeout, the method returns nil followed by the +string 'timeout'. +

+ + + +

+unconnected:receivefrom([size]) +

+ +

+Works exactly as receive, except it +also returns the sender's path as a second return value. +

+ +

+In case of success, the method returns the received datagram followed by +the sender's path (the empty string if the sender's socket was not +bound). In case of timeout, the method returns nil +followed by the string 'timeout'. +

+ + + +

+connected:send(datagram) +

+ +

+Sends a datagram to the peer of a connected object. +

+ +

+If successful, the method returns the number of bytes sent. In case of +error, the method returns nil followed by an error +message (the string 'refused' if the peer's socket is not +accepting datagrams). +

+ + + +

+unconnected:sendto(datagram, path) +

+ +

+Sends a datagram to the object bound to path. +

+ +

+Datagram is a string with the datagram contents. Path +is the file system path of the recipient. +

+ +

+If successful, the method returns the number of bytes sent. In case of +error, the method returns nil followed by an error +message (the string 'refused' if the recipient's socket is not +accepting datagrams). +

+ + + +

+connected:setfd(fd)
+unconnected:setfd(fd) +

+ +

+Sets the underlying socket descriptor or handle associated to the object. +

+ +

+No return value. +

+ +

+Note: This is an internal method. Unlikely to be portable. Use at your +own risk. +

+ + + +

+connected:setoption(option [, value])
+unconnected:setoption(option [, value]) +

+ +

+Sets options for the datagram object. +

+ +

+Option is a string with the option name: +

+ +

'reuseaddr': Indicates that the rules used in validating +addresses supplied in a bind call +should allow reuse of local addresses. Receives a boolean value.

+ +

+The method returns 1 in case of success, or nil followed +by an error message otherwise. +

+ + + +

+connected:settimeout(value)
+unconnected:settimeout(value) +

+ +

+Changes the timeout value for the object. Works like +udp:settimeout: since +send and +sendto never block, this only +affects receive and +receivefrom. +

+ + + +

+unix.dgram() +

+ +

+Creates and returns an unconnected datagram Unix domain object. +Unconnected objects support +sendto, +receive, +receivefrom, +getsockname, +setoption, +settimeout, +connect, and +close. Use +connect to turn the object into a +connected object. +

+ +

+In case of success, a new unconnected datagram object is returned. In +case of error, nil is returned, followed by an error +message. +

+ + + + + + + -- cgit v1.2.3-55-g6feb

More Information

Filters

Serial port support

Unix domain sockets

Stream (socket.unix.stream)

Datagram (socket.unix.dgram)

Stream (`socket.unix.stream`)

Datagram (`socket.unix.dgram`)