`stdlib.os`¶

OS Library

Generated from v0.65.7. 26 source files, 404 documented symbols.

`args.xi`¶

`fn args_raw() -> Vec[Str]`¶

All arguments as freshly-owned strings. Index 0 is conventionally the program name when the host provides one. Complexity: O(total bytes).

Precondition: true

`fn flag_lookup(args: &Vec[Str], flag: Str) -> Bool`¶

True when args contains exactly flag. Complexity: O(n * flag.len()). Pure.

Postcondition: (args.len() == 0) => (result == false)
Postcondition: (result == true) => (args.len() >= 1)

`fn option_value(args: &Vec[Str], key: Str) -> Option[Str]`¶

Value for key: supports both --key=value and --key value. Later occurrences win (last-one-wins convention, matching most CLI frameworks). Returns None when absent. Complexity: O(n * key.len()). Pure.

Postcondition: (args.len() == 0) => (result.is_none == true)

`fn positionals(args: &Vec[Str]) -> Vec[Str]`¶

Positional arguments: every entry that does not start with '--' and is not consumed as a spaced-option value of a preceding '--key'. Note this simple scanner treats any '--' entry as a flag/key, never as a negative number or literal. Complexity: O(n). Pure.

Postcondition: result.len() <= args.len()

`fn args_has_flag(flag: Str) -> Bool`¶

Convenience: flag lookup over the process's own arguments.

Postcondition: (result == true) => (args_raw().len() >= 1)

`fn args_option(key: Str) -> Option[Str]`¶

Convenience: option lookup over the process's own arguments.

Postcondition: (args_raw().len() == 0) => (result.is_none == true)

`dir.xi`¶

`fn dir_current() -> Result[Str, Str]`¶

dir_current returns the current working directory. Delegates to env.current_dir. Complexity: O(1) syscall.

Postcondition: result is Ok(_) => result.len() > 0

`fn dir_create(path: Str) -> Result[Unit, Str]`¶

dir_create creates a single directory. Delegates to io.create_dir. Complexity: O(1) syscall.

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn dir_create_all(path: Str) -> Result[Unit, Str]`¶

dir_create_all creates a directory and all missing parents. Delegates to io.create_dir_all. Complexity: O(depth) syscalls.

Postcondition: (path.len() == 0) => (result.is_ok == true)

`fn dir_list(path: Str) -> Result[Vec[Str], Str]`¶

dir_list returns the names of entries in a directory. Delegates to io.list_dir. Complexity: O(n) syscalls.

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn dir_exists(path: Str) -> Bool`¶

dir_exists returns true if path exists and is a directory. Delegates to io.is_dir. Complexity: O(1) syscall.

Postcondition: (path.len() == 0) => (result == false)

`fn dir_remove(path: Str) -> Result[Unit, Str]`¶

dir_remove removes an empty directory. Delegates to io.remove_file (which handles both files and dirs via the C runtime). Complexity: O(1) syscall.

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn dir_temp() -> Str`¶

dir_temp returns the system temporary directory. Delegates to env.temp_dir. Complexity: O(1).

Postcondition: result == env.temp_dir()

`fn dir_home() -> Option[Str]`¶

dir_home returns the current user's home directory, if known. Delegates to env.home_dir. Complexity: O(1).

Postcondition: result is Some(_) => result.len() > 0

`fn dir_is_empty(path: Str) -> Bool`¶

dir_is_empty returns true if a directory contains no entries. Complexity: O(n) syscalls.

Postcondition: (path.len() == 0) => (result == false)

`fn dir_join(a: Str, b: Str) -> Str`¶

dir_join joins two path components with the OS separator. Delegates to io.join_paths. Complexity: O(1).

Postcondition: result.len() == a.len() + b.len() + 1

`fn dir_parent(path: Str) -> Option[Str]`¶

dir_parent returns the parent directory of path, or None if there is none. Delegates to fs.fs_parent_dir. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_none == true)

`env.xi`¶

`fn host_is_windows() -> Bool`¶

host_is_windows returns true when the RUNNING host is Windows (runtime probe). Use this -- not the compile-time FAMILY constant -- for any behavior branch inside this module and for WSL/Linux-correct paths. Complexity: O(1).

Postcondition: result == (_host_os_name() == "windows")

`fn get_var(name: Str) -> Result[Str, Str]`¶

Environment variable value; Err with a message when unset.

Precondition: name.len() > 0

`fn var_opt(name: Str) -> Option[Str]`¶

Environment variable value, or None when unset.

Precondition: name.len() > 0

`fn set_var(name: Str, value: Str)`¶

Set an environment variable (overwrites; portable runtime shim).

Precondition: name.len() > 0

`fn remove_var(name: Str)`¶

Remove an environment variable.

Precondition: name.len() > 0

`fn vars() -> Vec[(Str, Str)]`¶

All environment variables as (name, value) pairs.

Postcondition: result.len() == 0

`fn args() -> Vec[Str]`¶

Process arguments (UTF-8, lossy; stable across calls).

Postcondition: result.len() == io.args().len()

`fn args_os() -> Vec[Str]`¶

Process arguments (OS-native strings; same representation here).

Postcondition: result.len() == args().len()

`fn current_exe() -> Result[Str, Str]`¶

Path of the running executable, or Err with the OS message.

Postcondition: result is Ok(_) => args().len() > 0

`fn current_dir() -> Result[Str, Str]`¶

Process working directory, or Err with the OS message.

Precondition: true
Postcondition: result is Ok(_) => result.len() > 0

`fn set_current_dir(path: Str) -> Result[Unit, Str]`¶

Change the working directory, or Err with the OS message.

Precondition: path.len() > 0

`fn temp_dir() -> Str`¶

Platform temporary directory.

Postcondition: result.len() > 0

`fn home_dir() -> Option[Str]`¶

User home directory, or None when it cannot be resolved.

Postcondition: result is Some(_) => result.len() > 0

`fn data_dir() -> Option[Str]`¶

Per-user data directory, or None.

Postcondition: (result.is_none == true) => (home_dir().is_none == true)

`fn cache_dir() -> Option[Str]`¶

Per-user cache directory, or None.

Postcondition: (result.is_none == true) => (home_dir().is_none == true)

`fn config_dir() -> Option[Str]`¶

Per-user configuration directory, or None.

Postcondition: (result.is_none == true) => (home_dir().is_none == true)

`fn executable_dir() -> Option[Str]`¶

Directory containing the running executable, or None.

Postcondition: (result.is_some == true) => (current_exe().is_ok == true)

`fn join_paths(a: Str, b: Str) -> Str`¶

Join two path fragments with the platform separator.

Postcondition: result.len() == a.len() + b.len() + 1

`fn path_separator() -> Str`¶

Platform path separator ("/" or "\"). Wave 164: branches on the runtime host probe -- the bare compile-time FAMILY check returned "\" on Linux.

Postcondition: result.len() == 1

`fn var_or(name: Str, default: Str) -> Str`¶

var_or returns the value of the environment variable name, or default if the variable is not set. Complexity: O(1).

Postcondition: (var_opt(name).is_none == true) => (result == default)

`fn has_var(name: Str) -> Bool`¶

has_var returns true if the environment variable name is set. Complexity: O(1).

Postcondition: (result == true) => (var_opt(name).is_some == true)

`fn all_var_names() -> Vec[Str]`¶

all_var_names returns an empty vector on all platforms -- the Xiom runtime does not support iterating over environment variables via the C standard library.

Postcondition: result.len() == 0

`fn all_var_values() -> Vec[Str]`¶

all_var_values returns an empty vector on all platforms -- see all_var_names for rationale.

Postcondition: result.len() == 0

`fn set_var_if_absent(name: Str, value: Str)`¶

set_var_if_absent sets name to value only if name is not already set. Complexity: O(1). WARNING: setenv is not available on Windows MSVC.

Precondition: name.len() > 0

`fn clear_var(name: Str)`¶

clear_var removes the environment variable name. Alias for remove_var. Same Windows caveat.

Precondition: name.len() > 0

`fn args_len() -> Int`¶

args_len returns the number of command-line arguments. Complexity: O(1).

Postcondition: result == io.args().len()

`fn arg_at(i: Int) -> Option[Str]`¶

arg_at returns the i-th command-line argument, or None if i is out of bounds. Complexity: O(1).

Postcondition: (i < 0 || i >= io.args().len()) => (result.is_none == true)

`fn arg_contains(s: Str) -> Bool`¶

arg_contains returns true if any command-line argument equals s. Complexity: O(n) where n = arg count.

Postcondition: (io.args().len() == 0) => (result == false)

`fn current_dir_str() -> Str`¶

current_dir_str returns the current working directory as a Str, or "." if the OS call fails. Wraps getcwd directly. Complexity: O(1).

Precondition: true

`err.xi`¶

`fn errno() -> Int`¶

Return the current errno value. NOT IMPLEMENTED: the runtime does not expose errno(). Returns 0. Complexity: O(1). Pure.

`fn errno_name(code: Int) -> Str`¶

Return the symbolic name for an errno code. Parameters: code -- the errno number. Returns: the symbolic name (e.g. "ENOENT"), or "EUNKNOWN". Complexity: O(1). Pure.

Postcondition: (code == 2) => (result == "ENOENT")
Postcondition: (code == 1) => (result == "EPERM")
Postcondition: (code == 0) => (result == "EUNKNOWN")

`fn strerror(code: Int) -> Str`¶

Return the human-readable message for an errno code. Parameters: code -- the errno number. Returns: the descriptive message, or "unknown error". Complexity: O(1). Pure.

Postcondition: (code == 2) => (result == "no such file or directory")
Postcondition: (code == 0) => (result == "unknown error")

`fn perror(msg: Str) -> Unit`¶

Print msg plus the current errno message. Parameters: msg -- the prefix message. Returns: Unit. Prints "msg: " (stdout; the runtime exposes no stderr writer). Complexity: O(1). Pure.

`fn errno_message() -> Str`¶

Return the message for the current errno value. Returns: strerror(errno()). Complexity: O(1). Pure.

Postcondition: result.len() > 0

`fn errno_set(code: Int) -> Unit`¶

Set the errno value. NOT IMPLEMENTED: the runtime does not expose errno(). No-op.

`fn backtrace() -> Vec[Str]`¶

Capture the current call stack as formatted frame strings. NOT IMPLEMENTED: the runtime does not expose a backtrace API. Returns an empty vector. Complexity: O(1). Pure.

`fn backtrace_symbols(frames: &Vec[Int]) -> Vec[Str]`¶

Resolve raw frame addresses to symbols. NOT IMPLEMENTED: the runtime does not expose a symbolizer. Returns an empty vector. Complexity: O(1). Pure.

`fn demangle(symbol: Str) -> Str`¶

Demangle a compiler-mangled symbol name. NOT IMPLEMENTED: no demangler is available. Returns the symbol unchanged. Complexity: O(1). Pure.

Postcondition: result == symbol

`fn last_error() -> Str`¶

Return the most recently captured error string. NOT IMPLEMENTED: no error capture is wired in. Returns "". Complexity: O(1). Pure.

`fn errno_to_string(code: Int) -> Str`¶

Format an errno code as "name (code): message". Parameters: code -- the errno number. Returns: the formatted string. Complexity: O(1). Pure.

Postcondition: (code == 2) => (result == "ENOENT (2): no such file or directory")

`event.xi`¶

`type EpollEvent`¶

struct EpollEvent { events: UInt32, data: UInt64 } - one epoll readiness event; layout matches struct epoll_event.

Field	Type
`events`	`UInt32`
`data`	`UInt64`

`type KEvent`¶

struct KEvent { ident: UInt64, filter: Int16, flags: UInt16, fflags: UInt32, data: Int64 } - one kqueue event; layout matches struct kevent.

Field	Type
`ident`	`UInt64`
`filter`	`Int16`
`flags`	`UInt16`
`fflags`	`UInt32`
`data`	`Int64`

`type PollFd`¶

struct PollFd { fd: Int, events: Int16, revents: Int16 } - one poll descriptor; layout matches struct pollfd.

Field	Type
`fd`	`Int`
`events`	`Int16`
`revents`	`Int16`

`fn epoll_create() -> Result[Int, Str]`¶

Create an epoll instance and return its fd. NOT IMPLEMENTED: requires the epoll syscall (Linux-only; not exposed by the pure stdlib). Returns: Err("epoll_create: epoll is not available in the pure stdlib").

`fn epoll_add(ep: Int, fd: Int, events: Int) -> Result[Unit, Str]`¶

Register fd with the epoll instance. NOT IMPLEMENTED: requires the epoll syscall (see epoll_create). Returns: Err("epoll_add: epoll is not available in the pure stdlib").

`fn epoll_mod(ep: Int, fd: Int, events: Int) -> Result[Unit, Str]`¶

Change the event mask for fd. NOT IMPLEMENTED: requires the epoll syscall (see epoll_create). Returns: Err("epoll_mod: epoll is not available in the pure stdlib").

`fn epoll_del(ep: Int, fd: Int) -> Result[Unit, Str]`¶

Remove fd from the epoll instance. NOT IMPLEMENTED: requires the epoll syscall (see epoll_create). Returns: Err("epoll_del: epoll is not available in the pure stdlib").

`fn epoll_wait(ep: Int, max_events: Int, timeout_ms: Int) -> Result[Vec[EpollEvent], Str]`¶

Wait for and return ready events. NOT IMPLEMENTED: requires the epoll syscall (see epoll_create). Returns: Err("epoll_wait: epoll is not available in the pure stdlib").

`fn epoll_close(ep: Int) -> Unit`¶

Close the epoll fd. NO-OP: no epoll instances exist in the pure stdlib.

`fn kqueue_create() -> Result[Int, Str]`¶

Create a kqueue and return its fd. NOT IMPLEMENTED: requires the kqueue syscall (BSD/macOS-only; not exposed by the pure stdlib). Returns: Err("kqueue_create: kqueue is not available in the pure stdlib").

`fn kqueue_add_read(kq: Int, fd: Int) -> Unit`¶

Register fd for EVFILT_READ events. NO-OP: no kqueue instances exist in the pure stdlib.

`fn kqueue_add_write(kq: Int, fd: Int) -> Unit`¶

Register fd for EVFILT_WRITE events. NO-OP: no kqueue instances exist in the pure stdlib.

`fn kqueue_wait(kq: Int, timeout_ms: Int) -> Result[Vec[KEvent], Str]`¶

Wait for and return kqueue events. NOT IMPLEMENTED: requires the kqueue syscall (see kqueue_create). Returns: Err("kqueue_wait: kqueue is not available in the pure stdlib").

`fn kqueue_close(kq: Int) -> Unit`¶

Close the kqueue fd. NO-OP: no kqueue instances exist in the pure stdlib.

`fn eventfd_new(init: Int) -> Result[Int, Str]`¶

Create an eventfd with the given initial counter. NOT IMPLEMENTED: requires the eventfd syscall (Linux-only; not exposed by the pure stdlib). Returns: Err("eventfd_new: eventfd is not available in the pure stdlib").

`fn eventfd_read(fd: Int) -> Result[Int, Str]`¶

Read and reset the eventfd counter. NOT IMPLEMENTED: requires the eventfd syscall (see eventfd_new). Returns: Err("eventfd_read: eventfd is not available in the pure stdlib").

`fn eventfd_write(fd: Int, value: Int) -> Result[Unit, Str]`¶

Add value to the eventfd counter, waking readers. NOT IMPLEMENTED: requires the eventfd syscall (see eventfd_new). Returns: Err("eventfd_write: eventfd is not available in the pure stdlib").

`fn timerfd_new() -> Result[Int, Str]`¶

Create a timerfd. NOT IMPLEMENTED: requires the timerfd syscall (Linux-only; not exposed by the pure stdlib). Returns: Err("timerfd_new: timerfd is not available in the pure stdlib").

`fn timerfd_set(fd: Int, ms: Int) -> Result[Unit, Str]`¶

Arm the timerfd to fire after ms milliseconds. NOT IMPLEMENTED: requires the timerfd syscall (see timerfd_new). Returns: Err("timerfd_set: timerfd is not available in the pure stdlib").

`fn signalfd_new(signals: &Vec[Int]) -> Result[Int, Str]`¶

Create a signalfd for the given signal numbers. NOT IMPLEMENTED: requires the signalfd syscall (Linux-only; not exposed by the pure stdlib). Returns: Err("signalfd_new: signalfd is not available in the pure stdlib").

`fn poll(fds: &Vec[PollFd], timeout_ms: Int) -> Result[Int, Str]`¶

Poll the descriptors and update revents; returns the ready count. NOT IMPLEMENTED: requires the poll syscall (not exposed by the pure stdlib). Returns: Err("poll: poll is not available in the pure stdlib").

`fn ppoll(fds: &Vec[PollFd], timeout_ms: Int) -> Result[Int, Str]`¶

Poll with a millisecond timeout, atomic wrt the signal mask. NOT IMPLEMENTED: requires the ppoll syscall (not exposed by the pure stdlib). Returns: Err("ppoll: ppoll is not available in the pure stdlib").

`fn select(read_fds: &Vec[Int], write_fds: &Vec[Int], timeout_ms: Int) -> Result[Int, Str]`¶

Wait on the given fd sets; returns the ready count. NOT IMPLEMENTED: requires the select syscall (not exposed by the pure stdlib). Returns: Err("select: select is not available in the pure stdlib").

`fn pselect(read_fds: &Vec[Int], write_fds: &Vec[Int], timeout_ms: Int) -> Result[Int, Str]`¶

Select with a millisecond timeout, atomic wrt the signal mask. NOT IMPLEMENTED: requires the pselect syscall (not exposed by the pure stdlib). Returns: Err("pselect: pselect is not available in the pure stdlib").

`file.xi`¶

`fn file_read(path: Str) -> Result[Str, Str]`¶

file_read reads an entire file as text. Delegates to io.read_file. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn file_write(path: Str, content: Str) -> Result[Unit, Str]`¶

