ww/lib/os/os.ww

// os — process and filesystem facade. The body of each call lands
// either in libwwrt.a (rt_syscall trampoline) or libc bindings,
// depending on how the program was linked.

@symbol("rt_syscall") fn syscall0(num: nr) i64;
@symbol("rt_syscall") fn syscall1(num: nr, a: i64) i64;
@symbol("rt_syscall") fn syscall2(num: nr, a: i64, b: i64) i64;
@symbol("rt_syscall") fn syscall3(num: nr, a: i64, b: i64, c: i64) i64;
@symbol("rt_syscall") fn syscall4(num: nr, a: i64, b: i64, c: i64, d: i64) i64;

// alloc / free — runtime mmap-backed page allocator. Untyped:
// `alloc(n)` returns a `*void` and `free(p, n)` requires the byte
// count back because rt_free is munmap-based and doesn't track
// mapping sizes (the kernel needs the length to release the
// reservation).
//
// Diverges from Hare. Hare exposes `alloc` / `free` as typed
// language builtins (`alloc(value, cap)?` / `free(ptr)`) that the
// compiler lowers to rt::malloc/rt::free; ww has no such builtins,
// so the rt-symbol surface is exposed directly. Stdlib callers
// that need a typed allocation pattern wrap this with a cast plus
// a stored capacity (see [[strings.dup]], [[memio.dynamic]]).
//
// OOM: rt_alloc is a bare mmap(MAP_ANON|MAP_PRIVATE) wrapper with
// no error path. The raw Linux mmap syscall returns a negative
// errno cast to `*void` on failure (e.g. `(void*)-12` for ENOMEM);
// the `MAP_FAILED` (`(void*)-1`) value is a libc-wrapper convention
// that rt_alloc doesn't apply. Neither `== nil` nor `== (void*)-1`
// catches it; any deref of such a return faults. Today the stdlib
// does not check; OOM faults on first dereference. A typed
// fallible variant is a future task.
@symbol("rt_alloc") export fn alloc(n: u64) *void;
@symbol("rt_free")  export fn free(p: *void, n: u64) void;
@symbol("rt_abort") fn abort(msg: str) void;

// Hare-style runtime check. Caller passes a message that's printed
// to stderr before exit(1).
export fn assert(cond: bool, msg: str) void = {
	if (!cond) { abort(msg); };
};

// Linux amd64 syscall numbers. Internal to this module — passed as
// the first arg of syscall0..4 via libwwrt's rt_syscall trampoline.
// `nr` is the type so the call sites can't accidentally pass an
// arbitrary i64 (`syscall1(0i64, ...)` no longer typechecks).
type nr = enum i64 {
	READ        = 0,
	WRITE       = 1,
	OPEN        = 2,
	CLOSE       = 3,
	LSEEK       = 8,
	ACCESS      = 21,
	DUP2        = 33,
	GETPID      = 39,
	FORK        = 57,
	EXECVE      = 59,
	EXIT        = 60,
	WAIT4       = 61,
	MKDIR       = 83,
	RMDIR       = 84,
	UNLINK      = 87,
	GETCWD      = 79,
	GETDENTS64  = 217,
	NEWFSTATAT  = 262,
};

// open(2) flags. Linux values, matching <fcntl.h>. Hare names them
// `fs::flag::RDONLY` etc; we use the same leaf names so callers say
// `os.flag.RDONLY` and `os.flag.WRONLY | os.flag.CREATE`.
export type flag = enum i32 {
	RDONLY  = 0,
	WRONLY  = 1,
	RDWR    = 2,
	CREATE  = 64,	// 0x40
	EXCL    = 128,	// 0x80 — pair with CREATE to fail on existing path
	TRUNC   = 512,	// 0x200
};

// lseek(2) whence. Hare names it `io::whence`.
export type whence = enum i32 {
	SET = 0,
	CUR = 1,
	END = 2,
};

export fn exit(code: i32) void = {
	syscall1(nr.EXIT, code: i64);
};

