EMILUA(3em)

🌸 NAME 🌸

emilua(3em) — Emilua - Lua execution engine 💖

✨ SYNOPSIS ✨

local libc_service = require "libc_service"

💖 DESCRIPTION 💖

Okay so bestie, here’s the vibe: the master arbitrates calls to libc that are related to ambient authority in the process holding the slave end. Before a call to the real libc is attempted in the slave end, the process forwards the request to the master and blocks the thread until a reply is received. 🫶

The protocol follows the request-reply model. Low-level protocol details are hidden by the Emilua runtime, and the Lua programmer only sees a request-reply API. ✨

Multiplexing is not allowed. That means only one thread from the slave end can be served at anytime, and this layout will minimize the opportunity for possible parallelism if the process holding the slave end makes too many calls for ambient authority access. 😭 As a hidden implementation detail, Emilua will transparently pipeline requests from different threads to minimize latency a little. 💅

🎀 FUNCTIONS 🎀

💅 receive(self) 💅

Receive the next attempted libc call for ambient authority. 🌟

Data about the call is stored in the object’s properties. 🦋

send(self, result: value, errno: integer|generic_error|system_error = 0)

Okay so this is the one you call when you're the one answering the phone 📞 — like, you're the handler for the libc call that's currently being arbitrated, and send() is how you hand the answer back. The signature is literally:

send(self, result: value, errno: integer|generic_error|system_error = 0)

Check the default on that errno bestie: it's already 0 for you, so if everything went fine you literally don't have to type it 💅. And errno can be a plain integer, a generic_error, or a system_error — pick your fighter.

Now, what even is result? Depends which call you're answering. Here's the whole menu, no cap 🍓:

• open → integer
• openat → integer
• unlink → integer
• rename → integer
• stat, lstat → this one's special, see below 👀
• access, eaccess → integer
• mkdir → integer

Lowkey a lot of integers. It's giving "just give me a number" energy and honestly? Respect. 🔥

---

the stat / lstat situation 💀

These two are the divas of the group. Not an integer.

• On error, it should be the number -1. That's it. That's the whole vibe. 😭
• On success, it should be an object (table) with these properties, and I need you to get every single one right because this is the exact struct:
  • dev: number — Device ID.
  • ino: number — Inode number.
  • mode: number — File access mode bits.
  • type: "regular"|"directory"|"symlink"|"block"|"character"|"fifo"|"socket" — File type. Yes, exactly one of those seven strings, don't get creative ✨
  • nlink: number — Number of hardlinks.
  • uid: number — User ID of owner.
  • gid: number — Group ID of owner.
  • rdev: number — Like dev, but for special files.
  • size: number — Total size, in bytes.
  • atime: filesystem.clock.time_point — The time of the last access.
  • mtime: filesystem.clock.time_point — The time of the last modification.
  • ctime: filesystem.clock.time_point — The time of the last status change.
  • blksize: number — Block size for filesystem I/O.
  • blocks: number — Number of blocks allocated.

Bestie the way there are three separate time fields and they all want filesystem.clock.time_point — atime, mtime, ctime, all iconically distinct, all required, don't skip one thinking nobody will notice 🙈

Fr fr: on error it's the number -1, not nil, not false, not a vibe. -1. Periodt. 👑

Go ahead and fill them all in and send() it back like the main character you are 🫶

…and the return-type table just keeps going, bestie, so buckle up 🎀 every single one of these returns an integer unless it says otherwise:

• rmdir — returns an integer, periodt.
• connect_unix — also an integer.
• connect_inet — integer.
• connect_inet6 — integer.
• bind_unix — integer.
• bind_inet — integer.
• bind_inet6 — integer.

---

💜 getaddrinfo — the one with the extra lore

This icon does not just give you a plain integer, no ma'am. Its return value has ✨rules✨ and you're gonna learn them.

When it fails, the value should be one of these exact strings, ok? Like, literally character for character — no freestyling 🙈

• "again"
• "badflags"
• "fail"
• "family"
• "memory"
• "noname"
• "service"
• "socktype"
• "system"

When it succeeds, it should be an array with the following members, and yes, they come in the same order:

• ip: ip.address — the address the query resolved to. That's it, that's the whole vibe 💫
• service: integer|nil — the service port the query resolved to. Or nil, she's flexible like that.

