EMILUA(3em)

🌸 NAME 🌸

okay so bestie, welcome to the EMILUA(3em) page — this is the reference for Emilua, the Lua execution engine 💖. That’s the whole name vibe: Emilua - Lua execution engine.

🎀 SYNOPSIS 🎀

Here’s the shape of it, literally:

local unix = require "unix"

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

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

So yeah, you pull in the unix module with require "unix", and the synopsis shows unix.stream.listen() and unix.seqpacket.listen() showing up to the party ✨.

💅 DESCRIPTION 💅

okay so this function is a whole little sequence, and it’s giving “step-by-step main character energy” 👑:

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. If mode is given, chmod() the endpoint to bit.band(mode, filesystem.mode(7,7,7)).
6. Put the socket in the listening state.
7. Returns the socket.

Note 💭 — If ep starts with @ then it’s assumed to represent an abstract UNIX socket. no cap.

🧚 RATIONALE 🧚

🌈 mode as an extra parameter 🌈

okay so 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.

made with 💖 by Emilua 0.12.1-nixpkgs1, dated 1980-01-01 — periodt.