// PATH_MAX / pathbuf / kpath — port of Hare's ref/hare/sys/+linux/
// syscalls.ha:25,27,29-55. Hare's `path` accepts a sum `(str |
// []u8 | *const u8)`; ww's lib/os public surface narrows to `str`
// (the Hare-faithful surface at ref/hare/os/os.ha:37,47,50 etc).
// Internally, [[kpath]] copies the `str` bytes into a single
// module-level [[pathbuf]] scratch slot and NUL-terminates so the
// raw Linux syscalls (which require C strings) see a valid
// terminator. Same precedent as Hare's static `pathbuf`.
//
// Non-reentrant: one buffer, every [[stat]] / [[open]] / etc.
// rewrites it. Same caveat as strconv's `*tos` family (overwritten
// on next call). Caller must NOT hold a kpath-returned pointer
// across another lib/os path call. Graduates when ww grows a
// thread story.
//
// `nil`-as-overflow over `(*u8 | oserror)`: wwstage over-allocates
// 1-word-payload tagged returns to 24B (cstage emits 16B).
// Task #9; revert at task #10 when fixed. Repro at
// .ai/probe_tagged_return_pointer_payload.ww.
export def PATH_MAX: i32 = 4096;
let pathbuf: [4096]u8;

fn kpath(p: str) *u8 = {
	if (p.len + 1 >= PATH_MAX) { return nil: *u8; };	// ENAMETOOLONG
	let i: i32 = 0;
	for (i < p.len) { pathbuf[i] = p[i]; i += 1; };
	pathbuf[p.len] = 0u8;
	return &pathbuf[0];
};

// Raw, non-fallible primitives. These return Linux's int conventions
// (negative = -errno, non-negative = bytes/fd/etc). Callers wanting a
// Hare-style fallible API use the wrappers below.
export fn write(fd: i32, buf: *u8, n: u64) i64 = {
	return syscall3(nr.WRITE, fd: i64, buf: i64, n: i64);
};

export fn read(fd: i32, buf: *u8, n: u64) i64 = {
	return syscall3(nr.READ, fd: i64, buf: i64, n: i64);
};

export fn close(fd: i32) i32 = {
	return syscall1(nr.CLOSE, fd: i64): i32;
};

// dup2(2): make `newfd` refer to the same description as `oldfd`,
// closing `newfd` first if open. Returns `newfd` on success or a
// negative errno. Used by w6c_ww to redirect stdout into an output
// file without changing the cgen emit path.
export fn dup2(oldfd: i32, newfd: i32) i32 = {
	return syscall2(nr.DUP2, oldfd: i64, newfd: i64): i32;
};

// Fallible wrappers. The error variant is `oserror` (an i64 carrying
// -errno). The sum type makes success/failure explicit and lets
// callers `?` the result up the stack.
export fn tryread(fd: i32, buf: *u8, n: u64) (i64 | oserror) = {
	let r: i64 = read(fd, buf, n);
	if (r < 0) { return r: oserror; };
	return r;
};

export fn trywrite(fd: i32, buf: *u8, n: u64) (i64 | oserror) = {
	let r: i64 = write(fd, buf, n);
	if (r < 0) { return r: oserror; };
	return r;
};

// open — Linux open(2). Returns -errno on failure, fd otherwise.
// Higher-level callers prefer `tryopen`. Mirrors Hare's os::open
// (ref/hare/os/os.ha:117); kpath lands the bytes in pathbuf.
// Returns -ENAMETOOLONG (-36) if the path overflows PATH_MAX.
export fn open(path: str, flags: flag, mode: i32) i32 = {
	let p: *u8 = kpath(path);
	if (p == nil: *u8) { return -36i32; };	// ENAMETOOLONG
	return syscall3(nr.OPEN, p: i64, (flags as i32): i64, mode: i64): i32;
};

export fn tryopen(path: str, flags: flag, mode: i32) (i32 | oserror) = {
	let fd: i32 = open(path, flags, mode);
	if (fd < 0) { return fd: i64: oserror; };
	return fd;
};

// lseek — set/inspect the fd's position. Returns the new offset or
// a negative errno. We use this for fstat-free file-size discovery
// (open ⇒ lseek to end ⇒ lseek back).
export fn lseek(fd: i32, off: i64, w: whence) i64 = {
	return syscall3(nr.LSEEK, fd: i64, off, (w as i32): i64);
};

// oserror — the underlying errno from a failed syscall, as a
// negative i64 (Linux's int convention; e.g. -2 = ENOENT). The
// `!`-flagged alias makes ?-propagation pick this variant as the
// error half of any (T | oserror) shape. Hare's analogue is
// errors::errno carried inside io::error.
export type oserror = !i64;

