stdlib.os

OS Library

Generated from v0.60.1. 24 source files, 377 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.

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.

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.

fn args_has_flag(flag: Str) -> Bool

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

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

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

---

---

---

dir.xi

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

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

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

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

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.

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.

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.

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.

fn dir_temp() -> Str

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

fn dir_home() -> Option[Str]

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

fn dir_is_empty(path: Str) -> Bool

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

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).

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).

---

---

---

env.xi

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.

fn args() -> Vec[Str]

Process arguments (UTF-8, lossy).

fn args_os() -> Vec[Str]

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

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

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

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.

fn cache_dir() -> Option[Str]

Per-user cache directory, or None.

fn config_dir() -> Option[Str]

Per-user configuration directory, or None.

fn executable_dir() -> Option[Str]

Directory containing the running executable, or None.

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

Join two path fragments with the platform separator.

fn path_separator() -> Str

Platform path separator ("/" or "\").

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).

fn has_var(name: Str) -> Bool

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

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.

fn all_var_values() -> Vec[Str]

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

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.

fn clear_var(name: Str)

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

fn args_len() -> Int

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

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).

fn arg_contains(s: Str) -> Bool

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

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.

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.

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.

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.

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.

---

---

---

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).

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).

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).

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.

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

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

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).

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.

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.

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).

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

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

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).

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).

---

---

---

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

---

---

---

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.

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.

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.

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".

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 "..".

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).

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".

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".

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

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

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.

---

---

---

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).

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

Memory-map a file. NOT IMPLEMENTED: requires the mmap syscall. Returns: Err("mmap: mmap syscall not available in the pure stdlib").

fn munmap(m: MappedFile)

Unmap a mapped region. NO-OP: no mappings exist in the pure stdlib.

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

Flush mapped pages. NOT IMPLEMENTED: requires the msync syscall. Returns: Err("msync: msync syscall not available in the pure stdlib").

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

Advise the kernel on page use. NOT IMPLEMENTED: requires the madvise syscall. Returns: Err("madvise: madvise syscall not available in the pure stdlib").

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

Lock pages in memory. NOT IMPLEMENTED: requires the mlock syscall. Returns: Err("mlock: mlock syscall not available in the pure stdlib").

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

Unlock pages. NOT IMPLEMENTED: requires the munlock syscall. Returns: Err("munlock: munlock syscall not available in the pure stdlib").

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. NOT IMPLEMENTED: requires the writev syscall. Returns: Err("writev: writev syscall not available in the pure stdlib").

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

Copy between fds in-kernel. NOT IMPLEMENTED: requires the sendfile syscall. Returns: Err("sendfile: sendfile syscall not available in the pure stdlib").

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. NOT IMPLEMENTED: requires the fsync syscall. Returns: Err("fsync: fsync syscall not available in the pure stdlib").

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

Flush file data only. NOT IMPLEMENTED: requires the fdatasync syscall. Returns: Err("fdatasync: fdatasync syscall not available in the pure stdlib").

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").

---

---

---

mmap.xi

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

Map a private anonymous region and return its address. NOT IMPLEMENTED: requires the mmap syscall. Returns: Err("mmap_anonymous: mmap not available in the pure stdlib").

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

Map a read-only view of a file region. NOT IMPLEMENTED: requires the mmap syscall. Returns: Err("mmap_file: mmap not available in the pure stdlib").

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

Map a writable view of a file region. NOT IMPLEMENTED: requires the mmap syscall. Returns: Err("mmap_writeable: mmap not available in the pure stdlib").

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

Unmap a previously mapped region. NOT IMPLEMENTED: requires the munmap syscall. Returns: Err("mmap_unmap: munmap not available in the pure stdlib").

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

Flush mapped pages back to the backing file. NOT IMPLEMENTED: requires the msync syscall. Returns: Err("mmap_sync: msync not available in the pure stdlib").

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

Give the kernel usage advice about a mapped region. NOT IMPLEMENTED: requires the madvise syscall. Returns: Err("mmap_advise: madvise not available in the pure stdlib").

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

Change the protection flags of a mapped region. NOT IMPLEMENTED: requires the mprotect syscall. Returns: Err("mmap_protect: mprotect not available in the pure stdlib").

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

Lock mapped pages in memory. NOT IMPLEMENTED: requires the mlock syscall. Returns: Err("mmap_lock: mlock not available in the pure stdlib").

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

Unlock mapped pages. NOT IMPLEMENTED: requires the munlock syscall. Returns: Err("mmap_unlock: munlock not available in the pure stdlib").

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

Copy length bytes out of a mapped region. NOT IMPLEMENTED: no mappings exist in the pure stdlib. Returns an empty vector.

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

Copy bytes into a mapped region. NOT IMPLEMENTED: no mappings exist in the pure stdlib. Returns: Err("mmap_write: no mappings available in the pure stdlib").

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. 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).

fn env_unset(name: Str)

Remove an environment variable (portable shim).

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 ===

Field	Type
path	Str
recursive	Bool

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

Watch a single file for changes, or Err with the OS message.

• Precondition: path.len() > 0

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

Watch a directory (optionally recursive), or Err.

• 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.

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; unsupported on Windows).

• 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.

fn user_name() -> Option[Str]

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

fn total_memory_mb() -> Int

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

fn free_memory_mb() -> Int

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

fn page_size() -> Int

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

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.

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.

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".

---

---

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

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

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

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.

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.

fn has_root(self: Self) -> Bool

True when the path starts at a root component.

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.

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

Append child, inserting a separator when needed.

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

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

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

Replace the final component with name.

fn exists(self: Self) -> Bool

True when the path exists on disk.

fn is_file(self: Self) -> Bool

True when the path exists and is a regular file.

