system/posix

struct pollfd: one descriptor and what to watch it for.

Field names are the C ones because a mirror copies BY NAME.

struct winsize: the terminal size TIOCGWINSZ fills in.

Field names are the C ones because a mirror copies BY NAME; the snake_case rule does not reach across the boundary.

write(2). Byte count written, or -1 with errno set.

i64, not i32: POSIX returns ssize_t, 64-bit on every target here. @c_header hands cc the real prototype, so a width mismatch stops the build rather than truncating silently.

opendir(3). NULL when path is not a directory, does not exist, or cannot be searched.

It answers "is this a directory" only for a directory the caller can READ: sys_path_kind is what std/io::is_dir asks, and says why.

closedir(3). Pairs with sys_opendir.

The calling thread's errno, as the LAST foreign call left it.

errno is a macro, not a symbol: *__error() on Darwin, *__errno_location() on glibc, so no @extern can name it directly and the runtime reads it for us.

⚠️ Read it IMMEDIATELY after the call that failed. Any foreign call in between may overwrite it, this one included once it has returned.

What KIND of thing path is, via stat(2).

struct stat is NOT mirrorable, not "ambiguous between arches", genuinely inexpressible. A mirror is pinned field by field to __builtin_offsetof, so it is only valid as a contiguous LEADING prefix ; st_mode leads on neither arch (offset 24 on linux-x86_64, 16 on linux-arm64), and the two arches also disagree on field ORDER, which no width or arch axis could express. So the runtime resolves the member and hands back an ordinal. See docs/adr/0013-what-the-ffi-boundary-cannot-express.md.

sys_opendir is NOT a substitute: it needs READ permission where stat needs only traverse rights on the parent, so a directory with mode 0111 answers "not a directory".

An enum would name the answer set better, but @extern cannot carry one (T3050), and a Vader wrapper here would give this module a BODY, which the seed refuses: system/posix would then emit a unit on POSIX targets and none on Windows, and --seed-targets requires one module set for every target. Hence four constants and a declaration-only module.

When path was last modified, in nanoseconds since the Unix epoch, via stat(2) : the runtime reads the member for the reason sys_path_kind gives, and Darwin names it st_mtimespec where Linux says st_mtim.

The size of the regular file stream reads, via fstat(2), for the reason sys_path_kind gives.

readdir(3). The next entry, or null at the end of the directory.

The struct dirent it returns is owned and REUSED by the C library: read the name out before the next call and never keep the pointer.

The d_name of a struct dirent, as a Vader string.

The one step a Vader FFI call cannot take for itself: reading a NAMED member of a C struct. d_name sits at a different offset on every system, and only cc can resolve it: from the real header, at the accessor in the runtime.

It has to be a CALL, not a read of the struct: the interpreter has no C layout, but it resolves an @extern by name out of the running process the way it reaches libc. That is what keeps read_dir working on both backends, which anything in the stdlib has to.

The returned bytes belong to the C library and die at the next sys_readdir; the shim interns them before then.

ferror(3). Non-zero once the stream's error indicator is set.

A short fread means end of file OR an error, and the count cannot tell them apart -- this is what separates them.

read(2). Returns the byte count, 0 at end of file, -1 on error, and a SHORT read is not an error: a pipe hands over what has arrived so far, so a caller wanting n bytes loops until it has them.

pipe(2). Fills fds with the read end then the write end.

close(2).

posix_spawn_file_actions_init(3).

posix_spawn_file_actions_destroy(3). Pairs with the init.

posix_spawn_file_actions_addclose(3): close fd in the child.

posix_spawn_file_actions_adddup2(3): dup2(fd, newfd) in the child.

posix_spawnp(3): launch file, resolved through PATH.

waitpid(2).

kill(2).

strdup(3): a heap copy of s, owned by the caller.

Used to build the char** a spawn wants: a i64[] of these lends as one.

free(3). Releases what sys_strdup returned.

The process environment, for sys_posix_spawnp.

environ is a VARIABLE and the FFI calls functions, so the runtime names it. Passing null instead gives the child an EMPTY environment: no PATH, which every spawned tool needs.

poll(2) on a SINGLE descriptor.

poll takes an array; one element crosses as its address, which is the same thing to C. A caller watching several would need the array form.

tcgetattr(3). Reads the terminal state into an OPAQUE buffer.

The buffer is never interpreted on the Vader side: it travels from here to sys_tcsetattr and back, so nothing needs the layout of struct termios, whose shape differs between systems (c_line is Linux-only) and whose c_cc is an array. buf must hold at least TERMIOS_BYTES.