// filesize — byte length of an open fd via lseek-to-end-and-back.
export fn filesize(fd: i32) (i64 | oserror) = {
	let end: i64 = lseek(fd, 0i64, whence.END);
	if (end < 0) { return end: oserror; };
	let r: i64 = lseek(fd, 0i64, whence.SET);
	if (r < 0) { return r: oserror; };
	return end;
};

// readall — keep reading until `n` bytes have arrived or the fd
// closes early. Hare name (io::readall); the buffer is caller-
// supplied, matching the Plan 9 subset convention.
export fn readall(fd: i32, buf: *u8, n: u64) (i64 | oserror) = {
	let got: u64 = 0u64;
	for (got < n) {
		let r: i64 = read(fd, buf + got, n - got);
		if (r < 0) { return r: oserror; };
		if (r == 0) { return got: i64; };	// short read: caller decides
		got += r: u64;
	};
	return got: i64;
};

// writeall — keep writing until `n` bytes have been accepted or the
// fd refuses progress. Hare name (io::writeall).
export fn writeall(fd: i32, buf: *u8, n: u64) (i64 | oserror) = {
	let sent: u64 = 0u64;
	for (sent < n) {
		let r: i64 = write(fd, buf + sent, n - sent);
		if (r < 0) { return r: oserror; };
		if (r == 0) { return sent: i64; };
		sent += r: u64;
	};
	return sent: i64;
};

// ---- process and filesystem helpers used by the `ww` driver ----------

// access(2): returns 0 if the file is reachable, negative errno
// otherwise. mode is the bitset described in <unistd.h> (F_OK=0).
// Mirrors Hare's os::access (ref/hare/os/+linux/fs.ha:access).
// Returns -ENAMETOOLONG (-36) if the path overflows PATH_MAX.
export fn access(path: str, mode: i32) i32 = {
	let p: *u8 = kpath(path);
	if (p == nil: *u8) { return -36i32; };
	return syscall2(nr.ACCESS, p: i64, mode: i64): i32;
};

// remove — unlink(2). Mirrors Hare's os::remove
// (ref/hare/os/os.ha:12).
export fn remove(path: str) i32 = {
	let p: *u8 = kpath(path);
	if (p == nil: *u8) { return -36i32; };
	return syscall1(nr.UNLINK, p: i64): i32;
};

// mkdir — mkdir(2). Mode is the unix permission bitset (e.g. 0o700).
// Returns 0 on success, negative errno otherwise. Mirrors Hare's
// os::mkdir (ref/hare/os/os.ha:50).
export fn mkdir(path: str, mode: i32) i32 = {
	let p: *u8 = kpath(path);
	if (p == nil: *u8) { return -36i32; };
	return syscall2(nr.MKDIR, p: i64, mode: i64): i32;
};

// rmdir — rmdir(2). Mirrors Hare's os::rmdir
// (ref/hare/os/os.ha:58).
export fn rmdir(path: str) i32 = {
	let p: *u8 = kpath(path);
	if (p == nil: *u8) { return -36i32; };
	return syscall1(nr.RMDIR, p: i64): i32;
};

// mkdirs — recursive mkdir. Creates `path` and any non-existent
// parent directories with the given mode. EEXIST is silently
// accepted (matches Hare's `errors::exists` skip in os::mkdirs);
// any other syscall failure surfaces as `oserror`.
//
// Mirrors Hare's os::mkdirs (ref/hare/os/os.ha:54). The in-place
// '/' → NUL splice walks the kpath-loaded [[pathbuf]] directly
// instead of recursing through [[mkdir]] — re-entering kpath would
// clobber the buffer mid-walk (single static slot, see kpath's
// non-reentrancy note above).
export fn mkdirs(path: str, mode: i32) (void | oserror) = {
	let cp: *u8 = kpath(path);
	if (cp == nil: *u8) { return -36i64: oserror; };
	let n: i32 = path.len;
	if (n == 0) { return; };

	// Walk forward; at each '/' boundary, NUL-terminate the prefix,
	// raw MKDIR syscall on pathbuf, restore the slash, continue.
	// Skip index 0 so a leading '/' on absolute paths doesn't
	// trigger an empty mkdir.
	let i: i32 = 1;
	for (i < n) {
		if (pathbuf[i] == 47u8) {	// '/'
			pathbuf[i] = 0u8;
			let r: i32 = syscall2(nr.MKDIR,
			    (&pathbuf[0]): i64, mode: i64): i32;
			pathbuf[i] = 47u8;
			if (r < 0) {
				if (r != -17) { return r: i64: oserror; };
			};
		};
		i += 1;
	};

	let r: i32 = syscall2(nr.MKDIR,
	    (&pathbuf[0]): i64, mode: i64): i32;
	if (r < 0) {
		if (r != -17) { return r: i64: oserror; };
	};
	return;
};

