Skip to content

stdlib.io

I/O Library

Generated from v0.65.7. 5 source files, 129 documented symbols.

buffer.xi

fn buf_reader_new(fd: Int) -> BufReader

Wrap a standard fd or a FILE; 0 resolves to the real stdin FILE via the runtime (so buf_reader_new(io.stdin()) works with piped input), any other nonzero value is used as the stream handle directly (e.g. a pointer from fs.fopen). Params: fd - 0 for stdin, or a FILE* as Int. Returns: a buffered reader over the stream. Complexity: O(1).

  • Postcondition: (fd != 0) => (result.inner == fd)
fn br_read_line(r: &mut BufReader) -> Result[Str, Str]

Read one line through the buffer. Params: r - the reader. Returns: Ok(line without the trailing newline), Err on read failure. Complexity: O(n) where n is the line length.

  • Postcondition: result is Ok(_)
fn br_read_bytes(r: &mut BufReader, n: Int) -> Result[Vec[UInt8], Str]

Read exactly n bytes. Params: r - the reader; n - the byte count (clamped to >= 0). Returns: Ok(bytes read; fewer than n only at EOF), Err on read failure. Complexity: O(n).

  • Postcondition: result is Ok(_)
fn br_read_until(r: &mut BufReader, delim: UInt8) -> Result[Vec[UInt8], Str]

Read bytes up to a delimiter (inclusive). Params: r - the reader; delim - the delimiter byte. Returns: Ok(bytes including the delimiter), Err on read failure. Complexity: O(n) where n is the number of bytes read.

  • Postcondition: result is Ok(_)
fn br_peek(r: &mut BufReader, n: Int) -> Result[Vec[UInt8], Str]

Look ahead n bytes without consuming. Params: r - the reader; n - the byte count (clamped to >= 0). Returns: Ok(bytes staged in the internal buffer), Err on read failure. Complexity: O(n).

  • Postcondition: result is Ok(_)
fn br_seek(r: &mut BufReader, pos: Int)

Move the underlying read position. Params: r - the reader; pos - the byte offset from the start. Complexity: O(1) syscall.

  • Precondition: pos >= -2147483648 && pos <= 2147483647
  • Precondition: r.inner != 0
fn br_tell(r: &BufReader) -> Int

Current read position. Params: r - the reader. Returns: the byte offset of the underlying stream. Complexity: O(1) syscall.

  • Precondition: r.inner != 0
fn buf_writer_new(fd: Int) -> BufWriter

Wrap a standard fd or a FILE; 1 resolves to the real stdout FILE via the runtime (so buf_writer_new(io.stdout()) works), any other value is used as the stream handle directly. Params: fd - 1 for stdout, or a FILE* as Int. Returns: a buffered writer over the stream. Complexity: O(1).

  • Postcondition: (fd != 1) => (result.inner == fd)
fn bw_write(w: &mut BufWriter, data: &Vec[UInt8]) -> Result[Unit, Str]

Buffer bytes for writing. Params: w - the writer; data - the bytes to buffer. Returns: Ok(()) on success. Complexity: O(n) where n is the data length.

  • Postcondition: result is Ok(_)
fn bw_write_str(w: &mut BufWriter, s: Str) -> Result[Unit, Str]

Buffer a string for writing. Params: w - the writer; s - the string. Returns: Ok(()) on success. Complexity: O(n) where n is the string length.

  • Postcondition: result is Ok(_)
fn bw_flush(w: &mut BufWriter) -> Result[Unit, Str]

Flush buffered bytes to the fd. Params: w - the writer. Returns: Ok(()) on success, Err if fewer bytes than buffered were written. Complexity: O(n) where n is the buffer length.

  • Postcondition: result is Ok(_) => w.buf.len() == 0
fn bw_into_inner(w: &mut BufWriter) -> Int

Flush and return the underlying fd. Params: w - the writer (consumed). Returns: the file descriptor. Complexity: O(n) where n is the buffer length.

  • Postcondition: result == w.inner

console.xi

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