tcsetattr(3). Applies a state read by sys_tcgetattr.

cfmakeraw(3). Turns a state into the raw one, in place.

The whole reason Vader never has to name a termios member: the flag surgery happens in C. It is MORE aggressive than a hand-rolled raw mode: it also clears OPOST, so \n no longer returns the carriage and a caller must write \r\n itself.

ioctl(2) for TIOCGWINSZ. 0 on success, -1 otherwise.

ioctl is variadic; @c_header brings the real prototype, so the shim's three-argument call is ordinary C rather than a redeclaration.

sysconf(3). The value of the configuration variable name, or -1 with errno set: an unknown name is EINVAL.

isatty(3). Whether fd refers to a terminal.

readlink(2). Bytes placed in buf (NOT NUL-terminated) or -1.

Linux reads the running binary's path from /proc/self/exe.

realpath(3). Writes the canonical path into resolved and returns it, or null on failure. resolved must hold at least PATH_MAX bytes.

fopen(3). A stream handle, or null when the file cannot be opened.

stdio rather than open(2): the mode is a STRING, so nothing here has to know the numeric value of O_CREAT, which is 512 on Darwin and 64 on Linux. Reading proceeds until end of file, so SEEK_END is not needed either.

fclose(3). 0 on success.

fread(3). The number of ITEMS read: short at end of file.

fwrite(3). The number of items written; short means failure.

getcwd(3). Fills buf with the working directory, NUL-terminated, and returns it, or null when buf is too small or the directory is unreadable. The length is not reported: read up to the NUL.

chdir(2). 0 on success, -1 with errno set.

mkdir(2). 0 on success, -1 with errno set: EEXIST included, which is why the caller re-tests the path rather than reading errno.

access(2). 0 when the check passes, -1 with errno set otherwise.

F_OK answers existence without a struct stat, which is why exists uses it: no C struct has to be mirrored to ask the only question being asked.

unlink(2). 0 on success, -1 with errno set.

NOT remove(3): on POSIX that falls back to rmdir for a directory, so an empty one would vanish through a call named remove_FILE.

clock_gettime(2). Fills ts: two cells standing in for struct timespec, both members being 64-bit here: with seconds then nanoseconds. -1 on failure.

Standard output's file descriptor.

Standard error's file descriptor.

CLOCK_REALTIME: the wall clock.

CLOCK_MONOTONIC. The value is not portable: 6 on Darwin, 1 elsewhere.

errno values std/io classifies.

The low numbers are fixed by history and identical on Darwin and Linux; the ones that are not say so on their own line. A raw errno is a PLATFORM value: compare against these, never against a literal.

Diverges: 35 on Darwin, 11 on Linux, where EDEADLK sits on the other.

Diverges: 66 on Darwin, 39 on Linux.

The four answers sys_path_kind gives. Values must match vader_path_kind.

Device, FIFO, socket: anything with no size to speak of.

Bytes to reserve for a posix_spawn_file_actions_t.

An OPAQUE buffer: Vader never looks inside, the spawn_file_actions_* calls fill it. Nothing checks this number, so it is taken HIGH: MEASURED at 8 on Darwin (the type is a bare void*) and 80 on glibc: the same on x86_64, aarch64 and musl.

⚠️ Do NOT narrow this to what one system reports.

WNOHANG: return immediately rather than waiting. 1 on both systems.

SIGKILL. 9 on both systems.

POLLIN: data is available to read. 1 on both systems.

Bytes to reserve for a struct termios. The LARGER of the measured sizes, deliberately, and not a per-system value.

MEASURED: 72 on Darwin, 60 on Linux, x86_64 and arm64 alike, the type being built from fixed-width members. A SIZE, not an offset, which is why no architecture axis is needed where a struct stat mirror would have wanted one.

⚠️ Do NOT narrow this to the per-system figure. The risk is asymmetric: over-reserving wastes 12 bytes on Linux, under-reserving is an out-of-bounds write by tcgetattr, which nothing here checks. One constant, taken high, is the shape that cannot be got wrong.

TCSAFLUSH: apply after draining output, DISCARDING pending input. That last part is why raw mode uses it: keystrokes meant for the shell must not land in the prompt. 2 on both systems.

TIOCGWINSZ. A macro, and its value is not portable: it encodes the direction and the payload size, which differ between the two ioctl schemes.

_SC_NPROCESSORS_ONLN: the processors currently online. The value is not portable: 58 on Darwin, 84 on Linux.

access(2) mode: does the entry exist at all.