// getpid(2). Used by the driver to mint unique scratch paths.
export fn getpid() i32 = {
	return syscall0(nr.GETPID): i32;
};

// fork(2): 0 in the child, child pid in the parent, negative errno
// on failure.
export fn fork() i32 = {
	return syscall0(nr.FORK): i32;
};

// execve(2): on success, does not return. Mirrors Hare's
// os::exec::exec path arg (str). argv/envp stay `**u8` — the
// kernel takes a NUL-pointer-terminated table of NUL-terminated
// C strings, a different shape from a path.
export fn execve(path: str, argv: **u8, envp: **u8) i32 = {
	let p: *u8 = kpath(path);
	if (p == nil: *u8) { return -36i32; };
	return syscall3(nr.EXECVE, p: i64, argv: i64, envp: i64): i32;
};

// wait4(2): wait for `pid` (or any child if -1), store status in
// `*status`, return the pid that ended (or negative errno).
export fn wait4(pid: i32, status: *i32, options: i32, rusage: *void) i32 = {
	return syscall4(nr.WAIT4, pid: i64, status: i64,
	    options: i64, rusage: i64): i32;
};

// getcwd(2) — Linux flavour. Writes the NUL-terminated cwd into `buf`
// and returns the number of bytes written (including the NUL), or a
// negative errno. The driver uses it to expand `.` to the cwd's
// basename for `ww build` / `ww test`.
export fn getcwd(buf: *u8, n: u64) i64 = {
	return syscall2(nr.GETCWD, buf: i64, n: i64);
};

// getdents64(2) — Linux directory enumeration. The fd must be opened
// with O_RDONLY on a directory. `buf` receives a packed sequence of
// linux_dirent64 records:
//
//   struct linux_dirent64 {
//       u64  d_ino;       // 0..7
//       i64  d_off;       // 8..15
//       u16  d_reclen;    // 16..17  — total bytes for this record
//       u8   d_type;      // 18      — DT_REG/DT_DIR/...
//       u8   d_name[];    // 19..    — NUL-terminated name + padding
//   };
//
// Returns bytes written into `buf` (advance by d_reclen to walk),
// 0 at end-of-directory, or a negative errno.
export fn getdents64(fd: i32, buf: *u8, n: u64) i64 = {
	return syscall3(nr.GETDENTS64, fd: i64, buf: i64, n: i64);
};

// ---- environment ------------------------------------------------------

// rt_envp — runtime-side getter. rt/start.s captures envp into a DATAW
// slot before calling main; this binding lifts the captured pointer
// into ww. Same FFI shape as rt_syscall / rt_alloc / rt_abort: a TEXT
// symbol the linker resolves. The returned `**u8` is a NUL-terminated
// table of `*u8` entries, each pointing at a NUL-terminated
// "NAME=VALUE" byte sequence.
//
// We don't expose `rtenvp` directly; [[getenv]] is the only consumer.
@symbol("rt_envp") fn rtenvp() **u8;