Read a line from standard input. Returns: Ok(line without the trailing newline), Err on EOF or failure. Complexity: O(n) where n is the line length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn console_read_char() -> Option[Char]

Read one character without echo. Returns: Some(char) read from stdin, None at EOF. Complexity: O(1).

  • Postcondition: result is Some(_) => to_int_from_char(result.value) >= 0 && to_int_from_char(result.value) <= 255
fn console_read_key() -> Option[Char]

Read one raw key press. Returns: Some(char) for the key, None at EOF. Raw mode is not exposed by the runtime; this reads one buffered character. Complexity: O(1).

  • Postcondition: result is Some(_) => to_int_from_char(result.value) >= 0 && to_int_from_char(result.value) <= 255
fn console_write(s: Str)

Write a string to standard output. Params: s - the string. Complexity: O(n).

  • Precondition: true
fn console_write_line(s: Str)

Write a string followed by a newline. Params: s - the string. Complexity: O(n).

  • Precondition: true
fn console_write_error(s: Str)

Write a string to standard error. Params: s - the string. Complexity: O(n).

  • Precondition: true
fn console_clear()

Clear the terminal screen. Complexity: O(1) shell invocation.

  • Precondition: true
fn console_set_title(title: Str)

Set the terminal window title. Params: title - the new title. Complexity: O(1) shell invocation.

  • Precondition: true
fn console_get_size() -> (Int, Int)

Terminal dimensions; tuple is (rows, cols). Returns: a documented simulation of (24, 80). Complexity: O(1).

  • Postcondition: result._0 == 24 && result._1 == 80
fn console_is_tty() -> Bool

Whether standard output is an interactive terminal. Returns: false (the runtime does not expose isatty). Complexity: O(1).

  • Postcondition: result == false
fn console_password(prompt: Str) -> Result[Str, Str]

Read input without echo. Params: prompt - the prompt to display. Returns: Ok(line) without echo, Err on EOF. Complexity: O(n) where n is the line length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn console_read_until_eof() -> Result[Str, Str]

Read all remaining standard input. Returns: Ok(all bytes until EOF), Err on a read failure. Complexity: O(N) where N is the total input size.

  • Postcondition: result is Ok(_)
fn console_flush()

Flush standard output. Complexity: O(1) syscall.

  • Precondition: true

fs.xi

fn fs_read(path: Str) -> Result[Vec[UInt8], Str]

Read the whole file as bytes. Params: path - the file path. Returns: Ok(file bytes), Err on failure. Complexity: O(n) where n is the file size.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_write(path: Str, data: &Vec[UInt8]) -> Result[Unit, Str]

Write bytes, truncating an existing file (binary mode). Params: path - the file path; data - the bytes to write. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the data length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_append(path: Str, data: &Vec[UInt8]) -> Result[Unit, Str]

Append bytes to a file (binary mode). Params: path - the file path; data - the bytes to append. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the data length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_read_text(path: Str) -> Result[Str, Str]

Read a file as UTF-8 text. Params: path - the file path. Returns: Ok(file content), Err on failure. Complexity: O(n) where n is the file size.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_write_text(path: Str, s: Str) -> Result[Unit, Str]

Write a text string to a file. Params: path - the file path; s - the content. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the content length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_remove(path: Str) -> Result[Unit, Str]

Remove (delete) a file; Err on failure. Delegates to xiom.io.remove_file. Params: path - the file path. Returns: Ok(()) on success, Err on failure. Complexity: O(1). Bindings-lane relay 2026-10-08 (docs/BINDINGS-STDLIB-WISHLIST.md W-1).

  • Postcondition: result is Ok(_) => !io.file_exists(path)
fn fs_copy(src: Str, dst: Str) -> Result[Unit, Str]

Copy a file to a new path. Params: src - the source path; dst - the destination path. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the source size.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_move(src: Str, dst: Str) -> Result[Unit, Str]

