File System

A unified API for Files, Pipes, and Streams.

Concept & Motivation

Standard C file handling (fopen, fread) is inconsistent. It requires manual resource management (remembering to fclose) and behaves unpredictably with non-seekable streams like Pipes or Sockets.

Camelot's FS module introduces "Slurping" (atomic reads) and a Unified Dispatcher that abstracts away the differences between static files and streams.

---

API Reference

io.slurp

Reads an entire file into a single String buffer.

String slurp(Arena *a, const char *path);

• Atomic: Opens, reads, and closes the file in one operation.

• Safety: Automatically releases the file handle, even if the read fails or the file doesn't exist.

• Memory: Allocates exactly the file size + 1 byte (for null termination) on the Arena.

String config = io.slurp(&arena, "settings.ini");

io.stream

A Unified Dispatcher for low-level file operations.

u64 stream(File *f, Op op, void *arg, u64 num);

Use this for chunked reading or manual stream control.

• Op Codes: OPEN, READ, SKIP, CLOSE.

Warning

Unlike slurp, this function does not auto-close. You must explicitly call CLOSE to prevent resource leaks.

Example

File f = {0};
if (io.stream(&f, OPEN, "data.bin", 0)) {
    io.stream(&f, READ, buffer, 1024);
    io.stream(&f, CLOSE, NULL, 0);
}