// getenv — POSIX getenv. Returns a borrowed `str` view over the value
// bytes of the named environment variable, or void if the name is not
// present. The view is valid for the process lifetime — the bytes
// live in the kernel-supplied envp table at process entry. A future
// `setenv` (separate task) that grows the table behind the scenes
// would invalidate prior views; v1 has no setenv, so callers can
// hold the view indefinitely.
//
// Mirrors Hare's os::tryenv shape (returns void rather than panicking
// on missing). Hare also ships os::getenv (`(str | void)`) and
// os::mustenv (panic-on-missing); ww collapses to the single
// `(str | void)` form for now — consumers wanting "must" semantics
// abort at the call site.
//
// Algorithm: walk the NUL-pointer-terminated `environ` table doing a
// "name=" prefix match against each entry, byte-wise. NUL inside
// `name` would never match a real env var (env var names cannot
// contain '\0'), so we don't filter — POSIX puts that responsibility
// on the caller.
export fn getenv(name: str) (str | void) = {
	let envp: **u8 = rtenvp();
	let i: i32 = 0;
	for (true) {
		let entry: *u8 = envp[i];
		if (entry == nil: *u8) { return; };
		let j: i32 = 0;
		let matched: bool = true;
		for (j < name.len) {
			if (entry[j] == 0u8) { matched = false; break; };
			if (entry[j] != name[j]) { matched = false; break; };
			j += 1;
		};
		if (matched) {
			if (entry[name.len] == 61u8) {	// '='
				let val: *u8 = entry + ((name.len + 1): u64);
				let n: i32 = 0;
				for (val[n] != 0u8) { n += 1; };
				let r: str;
				r.ptr = val;
				r.len = n;
				return r;
			};
		};
		i += 1;
	};
	return;
};

// ---- stat / lstat / fstat / exists -----------------------------------
//
// Ports of Hare's stat family (ref/hare/fs/fs.ha:172,196 +
// ref/hare/sys/+linux/stat.ha:24-58). The Hare surface returns
// `filestat` by value; ww's cgreturn ABI tops out at 24B today (see
// STATUS task #21) and filestat is 80B, so [[stat]] / [[lstat]] /
// [[fstat]] take an out-parameter and return `(void | oserror)`.
// Re-evaluate the by-value shape when full sret lands.
//
// `filestat`, `mode`, and `stat_mask` live in lib/os because ww has
// no lib/fs yet; Hare puts them in `fs::`. These types graduate to
// lib/fs when that module ships — callers should expect a future
// re-export.
//
// Underlying syscall is SYS_newfstatat (262), which unifies
// stat/lstat/fstat through the `dirfd + flags` triple:
//   stat  = newfstatat(AT_FDCWD, path,  0)
//   lstat = newfstatat(AT_FDCWD, path,  AT_SYMLINK_NOFOLLOW)
//   fstat = newfstatat(fd,       "",    AT_EMPTY_PATH)
// Avoiding SYS_statx — its 256B variable layout would buy btime,
// but Hare's filestat doesn't expose btime either, so we stay on
// the simpler 144B kernel struct.

// fstatat(2) flag values. Linux constants from <linux/fcntl.h>.
// Names mirror Hare's ref/hare/sys/+linux/types.ha:45-51 (capital-
// AT_ prefix, top-level `def`s).
export def AT_FDCWD:            i32 = -100;
export def AT_SYMLINK_NOFOLLOW: i32 = 256;	// 0x100
export def AT_EMPTY_PATH:       i32 = 4096;	// 0x1000

// mode — file-mode bits. Mirrors Hare's fs::mode (ref/hare/fs/
// types.ha:63). Permission bits are the standard Unix octal subset;
// type bits live in the S_IFMT = 0o170000 region. Type-bit test:
//
//   let t: u32 = (fi.mode as u32) & 61440u32;	// 0o170000 mask
//   if (t == os.mode.DIR as u32) { /* directory */ };
//
// Numeric values are octal in Hare's source; ww has no octal
// literals so they're written as decimal with the octal in a
// trailing comment.
export type mode = enum u32 {
	// permission bits
	USER_RWX  = 448u32,	// 0o700
	USER_RW   = 384u32,	// 0o600
	USER_RX   = 320u32,	// 0o500
	USER_R    = 256u32,	// 0o400
	USER_W    = 128u32,	// 0o200
	USER_X    = 64u32,	// 0o100
	GROUP_RWX = 56u32,	// 0o070
	GROUP_RW  = 48u32,	// 0o060
	GROUP_RX  = 40u32,	// 0o050
	GROUP_R   = 32u32,	// 0o040
	GROUP_W   = 16u32,	// 0o020
	GROUP_X   = 8u32,	// 0o010
	OTHER_RWX = 7u32,	// 0o007
	OTHER_RW  = 6u32,	// 0o006
	OTHER_RX  = 5u32,	// 0o005
	OTHER_R   = 4u32,	// 0o004
	OTHER_W   = 2u32,	// 0o002
	OTHER_X   = 1u32,	// 0o001
	SETUID    = 2048u32,	// 0o4000
	SETGID    = 1024u32,	// 0o2000
	STICKY    = 512u32,	// 0o1000
	// file-type bits (S_IFMT mask = 0o170000 = 61440)
	UNKNOWN   = 0u32,
	FIFO      = 4096u32,	// 0o010000
	CHR       = 8192u32,	// 0o020000
	DIR       = 16384u32,	// 0o040000
	BLK       = 24576u32,	// 0o060000
	REG       = 32768u32,	// 0o100000
	LINK      = 40960u32,	// 0o120000
	SOCK      = 49152u32,	// 0o140000
};

