Module: io.file

Source: ./io/file.reef

Overview

io/file - File input/output operations

Provides functions for reading from and writing to files

Functions

fn fileExists(path: string): bool

Checks if a file exists

fn readFile(path: string): result.Result[string, error.Error]

Reads entire file contents into a string. Ok(content) on success — content is "" for a genuinely empty file, which is NOT an error. Err(NotFound) if the path does not exist, Err(IoError) if it exists but cannot be opened for reading.

fn writeFile(path: string, content: string): result.Result[bool, error.Error]

Writes content to a file (overwrites if exists). Ok(true) on success. Err(IoError) if the file cannot be opened for writing, or if the write is short (not all bytes were written).

fn appendFile(path: string, content: string): result.Result[bool, error.Error]

Appends content to a file (creates if doesn't exist). Ok(true) on success. Err(IoError) if the file cannot be opened for appending, or if the write is short (not all bytes were written).

fn fileSize(path: string): result.Result[int64, error.Error]

Gets the size of a file in bytes as int64 (file sizes can exceed 2^31 bytes). Delegates to fs.stat.file_size: Ok(size) on success, Err(NotFound) if the path does not exist, Err(IoError) otherwise.

fn readBinaryFile(path: string): result.Result[[uint8], error.Error]

Reads entire file as binary data (handles null bytes). Ok(data) on success — data is empty for a genuinely empty file, which is NOT an error. Err(NotFound) if the path does not exist, Err(IoError) if it exists but cannot be opened for reading.

fn writeBinaryFile(path: string, data: [uint8]): result.Result[bool, error.Error]

Writes binary data to a file (overwrites if exists). Ok(true) on success. Err(IoError) if the file cannot be opened for writing, or if the write is short.

fn appendBinaryFile(path: string, data: [uint8]): result.Result[bool, error.Error]

Appends binary data to a file (creates if doesn't exist). Ok(true) on success. Err(IoError) if the file cannot be opened for appending, or if the write is short.

fn appendBinaryChunk(path: string, data: [uint8], length: int): result.Result[bool, error.Error]

Appends a chunk of binary data to a file (for streaming downloads). Only writes the first 'length' bytes from the data array. Ok(true) on success. Err(IoError) if the file cannot be opened for appending, or if the write is short.

fn deleteFile(path: string): result.Result[bool, error.Error]

Deletes a file. Ok(true) on success. Err(NotFound) if path doesn't exist, Err(IoError) for any other failure.

fn rename(old_path: string, new_path: string): result.Result[bool, error.Error]

Renames (moves) a file. Ok(true) on success. Err(NotFound) if old_path does not exist, Err(IoError) for any other failure.

C4 / ROADMAP 8.2a: this used to be a second INDEPENDENT body with the same Ok/Err contract as fs.ops.rename, and both files carried a comment saying so. Two names for one operation is fine -- io.file is the file API and fs.ops is the tree API -- but two bodies is how the contracts drift apart. There is exactly one body now, and it is fs.ops.rename's.

fn fsync(path: string): result.Result[bool, error.Error]

Forces file contents to disk via fsync(). Ok(true) on success. Err(NotFound) if path doesn't exist, Err(IoError) for any other failure.

This fsyncs the file's data only, not its directory entry. For full crash-safe atomic writes use the recipe: writeFile(tmp) -> fsync(tmp) -> rename(tmp, dst) -> fsync_parent(dst) The trailing fsync_parent makes the rename durable across power loss.

fn fsync_parent(path: string): result.Result[bool, error.Error]

Fsyncs the directory containing path. Required for full crash-safe atomic writes — without it, a rename's directory entry can be lost on power loss even after the file's data is on disk. The file at path does not need to exist; only its containing directory does.

Ok(true) on success. Err(NotFound) if path doesn't exist (the common cause being that its containing directory doesn't exist either), Err(IoError) if the parent directory cannot be opened for any other reason.

Generated by reefc doc