Move or rename a file. Params: src - the source path; dst - the destination path. Returns: Ok(()) on success, Err on failure. Complexity: O(1) syscall (atomic rename via the runtime shim; an existing dst is replaced, matching POSIX rename semantics on both platforms).

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_exists(path: Str) -> Bool

Whether the path exists. Params: path - the path. Returns: true if the path can be opened for reading. Complexity: O(1).

  • Postcondition: result == true => io.file_exists(path) || io.is_dir(path)
  • Postcondition: result == false => !io.file_exists(path) && !io.is_dir(path)
fn fs_is_file(path: Str) -> Bool

Whether the path is a regular file. Params: path - the path. Returns: true if the path is a regular file. Complexity: O(1).

  • Postcondition: result == true => fs_exists(path)
fn fs_is_dir(path: Str) -> Bool

Whether the path is a directory. Params: path - the path. Returns: true if the path is a directory. Complexity: O(1).

  • Postcondition: result == true => fs_exists(path)
fn fs_size(path: Str) -> Result[Int, Str]

File size in bytes. Params: path - the file path. Returns: Ok(size in bytes), Err on failure. Complexity: O(1).

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_mtime(path: Str) -> Result[Int, Str]

Last modification time as a Unix timestamp. Params: path - the file path. Returns: Ok(mtime in seconds since the epoch), Err on failure. Complexity: O(1).

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_read_range(path: Str, offset: Int, len: Int) -> Result[Vec[UInt8], Str]

Read len bytes starting at offset. Params: path - the file path; offset - the start offset; len - the count. Returns: Ok(bytes read; fewer only at EOF), Err on failure. Complexity: O(len).

  • Postcondition: result is Ok(_) && len >= 0 => result.value.len() <= len
  • Postcondition: result is Ok(_) && len <= 0 => result.value.len() == 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_write_range(path: Str, offset: Int, data: &Vec[UInt8]) -> Result[Int, Str]

Write bytes at an offset, returning bytes written. Params: path - the file path; offset - the start offset; data - the bytes. Returns: Ok(bytes written), Err on failure. Complexity: O(n) where n is the data length.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Ok(_) => result.value <= data.len()
fn fs_touch(path: Str) -> Result[Unit, Str]

Create an empty file if missing, update mtime. Params: path - the file path. Returns: Ok(()) on success, Err on failure. Complexity: O(1).

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_temp_dir() -> Str

Return a usable temporary directory path. Returns: the system temporary directory. Complexity: O(1).

  • Postcondition: result.len() >= 0

io.xi

type IOError

=== Error type ===

Field Type
message Str
code Int

enum SeekFrom

=== SeekFrom ===

  • Start(_0: Int)
  • End(_0: Int)
  • Current(_0: Int)

fn print(msg: Str)

=== Console ===

  • Precondition: true

fn println(msg: Str)

Write a line to standard output.

  • Precondition: true

fn eprintln(msg: Str)

Write a line to standard error and flush it immediately. Use this for crash/diagnostic markers: stdout is buffered, so a later fault can lose pending println output while stderr is already on the sink.

  • Precondition: true

fn read_line() -> Str

Read one line from standard input (newline stripped). This is the interactive reader: use it (or read_int / read_float) for console input. Do NOT use stdin() for this -- stdin() returns the numeric file descriptor 0 (for pipe/dup/close APIs), so age = stdin() silently stores 0 and never waits for input (playground-4 trap; see docs/ACCELERATED.md for the stream surfaces).

  • Postcondition: result.len() >= 0

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

Read and parse an Int from standard input; Err on bad input. Use this (or read_line / read_float) for interactive input; stdin() is the fd 0 accessor, not a reader.

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

fn read_float() -> Result[Float64, Str]

Read and parse a Float64 from standard input; Err on bad input.

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

fn parse_int(s: Str) -> Result[Int, Str]

Parse a decimal integer (optional leading +/- sign, ASCII digits only). Deterministic core of read_int, exposed for parsing without stdin.

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

fn parse_float(s: Str) -> Result[Float64, Str]

Parse a decimal float (optional sign, one optional '.', ASCII digits; no exponent support). Deterministic core of read_float.

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