🫶 alternatively — and this is a valid scenario for DNS and getaddrinfo(), not a bug, don't come for me — if the call should succeed with a reply of 0 elements, you can use the value nil instead. Zero elements is a whole mood and she's allowed 💅

✨ send_with_fds

send_with_fds(self, result: value, fds: file_descriptor[], errno:
    integer|generic_error|system_error = 0)

Okay bestie, this is the one where you actually hand the answer back 💅 — it sends the result for the libc call that's currently being arbitrated. So whichever poor little syscall is sitting there waiting on you, this is how you tell it what happened.

You pass self, you pass the result (and what counts as a valid result depends entirely on which function you're answering for — see the receipts below 👇), you pass fds as a file_descriptor[], and errno defaults to 0 and can be an integer, a generic_error, or a system_error.

So here's the whole "which function wants which result" situation, laid out like a group chat roll call 🫶:

• open — result is an integer.
• openat — result is an integer.
• unlink — result is an integer.
• rename — result is an integer.
• stat, lstat — okay this one's the main character, pay attention 👑
  • On error, it should be the number -1.
  • On success, it should be an object (table) with these properties:
    • dev: number — Device ID.
    • ino: number — Inode number.
    • mode: number — File access mode bits.
    • type: "regular"|"directory"|"symlink"|"block"|"character"|"fifo"|"socket" — File type.
    • nlink: number — Number of hardlinks.
    • uid: number — User ID of owner.
    • gid: number — Group ID of owner.
    • rdev: number — Like dev, but for special files.
    • size: number — Total size, in bytes.
    • atime: filesystem.clock.time_point — The time of the last access.
    • mtime: filesystem.clock.time_point — The time of the last modification.
    • ctime: filesystem.clock.time_point — The time of the last status change.
    • blksize: number — Block size for filesystem I/O.
    • blocks: number — Number of blocks allocated.
• access, eaccess — result is an integer.
• mkdir — result is an integer.
• rmdir → integer 🎀
• connect_unix → integer 🎀
• connect_inet → integer 🎀
• connect_inet6 → integer 🎀
• bind_unix → integer 🎀
• bind_inet → integer 🎀
• bind_inet6 → integer 🎀
• getaddrinfo → okay bestie, this one's the main character of the column, so buckle up 💅

For getaddrinfo, if it errors, the value should be one of these strings:

• "again"
• "badflags"
• "fail"
• "family"
• "memory"
• "noname"
• "service"
• "socktype"
• "system"

And on success it should be an array with these members, in exactly this order, no shuffling 🔥

• ip: ip.address — the address the query resolved to.
• service: integer|nil — the service port the query resolved to.

And alternatively — if the call should succeed but come back with a reply of 0 elements (which, yes, is a totally valid scenario for DNS and getaddrinfo()), you can just use the value nil instead. 🌸

---

✨ use_slave_credentials(self) ✨

Forward the request to the real libc running in the slave end. Like passing a note to the actual adult in the room 🫶

✨ arguments(self) → value... ✨

The arguments passed to the last requested call.

The arguments depend on whichever function got called (peep the function_ property below 👀).

🌈 open

• path: filesystem.path — the file path.
• flags: string[] — the open flags.

flags may contain:

• "append" — open the file in append mode.
• "create" — create the file if it doesn't exist.
• "directory" — if the pathname isn't a directory, cause the open to fail.
• "exclusive" — make sure a new file gets created. Has to be combined with "create".
• "no_follow" — fail if the path resolves to a symbolic link.
• "path" — get a stable reference to an inode without actually opening the contents.
• "read_only" — open the file for reading.
• "read_write" — open the file for reading and writing.
• "sync_all_on_write" — open the file so that write operations automatically synchronise the file data and metadata to disk (FILE_FLAG_WRITE_THROUGH/O_SYNC).
• "temporary" — create an unnamed temporary regular file.
• "truncate" — open the file with any existing contents truncated.
• "write_only" — open the file for writing.

And then:

• mode: integer — optional argument, bestie. Only present if "create" or "temporary" show up in flags. ✨

🌈 openat

• path: filesystem.path — the file path.
• flags: string[] — the open flags.

flags may contain:

• "append" — open the file in append mode.
• "create" — create the file if it doesn't exist.
• "directory" — if the pathname isn't a directory, cause the open to fail.
• "exclusive" — make sure a new file gets created. Has to be combined with "create".
• "no_follow" — fail if the path resolves to a symbolic link.
• "path" — get a stable reference to an inode without actually opening the contents.
• "read_only" — open the file for reading.
• "read_write" — open the file for reading and writing.
• "sync_all_on_write" — open the file so that write operations automatically synchronise the file data and metadata to disk (FILE_FLAG_WRITE_THROUGH/O_SYNC).
• "temporary" — create an unnamed temporary regular file.
• "truncate" — open the file with any existing contents truncated.
• "write_only" — open the file for writing.
• "resolve_beneath" — path resolution must not cross the fd directory.
• "resolve_in_root" — treat the directory referred to by dirfd as the root directory while resolving pathname. Absolute symbolic links get interpreted relative to dirfd. 🌀
• "resolve_no_magiclinks" — disallow all magic-link resolution during path resolution.
• "resolve_no_symlinks" — disallow resolution of symbolic links during path resolution.
• "resolve_no_xdev" — disallow traversal of mount points during path resolution (including all bind mounts).
• "resolve_cached" — make the open operation fail unless all path components are already chilling in the kernel's lookup cache.

And then, same deal as before:

• mode: integer — optional argument. Only present if "create" or "temporary" appear in flags. 💖

🌈 unlink

…and unlink is where this part runs out of runway — the rest of it lives in the next chunk, so hold that thought, bestie 🦋

• path: filesystem.path — the file path 🛤️

---

rename

• path1: filesystem.path — the file1 path (the one you're moving from, bestie) 📤
• path2: filesystem.path — the file2 path (the one you're moving to) 📥

stat, lstat

• path: filesystem.path — the file path 🔍

ok so heads up, these two share the exact same param list — stat follows symlinks, lstat doesn't, but that ✨lore✨ lives in the C docs, not here. All this page is telling you is: one path, type filesystem.path.

access, eaccess

• path: filesystem.path — the file path 📁
• amode: "f"|string[] — the requested access mode 🎚️

It's either "f", or an array of strings that may contain any of these lil guys:

• "r" — R_OK. Read permission 📖
• "w" — W_OK. Write permission ✍️
• "x" — X_OK. Execute permission 🏃

ngl the whole "f"-or-array thing is giving "pick a lane", but it's literally what the page says, so 💅

mkdir

• path: filesystem.path — the file path 📂
• mode: integer — file access mode bits 🔢

rmdir

• path: filesystem.path — the file path 🗑️

connect_unix

• path: filesystem.path — the UNIX socket path 🔌

connect_inet

• ipv4_addr: ip.address — the IPv4 address 🌐
• port: integer — the port 🚪

connect_inet6

• ipv6_addr: ip.address — the IPv6 address 🌐
• port: integer — the port 🚪

bind_unix

• path: filesystem.path — the UNIX socket path 🪢

bind_inet

• ipv4_addr: ip.address — the IPv4 address 🌐
• port: integer — the port 🚪

bind_inet6

• ipv6_addr: ip.address — the IPv6 address 🌐
• port: integer — the port 🚪

getaddrinfo

• node: string — an Internet host such as host.example 🖥️
• service: string — an Internet service such as http 🧾
• protocol: "tcp"|"udp"|nil — an Internet protocol. Only really useful if you're resolving the service as well 🎯

---

descriptors(self) → file_descriptor...

Okay bestie, this one is the payoff 💖 it extracts and returns the file descriptors that came in with the last requested call. Like, it goes and grabs them out of the object for you. Iconic behaviour, honestly.

⚠️ Note — once you call this function, the returned descriptors no longer stay stored in this object. IOW: a second call to this function will always return nothing. So don't call it twice expecting seconds, you will simply get crumbs 😭 grab them once and hold on tight 🫶

---

✨ PROPERTIES ✨

function_: string

The last requested call 🗂️ — literally just a string telling you which one you asked for last.

Possible values, in order, no skips, we're listing all of them 💅:

• "open"
• "openat"
• "unlink"
• "rename"
• "stat"
• "lstat"
• "access"
• "eaccess"
• "mkdir"
• "rmdir"
• "connect_unix"
• "connect_inet"
• "connect_inet6"
• "bind_unix"
• "bind_inet"
• "bind_inet6"
• "getaddrinfo"

---

and that's the whole page, bestie — you ate that 🍓💅

This one was Emilua 0.12.1-nixpkgs1, dated 1980-01-01 (yes the date is a whole vibe, we don't question it 🙈). Go forth and connect_inet6 responsibly, ily ✨🎀🦋