fn is_dir(self: Self) -> Bool

True when the path exists and is a directory.

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

File metadata, or Err carrying the OS message.

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

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

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

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

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

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

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.

fn as_path(self: Self) -> Path

Borrow as a Path.

fn clear(self: Self)

Empty the buffer.

fn path_separator() -> Str

Utility

fn path_is_absolute_str(p: Str) -> Bool

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

---

---

platform.xi

fn platform_name() -> Str

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

fn platform_arch() -> Str

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

fn platform_family() -> Str

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

fn platform_is_windows() -> Bool

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

fn platform_is_linux() -> Bool

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

fn platform_is_macos() -> Bool

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

fn platform_is_unix() -> Bool

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

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).

fn platform_os_version() -> Str

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

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).

---

---

---

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.

fn proc_exit_code_success(code: Int) -> Bool

proc_exit_code_success returns true when the exit code indicates success (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.

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.

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.

---

---

---

proc_ffi.xi

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

Fork the current process (child gets 0). NOT IMPLEMENTED: requires the fork syscall. Returns: Err("fork: fork syscall not available in the pure stdlib").

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

Wait for a child. NOT IMPLEMENTED: requires the waitpid syscall. Returns: Err("waitpid: waitpid syscall not available in the pure stdlib").

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

Wait for any child. NOT IMPLEMENTED: requires the wait syscall. Returns: Err("wait: wait syscall not available in the pure stdlib").

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

Open a pipe to/from a command. NOT IMPLEMENTED: requires the popen libc call. Returns: Err("popen: popen not available in the pure stdlib").

fn pclose(pipe: Int) -> Result[Int, Str]

Close a popen pipe and get the status. NOT IMPLEMENTED: requires the pclose libc call. Returns: Err("pclose: pclose not available in the pure stdlib").

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

Spawn a process by path. NOT IMPLEMENTED: requires posix_spawn. Returns: Err("posix_spawn: posix_spawn not available in the pure stdlib").

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

Spawn searching PATH. NOT IMPLEMENTED: requires posix_spawnp. Returns: Err("posix_spawnp: posix_spawnp not available in the pure stdlib").

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

Replace the process image. NOT IMPLEMENTED: requires the execv syscall. Returns: Err("execv: execv syscall not available in the pure stdlib").

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

Exec searching PATH. NOT IMPLEMENTED: requires the execvp syscall. Returns: Err("execvp: execvp syscall not available in the pure stdlib").

fn getpid() -> Int

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

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 kill(pid: Int, sig: Int) -> Result[Unit, Str]

Send a signal. NOT IMPLEMENTED: requires the kill syscall. Returns: Err("kill: kill syscall not available in the pure stdlib").

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

Send a signal to the current process. NOT IMPLEMENTED: requires the raise libc call. Returns: Err("raise: raise not available in the pure stdlib").

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.

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.

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.

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.

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. Complexity: O(1). Pure.

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.

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.

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.

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

signal_raise sends a signal to the current process via the runtime raise() primitive. Complexity: O(1) syscall.

---

---

---

sync_io.xi

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

Fill buf completely or fail. NOT IMPLEMENTED: requires raw fd read syscalls. Returns: Err("read_exact: fd syscalls not available in the pure stdlib").

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

Write every byte or fail. NOT IMPLEMENTED: requires raw fd write syscalls. Returns: Err("write_all: fd syscalls not available in the pure stdlib").

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. NOT IMPLEMENTED: requires the fsync syscall. Returns: Err("sync_fd: fsync not available in the pure stdlib").

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

fsync a directory so entry changes are durable. NOT IMPLEMENTED: requires opening the directory and calling fsync. Returns: Err("fsync_dir: fsync not available in the pure stdlib").

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, blocking. NOT IMPLEMENTED: requires fcntl(F_SETLKW). Returns: Err("file_lock: fcntl locking not available in the pure stdlib").

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

Release an advisory lock. NOT IMPLEMENTED: requires fcntl(F_SETLK). Returns: Err("file_unlock: fcntl locking not available in the pure stdlib").

fn file_try_lock(fd: Int) -> Bool

Attempt a non-blocking exclusive lock. NOT IMPLEMENTED: requires fcntl(F_SETLK). Returns false.

---

---

---

sysinfo.xi

fn sysinfo_cpu_count() -> Int

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

fn sysinfo_total_memory() -> Int

sysinfo_total_memory returns total system memory in bytes. Complexity: O(1) syscall.

fn sysinfo_free_memory() -> Int

sysinfo_free_memory returns free system memory in bytes. Complexity: O(1) syscall.

fn sysinfo_total_memory_mb() -> Int

sysinfo_total_memory_mb returns total system memory in MiB. Complexity: O(1).

fn sysinfo_free_memory_mb() -> Int

sysinfo_free_memory_mb returns free system memory in MiB. Complexity: O(1).

fn sysinfo_page_size() -> Int

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

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

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

fn sysinfo_os_name() -> Str

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

fn sysinfo_os_version() -> Str

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

fn sysinfo_process_id() -> Int

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

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).

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).

---

---

---

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.

fn term_set_foreground(color: Int) -> Str

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

fn term_reset() -> Str

term_reset returns the ANSI sequence that resets all attributes.

fn term_bold() -> Str

term_bold returns the ANSI sequence enabling bold.

fn term_dim() -> Str

term_dim returns the ANSI sequence enabling dim intensity.

fn term_underline() -> Str

term_underline returns the ANSI sequence enabling underline.

fn term_cursor_hide() -> Str

term_cursor_hide returns the ANSI sequence that hides the cursor.

fn term_cursor_show() -> Str

term_cursor_show returns the ANSI sequence that shows the cursor.

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.

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;