file_write writes text to a file, truncating if it exists. Delegates to io.write_file. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn file_append(path: Str, content: Str) -> Result[Unit, Str]`¶

file_append appends text to a file, creating it if needed. Delegates to io.append_file. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn file_exists(path: Str) -> Bool`¶

file_exists returns true if path exists (file or directory). Implemented locally via io.metadata to avoid a same-name delegation. Complexity: O(1) syscall.

Postcondition: (path.len() == 0) => (result == false)

`fn file_remove(path: Str) -> Result[Unit, Str]`¶

file_remove deletes a file. Delegates to io.remove_file. Complexity: O(1) syscall.

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn file_copy(src: Str, dst: Str) -> Result[Unit, Str]`¶

file_copy copies a file from src to dst. Delegates to io.copy_file. Complexity: O(n).

Postcondition: (src.len() == 0 || dst.len() == 0) => (result.is_err == true)

`fn file_rename(src: Str, dst: Str) -> Result[Unit, Str]`¶

file_rename renames (moves) a file or directory. Delegates to io.rename. Complexity: O(1) syscall.

Postcondition: (src.len() == 0 || dst.len() == 0) => (result.is_err == true)

`fn file_size(path: Str) -> Result[Int, Str]`¶

file_size returns the size of a file in bytes. Implemented locally via io.metadata. Complexity: O(1) syscall.

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn file_extension(path: Str) -> Option[Str]`¶

file_extension returns the extension of path's file name (text after the last dot), or None. Delegates to fs.fs_extension. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_none == true)

`fn file_stem(path: Str) -> Option[Str]`¶

file_stem returns path without its last extension. Delegates to fs.fs_stem. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_none == true)

`fn file_name(path: Str) -> Option[Str]`¶

file_name returns the file-name portion of path, or None. Delegates to fs.fs_file_name. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_none == true)

`fn file_parent(path: Str) -> Option[Str]`¶

file_parent returns the directory portion of path, or None. Delegates to fs.fs_parent_dir. Complexity: O(n).

Postcondition: (path.len() == 0) => (result.is_none == true)

`filetype.xi`¶

`fn detect_eol(data: &Vec[UInt8]) -> Str`¶

Detect the line ending style. Parameters: data -- the bytes to inspect. Returns: "lf", "crlf", "cr", "mixed" or "none". Complexity: O(n). Pure.

Postcondition: result.len() >= 2
Postcondition: (data.len() == 0) => (result == "none")

`fn detect_bom(data: &Vec[UInt8]) -> Str`¶

Detect and describe the byte-order mark, or "" if absent. Parameters: data -- the bytes to inspect. Returns: "utf-8", "utf-16le", "utf-16be", "utf-32le", "utf-32be" or "". Complexity: O(1). Pure.

Postcondition: (data.len() < 2) => (result == "")

`fn has_utf8_bom(data: &Vec[UInt8]) -> Bool`¶

Return true if data starts with the UTF-8 BOM. Parameters: data -- the bytes to inspect. Returns: true for the EF BB BF prefix. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 3)

`fn has_utf16le_bom(data: &Vec[UInt8]) -> Bool`¶

Return true if data starts with the UTF-16 LE BOM. Parameters: data -- the bytes to inspect. Returns: true for the FF FE prefix. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 2)

`fn has_utf16be_bom(data: &Vec[UInt8]) -> Bool`¶

Return true if data starts with the UTF-16 BE BOM. Parameters: data -- the bytes to inspect. Returns: true for the FE FF prefix. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 2)

`fn has_utf32le_bom(data: &Vec[UInt8]) -> Bool`¶

Return true if data starts with the UTF-32 LE BOM. Parameters: data -- the bytes to inspect. Returns: true for the FF FE 00 00 prefix. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 4)

`fn has_utf32be_bom(data: &Vec[UInt8]) -> Bool`¶

Return true if data starts with the UTF-32 BE BOM. Parameters: data -- the bytes to inspect. Returns: true for the 00 00 FE FF prefix. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 4)

`fn is_binary(data: &Vec[UInt8]) -> Bool`¶

Classify data as binary by a control-byte heuristic. Parameters: data -- the bytes to inspect. Returns: true when a NUL byte is present or control bytes exceed 30% of the sampled prefix. Complexity: O(min(n, 1024)). Pure.

Postcondition: (data.len() == 0) => (result == false)

`fn is_text(data: &Vec[UInt8]) -> Bool`¶

Classify data as plain text by a control-byte heuristic. Parameters: data -- the bytes to inspect. Returns: true when the data is not classified as binary. Complexity: O(min(n, 1024)). Pure.

Postcondition: (data.len() == 0) => (result == true)

`fn detect_encoding(data: &Vec[UInt8]) -> Str`¶

Guess the character encoding. Parameters: data -- the bytes to inspect. Returns: "utf-8", "utf-16le", "utf-16be", "utf-32le", "utf-32be", "ascii" or "binary". Complexity: O(n). Pure.

Postcondition: result.len() >= 5
Postcondition: (data.len() == 0) => (result == "ascii")

`fn magic_number(data: &Vec[UInt8]) -> Str`¶

Return the magic-number hex prefix of data. Parameters: data -- the bytes to inspect. Returns: the lowercase hex of the first up-to-8 bytes ("" for empty input). Complexity: O(1). Pure.

Postcondition: (data.len() == 0) => (result == "")
Postcondition: (data.len() > 0 && data.len() <= 8) => (result.len() == data.len() * 2)
Postcondition: (data.len() > 8) => (result.len() == 16)

`fn detect_mime(data: &Vec[UInt8]) -> Str`¶

Detect the MIME type by content sniffing. Parameters: data -- the bytes to inspect. Returns: a MIME type guessed from magic bytes and text heuristics. Complexity: O(1). Pure.

Postcondition: result.len() >= 9
Postcondition: (data.len() == 0) => (result == "text/plain")

`fn mime_from_magic(data: &Vec[UInt8]) -> Str`¶

Detect the MIME type from magic bytes only. Parameters: data -- the bytes to inspect. Returns: the magic-derived MIME type or "application/octet-stream". Complexity: O(1). Pure.

Postcondition: result.len() >= 9
Postcondition: (data.len() == 0) => (result == "application/octet-stream")

`fn is_image_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data matches a known image format. Parameters: data -- the bytes to inspect. Returns: true for PNG/JPEG/GIF/BMP/WebP/ICO signatures. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 2)

`fn is_audio_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data matches a known audio format. Parameters: data -- the bytes to inspect. Returns: true for WAV/OGG/FLAC/MP3 (ID3) signatures. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 3)

`fn is_video_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data matches a known video container. Parameters: data -- the bytes to inspect. Returns: true for AVI/MP4/MKV/WebM/Ogg signatures. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 4)

`fn is_pdf_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data looks like a PDF. Parameters: data -- the bytes to inspect. Returns: true for the "%PDF-" header. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 5)

`fn is_zip_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data is a ZIP archive. Parameters: data -- the bytes to inspect. Returns: true for the "PK\x03\x04" local-file header. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 4)

`fn is_gzip_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data is a gzip stream. Parameters: data -- the bytes to inspect. Returns: true for the 1F 8B header. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 2)

`fn is_elf_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data is an ELF binary. Parameters: data -- the bytes to inspect. Returns: true for the 7F 45 4C 46 header. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 4)

`fn is_pe_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data is a PE/COFF binary. Parameters: data -- the bytes to inspect. Returns: true for the "MZ" DOS header. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 2)

`fn is_macho_data(data: &Vec[UInt8]) -> Bool`¶

Return true if data is a Mach-O binary. Parameters: data -- the bytes to inspect. Returns: true for the Mach-O magic numbers. Complexity: O(1). Pure.

Postcondition: result => (data.len() >= 4)

`fs.xi`¶

`fn fs_file_name(path: Str) -> Option[Str]`¶