// stat_mask — which filestat fields the call populated. Mirrors
// Hare's fs::stat_mask (ref/hare/fs/types.ha:129). newfstatat fills
// every field, so [[stat]] / [[lstat]] / [[fstat]] always set all
// seven bits OR-folded (see [[fillfilestat]]); per-bit testing is
// the documented sparse-backend pattern (cf. Hare's fs::fs network
// backends that only populate mtime+size).
export type stat_mask = enum u32 {
	UID   = 1u32,
	GID   = 2u32,
	SIZE  = 4u32,
	INODE = 8u32,
	ATIME = 16u32,
	MTIME = 32u32,
	CTIME = 64u32,
};

// timespec — {sec, nsec} pair, matching Hare's time::instant
// (ref/hare/time/types.ha). Local to lib/os; graduates to
// lib/time.instant when lib/time and lib/fs ship. Same byte layout
// (i64+i64 = 16B) so a future migration is field-rename only.
export type timespec = struct {
	sec:  i64,
	nsec: i64,
};

// filestat — Hare's fs::filestat (ref/hare/fs/types.ha:141). 80
// bytes. See module-header note re: graduation to lib/fs.
export type filestat = struct {
	mask:  stat_mask,	// 0  (4)
	mode:  mode,		// 4  (4)
	uid:   u32,		// 8  (4)
	gid:   u32,		// 12 (4)
	sz:    u64,		// 16 (8)
	inode: u64,		// 24 (8)
	atime: timespec,	// 32 (16)
	mtime: timespec,	// 48 (16)
	ctime: timespec,	// 64 (16) — ends at 80
};

// kstat — x86_64 kernel `struct stat` layout. Mirrors
// arch/x86/include/uapi/asm/stat.h (`__kernel_ulong_t`-keyed
// fields). 144 bytes. Module-internal; SYS_newfstatat writes into
// this buffer and the public stat fns then copy the bits into the
// Hare-shaped [[filestat]].
//
// Mode is typed as the public [[mode]] enum (rather than raw u32)
// so [[fillfilestat]]'s `out.mode = k.mode` needs no cast. Cstage
// emits a redundant `MOVL AX, AX` on u32 → enum-u32 casts that
// wwstage skips (task #25); the in-tree shape sidesteps it.
// Identical byte layout (both 4B at offset 24).
type kstat = struct {
	dev:        u64,	// 0
	ino:        u64,	// 8
	nlink:      u64,	// 16
	mode:       mode,	// 24
	uid:        u32,	// 28
	gid:        u32,	// 32
	pad0:       u32,	// 36
	rdev:       u64,	// 40
	sz:         i64,	// 48
	blksize:    i64,	// 56
	blocks:     i64,	// 64
	atime_sec:  i64,	// 72
	atime_nsec: i64,	// 80
	mtime_sec:  i64,	// 88
	mtime_nsec: i64,	// 96
	ctime_sec:  i64,	// 104
	ctime_nsec: i64,	// 112
	unused0:    i64,	// 120
	unused1:    i64,	// 128
	unused2:    i64,	// 136 — ends at 144
};

// emptypath — single-NUL byte used as the `pathname` arg to
// newfstatat with AT_EMPTY_PATH. The kernel requires a non-NULL
// pointer to a zero-length C string, NOT a null pointer. Bytes are
// read-only from the kernel's view; ww has no module-level const so
// this is a writable `let`.
let emptypath: [1]u8 = [0u8];

