Lunatik
Lua API · Sockets and netlink

socket.unixModule

UNIX domain socket (AF_UNIX) operations.

This module provides an OOP-style abstraction over the socket module for AF_UNIX sockets, modeled after socket.inet.

A socket instance can be created with an optional path stored as default address, which is then reused automatically in bind, connect, and dgram:sendto without an explicit per-call address.

See also

Class unix

unix.dgram DGRAM socket specialization (connectionless).
unix.dgram:receivefrom (len, flags) Receives data from a DGRAM socket along with the sender’s path.
unix.dgram:sendto (msg, path) Sends data to a UNIX domain socket path.
unix.stream STREAM socket specialization (connection-oriented).
unix.stream:accept (flags) Accepts an incoming connection on a listening STREAM socket.
unix.stream:listen (backlog) Listens for incoming connections on a STREAM socket.
unix:__call (path) Creates a new UNIX domain socket instance.
unix:bind (path) Binds the socket to a UNIX domain path.
unix:close () Closes the underlying socket.
unix:connect (path) Connects the socket to a UNIX domain path.
unix:getpeername () Gets the remote address (path) the socket is connected to.
unix:getsockname () Gets the local address (path) of the socket.
unix:new ([o]) Derives a specialization of the class, as unix.stream and unix.dgram are, or wraps a table in it.
unix:receive (...) Receives data from the socket.
unix:send (msg, path) Sends data through the socket.

Class unix in detail

Base class for UNIX domain socket objects.
unix.dgram
DGRAM socket specialization (connectionless). Create instances with unix.dgram([path]). The optional path is stored as the default destination for sendto.

Fields

  • type The socket type (linux.socket.sock.DGRAM).
unix.dgram:receivefrom (len, flags)
Receives data from a DGRAM socket along with the sender’s path.

Parameters

  • len (number) Maximum number of bytes to receive.
  • flags (number) [optional] Receive flags.

Returns

  1. (string) The received data, or nil when the wait ended with nothing to read.
  2. (string) The sender’s path, carrying its leading NUL when the name is an abstract one; nothing follows the message when the peer never bound, and "EAGAIN" follows that nil.

See also

unix.dgram:sendto (msg, path)
Sends data to a UNIX domain socket path. If path is omitted, uses the path provided at construction time.

Parameters

  • msg (string) The message to send.
  • path (string) [optional] Destination socket path.

Returns

    (number|boolean) Number of bytes sent, or false when a send timeout ended the wait with nothing queued.

Raises

error on failure.

See also

unix.stream
STREAM socket specialization (connection-oriented). Create instances with unix.stream([path]).

Fields

  • type The socket type (linux.socket.sock.STREAM).
unix.stream:accept (flags)
Accepts an incoming connection on a listening STREAM socket.

Parameters

  • flags (number) [optional] Flags for the accept operation.

Returns

    A new socket object for the accepted connection, or nil and "EAGAIN" when the wait ended with no connection to accept.

See also

unix.stream:listen (backlog)
Listens for incoming connections on a STREAM socket.

Parameters

  • backlog (number) Maximum length of the queue of pending connections.

See also

unix:__call (path)
Creates a new UNIX domain socket instance. This is the primary way to create instances (e.g. local s = unix.stream(path)).

Parameters

  • path (string) [optional] Default UNIX socket path stored in the object. Reused by bind, connect and dgram:sendto when no explicit path is given.

Returns

    (table) A new unix socket object.

See also

unix:bind (path)
Binds the socket to a UNIX domain path.

Parameters

  • path (string) [optional] Path to bind to. Defaults to the path provided at construction time.

See also

unix:close ()
Closes the underlying socket.

See also

unix:connect (path)
Connects the socket to a UNIX domain path.

Parameters

  • path (string) [optional] Path to connect to. Defaults to the path provided at construction time.

Returns

    (boolean) true once connected, or false when a send timeout ended the wait for room in the listener’s backlog.

See also

unix:getpeername ()
Gets the remote address (path) the socket is connected to.

Returns

    (string) The remote path, carrying its leading NUL when the name is an abstract one, and the empty string when the peer is unbound.

See also

unix:getsockname ()
Gets the local address (path) of the socket.

Returns

    (string) The local path, carrying its leading NUL when the name is an abstract one, and the empty string when the socket is unbound.

See also

unix:new ([o])
Derives a specialization of the class, as unix.stream and unix.dgram are, or wraps a table in it. It opens no socket: calling the class does, unix.stream(path).

Parameters

  • o table an initial object table. (optional)

Returns

    unix the derived class or the wrapped table.

See also

unix:receive (...)
Receives data from the socket.

Parameters

  • ... Varargs passed directly to socket:receive().

Returns

    Varargs returned by socket:receive().

See also

unix:send (msg, path)
Sends data through the socket. For connected STREAM sockets, path is omitted. For DGRAM sockets, use sendto() to send to the stored path or an explicit destination.

Parameters

  • msg (string) The message to send.
  • path (string) [optional] Explicit destination socket path.

Returns

    (number|boolean) Number of bytes sent, or false when a send timeout ended the wait with nothing queued.

Raises

error on failure.

See also