EMILUA(3em)

💖 EMILUA(3em) 💖

bestie, welcome to the Emilua reference page for file_descriptor. This is the EMILUA(3em) manual page, and we're gonna get you comfy with it — no cap. It's giving “low-level fd energy” but make it cute. 💅

---

✨ NAME ✨

Emilua — Lua execution engine.

🦋 DESCRIPTION 🦋

Okay so this whole page is about a file descriptor. That's the main character.

🚨 Note: it cannot be created directly. Not me trying to instantiate an fd from scratch — nope, not happening.

🪟 Note: on Windows, file_descriptor is only implemented for pipes and file.stream. So Windows besties, that's the vibe check.

💅 FUNCTIONS 💅

• close(self) — closes the file descriptor w/o waiting for the GC. She said bye immediately, no ghosting the garbage collector.
• dup(self) → file_descriptor — creates a new file descriptor that refers to the same open file description. Sibling fds, same underlying vibe.
• is_socket(self, family: unix"|"inet"|"inet6"[, type: stream |"datagram"|"seqpacket"[, protocol: tcp |"udp"]]) → boolean" — checks whether the file descriptor refers to a socket of the specified family, type, and protocol.
• kcmp(self, other: file_descriptor) → integer — see kcmp(2) and KCMP_FILE. Like a little fd comparison check, iykyk.
• openat(self, path: filesystem.path, flags: string[][, mode: integer]) → file_descriptor — the implementation for this function always includes the flag O_NOCTTY behind the scenes. Like a secret little helper. 🫶

flags may contain:

• "append" — open the file in append mode.
• "create" — create the file if it does not exist.
• "directory" — fail if path resolves to a non-directory file.
• "exclusive" — ensure a new file is created. Must be combined with create.
• "no_follow" — fail if 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 (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 are 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 present in the kernel’s lookup cache.

See openat(3).

• cap_get(self) → system.linux_capabilities — see cap_get_fd(3).
• cap_set(self, caps: system.linux_capabilities) — see cap_set_fd(3).
• cap_rights_limit(self, rights: string[]) — see cap_rights_limit(2).

Parameters:

• rights: string[] — one of these cuties:
  • "accept"
  • "acl_check"
  • "acl_delete"
  • "acl_get"
  • "acl_set"
  • "bind"
  • "bindat"
  • "chflagsat"
  • "connect"
  • "connectat"
  • "create"
  • "event"
  • "extattr_delete"
  • "extattr_get"
  • "extattr_list"
  • "extattr_set"
  • "fchdir"
  • "fchflags"
  • "fchmod"
  • "fchmodat"
  • "fchown"
  • "fchownat"
  • "fcntl"
  • "fexecve"
  • "flock"
  • "fpathconf"
  • "fsck"
  • "fstat"
  • "fstatat"
  • "fstatfs"
  • "fsync"
  • "ftruncate"
  • "futimes"
  • "futimesat"
  • "getpeername"
  • "getsockname"
  • "getsockopt"
  • "ioctl"
  • "kqueue"
  • "kqueue_change"
  • "kqueue_event"
  • "linkat_source"
  • "linkat_target"
  • "listen"
  • "lookup"
  • "mac_get"
  • "mac_set"
  • "mkdirat"
  • "mkfifoat"
  • "mknodat"
  • "mmap"
  • "mmap_r"
  • "mmap_rw"
  • "mmap_rwx"
  • "mmap_rx"
  • "mmap_w"
  • "mmap_wx"
  • "mmap_x"
  • "pdgetpid"
  • "pdkill"
  • "peeloff"
  • "pread"
  • "pwrite"
  • "read"
  • "recv"
  • "renameat_source"
  • "renameat_target"
  • "seek"
  • "sem_getvalue"
  • "sem_post"
  • "sem_wait"
  • "send"
  • "setsockopt"
  • "shutdown"
  • "symlinkat"
  • "ttyhook"
  • "unlinkat"
  • "write"

• cap_rights_contains(self, rights: string[]) → boolean — returns whether all the given capability rights are set. rights has the same set of allowed values as cap_rights_limit().
• cap_rights_remove(self, rights: string[]) — it performs the following actions (in a non-atomic manner):
  1. Query current capabilities on the file descriptor.
  2. Remove rights from the returned set.
  3. Limit capabilities to the new set.

rights has the same set of allowed values as cap_rights_limit().

• cap_ioctls_limit(self, cmds: integer[]) — see cap_ioctls_limit(2).
• cap_ioctls_get(self) → integer[]| all"" — see cap_ioctls_get(2).
• cap_fcntls_limit(self, fcntlrights: string[]) — see cap_fcntls_limit(2).

Parameters:

• fcntlrights: string[] — one of:
  • "getfl"
  • "setfl"
  • "getown"
  • "setown"

• cap_fcntls_get(self) → string[] — see cap_fcntls_get(2).

🌸 PROPERTIES 🌸

• non_blocking: boolean — query/set the fcntl flag O_NONBLOCK.
• type: string — one of:
  • "regular"
  • "directory"
  • "symlink"
  • "block"
  • "character"
  • "fifo"
  • "socket"
  • "unknown"

🎀 METAMETHODS 🎀

• __tostring() — produces a string in the format "/dev/fd/%i" where "%i" is the integer value as seen by the OS.

---

That’s the whole page, bestie. source/version: Emilua 0.12.1-nixpkgs1 · date: 1980-01-01 💖✨