fn read_file(path: Str) -> Result[Str, IOError]

=== File system ===

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

fn write_file(path: Str, content: Str) -> Result[Unit, IOError]

Write (create/truncate) a file byte-exactly; Err with the OS message. Opened in binary mode so content is not newline-translated on Windows (ORBITDB relay 2026-10-08: text mode silently turned LF into CRLF).

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

fn append_file(path: Str, content: Str) -> Result[Unit, IOError]

Append to a file byte-exactly, creating it when missing; Err. Opened in binary mode so content is not newline-translated on Windows.

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

fn file_exists(path: Str) -> Bool

True when the path exists (file or directory).

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

fn is_dir(path: Str) -> Bool

True when the path exists and is a directory.

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

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

Create a directory (with missing parents); Err on failure.

  • Precondition: path.len() > 0
  • Precondition: !file_exists(path)
  • Postcondition: result is Ok(_) => is_dir(path)

fn list_dir(path: Str) -> Result[Vec[Str], IOError]

Directory entry names, or Err with the OS message.

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

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

Delete a file; Err with the OS message.

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

fn copy_file(src: Str, dst: Str) -> Result[Unit, IOError]

Copy a file's contents to a new path; Err. Wave 137 (REL-20261014-1427): byte-exact copy. The previous read_file/write_file pair moved the bytes through Str, which is NUL-terminated by design, so binary sources truncated at the first NUL byte (a copied PE DLL became 3 bytes MZ\x90). read_file_bytes / write_file_bytes are length-carrying and byte-exact.

  • Precondition: src.len() > 0
  • Precondition: dst.len() > 0
  • Precondition: src != dst
  • Precondition: file_exists(src)
  • Postcondition: result is Ok(_) => file_exists(dst)

fn rename(src: Str, dst: Str) -> Result[Unit, IOError]

Rename or move a path; Err with the OS message.

  • Precondition: src.len() > 0
  • Precondition: dst.len() > 0
  • Postcondition: result is Ok(_) => !fs_exists(src) && fs_exists(dst)

fn exit(code: Int)

=== Process ===

  • Precondition: code >= 0

fn args() -> Vec[Str]

Process arguments.

  • Postcondition: result.len() >= 0

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

Environment variable value, or None when unset.

  • Precondition: name.len() > 0

fn time_now() -> Int

=== Time ===

  • Precondition: true

fn sleep(ms: Int)

Sleep for ms milliseconds.

  • Precondition: ms >= 0

fn open(path: Str, mode: Str) -> Result[Int, IOError]

Open path with the stdio mode ("r", "w", "a", ...) and return the FILE* handle as Int -- the handle type BufReader.new and other stdio-backed APIs expect (stdin_file()/stdout_file()/stderr_file() cover the standard streams). Close with io.close when done.

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

fn close(handle: Int) -> Result[Unit, IOError]

Close a FILE* handle previously returned by io.open or the stdio *_file() accessors.

  • Precondition: handle != 0

type BufReader

=== Buffered I/O ===

Field Type
inner Int
buf Vec[UInt8]

Invariants: - inner >= 0

fn new(reader: Int) -> BufReader

Wrap a file descriptor in a buffered reader.

  • Postcondition: result.inner == reader

fn read_line(self: Self, buf: &mut Str) -> Result[Int, IOError]

Read one line into buf; Ok(bytes) including the newline, 0 at EOF.

  • Precondition: inner >= 0
  • Postcondition: result is Ok(_) => result >= 0

fn lines(self: Self) -> Vec[Str]

All remaining lines (newlines stripped).

  • Postcondition: result.len() >= 0

type BufWriter

Buffered writer over a file descriptor.

Field Type
inner Int
buf Vec[UInt8]

fn new(writer: Int) -> BufWriter

Wrap a file descriptor in a buffered writer.

  • Postcondition: result.inner == writer

type Metadata

=== File metadata ===

Field Type
size Int
is_file Bool
is_dir Bool
modified Int
created Int
permissions Int

