|
| Network support for the Lua language |
|
|
| Network support for the Lua language |
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 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:
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 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:
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.