Filesystem

std.fs is the small filesystem convenience surface for text files. Binary buffers, directory iteration, metadata, permission customization, symlink policy, and path manipulation remain separate or future API.

For lower-level descriptor work, use std.os and std.io.

fs.read_file(path) opens path read-only, reads the complete file, closes the descriptor before returning, and validates the bytes as a Zynx String.

fs.write_file(path, text) creates path if it is missing, truncates and overwrites it if it already exists, writes the complete UTF-8 text, and closes the descriptor before returning. It is not an atomic write and it does not create parent directories. Newly created files use the host default file mode.

The functions do not normalize paths. Relative paths are resolved by the host process working directory. Host open, read, and write behavior determines ordinary filesystem details such as symlink traversal.

Text validation uses the String invariant: the file must contain valid UTF-8 and must not contain embedded NUL bytes. Invalid text throws utf8.UnicodeError.Invalid. Filesystem and descriptor failures throw io.IOError; allocation failures throw AllocError.

Descriptor ownership is internal to both helpers. Callers do not receive or own a descriptor.

import std.fs;
import std.io;

fn main() {
    try fs.write_file("message.txt", "hello\n");
    let text = try fs.read_file("message.txt");

    assert text.str() == "hello\n";
    io.println("read {text.size()} bytes");
}

Symbol	Signature	Notes
read_file	read_file(path: str) throws(io.IOError | utf8.UnicodeError | AllocError) -> String	Reads the whole file as validated text and closes the descriptor before returning.
write_file	write_file(path: str, text: str) throws(io.IOError) -> void	Creates or truncates a text file, writes the complete string, and closes the descriptor before returning.