fn metadata(path: Str) -> Result[Metadata, IOError]

File metadata (size, timestamps, permissions), or Err.

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

fn set_permissions(path: Str, perm: Int) -> Result[Unit, IOError]

Set POSIX permission bits; Err on failure.

  • Precondition: path.len() > 0
  • Precondition: perm >= 0

fn stdin() -> Int

=== Standard streams === Numeric file descriptors (for fd-based APIs: pipe/dup/close). NOTE: stdin() returns fd 0 -- it is NOT a reader and never blocks. For console input use read_line / read_int / read_float (or stdin_file() for FILE*-based APIs).

  • Postcondition: result >= 0

fn stdout() -> Int

File descriptor for standard output.

  • Postcondition: result >= 0

fn stderr() -> Int

File descriptor for standard error.

  • Postcondition: result >= 0

fn stdin_file() -> Int

FILE* handle of the standard input stream.

  • Precondition: true
  • Postcondition: result != 0

fn stdout_file() -> Int

FILE* handle of the standard output stream.

  • Precondition: true
  • Postcondition: result != 0

fn stderr_file() -> Int

FILE* handle of the standard error stream.

  • Precondition: true
  • Postcondition: result != 0

type Cursor

=== Memory I/O ===

Field Type
data Vec[UInt8]
pos Int

Invariants: - pos >= 0 - pos <= data.len()

fn new(data: Vec[UInt8]) -> Cursor

In-memory cursor over a byte vector.

  • Postcondition: self.pos == 0

fn into_inner(self: Self) -> Vec[UInt8]

Consume the cursor and return its bytes.

  • Postcondition: result.len() == self.data.len()

fn join_paths(base: Str, child: Str) -> Str

=== Path operations === Join child onto base, recognizing BOTH / and \ as separators so a Windows-style path is not silently treated as one segment. The result keeps the caller's separator style; a missing separator is added as /.

  • Postcondition: result.len() >= base.len()

fn normalize_path(path: Str) -> Str

Normalize a filesystem path lexically without touching the disk. Both / and \ are accepted as separators and the output uses /; repeated separators and . segments are removed; .. pops the previous segment (and is dropped at a root). A drive prefix (C:) or a leading / / // (UNC) root is preserved. An empty or fully-relative-empty path yields .. This is a lexical helper only: it does not resolve symlinks.

  • Postcondition: result.len() >= 1

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

Parent directory of the path, or None.

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

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

Final component of the path, or None.

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

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

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

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

fn is_absolute(path: Str) -> Bool

True when the path is absolute.

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

fn read_line_trim() -> Str

read_line_trim reads a line from stdin and trims trailing whitespace (including \r, \n). Delegates to read_line + trim. Complexity: O(n) where n is line length.

  • Postcondition: result.len() >= 0

fn read_all_stdin() -> Str

read_all_stdin reads the entire standard input stream until EOF and returns the concatenated content. Returns "" if stdin is empty. Complexity: O(N) where N is total bytes read. Each call to read_line allocates up to 4096 bytes; memory usage peaks at ~2x input size.

  • Postcondition: result.len() >= 0

fn stdin_read_line() -> Str

stdin_read_line is an alias for read_line.

  • Postcondition: result.len() >= 0

fn flush_stdout()

flush_stdout flushes the C stdout buffer (real since wave 115). Makes redirected/piped logs visible immediately; OS-level durability of the sink still depends on it (use io.fsync on a handle you own).

  • Precondition: true

fn flush_stderr()

flush_stderr flushes the C stderr buffer. eprintln already flushes per line; use this only after writing through a raw stderr FILE* handle.

  • Precondition: true

fn write_file_bytes(path: Str, data: &Vec[UInt8]) -> Result[Unit, IOError]

write_file_bytes writes raw bytes to a file, truncating if it exists. Opened in binary mode: bytes are stored exactly (no newline translation). Complexity: O(n) where n = data.len().

  • Postcondition: result is Ok(_) => file_exists(path)

fn read_file_bytes(path: Str) -> Result[Vec[UInt8], IOError]

