file_descriptor

A file descriptor.

It cannot be created directly.
On Windows, file_descriptor is only implemented for pipes and file.stream.

Functions

close(self)

Closes the file descriptor w/o waiting for the GC.

dup(self) → file_descriptor

Creates a new file descriptor that refers to the same open file description.

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.

openat(self, path: filesystem.path, flags: string[][, mode: integer]) → file_descriptor

The implementation for this function always include the flag O_NOCTTY behind the scenes.

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[]

    • "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[]

    • "getfl"

    • "setfl"

    • "getown"

    • "setown"

cap_fcntls_get(self) → string[]

See cap_fcntls_get(2).

Properties

non_blocking: boolean

Query/set 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.