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 open_failure_kind(path: string): error.ErrorKind

Classifies a failed fopen() for path: NotFound if the path doesn't exist at all, IoError for any other reason (e.g. permission denied, or a non-directory component in the path).

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 delete_failure_kind(path: string): error.ErrorKind

Classifies a failed deleteFile for path: NotFound if the path doesn't exist, IoError for any other reason (e.g. permission denied on the parent directory, or path names a non-empty directory). Mirrors fs.ops.remove_file_failure_kind exactly.

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_failure_kind(old_path: string): error.ErrorKind

Classifies a failed rename: NotFound if old_path doesn't exist, IoError for any other reason (e.g. cross-device rename, missing parent directory for new_path, permission denied).

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 doesn't exist, Err(IoError) for any other failure. Also exposed as fs.ops.rename for filesystem-tree operations.

fn fsync_failure_kind(path: string): error.ErrorKind

Classifies a failed fsync/fsync_parent for path: NotFound if path doesn't exist, IoError for any other reason (e.g. permission denied, or — for fsync_parent — the containing directory cannot be opened).

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