read_file_bytes reads a file and returns its raw bytes. Complexity: O(n) where n = file size. The Ok payload is a fresh main-heap Vec owned by the caller (m375).

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

fn fsync(handle: Int) -> Result[Unit, IOError]

fsync a FILE* handle (from io.open, append modes included) to stable storage. Real implementation (wave 115): fflush + fsync(fileno) on POSIX, fflush + _commit on Windows, through the runtime. Returns: Ok(()) once the handle is durable; Err on failure.

  • Precondition: handle != 0

fn read_at(path: Str, offset: Int, len: Int) -> Result[Vec[UInt8], IOError]

read_at reads up to len bytes starting at byte offset, clamped to the file size (no past-EOF fabrication). Binary read. Returns: Ok(bytes) with bytes.len() <= len; Err on open failure. The Ok payload is a fresh main-heap Vec owned by the caller (m375).

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

fn read_at_into(path: Str, offset: Int, buf: &mut Vec[UInt8], len: Int) -> Result[Int, IOError]

read_at_into reads up to len bytes at offset into the caller's buf (cleared first), clamped to the file size, and returns the byte count. Reuses the existing buffer capacity: no fresh Vec per call (m375 page-reader path). Binary read.

  • Precondition: path.len() > 0
  • Precondition: offset >= 0
  • Precondition: len >= 0
  • Postcondition: result is Ok(_) => result.value <= len
  • Postcondition: result is Ok(_) => buf.len() == result.value

fn write_at(path: Str, offset: Int, data: &Vec[UInt8]) -> Result[Unit, IOError]

write_at writes data at byte offset, creating the file when missing and zero-filling a gap when the offset is past the current end. Binary. Returns: Err on open/write failure; an empty data is a no-op.

  • Precondition: path.len() > 0
  • Precondition: offset >= 0

fn append_file_bytes(path: Str, data: &Vec[UInt8]) -> Result[Unit, IOError]

append_file_bytes appends raw bytes to a file byte-exactly, creating it when missing; binary mode (no newline translation). Returns: Err on open/write failure; an empty data is a no-op.

  • Precondition: path.len() > 0

fn truncate_file(path: Str, size: Int) -> Result[Unit, IOError]

truncate_file sets the file size to size bytes (extending zero-fills). Returns: Err when the file cannot be opened; Ok once the size is set.

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

fn file_last_byte(path: Str) -> Option[UInt8]

file_last_byte returns the final byte of a file, or None when the file is missing or empty. Reads a single byte at (size - 1): O(1), no full rescan. Binary.

  • Precondition: path.len() > 0

fn ends_with_newline(path: Str) -> Bool

ends_with_newline reports whether a file's final byte is '\n'; false when the file is missing, empty, or has any other tail byte. O(1) via file_last_byte.

  • Precondition: path.len() > 0

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

remove_dir deletes an empty directory (rmdir/_rmdir); Err when the path is missing or not empty.

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

fn append_line_sync(path: Str, line: Str) -> Result[Unit, IOError]

append_line_sync appends line as one durable line: a torn tail (a nonempty file not ending in '\n') is terminated first, then line + '\n' is appended and the append handle is fsynced before returning. Binary; creates the file when missing. Err when open/write/flush fails.

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

fn file_size(path: Str) -> Option[Int]

file_size returns the size of a file in bytes, or None if the path cannot be stated.

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

fn file_modified_time(path: Str) -> Option[Int]

file_modified_time returns the last modification time of a file as a Unix timestamp, or None if the path cannot be stated.

  • Precondition: true

fn move_file(src: Str, dst: Str) -> Result[Unit, IOError]

move_file renames (moves) a file or directory from src to dst. Alias for rename. Complexity: O(1) OS call.

  • Postcondition: result is Ok(_) => file_exists(dst)

fn dir_exists(path: Str) -> Bool

dir_exists returns true if the path exists and is a directory.

  • Postcondition: result == is_dir(path)

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

