std/io

What went wrong, classified so a caller can branch on it without transcribing platform numbers.

A raw errno is not portable (EAGAIN is 35 on Darwin and 11 on Linux) and Windows has no errno at all, only GetLastError with its own numbering. This is the shared vocabulary; IOError.code keeps the raw value for the cases it does not cover.

Raised by every fallible operation in this module: the concrete error member of each T | IOError return. Narrow with is IOError ; widen to Error for a trait-typed slot.

A standard output stream. Used by the print / println / eprint / eprintln wrappers below to pick a target, and exported so terminal-aware code (e.g. std/tty::is_tty) can name a stream. The two variants carry tags 0 (Stdout) and 1 (Stderr), matching the runtime write primitive.

Write msg to stdout without a trailing newline. Accepts any type implementing Display: the wrapper renders it via to_string before handing the string to the host.

Write msg to stdout followed by a \n. See print for the Display routing rule.

Write msg to stderr without a trailing newline.

Write msg to stderr followed by a \n.

Read one line from stdin, blocking until a newline arrives. The returned string does NOT include the trailing \n.

Read EXACTLY n bytes from stdin into a fresh UTF-8 string. Loops until n bytes are accumulated; end of input before n is an error. The bytes come as they are, \r\n included: required by length-prefixed transports (LSP, MCP, custom RPC).

Read what stdin has ready: block until at least one byte has arrived, then return what has, up to max bytes. Unlike read_stdin, it waits for no count, which is what reading keys as they are pressed needs.

read_available with null in place of its error, for a caller that only tells a read from its absence.

True iff stdin has data ready within timeout_ms (0 = non-blocking probe). Lets a length-prefixed server detect a quiescent input window, e.g. drain a burst of notifications, then do expensive work once. A pipe is read straight from its descriptor, so no buffer lags behind what this reports; a console reports ready. A closed peer (pipe hangup) reports ready so the next read observes EOF rather than spinning.

Read a file fully into a fresh owned byte array. Lossless for arbitrary binary: the bytes are taken verbatim, no UTF-8 reinterpretation. This is the canonical file-read primitive ; read_file_string decodes on top.

A first chunk is the whole of most files. Past it, a regular file is read in one go into an array of its size. Anything else is read by chunks to its end or to max_bytes: a pipe or a device, a file that grew, and one whose size passes max_bytes, a size being a claim the content may not bear out. On Windows, a read short of what it asked for ends the file, a pipe's included.

Write raw bytes to path, replacing any existing file. Lossless for arbitrary binary. The canonical file-write primitive.

Create path and every missing parent, the way mkdir -p does.

An existing directory is success, not an error: the caller asked for it to exist, and it does. Permissions follow the process umask.

Delete the file at path.

Files only. A directory is refused by the platform rather than silently recursed into: the conservative default for something irreversible. A missing path is an error too: a caller that does not care checks exists first, and one that does would rather hear about it.

Read a file fully into a UTF-8 string: a thin text decode over read_file_bytes. Use read_file_bytes directly for binary data.

Write a UTF-8 string to path, replacing any existing file: a thin encode over write_file_bytes. Use write_file_bytes directly for binary.

True iff path resolves to an existing filesystem entry (file or directory). Errors (e.g. permission denied) collapse to false.

True iff path exists AND is a directory. Errors collapse to false.

Read permission on the directory is NOT required: traverse rights on its parent are enough, which is what stat asks for.

When path was last modified, in nanoseconds since the Unix epoch : what a cache compares to learn that a file changed without reading it.

path as the filesystem resolves it: absolute, /-separated, every symbolic link followed and every . and .. gone. Two spellings of one file give one answer (/tmp and /private/tmp under macOS), which a lexical normalization (std/path) cannot promise.

List the immediate entries of path in OS-provided order. Excludes . and ... Names are relative: join against path (e.g. via std/path) for full paths.

Full path of the running executable, /-separated. Use std/path's parent to get its directory, e.g. to resolve sidecar resources (stdlib, C runtime) next to the binary. Falls back to "." if the OS query fails.

The directory the process resolves relative paths against, /-separated and WITHOUT a trailing separator: where it was started, unless set_current_working_directory moved it. Join with "/name" to build a path. Distinct from current_executable_location, which answers where the binary lives: use this one to resolve a path the user typed, that one for resources shipped beside the executable. Falls back to "." if the OS query fails.

Make path the directory the process resolves relative paths against. Process-wide: every thread, and every child spawned afterwards, sees it.

OS scratch directory for temporary files, /-separated and WITHOUT a trailing separator: join with "/name" to build a path. Honours the platform temp-dir environment ($TMPDIR on POSIX, %TMP% / %TEMP% via GetTempPath on Windows), falling back to "/tmp" when unset. The directory is assumed to exist and be writable ; this does not create it.

A ceiling for a read whose caller has no figure of its own.

It is a policy number, not a fact about files, and it is bounded from BOTH sides. It has to clear anything the toolchain legitimately reads: the largest .vader source here is 161 KiB and the largest emitted seed unit 2.3 MiB. And it has to stay under what the smallest backend can hold, or it never fires: the interpreter carries a u8 per slot, so 256 MiB of file costs it about 2 GB and the GC traps before the refusal can be returned. 16 MiB clears the first by ~100x and refuses cleanly on both backends.

Name your own when you know what you are reading.