fs_file_name returns the file-name portion of path (after the last '/' or '\'), or None if path is empty or ends in a separator.

Postcondition: (path.len() == 0) => (result.is_none == true)

`fn fs_parent_dir(path: Str) -> Option[Str]`¶

fs_parent_dir returns the directory portion of path (everything before the last '/' or '\'), or None if path has no parent.

Postcondition: (path.len() == 0) => (result.is_none == true)

`fn fs_extension(path: Str) -> Option[Str]`¶

fs_extension returns the extension (text after the last dot in the file name), or None if there is no dot or the dot is leading/trailing. "a/b.tar.gz" -> Some("gz"); "a/b" -> None.

Postcondition: (path.len() == 0) => (result.is_none == true)

`fn fs_stem(path: Str) -> Option[Str]`¶

fs_stem returns the path with the last extension stripped, or the path unchanged if it has no extension. "a/b.tar.gz" -> "a/b.tar".

Postcondition: (path.len() == 0) => (result.is_none == true)

`fn fs_is_hidden(path: Str) -> Bool`¶

fs_is_hidden returns true if the file name starts with a dot, except for the special entries "." and "..".

Postcondition: (path.len() == 0) => (result == false)

`fn fs_join_parts(parts: Vec[Str]) -> Str`¶

fs_join_parts joins the given components with the OS path separator (env.path_separator: "\" on Windows, "/" elsewhere).

Postcondition: (parts.len() == 0) => (result.len() == 0)

`fn fs_normalize(path: Str) -> Str`¶

fs_normalize collapses duplicate separators and resolves "." and ".." lexically, without touching the filesystem. Leading "/" and "C:\"-style drive prefixes are preserved. "a/b/../c//d/./e" -> "a/c/d/e".

Postcondition: (path.len() == 0) => (result.len() == 0)

`fn fs_with_extension(path: Str, new_ext: Str) -> Str`¶

fs_with_extension replaces the extension of path with new_ext, or appends it if path has no extension. "a/b.txt" + "md" -> "a/b.md".

Postcondition: (path.len() == 0) => (result.len() >= 1)

`fn fs_split(path: Str) -> (Str, Str)`¶

fs_split returns (dir, file) -- the directory and file-name portions.

Postcondition: (path.len() == 0) => (result._0 == "" && result._1 == "")

`fn fs_unique_path(dir: Str, name: Str) -> Str`¶

fs_unique_path returns dir/name if it does not exist, otherwise appends " (1)", " (2)", ... up to a maximum of 1000 attempts.

Postcondition: result.len() >= 1

`fs_ffi.xi`¶

`type MappedFile`¶

struct MappedFile { ptr: Int; length: Int; fd: Int; } - mmap result.

Field	Type
`ptr`	`Int`
`length`	`Int`
`fd`	`Int`

`fn symlink(target: Str, link: Str) -> Result[Unit, Str]`¶

Create a symbolic link. NOT IMPLEMENTED: requires the symlink syscall. Returns: Err("symlink: symlink syscall not available in the pure stdlib").

`fn readlink(path: Str) -> Result[Str, Str]`¶

Read a symlink target. NOT IMPLEMENTED: requires the readlink syscall. Returns: Err("readlink: readlink syscall not available in the pure stdlib").

`fn is_symlink(path: Str) -> Bool`¶

True if path is a symbolic link. NOT IMPLEMENTED: requires lstat. Returns false.

`fn hard_link(old: Str, new: Str) -> Result[Unit, Str]`¶

Create a hard link. NOT IMPLEMENTED: requires the link syscall. Returns: Err("hard_link: link syscall not available in the pure stdlib").

`fn chown(path: Str, uid: Int, gid: Int) -> Result[Unit, Str]`¶

Change owner/group. NOT IMPLEMENTED: requires the chown syscall. Returns: Err("chown: chown syscall not available in the pure stdlib").

`fn chmod_path(path: Str, mode: Int) -> Result[Unit, Str]`¶

Change permissions. Delegates to xiom.io.set_permissions. Parameters: path -- the file path; mode -- the permission bits. Returns: Ok(()) on success, Err with the underlying message otherwise. Complexity: O(1). Pure (OS call).

Precondition: path.len() > 0
Precondition: mode >= 0

`fn mmap(path: Str, offset: Int, length: Int) -> Result[MappedFile, Str]`¶

Memory-map a file read-only; the returned struct owns an open fd until munmap. Real implementation (wave 120): opens the path (O_RDONLY), maps it through the runtime mmap family (xiom.os.mmap) and keeps the fd. Returns: Ok(MappedFile) on success; Err on bad arguments or failure.

Precondition: path.len() > 0
Postcondition: result is Ok(_) => length > 0

`fn munmap(m: MappedFile)`¶

Unmap a mapped region and close the fd held by the struct. Real implementation (wave 120): munmap/UnmapViewOfFile + close; both steps are best-effort because the signature returns no Result.

Precondition: m.ptr >= 0 && m.length >= 0

`fn msync(m: MappedFile) -> Result[Unit, Str]`¶

Flush mapped pages back to the backing file (sync semantics). Real implementation (wave 120): delegates to mmap_sync with flags 4 (MS_SYNC-equivalent; msync/flush). Returns: Ok(()) once flushed; Err on failure.

Postcondition: result is Ok(_) => m.ptr > 0

`fn madvise(m: MappedFile, advice: Int) -> Result[Unit, Str]`¶

Advise the kernel on page use. Real implementation (wave 120): madvise on POSIX (platform MADV_* values; 0 = MADV_NORMAL is portable); a documented no-op success on Windows. Returns: Ok(()) once the advice was accepted; Err on failure.

Postcondition: result is Ok(_) => m.ptr > 0

`fn mlock(m: MappedFile) -> Result[Unit, Str]`¶

Lock mapped pages in memory (mlock / VirtualLock). Real implementation (wave 120): delegates to mmap_lock. Returns: Ok(()) once the pages are resident; Err on failure.

Postcondition: result is Ok(_) => m.ptr > 0

`fn munlock(m: MappedFile) -> Result[Unit, Str]`¶

Unlock mapped pages (munlock / VirtualUnlock). Real implementation (wave 120): delegates to mmap_unlock. Returns: Ok(()) once the pages are unlocked; Err on failure.

Postcondition: result is Ok(_) => m.ptr > 0

`fn dup(fd: Int) -> Result[Int, Str]`¶

Duplicate a file descriptor. NOT IMPLEMENTED: requires the dup syscall. Returns: Err("dup: dup syscall not available in the pure stdlib").

`fn dup2(old: Int, new: Int) -> Result[Int, Str]`¶

Duplicate onto a specific fd. NOT IMPLEMENTED: requires the dup2 syscall. Returns: Err("dup2: dup2 syscall not available in the pure stdlib").

`fn truncate(path: Str, length: Int) -> Result[Unit, Str]`¶

Truncate a file by path. NOT IMPLEMENTED: requires the truncate syscall. Returns: Err("truncate: truncate syscall not available in the pure stdlib").

`fn ftruncate(fd: Int, length: Int) -> Result[Unit, Str]`¶

Truncate an open file. NOT IMPLEMENTED: requires the ftruncate syscall. Returns: Err("ftruncate: ftruncate syscall not available in the pure stdlib").

`fn fallocate(fd: Int, offset: Int, length: Int) -> Result[Unit, Str]`¶

Pre-allocate space. NOT IMPLEMENTED: requires posix_fallocate. Returns: Err("fallocate: posix_fallocate not available in the pure stdlib").

`fn pread(fd: Int, offset: Int, length: Int) -> Result[Vec[UInt8], Str]`¶

Positioned read. NOT IMPLEMENTED: requires the pread syscall. Returns: Err("pread: pread syscall not available in the pure stdlib").

`fn pwrite(fd: Int, offset: Int, data: &Vec[UInt8]) -> Result[Int, Str]`¶

Positioned write. NOT IMPLEMENTED: requires the pwrite syscall. Returns: Err("pwrite: pwrite syscall not available in the pure stdlib").

`fn readv(fd: Int, buffers: &Vec[Vec[UInt8]]) -> Result[Int, Str]`¶

Vectored read. NOT IMPLEMENTED: requires the readv syscall. Returns: Err("readv: readv syscall not available in the pure stdlib").

`fn writev(fd: Int, buffers: &Vec[Vec[UInt8]]) -> Result[Int, Str]`¶

Vectored write (scatter write): writes every segment of buffers to fd in one call, in order. Real implementation (wave 159; REL-20261015-2202-pulse item 6): POSIX writev(2); on Windows a WSASend when the fd is a socket, otherwise a sequential _write fallback (short writes loop; the full total or Err). An empty buffers or all-empty segments is Ok(0); more than 1024 segments is Err. The returned count is the syscall's count -- a short count (pipe/socket backpressure) is reported as-is, not as an error. Returns: Ok(bytes written) on success; Err on an invalid fd or failure. Complexity: O(total bytes). Pure (OS call).

Postcondition: result is Ok(_) => fd >= 0

`fn sendfile(out_fd: Int, in_fd: Int, offset: Int, count: Int) -> Result[Int, Str]`¶

Copy a file region to an out fd without user-space copying. Real implementation (wave 159; REL-20261015-2202-pulse item 6): Linux sendfile(2); Windows TransmitFile (the out fd must be a socket; the in fd is a CRT file fd, mapped with _get_osfhandle). Offset semantics: offset >= 0 reads from that file offset; offset == -1 uses the current position. POSIX leaves the position unchanged for an explicit offset and advances it for -1; Windows keeps one shared file pointer, so the position ends past the sent range in both cases -- callers that need repeatable sends should pass an explicit offset. count == 0 is Ok(0). A short Ok count means EOF was reached before count bytes (POSIX); on Windows the count is clamped to the remaining file size first, so a successful Windows call always sends the full min(count, remaining). Returns: Ok(bytes sent); Err on invalid arguments, platform gaps (no portable sendfile outside Linux/Windows) or a failed transfer. Complexity: O(count) kernel-side. Pure (OS call).

Postcondition: result is Ok(_) => (out_fd >= 0 && in_fd >= 0 && count >= 0 && offset >= -1)

`fn splice(in_fd: Int, out_fd: Int, count: Int) -> Result[Int, Str]`¶

Move data between fds without copying. NOT IMPLEMENTED: requires the splice syscall. Returns: Err("splice: splice syscall not available in the pure stdlib").

`fn fsync(fd: Int) -> Result[Unit, Str]`¶

Flush file data and metadata to stable storage. Real implementation (wave 115): fsync(2) on POSIX, the CRT _commit on Windows, through the xiom_fsync_fd runtime shim. Returns: Ok(()) once the fd is durable; Err on failure.

Precondition: fd >= 0

`fn fdatasync(fd: Int) -> Result[Unit, Str]`¶

Flush file data only (fdatasync; fsync fallback on macOS, _commit on Windows). Returns: Ok(()) once the fd data is durable; Err on failure.

Precondition: fd >= 0

`fn mkfifo(path: Str, mode: Int) -> Result[Unit, Str]`¶

Create a named pipe. NOT IMPLEMENTED: requires the mkfifo syscall. Returns: Err("mkfifo: mkfifo syscall not available in the pure stdlib").

`fn fifo_open(path: Str) -> Result[Int, Str]`¶

Open a named pipe. NOT IMPLEMENTED: requires the open syscall. Returns: Err("fifo_open: open syscall not available in the pure stdlib").

`ioctl.xi`¶

`fn ioctl(fd: Int, request: Int, arg: Int) -> Result[Int, Str]`¶

Issue an ioctl request on fd, returning the kernel result. NOT IMPLEMENTED: requires the ioctl syscall. Returns: Err("ioctl: ioctl syscall not available in the pure stdlib").

`fn ioctl_get_winsize(fd: Int) -> Result[(Int, Int), Str]`¶

Fetch the terminal size as (rows, cols). NOT IMPLEMENTED: requires ioctl(TIOCGWINSZ). Returns: Err("ioctl_get_winsize: TIOCGWINSZ not available in the pure stdlib").

`fn ioctl_set_nonblock(fd: Int, on: Bool) -> Result[Unit, Str]`¶

Enable or disable non-blocking mode on fd. NOT IMPLEMENTED: requires fcntl(F_GETFL/F_SETFL). Returns: Err("ioctl_set_nonblock: fcntl not available in the pure stdlib").

`fn ioctl_fionread(fd: Int) -> Result[Int, Str]`¶

Number of bytes available for reading on fd. NOT IMPLEMENTED: requires ioctl(FIONREAD). Returns: Err("ioctl_fionread: FIONREAD not available in the pure stdlib").

`lock.xi`¶

`type FileLock`¶

struct FileLock - one held advisory whole-file lock. fd is the open read-write descriptor the lock is bound to; path is the locked path (diagnostics). The value owns the fd until file_lock_release consumes it; the struct is intentionally not Clone so a double release cannot be written.

Field	Type
`fd`	`Int`
`path`	`Str`

`fn file_lock_try(path: Str) -> Result[FileLock, Str]`¶

file_lock_try attempts a NON-blocking exclusive advisory lock on path and returns the held lock. The file must already exist and be writable (opened read-write, never created). Returns: Ok(lock) when the lock is now held; Err(LOCK_HELD_MSG) when it is held elsewhere; Err("file_lock_try: empty path") / Err("file_lock_try: open failed...") / Err("file_lock_try: lock failed") otherwise. An Ok lock stays held until file_lock_release. Complexity: O(1) syscall (no waiting).

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn file_lock(path: Str) -> Result[FileLock, Str]`¶

file_lock acquires the exclusive advisory lock on path, BLOCKING until it is free. The file must already exist and be writable (opened read-write, never created). On POSIX the wait survives EINTR; on Windows a synchronous fd queues inside LockFileEx. Returns: Ok(lock) once held (there is no "contended" outcome); Err("file_lock: empty path") / Err("file_lock: open failed...") / Err("file_lock: lock failed"). Do not call this on a path this process already holds on Windows (self-re-lock deadlocks). Complexity: blocking wait + O(1) syscall.

Postcondition: (path.len() == 0) => (result.is_err == true)

`fn file_lock_release(l: FileLock)`¶

file_lock_release releases the advisory lock and closes its fd. The unlock is best-effort: the authoritative release is the fd close (both platforms drop the locks when the fd/handle is closed), so a failed unlock is still released by the close. Consumes the FileLock (move): the value cannot be used or released again.

`mmap.xi`¶

`fn mmap_anonymous(length: Int) -> Result[Int, Str]`¶

Map a private anonymous read/write region and return its address. Real implementation (wave 120): mmap(MAP_PRIVATE|MAP_ANONYMOUS) on POSIX, CreateFileMapping(INVALID_HANDLE_VALUE) + MapViewOfFile on Windows. Non-positive lengths return Err. Returns: Ok(address) with a non-zero mapping address. Complexity: O(1). Pure (OS call).

Postcondition: result is Ok(_) => result > 0

`fn mmap_file(fd: Int, offset: Int, length: Int) -> Result[Int, Str]`¶

Map a read-only view of a file region (the fd must be readable). Real implementation (wave 120): mmap(PROT_READ, MAP_SHARED) / MapViewOfFile(FILE_MAP_READ). The offset must be page-aligned (POSIX) or 64 KiB-aligned (Windows); use 0 for the portable case. Returns: Ok(address) on success; Err on bad arguments or map failure. Complexity: O(1). Pure (OS call).

Postcondition: result is Ok(_) => result > 0

`fn mmap_writeable(fd: Int, offset: Int, length: Int) -> Result[Int, Str]`¶

Map a writable view of a file region (the fd must be read/write). Real implementation (wave 120): mmap(PROT_READ|PROT_WRITE, MAP_SHARED) / MapViewOfFile(FILE_MAP_WRITE). Writes through the mapping are visible to other readers of the file after mmap_sync (MS_SYNC-equivalent). Returns: Ok(address) on success; Err on bad arguments or map failure. Complexity: O(1). Pure (OS call).

Postcondition: result is Ok(_) => result > 0

`fn mmap_unmap(ptr: Int, length: Int) -> Result[Unit, Str]`¶

Unmap a region previously returned by the mmap_* functions. Real implementation (wave 120): munmap / UnmapViewOfFile. Returns: Ok(()) once the region is released; Err on bad arguments or unmap failure. Complexity: O(1). Pure (OS call).

Postcondition: result is Ok(_) => ptr > 0

`fn mmap_sync(ptr: Int, length: Int, flags: Int) -> Result[Unit, Str]`¶

Flush mapped pages back to the backing file. Real implementation (wave 120): msync (flags: 1 = async, anything else = sync, i.e. MS_SYNC semantics) / FlushViewOfFile (always sync). Returns: Ok(()) once the flush completed; Err on bad arguments or flush failure. Complexity: O(pages). Pure (OS call, may block).

Postcondition: result is Ok(_) => ptr > 0

`fn mmap_advise(ptr: Int, length: Int, advice: Int) -> Result[Unit, Str]`¶

Give the kernel usage advice about a mapped region. Real implementation (wave 120): madvise on POSIX (advice values are the platform MADV_* numbers; 0 = MADV_NORMAL is portable); a documented no-op success on Windows (no madvise equivalent). Returns: Ok(()) once the advice was accepted; Err on bad arguments or failure. Complexity: O(1). Pure (OS call).

Postcondition: result is Ok(_) => ptr > 0

`fn mmap_protect(ptr: Int, length: Int, prot: Int) -> Result[Unit, Str]`¶

Change the protection flags of a mapped region. Real implementation (wave 120): mprotect (prot bits: 1 = read, 2 = write, 4 = execute) / VirtualProtect. Returns: Ok(()) once the protection changed; Err on bad arguments or failure. Complexity: O(1). Pure (OS call).

Postcondition: result is Ok(_) => ptr > 0

`fn mmap_lock(ptr: Int, length: Int) -> Result[Unit, Str]`¶

Lock mapped pages in memory. Real implementation (wave 120): mlock / VirtualLock. May fail when the process locked-memory limit is exceeded. Returns: Ok(()) once the pages are resident; Err on bad arguments or failure. Complexity: O(pages). Pure (OS call).

Postcondition: result is Ok(_) => ptr > 0

`fn mmap_unlock(ptr: Int, length: Int) -> Result[Unit, Str]`¶

Unlock mapped pages. Real implementation (wave 120): munlock / VirtualUnlock. Returns: Ok(()) once the pages are unlocked; Err on bad arguments or failure. Complexity: O(pages). Pure (OS call).

Postcondition: result is Ok(_) => ptr > 0

`fn mmap_copy(ptr: Int, length: Int) -> Vec[UInt8]`¶

Copy length bytes out of a mapped region. Real implementation (wave 120): reads through the mapped pointer with cached offsets (no syscalls). A null pointer or non-positive length returns an empty vector. Returns: a fresh Vec[UInt8] with the mapped bytes. Complexity: O(length).

Postcondition: ptr <= 0 => result.len() == 0
Postcondition: length <= 0 => result.len() == 0

`fn mmap_write(ptr: Int, data: &Vec[UInt8]) -> Result[Unit, Str]`¶

Copy bytes into a mapped region. Real implementation (wave 120): memcpy through the runtime shim. Returns: Ok(()) once the bytes are copied; Err on a null pointer or a short write; an empty data is a no-op. Complexity: O(data.len()).

Postcondition: result is Ok(_) => ptr > 0

`fn mmap_resize(ptr: Int, old_len: Int, new_len: Int) -> Result[Int, Str]`¶

Grow or shrink a mapping and return the new address. NOT IMPLEMENTED: requires mremap (Linux-only; no Windows/macOS or POSIX equivalent). Use mmap_unmap + a fresh mapping instead. Returns: Err("mmap_resize: mremap not available in the pure stdlib").

`os.xi`¶

`fn platform() -> Str`¶

=== Platform & Architecture ===

Postcondition: result.len() > 0

`fn cpu_count() -> Int`¶

Number of logical CPUs.

Precondition: true
Postcondition: result > 0

`fn total_memory() -> Int`¶

Total physical memory in bytes (0 when unknown).

Precondition: true
Postcondition: result >= 0

`fn free_memory() -> Int`¶

Free physical memory in bytes (0 when unknown).

Precondition: true
Postcondition: result >= 0

`fn env_set(name: Str, value: Str)`¶

Set an environment variable (overwrites; portable shim).

Precondition: name.len() > 0

`fn env_unset(name: Str)`¶

Remove an environment variable (portable shim).

Precondition: name.len() > 0

`fn current_dir() -> Str`¶

Process working directory ("" on failure).

Postcondition: result.len() > 0

`fn set_current_dir(path: Str) -> Result[Unit, Str]`¶

Change the working directory, or Err with the OS message.

Precondition: path.len() > 0

`fn temp_dir() -> Str`¶

Platform temporary directory.

Postcondition: result.len() > 0

`fn home_dir() -> Option[Str]`¶

User home directory, or None when it cannot be resolved.

Postcondition: result is Some(_) => result.len() > 0

`type ChildProcess`¶

Spawned child process handle.

Field	Type
`pid`	`Int`
`stdin`	`Int`
`stdout`	`Int`
`stderr`	`Int`

`fn wait(self: Self) -> Result[Int, Str]`¶

Wait for the child; Ok(exit code) or Err with the OS message.

Precondition: self.pid > 0

`fn kill(self: Self) -> Result[Unit, Str]`¶

Terminate the child; Err when it cannot be killed.

Precondition: pid > 0

`fn id(self: Self) -> Int`¶

OS process id of the child.

Postcondition: result >= 0

`fn walk_dir(path: Str, callback: fn(Str, Metadata) -> Unit) -> Result[Unit, Str]`¶

=== Filesystem Walk ===

Precondition: path.len() > 0

`fn walk_dir_filtered(path: Str, pattern: Str, callback: fn(Str, Metadata) -> Unit) -> Result[Unit, Str]`¶

Walk path calling callback(path, metadata) for entries whose name matches pattern; Err on traversal failure.

Precondition: path.len() > 0

`type FileWatcher`¶

=== File System Watch (polling facade) === FileWatcher wraps a path and reports from FileWatcher.poll, which re-lists the directory on every call: it holds NO OS watch and keeps no diff state (entries are classified by metadata -- directories as Created, files as Modified, unreadable entries as Deleted). For native change notification use xiom.os.watch.watch_dir (ReadDirectoryChangesW on Windows, inotify on Linux).

Field	Type
`path`	`Str`
`recursive`	`Bool`

`fn watch_file(path: Str) -> Result[FileWatcher, Str]`¶

watch_file wraps path in the polling FileWatcher facade (see FileWatcher); it never consults the OS, so a non-empty path always yields Ok.

Precondition: path.len() > 0

`fn watch_dir(path: Str, recursive: Bool) -> Result[FileWatcher, Str]`¶

watch_dir wraps path in the polling FileWatcher facade (see FileWatcher); it never consults the OS, so a non-empty path always yields Ok, on every platform.

Precondition: path.len() > 0

`fn poll(self: Self) -> Result[Vec[FileEvent], Str]`¶

Non-blocking poll for accumulated events; Err on failure.

Postcondition: result is Ok(_) => result.len() >= 0

`fn close(self: Self)`¶

Stop watching and release the watcher (no-op: the polling facade holds no OS resources).

`enum FileEvent`¶

Kind of filesystem change reported by a watcher.

Created(path: Str)
Modified(path: Str)
Deleted(path: Str)
Renamed(from: Str, to: Str)

`fn on_signal(signal: Int, handler: fn(Int) -> Unit)`¶

=== Signal Handling ===

Precondition: signal > 0

`fn raise_signal(signal: Int)`¶

Raise a signal in the current process (POSIX; a no-op on Windows, where the CRT raise() fail-fasts on unsupported numbers).

Precondition: signal > 0

`type Pipe`¶

=== Pipe ===

Field	Type
`read_fd`	`Int`
`write_fd`	`Int`

`fn create_pipe() -> Result[Pipe, Str]`¶

Create an OS pipe, or Err with the OS message.

Postcondition: result is Ok(_) => result.read_fd >= 0 && result.write_fd >= 0

`fn read(self: Self, buf: &mut Vec[UInt8]) -> Result[Int, Str]`¶

Read into buf; Ok(bytes read, 0 at EOF) or Err.

Precondition: self.read_fd >= 0
Postcondition: result is Ok(_) => result >= 0

`fn write(self: Self, data: &Vec[UInt8]) -> Result[Int, Str]`¶

Write bytes; Ok(bytes written) or Err.

Precondition: self.write_fd >= 0
Postcondition: result is Ok(_) => result >= 0

`fn close_read(self: Self)`¶

Close the read end of the pipe.

Precondition: self.read_fd >= 0

`fn close_write(self: Self)`¶

Close the write end of the pipe.

Precondition: self.write_fd >= 0

`fn disk_free(path: Str) -> Result[Int, Str]`¶

=== Disk Usage ===

Precondition: path.len() > 0
Postcondition: result is Ok(_) => result >= 0

`fn disk_total(path: Str) -> Result[Int, Str]`¶

Total bytes on the filesystem containing path, or Err.

Precondition: path.len() > 0
Postcondition: result is Ok(_) => result >= 0

`fn file_size_bytes(path: Str) -> Result[Int, Str]`¶

Size of the file in bytes, or Err with the OS message.

Precondition: path.len() > 0
Postcondition: result is Ok(_) => result >= 0

`fn hostname() -> Result[Str, Str]`¶

hostname returns the system hostname via gethostname (POSIX) or GetComputerNameA (Windows). Uses an internal static buffer in the C runtime. Returns Err on failure.

Precondition: true

`fn os_version_str() -> Str`¶

os_version_str returns a best-effort OS version string via the xiom_os_version_str runtime intrinsic (GetVersionExA on Windows, uname on POSIX).

Precondition: true

`fn is_unix() -> Bool`¶

is_unix returns true if the platform is linux or macos.

Postcondition: result == (env.OS == "linux" || env.OS == "macos")

`fn user_name() -> Option[Str]`¶

user_name returns the current user name by reading the USERNAME (Windows) or USER (Unix) environment variable.

Postcondition: (result.is_some == true) => (env.var_opt("USERNAME").is_some == true || env.var_opt("USER").is_some == true)

`fn total_memory_mb() -> Int`¶

total_memory_mb returns total system memory in MiB. Wraps total_memory() / (1024 * 1024). Complexity: O(1).

Postcondition: result >= -1

`fn free_memory_mb() -> Int`¶

free_memory_mb returns free system memory in MiB. Wraps free_memory() / (1024 * 1024). Complexity: O(1).

Postcondition: result >= -1

`fn page_size() -> Int`¶

page_size returns the system page size in bytes. Returns 4096 -- the runtime does not expose sysconf(_SC_PAGESIZE).

Postcondition: result == 4096

`fn terminal_width() -> Option[Int]`¶

terminal_width returns the terminal width in columns, if detectable. The Xiom runtime does not expose TIOCGWINSZ -- always returns None.

Postcondition: result.is_none == true

`fn sleep_millis(ms: Int)`¶

sleep_millis sleeps for at least the given number of milliseconds. Uses busy-wait; usleep is not available on Windows MSVC.

`fn current_exe_path() -> Option[Str]`¶

current_exe_path returns the path of the currently running executable. Delegates to env.current_exe(). Returns None on failure.

Postcondition: (result.is_some == true) => (env.current_exe().is_ok == true)

`fn process_id() -> Int`¶

process_id returns the current process ID via the xiom_getpid runtime intrinsic.

Precondition: true

`fn cpu_model() -> Str`¶

cpu_model returns a human-readable CPU model string. The Xiom runtime does not expose CPUID or /proc/cpuinfo. Always returns "unknown".

Postcondition: result == "unknown"

`path.xi`¶

`type Path`¶

Borrowed path (wraps a Str); construct with Path.new.

Field	Type
`inner`	`Str`

Derives: Eq, Clone, Hash, Ord

`type PathBuf`¶

Owned, mutable path buffer.

Field	Type
`inner`	`Str`

Derives: Eq, Clone

`fn new(s: Str) -> Path`¶

Path constructors

Postcondition: result.inner == s

`fn new() -> PathBuf`¶

Create an empty PathBuf.

Postcondition: result.inner == ""

`fn from(s: Str) -> PathBuf`¶

Create a PathBuf from a string.

Postcondition: result.inner == s

`fn parent(self: Self) -> Option[Path]`¶

Path operations

Postcondition: (self.inner.len() == 0) => (result.is_none)
Postcondition: result.is_some => (self.inner.len() >= 1)

`fn file_name(self: Self) -> Option[Str]`¶

Final component of the path, or None when there is none.

Postcondition: (self.inner.len() == 0) => (result.is_some)
Postcondition: result.is_none => (self.inner.len() >= 1)

`fn extension(self: Self) -> Option[Str]`¶

Extension after the final dot of the file name, or None.

Postcondition: result.is_some => self.inner.len() > 0

`fn file_stem(self: Self) -> Option[Str]`¶

File name without its final extension, or None.

Postcondition: (self.inner.len() == 0) => (result.is_some)
Postcondition: result.is_none => (self.inner.len() >= 1)

`fn is_absolute(self: Self) -> Bool`¶

True when the path is absolute.

Postcondition: result => self.inner.len() >= 1

`fn is_relative(self: Self) -> Bool`¶

True when the path is relative.

Postcondition: (self.inner.len() == 0) => (result == true)
Postcondition: (result == false) => (self.inner.len() >= 1)

`fn has_root(self: Self) -> Bool`¶

True when the path starts at a root component.

Postcondition: result => (self.inner.len() >= 1)

`fn components(self: Self) -> Vec[Str]`¶

Path components as strings (separators normalized).

Postcondition: result.len() >= 1

`fn to_str(self: Self) -> Str`¶

The underlying string.

Postcondition: result == self.inner

`fn join(self: Self, child: Str) -> PathBuf`¶

Append child, inserting a separator when needed.

Postcondition: (self.inner.len() > 0 || child.len() > 0) => (result.inner.len() >= 1)
Postcondition: (self.inner.len() > 0) => (result.inner.len() >= self.inner.len())

`fn with_extension(self: Self, ext: Str) -> PathBuf`¶

Replace the extension with ext; an existing extension is removed.

Postcondition: result.inner.len() >= 1

`fn with_file_name(self: Self, name: Str) -> PathBuf`¶

Replace the final component with name.

Postcondition: (name.len() > 0) => (result.inner.len() >= 1)

`fn exists(self: Self) -> Bool`¶

True when the path exists on disk.

Postcondition: result => (self.inner.len() > 0)

`fn is_file(self: Self) -> Bool`¶

True when the path exists and is a regular file.

Postcondition: result => (self.inner.len() > 0)

`fn is_dir(self: Self) -> Bool`¶

True when the path exists and is a directory.

Postcondition: result => (self.inner.len() > 0)

`fn metadata(self: Self) -> Result[Metadata, Str]`¶

File metadata, or Err carrying the OS message.

Postcondition: result is Ok(_) => (self.inner.len() > 0)

`fn canonicalize(self: Self) -> Result[PathBuf, Str]`¶

Absolute, symlink-resolved path, or Err carrying the OS message.

Postcondition: result.is_ok

`fn starts_with(self: Self, base: Path) -> Bool`¶

True when base is a component-prefix of this path.

Postcondition: (base.inner.len() == 0) => (result == true)
Postcondition: result => (self.inner.len() >= base.inner.len())

`fn ends_with(self: Self, child: Path) -> Bool`¶

True when child is a component-suffix of this path.

Postcondition: (child.inner.len() == 0) => (result == true)
Postcondition: result => (self.inner.len() >= child.inner.len())

`fn push(self: Self, component: Str)`¶

PathBuf operations NOTE: These take &mut self (the old by-value forms mutated a copy and required callers to capture the return -- the stale "&mut self not supported" note predates the BUG 55 fixes; cell.xi &mut self works).

Precondition: component.len() >= 0

`fn pop(self: Self) -> Bool`¶

Remove the final component; false when the buffer is already empty.

Postcondition: (result == false) => (self.inner.len() == self.inner.len()@pre)

`fn as_path(self: Self) -> Path`¶

Borrow as a Path.

Postcondition: result.inner == self.inner

`fn clear(self: Self)`¶

Empty the buffer.

Postcondition: self.inner.len() == 0

`fn path_separator() -> Str`¶

Utility

Postcondition: result.len() >= 1

`fn path_is_absolute_str(p: Str) -> Bool`¶

path_is_absolute_str returns true if p starts with '/' or '\'.

Postcondition: (p.len() == 0) => (result == false)
Postcondition: result => (p.len() >= 1)

`platform.xi`¶

`fn platform_name() -> Str`¶

platform_name returns the OS name ("windows", "linux", "macos", ...). Complexity: O(1). Pure.

Postcondition: result.len() > 0

`fn platform_arch() -> Str`¶

platform_arch returns the target architecture ("x86_64", ...). Complexity: O(1). Pure.

Postcondition: result.len() >= 1

`fn platform_family() -> Str`¶

platform_family returns "unix" or "windows". Complexity: O(1). Pure.

Postcondition: result == "windows" || result == "unix"

`fn platform_is_windows() -> Bool`¶

platform_is_windows returns true on Windows. Complexity: O(1). Pure.

Postcondition: result == (platform_name() == "windows")

`fn platform_is_linux() -> Bool`¶

platform_is_linux returns true on Linux. Complexity: O(1). Pure.

Postcondition: result == (platform_name() == "linux")

`fn platform_is_macos() -> Bool`¶

platform_is_macos returns true on macOS. Complexity: O(1). Pure.

Postcondition: result == (platform_name() == "macos")

`fn platform_is_unix() -> Bool`¶

platform_is_unix returns true on Linux or macOS. Complexity: O(1). Pure.

Postcondition: result == (platform_name() != "windows")

`fn platform_hostname() -> Result[Str, Str]`¶

platform_hostname returns the system hostname. Implemented locally via the env.TEMP-free C getenv-free approach: reads the COMPUTERNAME variable (Windows) or HOSTNAME (Unix) as a best effort. Complexity: O(1).

Postcondition: result is Ok(_) => result.value.len() > 0

`fn platform_os_version() -> Str`¶

platform_os_version returns a best-effort OS version string derived from environment constants. Complexity: O(1). Pure.

Postcondition: result == env.OS

`fn platform_user_name() -> Option[Str]`¶

platform_user_name returns the current user name from the USERNAME (Windows) or USER (Unix) environment variable. Complexity: O(1).

Postcondition: (result is Some(_) && result.value.len() == 0) => env.var_opt("USER").is_some == true

`proc.xi`¶

`fn proc_is_running(pid: Int) -> Bool`¶

proc_is_running returns true if the process with the given pid is still alive. Delegates to xiom.process.is_running, which wraps the xiom_process_running runtime intrinsic. Pids must be positive.

Postcondition: (pid <= 0) => (result == false)

`fn proc_exit_code_success(code: Int) -> Bool`¶

proc_exit_code_success returns true when the exit code indicates success (code == 0).

Postcondition: result == (code == 0)

`fn proc_signal_name(sig: Int) -> Str`¶

proc_signal_name maps a POSIX signal number to its conventional name, or returns "SIG" + the number for unknown signals.

Postcondition: result.len() > 0

`fn proc_status_text(code: Int) -> Str`¶

proc_status_text formats a process exit code as "exit()". The runtime does not expose wait-status decoding (WIFSIGNALED etc.), so signals cannot be distinguished here.



Postcondition: result.len() >= 7

fn proc_command_exists(cmd: Str) -> Bool¶

proc_command_exists returns true if the named command can be found on the system PATH. Delegates to xiom.process.command_exists, which runs "where " (Windows) or "which " (Unix) via the shell. Spawning the command itself is not a reliable existence probe, since the system()-based spawn reports the command's exit code rather than a spawn failure.


Postcondition: (cmd.len() == 0) => (result == false)




proc_ffi.xi¶
type PipedChild¶

PipedChild is a non-blocking spawned child plus its three parent-side pipe descriptors. The parent keeps the fds: write the child's stdin on in_fd, read stdout/stderr from out_fd / err_fd through the xiom.io.pipe helpers (pipe_read / pipe_read_line) or drain_fd. The child runs independently of the parent (spawn never waits); reap it with wait() after draining, and kill() first when needed.




Field
Type




pid
Int


in_fd
Int


out_fd
Int


err_fd
Int



fn spawn_with_pipes(cmd: Str, dir: Str) -> Result[PipedChild, Str]¶

spawn_with_pipes starts cmd through the OS shell (cmd.exe /c on Windows, /bin/sh -c on POSIX) with fresh pipes on all three standard streams and returns immediately with the child pid and the parent-side fds (in_fd: write the child's stdin; out_fd / err_fd: read stdout / stderr). dir is the child's working directory; "" inherits the parent's. Reads/writes use the xiom.io.pipe surface; drain_fd reads until EOF (i.e. until the child and every holder of the write end closes it). Returns: Ok(PipedChild); Err on spawn failure. Complexity: O(1) OS calls.


Postcondition: cmd.len() == 0 => result.is_err == true

fn drain_fd(fd: Int, buf: &mut Vec[UInt8]) -> Result[Int, Str]¶

Drain all bytes from fd until EOF, appending them to buf. Blocks until the writer closes its end -- for a child's stdout that happens when the child (and every process holding the write end) exits/closes it. Returns: Ok(total bytes appended); Err when a read fails. Complexity: O(bytes) in 256-byte chunks.


Precondition: fd >= 0

fn wait(self: Self) -> Result[Int, Str]¶

Wait for the child and report its status: Ok(exit_code) for a normal exit, or Ok(128 + signal) when it was terminated by a signal (POSIX); on Windows the child's exit code as-is (PipedChild.kill reports 1). Err when the wait itself fails (unknown pid / wait error). BLOCKING: blocks until the child terminates. Complexity: one waitpid / WaitForSingleObject.


Precondition: self.pid > 0

fn kill(pid: Int, sig: Int) -> Result[Unit, Str]¶

Terminate a process (TerminateProcess on Windows, SIGKILL on POSIX). Only SIGKILL (9) is available: the runtime's spawn/terminate model is cross-platform, and other signals need a POSIX-only delivery path. Err when the signal is not 9 or the process cannot be terminated.


Precondition: pid > 0
Postcondition: sig != 9 => result.is_err == true

fn kill(self: Self) -> Result[Unit, Str]¶

Terminate the child (SIGKILL / TerminateProcess). The pipes stay open; close_pipes + wait after it to reap. Err when the kill fails (e.g. the child already exited and its handle is gone).


Precondition: self.pid > 0

fn close_pipes(self: Self)¶

Close the three parent-side pipe descriptors.


Precondition: true

fn is_running(self: Self) -> Bool¶

Whether the child process is still alive (best effort: may report false for processes owned by other users; a reaped child is never running).


Precondition: self.pid > 0

fn popen(cmd: Str, mode: Str) -> Result[PipedChild, Str]¶

popen opens a pipe to/from a shell command -- the libc-class pair with pclose, backed by spawn_with_pipes. mode selects the documented primary direction: "r" reads the child's stdout on out_fd, "w" writes the child's stdin on in_fd. Both directions are patched at once (and err_fd always carries the child's stderr); the mode only names the intended use. The child is not reaped until pclose / wait. Returns: Ok(PipedChild); Err on spawn failure or a mode other than "r"/"w". Complexity: O(1) OS calls.


Postcondition: cmd.len() == 0 => result.is_err == true
Postcondition: (mode != "r" && mode != "w") => result.is_err == true

fn pclose(child: PipedChild) -> Result[Int, Str]¶

pclose closes the parent-side fds and waits for the child, with the same status convention as PipedChild.wait (Ok(exit_code), or Ok(128 + signal) on POSIX signal death). Call it once per PipedChild. BLOCKING: waits for the child after closing the pipes.


Precondition: child.pid > 0

fn posix_spawn(path: Str, args: &Vec[Str]) -> Result[Int, Str]¶

posix_spawn starts path with args and no shell (fork + execv on POSIX). args are passed verbatim as argv[0..]; when empty, path itself is argv[0]. The child inherits the parent's standard handles (no pipes -- use spawn_with_pipes for those); reap it with wait / wait_status / PipedChild-style helpers. Windows maps to CreateProcessA with lpApplicationName = path (argv[0] stays whatever the caller passed). Returns: Ok(pid) -- the parent is NOT blocked; Err on spawn failure. Complexity: O(1) OS calls.


Postcondition: path.len() == 0 => result.is_err == true

fn posix_spawnp(file: Str, args: &Vec[Str]) -> Result[Int, Str]¶

posix_spawnp searches PATH for file (fork + execvp on POSIX; CreateProcessA image resolution from argv[0] on Windows -- argv[0] should name the program). Same handle-inheritance and reaping rules as posix_spawn. Returns: Ok(pid); Err on spawn failure. Complexity: O(1) OS calls.


Postcondition: file.len() == 0 => result.is_err == true

fn wait_status(pid: Int) -> Result[Int, Str]¶

wait_status waits for a child and returns the raw status word: on POSIX the waitpid status (decode with exit_code / exit_signal; WIFEXITED is (status & 0x7F) == 0); on Windows the exit code as an unsigned 32-bit value (no signal status exists there). Pairs with posix_spawn / posix_spawnp, which return bare pids. Returns: Ok(status); Err when the wait fails. BLOCKING: blocks until the target process terminates.


Precondition: pid > 0

fn fork() -> Result[Int, Str]¶

Fork the current process (child gets 0). NOT IMPLEMENTED: fork would duplicate the managed XIOM runtime state (heap, GC, threads) without a consistent reload; the spawn-based model (spawn_with_pipes / posix_spawn) is the supported route. Returns: Err("fork: ...").

fn waitpid(pid: Int, options: Int) -> Result[Int, Str]¶

Wait for a child. NOT IMPLEMENTED: requires the waitpid syscall. Use wait_status(pid), which returns the raw waitpid status. Returns: Err("waitpid: ...").

fn wait() -> Result[Int, Str]¶

Wait for any child. NOT IMPLEMENTED: requires the wait syscall. Use wait_status(pid). Returns: Err("wait: ...").

fn execv(path: Str, args: &Vec[Str]) -> Result[Int, Str]¶

Replace the process image. NOT IMPLEMENTED: exec replaces the running program image, which the managed runtime cannot survive (live heap, GC, threads); spawn a child instead (posix_spawn / spawn_with_pipes). Returns: Err("execv: ...").

fn execvp(file: Str, args: &Vec[Str]) -> Result[Int, Str]¶

Exec searching PATH. NOT IMPLEMENTED: see execv. Returns: Err("execvp: ...").

fn getpid() -> Int¶

Current process id. Delegates to xiom.os.process_id. Complexity: O(1).


Postcondition: result > 0

fn getppid() -> Int¶

Parent process id. NOT IMPLEMENTED: requires the getppid syscall. Returns 0.

fn getsid(pid: Int) -> Int¶

Session id. NOT IMPLEMENTED: requires the getsid syscall. Returns 0.

fn raise(sig: Int) -> Result[Unit, Str]¶

Send a signal to the current process. NOT IMPLEMENTED: requires the raise libc call; the spawn-based model terminates children via kill(pid, 9). Returns: Err("raise: ...").

fn exit_code(status: Int) -> Int¶

Extract the exit code from a wait status. Parameters: status -- a wait()/waitpid() status word. Returns: the low 8 bits of the shifted status. Complexity: O(1). Pure.


Postcondition: result >= 0 && result <= 255

fn exit_signal(status: Int) -> Int¶

Extract the terminating signal from a wait status. Parameters: status -- a wait()/waitpid() status word. Returns: the low 7 bits of the status. Complexity: O(1). Pure.


Postcondition: result >= 0 && result <= 127

fn process_status(pid: Int) -> Option[Int]¶

Poll a process (None if still running). NOT IMPLEMENTED: requires waitpid(WNOHANG). Returns None.




process.xi¶
fn exit(code: Int)¶

Terminate the current process with the given exit code. Delegates to xiom.io.exit (which calls the C exit() function). 0 indicates success, non-zero indicates failure.


Precondition: code >= 0

fn get_pid() -> Int¶

Return the current process ID (via the xiom_getpid runtime intrinsic).


Precondition: true

fn sleep_ms(ms: Int)¶

Sleep (block) the current thread for the specified number of milliseconds. Delegates to xiom.thread.sleep_ms which calls xiom_thread_sleep_ms.


Precondition: ms >= 0

fn env_var(name: Str) -> Option[Str]¶

Get the value of an environment variable. Returns Some(value) if the variable exists, None otherwise. Delegates to xiom.env.var_opt.


Precondition: name.len() > 0

fn current_exe_path() -> Option[Str]¶

Get the full path of the currently running executable. Delegates to xiom.env.current_exe() which reads argv[0]. Returns Some(path) on success, None if the path cannot be determined.


Postcondition: (result.is_some == true) => (xiom.env.current_exe().is_ok == true)

fn spawn_command(cmd: Str, args: &Vec[Str]) -> Result[Int, Str]¶

Spawn a command with arguments; Ok(pid) or Err.


Precondition: cmd.len() > 0
Postcondition: result is Ok(_) => result >= 0

fn command_exists(name: Str) -> Bool¶

Returns true if the named command can be found via the system PATH. On Windows: runs "where  > nul 2>&1". On Unix: runs "which  > /dev/null 2>&1".


Precondition: name.len() > 0

fn spawn_blocking(command: Str) -> Result[Int, Str]¶

Spawn a command via the OS shell and wait for completion. Returns Ok(exit_code) on success, Err on spawn failure. BLOCKING: the calling thread blocks until the child exits. On Windows: uses cmd.exe /c internally. On POSIX:   uses /bin/sh -c internally.


Precondition: command.len() > 0
Postcondition: result is Ok(_) => result >= 0

fn kill(pid: Int) -> Bool¶

Terminate a process by PID.  Returns true on success, false if the process could not be killed (doesn't exist, access denied).


Precondition: pid > 0

fn wait(pid: Int) -> Result[Int, Str]¶

Wait for a process to exit and return its exit code. Returns Ok(exit_code) on success, Err if the process doesn't exist or the wait failed. BLOCKING: blocks until the target process terminates.


Precondition: pid > 0

fn is_running(pid: Int) -> Bool¶

Check whether a process is still running. Returns true if the process exists and is running, false otherwise. May return false for processes owned by other users (access denied).


Precondition: pid > 0



signal.xi¶
fn signal_name(num: Int) -> Str¶

signal_name returns the canonical name for a signal number, or "unknown" for numbers outside the table. Complexity: O(1). Pure.


Postcondition: result.len() > 0

fn signal_code(name: Str) -> Option[Int]¶

signal_code returns the signal number for a canonical name, or None. Matching is case-insensitive on the letters (wave-123 fix: the body now upper-cases first, matching this contract). Complexity: O(n). Pure.


Postcondition: (result.is_some == true) => (name.len() >= 2)

fn signal_is_ignorable(num: Int) -> Bool¶

signal_is_ignorable returns true for signals that can be ignored (not SIGKILL or SIGSTOP). Complexity: O(1). Pure.


Postcondition: result == (num != 9 && num != 19 && num > 0)

fn signal_is_catchable(num: Int) -> Bool¶

signal_is_catchable returns true for signals a process can install a handler for (not SIGKILL or SIGSTOP). Complexity: O(1). Pure.


Postcondition: result == (num != 9 && num != 19 && num > 0)

fn signal_default_action(num: Int) -> Str¶

signal_default_action returns the default disposition ("term", "core", "stop", "cont", "ignore", or "unknown"). Complexity: O(1). Pure.


Postcondition: result.len() > 0

fn signal_raise(num: Int) -> Result[Unit, Str]¶

signal_raise delivers num to the current process. Real implementation (wave 123): POSIX uses the libc raise() (the handlers must be installed first -- signal_install -- or the default action terminates the process); Windows latches the number and wakes a signal_wait as self-delivery (there is no OS signal for SIGTERM on Windows; the console-event mapping is CTRL_C -> 2, CTRL_BREAK -> 3, close/logoff/ shutdown -> 15). Complexity: O(1) syscall. Returns: Ok(()) once delivered; Err before signal_install, for invalid numbers, and for uncatchable signals.


Postcondition: (num <= 0) => (result.is_err == true)

fn signal_install() -> Result[Unit, Str]¶

signal_install installs the delivery handlers: SIGINT/SIGTERM via sigaction with a self-pipe waker on POSIX; console control events (CTRL_C -> 2, CTRL_BREAK -> 3, close/logoff/shutdown -> 15) via SetConsoleCtrlHandler on Windows. Idempotent; call once before signal_wait / signal_raise. Returns: Ok(()) once installed; Err on failure. Complexity: O(1).


Postcondition: result is Ok(_) => signal_installed_marker()

fn signal_wait(timeout_ms: Int) -> Result[Int, Str]¶

signal_wait waits up to timeout_ms for a delivered signal and returns its number (2 = INT, 15 = TERM, 3 = BREAK/QUIT; 0 on timeout). Coalesced delivery: when several signals arrive between waits, the last one wins. Bounded timeouts only (negative is Err; no unbounded wait). Real implementation (wave 123) -- the graceful-drain primitive: install once, then loop { s = signal_wait(ms); if s == 15 || s == 2 { stop accepting; flush; exit 0 } }. Returns: Ok(signal number or 0); Err on bad arguments or failure. Complexity: blocking wait.


Postcondition: result is Ok(_) => result >= 0
Postcondition: result is Ok(_) => timeout_ms >= 0

fn signal_handle(num: Int, cb: fn(Int) -> Unit) -> Result[Unit, Str]¶

signal_handle installs a handler callback for num. NOT AVAILABLE: callbacks from signal context need a compiler-side trampoline; use the poll API instead (signal_install + signal_wait / signal_pending). Currently a documented Err stub so callers can compile against the surface and degrade to no-handler behavior. Complexity: O(1).


Postcondition: result.is_err == true

fn signal_pending() -> Result[Int, Str]¶

signal_pending is the non-blocking check: signal_wait(0) under the hood. Returns the pending signal number (0 when none); reading clears it. Real implementation (wave 123). Returns: Ok(signal number or 0); Err on failure.


Postcondition: result is Ok(_) => result >= 0




sync_io.xi¶
fn read_exact(fd: Int, buf: &mut Vec[UInt8]) -> Result[Int, Str]¶

Fill buf completely from fd or fail on early EOF. Real implementation (wave 115): reads through the xiom_read runtime shim in 4 KiB staging chunks; a short read returns Err("read_exact: unexpected EOF"). Returns: Ok(buf.len()) when every byte was read.


Precondition: fd >= 0

fn write_all(fd: Int, data: &Vec[UInt8]) -> Result[Int, Str]¶

Write every byte of data to fd or fail. Real implementation (wave 115): advances by the syscall-reported partial counts through the xiom_write runtime shim (no per-byte writes). Returns: Ok(data.len()) on success; Err("write_all: write failed").


Precondition: fd >= 0

fn read_until_eof(fd: Int) -> Result[Vec[UInt8], Str]¶

Read everything until end of file. NOT IMPLEMENTED: requires raw fd read syscalls. Returns: Err("read_until_eof: fd syscalls not available in the pure stdlib").

fn read_line_buffered(fd: Int) -> Result[Str, Str]¶

Read one line (without trailing newline). NOT IMPLEMENTED: requires raw fd read syscalls. Returns: Err("read_line_buffered: fd syscalls not available in the pure stdlib").

fn copy_fd(src: Int, dst: Int) -> Result[Int, Str]¶

Copy all bytes between two fds; returns the total copied. NOT IMPLEMENTED: requires raw fd read/write syscalls. Returns: Err("copy_fd: fd syscalls not available in the pure stdlib").

fn copy_fd_n(src: Int, dst: Int, n: Int) -> Result[Int, Str]¶

Copy up to n bytes between two fds. NOT IMPLEMENTED: requires raw fd read/write syscalls. Returns: Err("copy_fd_n: fd syscalls not available in the pure stdlib").

fn flush_fd(fd: Int) -> Result[Unit, Str]¶

Flush userspace buffers for an fd. NOT IMPLEMENTED: requires fflush on an fd stream. Returns: Err("flush_fd: fd flushing not available in the pure stdlib").

fn sync_fd(fd: Int) -> Result[Unit, Str]¶

fsync an fd to stable storage. Real implementation (wave 115): fsync(2) / _commit through the xiom_fsync_fd runtime shim. Returns: Ok(()) once the fd is durable; Err on failure.


Precondition: fd >= 0

fn fsync_dir(path: Str) -> Result[Unit, Str]¶

fsync a directory so entry changes are durable. Real implementation (wave 115): POSIX open + fsync + close; Windows opens the directory with backup semantics and flushes its handle (documented no-op-with-success where the filesystem rejects directory flushes). Returns: Ok(()) once the directory entry is durable; Err on failure.


Precondition: path.len() > 0

fn open_append(path: Str) -> Result[Int, Str]¶

Open path for durable appends and return a file descriptor. O_CREAT|O_APPEND binary open (runtime); write with write_all, flush with sync_fd, release with close_fd.


Precondition: path.len() > 0

fn open_read(path: Str) -> Result[Int, Str]¶

Open path for reading and return a file descriptor. Binary read-only open (runtime); read with read_exact, release with close_fd.


Precondition: path.len() > 0

fn open_rw(path: Str) -> Result[Int, Str]¶

Open path for reading and writing (creating it when missing) and return a file descriptor. Real implementation (wave 120): O_RDWR|O_CREAT binary open (runtime); the writable-fd counterpart backing mmap_writeable; release with close_fd.


Precondition: path.len() > 0

fn close_fd(fd: Int) -> Result[Unit, Str]¶

Close a file descriptor returned by open_append/open_read.


Precondition: fd >= 0

fn truncate_fd(fd: Int, len: Int) -> Result[Unit, Str]¶

truncate_fd sets the size of the file held by fd (ftruncate/_chsize_s); extending zero-fills. Returns: Ok(()) once the size is set.


Precondition: fd >= 0
Precondition: len >= 0

fn file_advise(fd: Int, offset: Int, length: Int, advice: Int) -> Result[Unit, Str]¶

Give access-pattern advice for a file range. NOT IMPLEMENTED: requires posix_fadvise. Returns: Err("file_advise: posix_fadvise not available in the pure stdlib").

fn file_allocate(fd: Int, offset: Int, length: Int) -> Result[Unit, Str]¶

Preallocate space for a file range. NOT IMPLEMENTED: requires posix_fallocate. Returns: Err("file_allocate: posix_fallocate not available in the pure stdlib").

fn file_lock(fd: Int) -> Result[Unit, Str]¶

Take an exclusive advisory lock on fd, blocking until it is held. Real implementation (wave 118): fcntl(F_SETLKW) whole-file on POSIX, LockFileEx (full range) on Windows. Returns: Ok(()) once the lock is held; Err on failure.


Precondition: fd >= 0

fn file_unlock(fd: Int) -> Result[Unit, Str]¶

Release the advisory lock held on fd (fcntl F_UNLCK / UnlockFileEx). Returns: Ok(()) once released; Err on failure.


Precondition: fd >= 0

fn file_try_lock(fd: Int) -> Bool¶

Attempt a non-blocking exclusive advisory lock; true when the lock is now held by this handle, false when it is held elsewhere (or the attempt failed). Real implementation (wave 118): F_SETLK / LockFileEx + LOCKFILE_FAIL_IMMEDIATELY.


Precondition: fd >= 0




sysinfo.xi¶
fn sysinfo_cpu_count() -> Int¶

sysinfo_cpu_count returns the number of logical CPUs. Complexity: O(1) syscall.


Postcondition: result >= 1

fn sysinfo_total_memory() -> Int¶

sysinfo_total_memory returns total system memory in bytes (-1 when the runtime cannot determine it). Complexity: O(1) syscall.


Postcondition: result >= -1

fn sysinfo_free_memory() -> Int¶

sysinfo_free_memory returns free system memory in bytes (-1 when the runtime cannot determine it). Complexity: O(1) syscall.


Postcondition: result >= -1

fn sysinfo_total_memory_mb() -> Int¶

sysinfo_total_memory_mb returns total system memory in MiB (-1 when the runtime cannot determine it). Complexity: O(1).


Postcondition: result >= -1

fn sysinfo_free_memory_mb() -> Int¶

sysinfo_free_memory_mb returns free system memory in MiB (-1 when the runtime cannot determine it). Complexity: O(1).


Postcondition: result >= -1

fn sysinfo_page_size() -> Int¶

sysinfo_page_size returns the system page size in bytes (4096 on the supported runtimes). Complexity: O(1).


Postcondition: result == 4096

fn sysinfo_hostname() -> Result[Str, Str]¶

sysinfo_hostname returns the system hostname from the COMPUTERNAME (Windows) or HOSTNAME (Unix) environment variable. Complexity: O(1).


Postcondition: result is Ok(_) => result.len() > 0

fn sysinfo_os_name() -> Str¶

sysinfo_os_name returns the OS name. Complexity: O(1). Pure.


Postcondition: result == env.OS

fn sysinfo_os_version() -> Str¶

sysinfo_os_version returns a best-effort OS version string derived from environment constants. Complexity: O(1). Pure.


Postcondition: result == env.OS

fn sysinfo_process_id() -> Int¶

sysinfo_process_id returns the current process ID. Complexity: O(1) syscall.


Postcondition: result > 0

fn sysinfo_user_name() -> Option[Str]¶

sysinfo_user_name returns the current user name from the USERNAME (Windows) or USER (Unix) environment variable. Complexity: O(1).


Postcondition: (result.is_some == true) => (env.var_opt("USERNAME").is_some == true || env.var_opt("USER").is_some == true)

fn sysinfo_cpu_model() -> Str¶

sysinfo_cpu_model returns a CPU model string. The runtime does not expose CPUID; always returns "unknown". Complexity: O(1).


Postcondition: result == "unknown"




term.xi¶
fn term_is_tty(fd: Int) -> Bool¶

term_is_tty returns true if the given file descriptor refers to a terminal. Delegates to xiom.os.terminal.isatty (the runtime does not expose an isatty intrinsic, so that is also false until an FFI exists).

fn term_clear_screen() -> Str¶

term_clear_screen returns the ANSI escape sequence that clears the screen and homes the cursor.


Postcondition: result == "[2J[H"

fn term_set_foreground(color: Int) -> Str¶

term_set_foreground returns the ANSI 256-color foreground escape for the given color index (0..255).


Postcondition: result.len() >= 9

fn term_reset() -> Str¶

term_reset returns the ANSI sequence that resets all attributes.


Postcondition: result == fmt_term.ansi_reset()

fn term_bold() -> Str¶

term_bold returns the ANSI sequence enabling bold.


Postcondition: result == fmt_term.ansi_bold()

fn term_dim() -> Str¶

term_dim returns the ANSI sequence enabling dim intensity.


Postcondition: result == fmt_term.ansi_dim()

fn term_underline() -> Str¶

term_underline returns the ANSI sequence enabling underline.


Postcondition: result == fmt_term.ansi_underline()

fn term_cursor_hide() -> Str¶

term_cursor_hide returns the ANSI sequence that hides the cursor.


Postcondition: result == "[?25l"

fn term_cursor_show() -> Str¶

term_cursor_show returns the ANSI sequence that shows the cursor.


Postcondition: result == "[?25h"

fn term_cursor_move(row: Int, col: Int) -> Str¶

term_cursor_move returns the ANSI sequence that moves the cursor to the given 1-based row and column.


Postcondition: result.len() >= 6

fn term_width() -> Int¶

term_width returns the terminal width in columns. Delegates to xiom.os.terminal.terminal_width; the runtime does not expose TIOCGWINSZ/GetConsoleScreenBufferInfo, so 0 means "unknown".




terminal.xi¶
type Termios¶

struct Termios { c_iflag: UInt32, c_oflag: UInt32, c_cflag: UInt32, c_lflag: UInt32, c_cc: Vec[UInt8] } - terminal attribute struct; layout mirrors struct termios.




Field
Type




c_iflag
UInt32


c_oflag
UInt32


c_cflag
UInt32


c_lflag
UInt32


c_cc
Vec[UInt8]



fn isatty(fd: Int) -> Bool¶

Return true if fd refers to a terminal. NOT IMPLEMENTED: requires the isatty syscall. Returns false.

fn tty_name(fd: Int) -> Result[Str, Str]¶

Return the name of the tty device for fd. NOT IMPLEMENTED: requires the ttyname syscall. Returns: Err("tty_name: ttyname not available in the pure stdlib").

fn pty_open() -> Result[(Int, Int), Str]¶

Open a pseudo-terminal pair (master, slave). NOT IMPLEMENTED: requires posix_openpt/grantpt/unlockpt/ptsname. Returns: Err("pty_open: pseudo-terminals not available in the pure stdlib").

fn pty_close(master: Int, slave: Int) -> Unit¶

Close both ends of a pseudo-terminal pair. NO-OP: no pty pairs exist in the pure stdlib.

fn termios_get(fd: Int) -> Result[Termios, Str]¶

Read the current termios attributes for fd. NOT IMPLEMENTED: requires tcgetattr. Returns: Err("termios_get: tcgetattr not available in the pure stdlib").

fn termios_set(fd: Int, t: Termios) -> Result[Unit, Str]¶

Apply the given termios attributes to fd. NOT IMPLEMENTED: requires tcsetattr. Returns: Err("termios_set: tcsetattr not available in the pure stdlib").

fn raw_mode(fd: Int) -> Result[Termios, Str]¶

Enable raw mode; returns the previous attributes. NOT IMPLEMENTED: requires tcgetattr/tcsetattr. Returns: Err("raw_mode: termios not available in the pure stdlib").

fn restore_mode(fd: Int, t: Termios) -> Result[Unit, Str]¶

Restore previously saved attributes. NOT IMPLEMENTED: requires tcsetattr. Returns: Err("restore_mode: tcsetattr not available in the pure stdlib").

fn cbreak_mode(fd: Int) -> Result[Termios, Str]¶

Enable cbreak mode; returns the previous attributes. NOT IMPLEMENTED: requires tcgetattr/tcsetattr. Returns: Err("cbreak_mode: termios not available in the pure stdlib").

fn canonical_mode(fd: Int) -> Result[Termios, Str]¶

Enable canonical (line-buffered) mode; returns the previous attributes. NOT IMPLEMENTED: requires tcgetattr/tcsetattr. Returns: Err("canonical_mode: termios not available in the pure stdlib").

fn nonblock(fd: Int) -> Result[Unit, Str]¶

Set the fd to nonblocking I/O. NOT IMPLEMENTED: requires fcntl(F_GETFL/F_SETFL). Returns: Err("nonblock: fcntl not available in the pure stdlib").

fn blocking(fd: Int) -> Result[Unit, Str]¶

Clear the nonblocking flag on fd. NOT IMPLEMENTED: requires fcntl(F_GETFL/F_SETFL). Returns: Err("blocking: fcntl not available in the pure stdlib").

fn winsize(fd: Int) -> Result[(Int, Int), Str]¶

Return the terminal window size as (rows, cols). NOT IMPLEMENTED: requires ioctl(TIOCGWINSZ). Returns: Err("winsize: TIOCGWINSZ not available in the pure stdlib").

fn set_winsize(fd: Int, rows: Int, cols: Int) -> Result[Unit, Str]¶

Set the terminal window size. NOT IMPLEMENTED: requires ioctl(TIOCSWINSZ). Returns: Err("set_winsize: TIOCSWINSZ not available in the pure stdlib").

fn terminal_width() -> Int¶

Query the width of the controlling terminal. NOT IMPLEMENTED: no termios query is available. Returns 0.

fn terminal_height() -> Int¶

Query the height of the controlling terminal. NOT IMPLEMENTED: no termios query is available. Returns 0.

fn terminal_title(title: Str) -> Str¶

Return the escape sequence that sets the window title. Parameters: title -- the desired title text. Returns: the "ESC]0;BEL" sequence. Complexity: O(n). Pure.</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result.len() == title.len() + 5</code></li>
</ul>
<h5 id="fn-terminal_bell-str"><code>fn terminal_bell() -> Str</code><a class="headerlink" href="#fn-terminal_bell-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Return the bell escape sequence. Returns: the BEL character "\x07". Complexity: O(1). Pure.</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result.len() == 1</code></li>
</ul>
<hr />
<hr />
<hr />
<h2 id="unixxi"><code>unix.xi</code><a class="headerlink" href="#unixxi" title="Permanent link">¶</a></h2>
<h5 id="fn-unix_umaskmask-int-int"><code>fn unix_umask(mask: Int) -> Int</code><a class="headerlink" href="#fn-unix_umaskmask-int-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>Set the file mode creation mask; returns the previous mask. NOT IMPLEMENTED: requires the umask syscall. Returns 0.</p>
</blockquote>
<h5 id="fn-unix_uid-int"><code>fn unix_uid() -> Int</code><a class="headerlink" href="#fn-unix_uid-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>The real user id of the process. NOT IMPLEMENTED: requires the getuid syscall. Returns 0.</p>
</blockquote>
<h5 id="fn-unix_gid-int"><code>fn unix_gid() -> Int</code><a class="headerlink" href="#fn-unix_gid-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>The real group id of the process. NOT IMPLEMENTED: requires the getgid syscall. Returns 0.</p>
</blockquote>
<h5 id="fn-unix_usernameuid-int-resultstr-str"><code>fn unix_username(uid: Int) -> Result[Str, Str]</code><a class="headerlink" href="#fn-unix_usernameuid-int-resultstr-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Resolve a uid to a user name. NOT IMPLEMENTED: requires getpwuid. Returns: Err("unix_username: getpwuid not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-unix_groupnamegid-int-resultstr-str"><code>fn unix_groupname(gid: Int) -> Result[Str, Str]</code><a class="headerlink" href="#fn-unix_groupnamegid-int-resultstr-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Resolve a gid to a group name. NOT IMPLEMENTED: requires getgrgid. Returns: Err("unix_groupname: getgrgid not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-unix_home_dir-str"><code>fn unix_home_dir() -> Str</code><a class="headerlink" href="#fn-unix_home_dir-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>The current user's home directory. Reads HOME via xiom.env (falls back to ""). Complexity: O(1). Pure (OS call).</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result.len() > 0 => env.home_dir().is_some</code></li>
</ul>
<h5 id="fn-unix_hostname-str"><code>fn unix_hostname() -> Str</code><a class="headerlink" href="#fn-unix_hostname-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>The system hostname. NOT IMPLEMENTED: requires the gethostname syscall. Returns "".</p>
</blockquote>
<h5 id="fn-unix_domainname-str"><code>fn unix_domainname() -> Str</code><a class="headerlink" href="#fn-unix_domainname-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>The system NIS/domain name. NOT IMPLEMENTED: requires getdomainname. Returns "".</p>
</blockquote>
<h5 id="fn-unix_uptime-int"><code>fn unix_uptime() -> Int</code><a class="headerlink" href="#fn-unix_uptime-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>System uptime in seconds. NOT IMPLEMENTED: requires sysinfo/getboottime. Returns 0.</p>
</blockquote>
<h5 id="fn-unix_loadavg-float64-float64-float64"><code>fn unix_loadavg() -> (Float64, Float64, Float64)</code><a class="headerlink" href="#fn-unix_loadavg-float64-float64-float64" title="Permanent link">¶</a></h5>
<blockquote>
<p>Load averages; the tuple is (1min, 5min, 15min). NOT IMPLEMENTED: requires getloadavg. Returns (0.0, 0.0, 0.0).</p>
</blockquote>
<h5 id="fn-unix_sysconfname-int-int"><code>fn unix_sysconf(name: Int) -> Int</code><a class="headerlink" href="#fn-unix_sysconfname-int-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>Query a system configuration value by name. NOT IMPLEMENTED: requires the sysconf syscall. Returns 0.</p>
</blockquote>
<h5 id="fn-unix_pathconfpath-str-name-int-int"><code>fn unix_pathconf(path: Str, name: Int) -> Int</code><a class="headerlink" href="#fn-unix_pathconfpath-str-name-int-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>Query a per-path configuration value. NOT IMPLEMENTED: requires the pathconf syscall. Returns 0.</p>
</blockquote>
<h5 id="fn-unix_getrlimitresource-int-int-int"><code>fn unix_getrlimit(resource: Int) -> (Int, Int)</code><a class="headerlink" href="#fn-unix_getrlimitresource-int-int-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>Resource limits; the tuple is (soft, hard). NOT IMPLEMENTED: requires getrlimit. Returns (0, 0).</p>
</blockquote>
<h5 id="fn-unix_setrlimitresource-int-soft-int-hard-int-resultunit-str"><code>fn unix_setrlimit(resource: Int, soft: Int, hard: Int) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-unix_setrlimitresource-int-soft-int-hard-int-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Set resource limits. NOT IMPLEMENTED: requires setrlimit. Returns: Err("unix_setrlimit: setrlimit not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-unix_utimepath-str-atime-int-mtime-int-resultunit-str"><code>fn unix_utime(path: Str, atime: Int, mtime: Int) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-unix_utimepath-str-atime-int-mtime-int-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Set a file's access and modification times. NOT IMPLEMENTED: requires the utime syscall. Returns: Err("unix_utime: utime not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-unix_chrootpath-str-resultunit-str"><code>fn unix_chroot(path: Str) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-unix_chrootpath-str-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Change the process root directory. NOT IMPLEMENTED: requires the chroot syscall. Returns: Err("unix_chroot: chroot not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-unix_niceinc-int-resultint-str"><code>fn unix_nice(inc: Int) -> Result[Int, Str]</code><a class="headerlink" href="#fn-unix_niceinc-int-resultint-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Adjust process priority; returns the new nice value. NOT IMPLEMENTED: requires the nice syscall. Returns: Err("unix_nice: nice not available in the pure stdlib").</p>
</blockquote>
<hr />
<hr />
<hr />
<h2 id="watchxi"><code>watch.xi</code><a class="headerlink" href="#watchxi" title="Permanent link">¶</a></h2>
<h5 id="type-watchevent"><code>type WatchEvent</code><a class="headerlink" href="#type-watchevent" title="Permanent link">¶</a></h5>
<blockquote>
<p>struct WatchEvent { kind: Int; path: Str } - one directory change; the path is relative to the watched directory (UTF-8).</p>
</blockquote>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>kind</code></td>
<td><code>Int</code></td>
</tr>
<tr>
<td><code>path</code></td>
<td><code>Str</code></td>
</tr>
</tbody>
</table>
<h5 id="fn-watch_kind_namekind-int-str"><code>fn watch_kind_name(kind: Int) -> Str</code><a class="headerlink" href="#fn-watch_kind_namekind-int-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>watch_kind_name returns the canonical name for a watch kind ("create", "modify", "remove", "rename", "overflow", "unknown"). Complexity: O(1). Pure.</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result.len() > 0</code></li>
</ul>
<h5 id="fn-watch_dirpath-str-recursive-bool-resultint-str"><code>fn watch_dir(path: Str, recursive: Bool) -> Result[Int, Str]</code><a class="headerlink" href="#fn-watch_dirpath-str-recursive-bool-resultint-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>watch_dir starts watching a directory and returns an opaque handle. Real implementation: ReadDirectoryChangesW on Windows (wave 124), inotify on Linux (wave 171); recursive watches subtrees (the Linux leg attaches up to 256 directories per watch, adding new ones as they appear). Other POSIX (darwin/BSD, kqueue) is a documented Err. Returns: Ok(handle > 0); Err for an empty/missing path, a non-directory, an unsupported platform, or when the 8-watch table or the OS open fails.</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result is Ok(_) => path.len() > 0</code></li>
</ul>
<h5 id="fn-watch_pollhandle-int-timeout_ms-int-resultvecwatchevent-str"><code>fn watch_poll(handle: Int, timeout_ms: Int) -> Result[Vec[WatchEvent], Str]</code><a class="headerlink" href="#fn-watch_pollhandle-int-timeout_ms-int-resultvecwatchevent-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>watch_poll collects the pending change events for a watch handle, waiting up to timeout_ms for the first one and draining the rest immediately (up to 256 per call; later calls pick up any remainder). The blocking wait is the platform primitive (overlapped event on Windows, poll(2) on Linux). A buffer overflow is surfaced as one WATCH_OVERFLOW event (empty path). Returns: Ok(events) (possibly empty on timeout); Err on a bad handle or a negative timeout. Complexity: blocking wait + O(events).</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result is Ok(_) => timeout_ms >= 0</code></li>
<li><strong>Postcondition:</strong> <code>result is Ok(_) => handle > 0</code></li>
</ul>
<h5 id="fn-watch_closehandle-int"><code>fn watch_close(handle: Int)</code><a class="headerlink" href="#fn-watch_closehandle-int" title="Permanent link">¶</a></h5>
<blockquote>
<p>watch_close releases a watch handle (best-effort; the signature returns no Result, mirroring fs_ffi.munmap).</p>
</blockquote>
<hr />
<hr />
<hr />
<h2 id="winxi"><code>win.xi</code><a class="headerlink" href="#winxi" title="Permanent link">¶</a></h2>
<h5 id="fn-win_registry_readhive-int-path-str-name-str-resultstr-str"><code>fn win_registry_read(hive: Int, path: Str, name: Str) -> Result[Str, Str]</code><a class="headerlink" href="#fn-win_registry_readhive-int-path-str-name-str-resultstr-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Read a registry value as a string. NOT IMPLEMENTED: requires the Win32 registry API. Returns: Err("win_registry_read: Win32 registry not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-win_registry_writehive-int-path-str-name-str-value-str-resultunit-str"><code>fn win_registry_write(hive: Int, path: Str, name: Str, value: Str) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-win_registry_writehive-int-path-str-name-str-value-str-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Write a string registry value. NOT IMPLEMENTED: requires the Win32 registry API. Returns: Err("win_registry_write: Win32 registry not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-win_registry_deletehive-int-path-str-name-str-resultunit-str"><code>fn win_registry_delete(hive: Int, path: Str, name: Str) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-win_registry_deletehive-int-path-str-name-str-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Delete a registry value. NOT IMPLEMENTED: requires the Win32 registry API. Returns: Err("win_registry_delete: Win32 registry not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-win_environment_varname-str-optionstr"><code>fn win_environment_var(name: Str) -> Option[Str]</code><a class="headerlink" href="#fn-win_environment_varname-str-optionstr" title="Permanent link">¶</a></h5>
<blockquote>
<p>Read a Windows environment variable. Delegates to xiom.env.var_opt. Parameters: name -- the variable name. Returns: Some(value) when set, None otherwise. Complexity: O(1). Pure (OS call).</p>
</blockquote>
<ul>
<li><strong>Precondition:</strong> <code>name.len() > 0</code></li>
</ul>
<h5 id="fn-win_set_environment_varname-str-value-str-resultunit-str"><code>fn win_set_environment_var(name: Str, value: Str) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-win_set_environment_varname-str-value-str-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Set a Windows environment variable. NOT IMPLEMENTED: the portable setenv path does not link on Windows MSVC, and the Win32 _putenv_s API is not exposed by the pure stdlib. Returns Err. Complexity: O(1).</p>
</blockquote>
<h5 id="fn-win_service_statusname-str-str"><code>fn win_service_status(name: Str) -> Str</code><a class="headerlink" href="#fn-win_service_statusname-str-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>The current status of a named Windows service. NOT IMPLEMENTED: requires the Win32 service API. Returns "unknown".</p>
</blockquote>
<h5 id="fn-win_service_startname-str-resultunit-str"><code>fn win_service_start(name: Str) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-win_service_startname-str-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Start a named Windows service. NOT IMPLEMENTED: requires the Win32 service API. Returns: Err("win_service_start: Win32 service API not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-win_service_stopname-str-resultunit-str"><code>fn win_service_stop(name: Str) -> Result[Unit, Str]</code><a class="headerlink" href="#fn-win_service_stopname-str-resultunit-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>Stop a named Windows service. NOT IMPLEMENTED: requires the Win32 service API. Returns: Err("win_service_stop: Win32 service API not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-win_shell_executeverb-str-file-str-args-str-resultint-str"><code>fn win_shell_execute(verb: Str, file: Str, args: Str) -> Result[Int, Str]</code><a class="headerlink" href="#fn-win_shell_executeverb-str-file-str-args-str-resultint-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>ShellExecute a file with a verb (open, runas, edit). NOT IMPLEMENTED: requires the Win32 ShellExecute API. Returns: Err("win_shell_execute: Win32 ShellExecute not available in the pure stdlib").</p>
</blockquote>
<h5 id="fn-win_version-str"><code>fn win_version() -> Str</code><a class="headerlink" href="#fn-win_version-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>The Windows version string. Returns the compile-time target OS name (the runtime does not expose GetVersionEx in the pure stdlib). Complexity: O(1).</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result.len() > 0</code></li>
</ul>
<h5 id="fn-win_is_admin-bool"><code>fn win_is_admin() -> Bool</code><a class="headerlink" href="#fn-win_is_admin-bool" title="Permanent link">¶</a></h5>
<blockquote>
<p>True when the process runs elevated. NOT IMPLEMENTED: requires the Win32 token API. Returns false.</p>
</blockquote>
<h5 id="fn-win_username-str"><code>fn win_username() -> Str</code><a class="headerlink" href="#fn-win_username-str" title="Permanent link">¶</a></h5>
<blockquote>
<p>The current Windows user name. Reads the USERNAME environment variable, or "" when unset. Complexity: O(1). Pure (OS call).</p>
</blockquote>
<ul>
<li><strong>Postcondition:</strong> <code>result.len() > 0 => env.var_opt("USERNAME").is_some</code></li>
</ul>
<hr />
<hr />
<hr />












                
              </article>
            </div>
          
          
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
        </div>
        
          <button type="button" class="md-top md-icon" data-md-component="top" hidden>
  
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
  Back to top
</button>
        
      </main>
      
        <footer class="md-footer">
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-copyright">
  
    <div class="md-copyright__highlight">
      Copyright © 2026 Eleftherios Notas and The XIOM Authors. Dual-licensed MIT or Apache-2.0. <a href="https://xiom-lang.org/terms.html">Terms of Use</a> · <a href="https://xiom-lang.org/privacy.html">Privacy Policy</a>
    </div>
  
  
    Made with
    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
      Material for MkDocs
    </a>
  
</div>
      
    </div>
  </div>
</footer>
      
    </div>
    <div class="md-dialog" data-md-component="dialog">
      <div class="md-dialog__inner md-typeset"></div>
    </div>
    
    
    
      
      
      <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.sections", "navigation.top", "content.code.copy", "search.suggest"], "search": "../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
    
    
      <script src="../../assets/javascripts/bundle.d7400e89.min.js"></script>
      
    
  </body>
</html>

Field	Type
`c_iflag`	`UInt32`
`c_oflag`	`UInt32`
`c_cflag`	`UInt32`
`c_lflag`	`UInt32`
`c_cc`	`Vec[UInt8]`

stdlib.os¶

args.xi¶

fn args_raw() -> Vec[Str]¶

fn flag_lookup(args: &Vec[Str], flag: Str) -> Bool¶

fn option_value(args: &Vec[Str], key: Str) -> Option[Str]¶

fn positionals(args: &Vec[Str]) -> Vec[Str]¶

fn args_has_flag(flag: Str) -> Bool¶

fn args_option(key: Str) -> Option[Str]¶

dir.xi¶

fn dir_current() -> Result[Str, Str]¶

fn dir_create(path: Str) -> Result[Unit, Str]¶

fn dir_create_all(path: Str) -> Result[Unit, Str]¶

fn dir_list(path: Str) -> Result[Vec[Str], Str]¶

fn dir_exists(path: Str) -> Bool¶

fn dir_remove(path: Str) -> Result[Unit, Str]¶

fn dir_temp() -> Str¶

fn dir_home() -> Option[Str]¶

fn dir_is_empty(path: Str) -> Bool¶

fn dir_join(a: Str, b: Str) -> Str¶

fn dir_parent(path: Str) -> Option[Str]¶

env.xi¶

fn host_is_windows() -> Bool¶

fn get_var(name: Str) -> Result[Str, Str]¶

fn var_opt(name: Str) -> Option[Str]¶

fn set_var(name: Str, value: Str)¶

fn remove_var(name: Str)¶

fn vars() -> Vec[(Str, Str)]¶

fn args() -> Vec[Str]¶

fn args_os() -> Vec[Str]¶

fn current_exe() -> Result[Str, Str]¶

fn current_dir() -> Result[Str, Str]¶

fn set_current_dir(path: Str) -> Result[Unit, Str]¶

fn temp_dir() -> Str¶

fn home_dir() -> Option[Str]¶

fn data_dir() -> Option[Str]¶

fn cache_dir() -> Option[Str]¶

fn config_dir() -> Option[Str]¶

fn executable_dir() -> Option[Str]¶

fn join_paths(a: Str, b: Str) -> Str¶

fn path_separator() -> Str¶

fn var_or(name: Str, default: Str) -> Str¶

fn has_var(name: Str) -> Bool¶

fn all_var_names() -> Vec[Str]¶

fn all_var_values() -> Vec[Str]¶

fn set_var_if_absent(name: Str, value: Str)¶

fn clear_var(name: Str)¶

fn args_len() -> Int¶

fn arg_at(i: Int) -> Option[Str]¶

fn arg_contains(s: Str) -> Bool¶

fn current_dir_str() -> Str¶

err.xi¶

fn errno() -> Int¶

fn errno_name(code: Int) -> Str¶

fn strerror(code: Int) -> Str¶

fn perror(msg: Str) -> Unit¶

fn errno_message() -> Str¶

fn errno_set(code: Int) -> Unit¶

fn backtrace() -> Vec[Str]¶

fn backtrace_symbols(frames: &Vec[Int]) -> Vec[Str]¶

fn demangle(symbol: Str) -> Str¶

fn last_error() -> Str¶

fn errno_to_string(code: Int) -> Str¶

event.xi¶

type EpollEvent¶

type KEvent¶

type PollFd¶

fn epoll_create() -> Result[Int, Str]¶

fn epoll_add(ep: Int, fd: Int, events: Int) -> Result[Unit, Str]¶

fn epoll_mod(ep: Int, fd: Int, events: Int) -> Result[Unit, Str]¶

fn epoll_del(ep: Int, fd: Int) -> Result[Unit, Str]¶

fn epoll_wait(ep: Int, max_events: Int, timeout_ms: Int) -> Result[Vec[EpollEvent], Str]¶

fn epoll_close(ep: Int) -> Unit¶

fn kqueue_create() -> Result[Int, Str]¶

fn kqueue_add_read(kq: Int, fd: Int) -> Unit¶

fn kqueue_add_write(kq: Int, fd: Int) -> Unit¶

fn kqueue_wait(kq: Int, timeout_ms: Int) -> Result[Vec[KEvent], Str]¶

fn kqueue_close(kq: Int) -> Unit¶

fn eventfd_new(init: Int) -> Result[Int, Str]¶

fn eventfd_read(fd: Int) -> Result[Int, Str]¶

fn eventfd_write(fd: Int, value: Int) -> Result[Unit, Str]¶

`stdlib.os`¶

`args.xi`¶

`fn args_raw() -> Vec[Str]`¶

`fn flag_lookup(args: &Vec[Str], flag: Str) -> Bool`¶

`fn option_value(args: &Vec[Str], key: Str) -> Option[Str]`¶

`fn positionals(args: &Vec[Str]) -> Vec[Str]`¶

`fn args_has_flag(flag: Str) -> Bool`¶

`fn args_option(key: Str) -> Option[Str]`¶

`dir.xi`¶

`fn dir_current() -> Result[Str, Str]`¶

`fn dir_create(path: Str) -> Result[Unit, Str]`¶

`fn dir_create_all(path: Str) -> Result[Unit, Str]`¶

`fn dir_list(path: Str) -> Result[Vec[Str], Str]`¶

`fn dir_exists(path: Str) -> Bool`¶

`fn dir_remove(path: Str) -> Result[Unit, Str]`¶

`fn dir_temp() -> Str`¶

`fn dir_home() -> Option[Str]`¶

`fn dir_is_empty(path: Str) -> Bool`¶

`fn dir_join(a: Str, b: Str) -> Str`¶

`fn dir_parent(path: Str) -> Option[Str]`¶

`env.xi`¶

`fn host_is_windows() -> Bool`¶

`fn get_var(name: Str) -> Result[Str, Str]`¶

`fn var_opt(name: Str) -> Option[Str]`¶

`fn set_var(name: Str, value: Str)`¶

`fn remove_var(name: Str)`¶

`fn vars() -> Vec[(Str, Str)]`¶

`fn args() -> Vec[Str]`¶

`fn args_os() -> Vec[Str]`¶

`fn current_exe() -> Result[Str, Str]`¶

`fn current_dir() -> Result[Str, Str]`¶

`fn set_current_dir(path: Str) -> Result[Unit, Str]`¶

`fn temp_dir() -> Str`¶

`fn home_dir() -> Option[Str]`¶

`fn data_dir() -> Option[Str]`¶

`fn cache_dir() -> Option[Str]`¶

`fn config_dir() -> Option[Str]`¶

`fn executable_dir() -> Option[Str]`¶

`fn join_paths(a: Str, b: Str) -> Str`¶

`fn path_separator() -> Str`¶

`fn var_or(name: Str, default: Str) -> Str`¶

`fn has_var(name: Str) -> Bool`¶

`fn all_var_names() -> Vec[Str]`¶

`fn all_var_values() -> Vec[Str]`¶

`fn set_var_if_absent(name: Str, value: Str)`¶

`fn clear_var(name: Str)`¶

`fn args_len() -> Int`¶

`fn arg_at(i: Int) -> Option[Str]`¶

`fn arg_contains(s: Str) -> Bool`¶

`fn current_dir_str() -> Str`¶

`err.xi`¶

`fn errno() -> Int`¶

`fn errno_name(code: Int) -> Str`¶

`fn strerror(code: Int) -> Str`¶

`fn perror(msg: Str) -> Unit`¶

`fn errno_message() -> Str`¶

`fn errno_set(code: Int) -> Unit`¶

`fn backtrace() -> Vec[Str]`¶

`fn backtrace_symbols(frames: &Vec[Int]) -> Vec[Str]`¶

`fn demangle(symbol: Str) -> Str`¶

`fn last_error() -> Str`¶

`fn errno_to_string(code: Int) -> Str`¶

`event.xi`¶

`type EpollEvent`¶

`type KEvent`¶

`type PollFd`¶

`fn epoll_create() -> Result[Int, Str]`¶

`fn epoll_add(ep: Int, fd: Int, events: Int) -> Result[Unit, Str]`¶

`fn epoll_mod(ep: Int, fd: Int, events: Int) -> Result[Unit, Str]`¶

`fn epoll_del(ep: Int, fd: Int) -> Result[Unit, Str]`¶

`fn epoll_wait(ep: Int, max_events: Int, timeout_ms: Int) -> Result[Vec[EpollEvent], Str]`¶

`fn epoll_close(ep: Int) -> Unit`¶

`fn kqueue_create() -> Result[Int, Str]`¶

`fn kqueue_add_read(kq: Int, fd: Int) -> Unit`¶

`fn kqueue_add_write(kq: Int, fd: Int) -> Unit`¶

`fn kqueue_wait(kq: Int, timeout_ms: Int) -> Result[Vec[KEvent], Str]`¶

`fn kqueue_close(kq: Int) -> Unit`¶

`fn eventfd_new(init: Int) -> Result[Int, Str]`¶

`fn eventfd_read(fd: Int) -> Result[Int, Str]`¶

`fn eventfd_write(fd: Int, value: Int) -> Result[Unit, Str]`¶