create_dir_all creates the directory and all missing parent directories along the path. Returns Ok(()) on success. Complexity: O(d) where d = directory depth.

  • Postcondition: result is Ok(_) && path.len() > 0 => is_dir(path)

fn list_dir_recursive(path: Str) -> Result[Vec[Str], IOError]

list_dir_recursive recursively collects all file and directory paths under the given root directory. Returns the full paths relative to root. Complexity: O(N) where N = total entries.

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

fn read_file_lines(path: Str) -> Result[Vec[Str], IOError]

read_file_lines reads a file and returns its lines as a Vec[Str]. Trailing newline characters are stripped; a trailing CR is removed from each line so CRLF files yield clean line values (ORBITDB relay 2026-10-08). An empty (zero-byte) file yields Ok with zero lines. The read relies on the size reported by the file system (regular files); files that report size 0 (e.g. /proc entries) read as empty -- use the byte reader for those. Complexity: O(n).

  • Precondition: path.len() > 0

fn write_file_lines(path: Str, lines: &Vec[Str]) -> Result[Unit, IOError]

write_file_lines writes a Vec[Str] to a file, one line per entry. Lines are separated by '\n'. Complexity: O(n).

  • Postcondition: result is Ok(_) => file_exists(path)

fn append_line(path: Str, line: Str) -> Result[Unit, IOError]

append_line appends a single line (followed by '\n') to a file. If the file does not exist it will be created. Complexity: O(n) where n = line length.

  • Postcondition: result is Ok(_) => file_exists(path)

pipe.xi

fn pipe_create() -> (Int, Int)

Create a pipe; tuple is (read_fd, write_fd). Returns: (read_fd, write_fd), or (-1, -1) on failure. Complexity: O(1) syscall.

  • Postcondition: result._0 == -1 => result._1 == -1
fn pipe_read(fd: Int, buf: &mut Vec[UInt8]) -> Result[Int, Str]

Read available bytes into buf. Params: fd - the pipe fd; buf - the destination buffer. Returns: Ok(bytes read), Err on failure. Complexity: O(n) syscall.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_write(fd: Int, data: &Vec[UInt8]) -> Result[Int, Str]

Write bytes to the pipe. Params: fd - the pipe fd; data - the bytes. Returns: Ok(bytes written), Err on failure. Complexity: O(n) syscall.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_close(fd: Int)

Close a pipe descriptor. Params: fd - the pipe fd. Complexity: O(1) syscall.

  • Precondition: fd >= 0
fn pipe_is_open(fd: Int) -> Bool

Whether a descriptor is still valid. Params: fd - the pipe fd. Returns: true while the fd is non-negative (documented simulation). Complexity: O(1).

  • Postcondition: result == (fd >= 0)
fn pipe_read_line(fd: Int) -> Result[Str, Str]

Read a line from a pipe. Params: fd - the pipe fd. Returns: Ok(line without the trailing newline), Err on failure. Complexity: O(n) where n is the line length.

  • Postcondition: result is Ok(_)
fn pipe_write_line(fd: Int, s: Str) -> Result[Unit, Str]

Write a line to a pipe. Params: fd - the pipe fd; s - the line. Returns: Ok(()) on success, Err on a short or failed write. Complexity: O(n) where n is the line length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_available(fd: Int) -> Int

Bytes currently buffered in the pipe. Params: fd - the pipe fd. Returns: 0 (the runtime does not expose FIONREAD). Complexity: O(1).

  • Postcondition: result >= 0
fn pipe_read_timeout(fd: Int, ms: Int) -> Result[Int, Str]

Read with a timeout, returning bytes read. Params: fd - the pipe fd; ms - the timeout in milliseconds. Returns: Ok(bytes read) even if the timeout elapsed, Err on failure. Complexity: O(ms) polls.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_write_timeout(fd: Int, data: &Vec[UInt8], ms: Int) -> Result[Int, Str]

Write with a timeout, returning bytes written. Params: fd - the pipe fd; data - the bytes; ms - the timeout. Returns: Ok(bytes written), Err on failure. Complexity: O(ms) polls.

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