Module tch.socket.unix

Lua C module exposing Unix domain sockets.

Currently implemented:

  • Datagram and stream sockets.
  • The sockets are created with SO_PASSCRED option.
  • All addresses are in the abstract namespace but the leading \0 will be added automatically.
  • Maximum size of datagrams is MAX_DGRAM_SIZE bytes.

See unix(7) for more information on Unix domain sockets.

See also:

Usage:

    Example server code:
  local unix = require("tch.socket.unix")
  local sk = unix.dgram()
  assert(sk:bind("myserveraddress"))
  while true do
    local data, from = sk:recvfrom()
    // process data and formulate response
    local response = process(data)
    sk:sendto(response, from)
  end
  sk:close()

Example client code:
  local unix = require("tch.socket.unix")
  local sk = unix.dgram()
  assert(sk:connect("myserveraddress))
  local data = produce()
  sk:send(data)
  local response = sk:recv()
  process(response)
  sk:close()

Functions

dgram(flags) Create a new datagram socket.
stream(flags) Create a new stream socket.

Class sk

sk:accept(flags) Accept a new connection.
sk:bind(path) Bind the socket to the given path in the abstract namespace.
sk:close() Close the socket.
sk:connect(path) Connect the socket to the given path in the abstract namespace.
sk:fd() Return the underlying file descriptor of this socket.
sk:listen() Mark the socket as a listening socket.
sk:recv() Receive data from the socket.
sk:recvfrom() Receive data from the socket and the address of the sender.
sk:send(data) Send the given data to the peer to which the socket is connected.
sk:sendto(data, path) Send the given data to the given path in the abstract namespace.
tch.socket.unix Useful constants.


Functions

dgram(flags)
Create a new datagram socket.

The SO_PASSCRED socket option is always set.

Parameters:

  • flags int Bitwise OR of the SOCK_* constants.

Returns:

    sk The newly created datagram socket.

Or

  1. nil
  2. string Error message.
stream(flags)
Create a new stream socket.

The SO_PASSCRED socket option is always set.

Parameters:

  • flags int Bitwise OR of the SOCK_* constants.

Returns:

    sk The newly created stream socket.

Or

  1. nil
  2. string Error message.

Class sk

Unixsocket methods.
sk:accept(flags)
Accept a new connection.

Parameters:

  • flags int Bitwise OR of the SOCK_* constants.

Returns:

    sk New socket representing the accepted connection.

Or

  1. nil
  2. string Error message. In particular, if the socket is marked non-blocking and the operation would block then the message "WOULDBLOCK" is returned.
sk:bind(path)
Bind the socket to the given path in the abstract namespace. The leading \0 will be added automatically. Can only be done once and before any data is sent.

Parameters:

  • path string The path in the abstract namespace to bind to.

Returns:

    boolean true

Or

  1. nil
  2. string Error message.
sk:close()
Close the socket.

Calling socket methods on the closed socket will result in errors. It's not an error to close a socket more than once. Closing a socket will automatically remove it from any event loop it was added to but not removed yet.

sk:connect(path)
Connect the socket to the given path in the abstract namespace. The leading \0 will be added automatically. Can be called multiple times.

Parameters:

  • path string The path in the abstract namespace to connect to.

Returns:

    boolean true

Or

  1. nil
  2. string Error message.
sk:fd()
Return the underlying file descriptor of this socket.

Returns:

    int The file descriptor.
sk:listen()
Mark the socket as a listening socket.

Returns:

    boolean true

Or

  1. nil
  2. string Error message.
sk:recv()
Receive data from the socket.

Returns:

    string The data read from the socket.

Or

  1. nil
  2. string Error message. In particular, if the socket is marked non-blocking and the operation would block then the message "WOULDBLOCK" is returned.
sk:recvfrom()
Receive data from the socket and the address of the sender.

Returns:

  1. string The data read from the socket.
  2. string The path in the abstract namespace (without leading \0) of the sender. Note that this can be an empty string if the sender didn't bind its socket and the kernel didn't automatically generate an address (like it does when e.g. the SO_PASSCRED option is set).

Or

  1. nil
  2. string Error message. In particular, if the socket is marked non-blocking and the operation would block then the message "WOULDBLOCK" is returned.
sk:send(data)
Send the given data to the peer to which the socket is connected. This means sk:connect must have been called first. The data can be provided as a string or as an array of strings. If the total size of the data is more than MAX_DGRAM_SIZE an error will be returned.

Parameters:

Returns:

    boolean true

Or

  1. nil
  2. string Error message. In particular, if the socket is marked non-blocking and the operation would block then the message "WOULDBLOCK" is returned.
sk:sendto(data, path)
Send the given data to the given path in the abstract namespace. The leading \0 will be added automatically. The data can be provided as a string or as an array of strings. If the total size of the data is more than MAX_DGRAM_SIZE an error will be returned.

Parameters:

Returns:

    boolean true

Or

  1. nil
  2. string Error message. In particular, if the socket is marked non-blocking and the operation would block then the message "WOULDBLOCK" is returned.
tch.socket.unix
Useful constants.

Fields:

  • MAX_DGRAM_SIZE The maximum size of a datagram, in bytes.
  • SOCK_CLOEXEC Option to close the socket across execve().
  • SOCK_NONBLOCK Option to make the socket non-blocking when invoking dgram or stream.
generated by LDoc 1.4.5 Last updated 2017-05-04 22:24:31