When To Use std.fs
In Zerolang, use std.fs for hosted file reads, writes, existence checks, copies, renames,
and explicit file-resource cleanup.
Runnable today:
| API | Return | Notes |
|---|---|---|
std.fs.read(path, buf) | usize | Reads bytes from a hosted path into a caller-provided MutSpan<u8> buffer. |
std.fs.write(path, bytes) | usize | Writes bytes to a hosted path and returns the byte count. |
std.fs.host() | Fs | Creates the hosted filesystem capability. |
std.fs.open(fs, path) | Maybe<owned<File>> | Opens a file and returns null when unavailable. |
std.fs.openOrRaise(fs, path) | owned<File> | Opens a file or raises raises [NotFound, TooLarge, Io]. |
std.fs.create(fs, path) | Maybe<owned<File>> | Creates a file and returns null when unavailable. |
std.fs.createOrRaise(fs, path) | owned<File> | Creates a file or raises raises [NotFound, TooLarge, Io]. |
std.fs.readOrRaise(&mut file, buf) | usize | Reads into caller storage or raises. |
std.fs.writeAll(&mut file, bytes) | Bool | Writes bytes to an owned file handle. |
std.fs.writeAllOrRaise(&mut file, bytes) | Void | Writes all bytes or raises. |
std.fs.fileLen(&mut file) | Maybe<usize> | Reports file length when available. |
std.fs.fileLenOrRaise(&mut file) | usize | Reports the file length or raises. |
std.fs.fileSize(fs, path) | Maybe<usize> | Opens a hosted path through fs and reports file length when available. |
std.fs.readAll(alloc, fs, path, limit) | Maybe<owned<ByteBuf>> | Reads through an explicit allocator and size limit. |
std.fs.readAllOrRaise(alloc, fs, path, limit) | owned<ByteBuf> | Reads through an explicit allocator and size limit. |
std.fs.readBytes(path, buf) | Maybe<usize> | Fills caller storage and returns the total file size; a value above len(buf) means the buffer holds only the first len(buf) bytes. |
std.fs.readBytesAt(path, offset, buf) | Maybe<usize> | Fills caller storage starting at a byte offset and returns the total file size, so bounded buffers can process larger files in chunks. |
std.fs.writeBytes(path, bytes) | Maybe<usize> | Writes byte spans to a hosted path. |
std.fs.appendBytes(path, bytes) | Maybe<usize> | Appends byte spans to a hosted path, creating the file when missing. |
std.fs.exists(path) | Bool | Checks whether a hosted path exists. |
std.fs.isFile(path) | Bool | Checks whether a hosted path opens and reports a file length. |
std.fs.isDir(path) | Bool | Checks whether a hosted path is a directory. |
std.fs.makeDir(path) | Bool | Creates a hosted directory. |
std.fs.ensureDir(path) | Bool | Succeeds when a hosted directory already exists or can be created. |
std.fs.removeDir(path) | Bool | Removes a hosted directory. |
std.fs.remove(path) | Bool | Removes a hosted file path. |
std.fs.rename(old, new) | Bool | Renames a hosted file path. |
std.fs.dirEntryCount(path) | Maybe<usize> | Counts entries in a hosted directory. |
std.fs.dirEntryName(buffer, path, index) | Maybe<Span<u8>> | Writes one hosted directory entry name into caller storage. |
std.fs.tempName(buffer, prefix) | Maybe<String> | Writes a temporary path into caller storage. |
std.fs.atomicWrite(path, temp, bytes) | Bool | Writes through a caller-provided temporary path and renames. |
std.fs.close(&mut file) | Void | Closes an owned file handle explicitly; remaining owned files are cleaned up deterministically. |
std.fs.readFile(fs, path, buffer) | Maybe<usize> | Opens, fills caller storage, and closes through explicit Fs; returns the total file size, so a value above len(buffer) signals truncation. |
std.fs.writeFile(fs, path, bytes) | Bool | Creates, writes all bytes, and closes through explicit Fs. |
std.fs.appendFile(fs, path, bytes) | Bool | Opens, appends all bytes, and closes through explicit Fs. |
std.fs.readFileBytes(fs, path, buffer) | Maybe<Span<u8>> | Opens, reads a full file, closes it, and returns the live prefix of caller storage; null when the file exceeds the buffer. |
std.fs.readFileEquals(fs, path, buffer, expected) | Bool | Reads a full file through caller storage and compares the bytes with an expected span. |
std.fs.copyFile(from, to, buffer) | Bool | Copies a hosted file through caller-provided scratch storage. |
Current limits:
- Richer permissions and platform-specific file modes.
- Recursive directory walking helpers.
- Async or nonblocking I/O.
Example
pub fn main(world: World) -> Void raises [NotFound, TooLarge, Io] { let fs: Fs = std.fs.host() var buf: [32]u8 = [0_u8; 32] if std.fs.ensureDir(".zero/out") && std.fs.writeFile(fs, ".zero/out/example.txt", "hello\n") { let bytes: Maybe<Span<u8>> = std.fs.readFileBytes(fs, ".zero/out/example.txt", buf) let size: Maybe<usize> = std.fs.fileSize(fs, ".zero/out/example.txt") if bytes.has && size.has && size.value == 6 && std.fs.isFile(".zero/out/example.txt") && std.fs.readFileEquals(fs, ".zero/out/example.txt", buf, "hello\n") && std.fs.rename(".zero/out/example.txt", ".zero/out/example-renamed.txt") { if std.fs.remove(".zero/out/example-renamed.txt") { check world.out.write("fs ok\n") } } }}Design Notes
The path helpers are a small current API, not a hidden global filesystem.
Stable file APIs make effects, ownership, and cleanup visible through capabilities.
Hosted filesystem APIs are denied on non-host targets with TAR002.
Target-neutral packages should keep filesystem code outside their cross-target
entry point.