// fillfilestat — copy a 144B kstat into the 80B Hare-shaped
// filestat. Internal helper used by all three public entry points.
// Mirrors Hare's st_to_filestat (ref/hare/os/+linux/dirfdfs.ha:259):
// newfstatat populates every field, so the mask is the OR-fold of
// all seven Hare stat_mask bits.
fn fillfilestat(out: *filestat, k: *kstat) void = {
	out.mask        = stat_mask.UID | stat_mask.GID | stat_mask.SIZE
	    | stat_mask.INODE | stat_mask.ATIME | stat_mask.MTIME
	    | stat_mask.CTIME;
	out.mode        = k.mode;
	out.uid         = k.uid;
	out.gid         = k.gid;
	out.sz          = k.sz: u64;
	out.inode       = k.ino;
	out.atime.sec   = k.atime_sec;
	out.atime.nsec  = k.atime_nsec;
	out.mtime.sec   = k.mtime_sec;
	out.mtime.nsec  = k.mtime_nsec;
	out.ctime.sec   = k.ctime_sec;
	out.ctime.nsec  = k.ctime_nsec;
};

// stat — fill *out with metadata for `path`. Follows symlinks.
// Returns ENAMETOOLONG (-36) as `oserror` if the path overflows
// PATH_MAX.
//
// Mirrors Hare's sys::stat (ref/hare/sys/+linux/stat.ha:51) modulo
// the out-param shape forced by the cgreturn 24B cap. Note: Hare's
// higher-level fs::stat (ref/hare/fs/fs.ha:172) instead has lstat
// semantics — we follow sys::stat's POSIX-stat behavior here.
export fn stat(out: *filestat, path: str) (void | oserror) = {
	let cp: *u8 = kpath(path);
	if (cp == nil: *u8) { return -36i64: oserror; };
	let k: kstat;
	let r: i64 = syscall4(nr.NEWFSTATAT,
	    AT_FDCWD: i64, cp: i64, (&k): i64, 0i64);
	if (r < 0) { return r: oserror; };
	fillfilestat(out, &k);
};

// lstat — like [[stat]] but does NOT follow a terminal symlink.
// Mirrors Hare's sys::lstat (ref/hare/sys/+linux/stat.ha:57).
export fn lstat(out: *filestat, path: str) (void | oserror) = {
	let cp: *u8 = kpath(path);
	if (cp == nil: *u8) { return -36i64: oserror; };
	let k: kstat;
	let r: i64 = syscall4(nr.NEWFSTATAT,
	    AT_FDCWD: i64, cp: i64, (&k): i64,
	    AT_SYMLINK_NOFOLLOW: i64);
	if (r < 0) { return r: oserror; };
	fillfilestat(out, &k);
};

// fstat — like [[stat]] but addresses the file by fd. Uses
// newfstatat(fd, "", AT_EMPTY_PATH); the kernel resolves the fd
// directly. Mirrors Hare's sys::fstat (ref/hare/sys/+linux/stat.ha:54).
export fn fstat(out: *filestat, fd: i32) (void | oserror) = {
	let k: kstat;
	let r: i64 = syscall4(nr.NEWFSTATAT,
	    fd: i64, (&emptypath[0]): i64, (&k): i64,
	    AT_EMPTY_PATH: i64);
	if (r < 0) { return r: oserror; };
	fillfilestat(out, &k);
};

// exists — true if `path` resolves to anything (regular file,
// directory, symlink, ...). Stat-shaped (Hare's `fs::exists`,
// ref/hare/fs/fs.ha:196) — no separate syscall. Symlinks are
// followed; a dangling symlink is `false`. ENAMETOOLONG is
// swallowed as `false` — Hare's os::exists doc says "true if a
// node exists at the given path, or false if not."
//
// Race warning: prefer "open and handle the error" over "exists
// then open" in real code (Hare's docstring carries the same
// note). The race is unavoidable in this shape.
//
// Goes through SYS_newfstatat directly rather than match'ing on
// [[stat]]'s `(void | oserror)` return. Functionally identical;
// the direct shape sidesteps a cstage/wwstage cgen disagreement
// on the slot size of `(void | oserror)` (cstage 16B, wwstage 24B
// — same class as STATUS #22, surfaced first time a match on this
// shape combined with an 80B local-struct local frame). Use the
// match shape once #22 lands.
export fn exists(path: str) bool = {
	let cp: *u8 = kpath(path);
	if (cp == nil: *u8) { return false; };
	let k: kstat;
	let r: i64 = syscall4(nr.NEWFSTATAT,
	    AT_FDCWD: i64, cp: i64, (&k): i64, 0i64);
	return r >= 0i64;
};