unix.listen

Synopsis

local unix = require "unix"

unix.stream.listen()
unix.seqpacket.listen()

function(ep: string[, mode: integer]) -> acceptor

Description

  1. Creates a socket.

  2. Set common options.

  3. If mode is given, fchmod() the socket to bit.band(mode, filesystem.mode(7,7,7)).

  4. Binds the socket to ep.

  5. Put the socket in the listening state.

  6. Returns the socket.

If ep starts with @ then it’s assumed to represent an abstract UNIX socket.

Rationale

mode as an extra parameter

To understand why mode is not part of the address string, we must understand why port is part of the address string in ip.tcp.listen(). ip.tcp.listen() accepts the port number as part of the address string because this info is usually stored in config files where there’s a single string to identify the endpoint to bind to. Having this logic embedded in ip.tcp.listen() makes it easier to parse these config files.

However the permission access mode is not part of the endpoint address. mode is not an address. It doesn’t identify an endpoint. It’s a separate value in the config file (possibly fully omitted from the config altogether and hardcoded in the program logic). It’s not even required in many situations (hence why it’s an optional parameter here).

(Not) Removing files by default

This function could simplify the user’s life even further if it also removed the file pointed to by ep before it binds the socket. However it’d make the function unusable in scenarios where the file must be removed by a different process (e.g. a supervised daemon, or many processes contending over the address with custom fallback code).

In other words, the presence/possibility of EADDRINUSE may be a desired property in this algorithm by some programs.

This function is a high-level API and it’s not intended to replace every usage of the lower-level API so the previous point may not be that strong of a reason. However an explicit call to filesystem.remove() in user’s code is not that big of a deal. It doesn’t add that much boilerplate.