Module sys/constants
File-system constants — the numeric flag values std/fs passes to the
async I/O runtime.
File mode bits, permission bits, AT_* flags, open flags, access mode
constants, copy flags, directory entry types, and the default permission
modes fs.create/fs.mkdir use.
Every value here is a Yo literal rather than a c_include of the real
header, because these numbers cross the Yo/C boundary as plain integers:
std/fs hands them to the generated runtime (src/codegen/async/), which
passes them to the syscall. Where a value DIFFERS between platforms it is a
cond on platform and the difference is called out at the definition —
AT_FDCWD, AT_REMOVEDIR and AT_SYMLINK_NOFOLLOW are the three that do.
Everything else is identical on Linux and macOS. Non-Unix targets take the
Linux arm.
Stability
unstable — this is a private constant table for std/fs, not a public
surface. It grows an entry whenever std/fs needs one more flag, it
duplicates numbers that live authoritatively in <fcntl.h> / <sys/stat.h>
/ <dirent.h>, and three of its members (AT_EMPTY_PATH,
COPYFILE_FICLONE, COPYFILE_FICLONE_FORCE) are exported with no Yo caller
at all. Callers want std/fs — FileType, FilePermission, OpenOptions
and fs.copy — which is where the stable spelling of all of this lives.
Freezing this module would mean deciding it is public, and the reason to do
that has not appeared; the more likely end state is that it becomes
_-private once std/fs covers the last raw-flag call site.
Constants
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
Value: <unknown: i32>
The dirfd that makes an *at() syscall resolve a relative path against
the process's current directory — every std/fs call that takes a path
rather than an open handle passes this. The value differs per kernel
(-2 on macOS, -100 on Linux), which is exactly why it is a constant
here and not a literal at the call sites.
Value: -100
unlinkat() flag selecting the rmdir() behaviour instead of unlink():
remove the name only if it is an empty directory. std/fs uses 0 to
delete a file and this to delete a directory. macOS 0x80, Linux 0x200.
Value: 512
Linux statx()/fstatat() flag meaning "the path is empty, stat the
dirfd itself" — the way to stat a handle whose name may already have been
renamed or unlinked. This is the LINUX value and there is no macOS
equivalent (the macOS runtime stats by fd another way), so it is not
cond-ed per platform: nothing in Yo reads it. The generated Linux runtime
uses the C macro directly (src/codegen/async/runtime_io_linux.yo).
Value: 4096
*at() flag that makes the call act on a symlink itself instead of its
target — what separates fs.symlink_metadata from fs.metadata. macOS
0x20, Linux 0x100.
Value: 256
statx() synchronisation mode: "whatever a plain stat() would do" —
zero, so OR-ing it into a flag word is a no-op that documents the intent at
the call site rather than changing behaviour.
Value: 0
statx() field mask requesting the fields a struct stat carries (all
eleven STATX_* basic bits). Linux-specific; the macOS and wasm runtimes
emulate statx over fstatat and ignore the mask.
Value: 2047
Mask selecting the file-type bits out of a mode word: mode & S_IFMT
yields one of the S_IF* values below. std/sys/statx.yo's is_file /
is_directory / is_symlink are exactly that comparison.
Value: 61440
File type: unix-domain socket.
Value: 49152
File type: symbolic link. Only ever seen through a NOFOLLOW stat — a following stat reports the target's type.
Value: 40960
File type: regular file.
Value: 32768
File type: block device.
Value: 24576
File type: directory.
Value: 16384
File type: character device.
Value: 8192
File type: FIFO (named pipe).
Value: 4096
Owner read + write + execute (0o700) — the union of the three below.
Value: 448
Owner may read.
Value: 256
Owner may write.
Value: 128
Owner may execute — on a directory, may traverse it.
Value: 64
Group read + write + execute (0o070).
Value: 56
Group may read.
Value: 32
Group may write.
Value: 16
Group may execute — on a directory, may traverse it.
Value: 8
Other read + write + execute (0o007).
Value: 7
Others may read.
Value: 4
Others may write.
Value: 2
Others may execute — on a directory, may traverse it.
Value: 1
Mode std/fs creates a new file with (rw-r--r--). It is the mode
REQUESTED — the process umask still masks bits out of it, so a file created
under umask 077 lands at 0o600.
Value: 420
Mode std/fs creates a new directory with (rwxr-xr-x), umask applied as
above. The owner-execute bit is what makes the directory traversable, so
this is not DEFAULT_FILE_MODE plus decoration.
Value: 493
dirent.d_type sentinel meaning the directory did not report a type.
It is not an error: several file systems (and every platform where the
field is absent) always answer this, so a directory walk that needs the
type must fall back to a stat of the entry — which is what
std/fs/dir.yo's read_dir does.
Value: 0
Directory entry is a FIFO (named pipe).
Value: 1
Directory entry is a character device.
Value: 2
Directory entry is a directory.
Value: 4
Directory entry is a block device.
Value: 6
Directory entry is a regular file.
Value: 8
Directory entry is a symbolic link.
Value: 10
Directory entry is a unix-domain socket.
Value: 12
Directory entry is a BSD whiteout marker — a union-mount tombstone. Only macOS ever reports it.
Value: 14
access()/faccessat() mode: test existence only. Zero, so it cannot be
OR-ed with the three below — asking for F_OK | R_OK is just R_OK.
Value: 0
access() mode: test read permission. OR-able with W_OK / X_OK.
Value: 4
access() mode: test write permission.
Value: 2
access() mode: test execute (for a directory, traverse) permission.
Value: 1
sys/copy.copyfile flag: fail with EEXIST rather than overwrite an
existing destination. Honoured on every platform — macOS maps it to
copyfile(3)'s COPYFILE_EXCL, Linux and wasm to O_EXCL when they open
the destination.
Value: 1
sys/copy.copyfile flag: prefer a copy-on-write clone, fall back to a
byte copy. macOS only — it becomes copyfile(3)'s COPYFILE_CLONE,
while the Linux and wasm arms of the runtime ignore the bit entirely
(src/codegen/async/runtime_io_common.yo); Linux tries
copy_file_range regardless of it. The name and the 1/2/4 numbering follow
libuv's UV_FS_COPYFILE_*, not any one platform's header. No Yo caller
passes it today.
Value: 2
sys/copy.copyfile flag: require a copy-on-write clone and fail if the
file system cannot do one. Same macOS-only caveat as COPYFILE_FICLONE
(COPYFILE_CLONE_FORCE there); ignored elsewhere, and unused from Yo.
Value: 4