Module: fs.ops

Source: ./fs/ops.reef

Overview

fs/ops - File copy, remove, and rename operations

Provides native file operations that replace common shell-outs (cp, cp -p, rm -f, rm -rf, mv). All functions return Result[bool, error.Error]: Ok(true) on success (the void-success convention — never Ok(false)).

copy_file/copy_file_preserve/copy_symlink classify failures via the exists()-recheck idiom on src (NotFound), plus a writability recheck on dst when it already exists (PermissionDenied, using the same access()-based primitive as fs.perm.is_writable); anything else is IoError (missing parent directory for dst, disk full, unsupported filesystem, etc.).

remove_file classifies via exists()-recheck on path: NotFound if it doesn't exist, IoError for any other reason.

rename classifies via exists()-recheck on old_path: NotFound if it doesn't exist, IoError for any other reason. Also exposed as io.file.rename, which mirrors this exact Ok/Err contract with its own independent body (no delegation between the two).

remove_tree returns Err(InvalidInput) when path is refused as a dangerous removal target (bare "/" or fewer than 2 path components) — classified in Reef before the call so callers can tell "you asked for something dangerous" apart from "the disk operation failed". The C runtime enforces the same refusal regardless of this classification (fail-safe); otherwise Err(IoError) for any other removal failure.

copy_tree returns Err(IoError) for any failure — the underlying recursive C copy collapses all failure causes to a single nonzero return, so no finer classification is available.

Functions

fn copy_failure_kind(src: string, dst: string): error.ErrorKind

Classifies a copy failure for src -> dst: NotFound if src doesn't exist (the exists()-recheck idiom), PermissionDenied if dst already exists but isn't writable (checkable via access(), the same primitive fs.perm.is_writable uses), IoError for any other reason (missing parent directory for dst, disk full, unsupported filesystem, etc.).

fn copy_file(src: string, dst: string): result.Result[bool, error.Error]

Copy a file (content only, default permissions). Ok(true) on success. See module doc comment for the Err classification.

fn copy_file_preserve(src: string, dst: string): result.Result[bool, error.Error]

Copy a file preserving permissions (like cp -p). Same Ok/Err contract as copy_file.

fn copy_symlink(src: string, dst: string): result.Result[bool, error.Error]

Copy a symlink without dereferencing (like cp -pP on a symlink). Same Ok/Err contract as copy_file.

fn remove_file_failure_kind(path: string): error.ErrorKind

Classifies a remove_file failure 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).

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

Remove a single file (like rm -f). 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 rename failure: 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]

Rename/move a file or directory. Ok(true) on success. Err(NotFound) if old_path doesn't exist, Err(IoError) for any other failure. Also exposed as io.file.rename — same shape/Ok-Err contract, independent body (no delegation between the two).

fn path_unsafe_to_remove(path: string): bool

Replicates reef_fs_path_is_safe (reef-runtime/src/reef_fs.c:356) for error CLASSIFICATION only: it decides whether remove_tree's refusal to touch a dangerous path should surface as Err(InvalidInput) rather than Err(IoError). The C guard is the real (fail-safe) enforcement of the safety rule regardless of what this function returns — a future drift between the two predicates would be a classification imprecision, not a safety hole. Keep them in sync anyway.

Unsafe if: path is empty, is the bare string "/", or splits into fewer than 2 non-empty "/"-separated components (e.g. "some/dir" and "/tmp/foo" are safe; "/" and "relative_single" are not).

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

Recursively remove a directory and all its contents (like rm -rf). Ok(true) on success. Err(InvalidInput) if path is refused as a dangerous removal target (bare "/" or fewer than 2 path components) — see path_unsafe_to_remove's comment for why this check is duplicated in Reef. Err(IoError) for any other removal failure.

fn copy_tree(src: string, dst: string): result.Result[bool, error.Error]

Recursively copy a directory tree preserving permissions and symlinks. Ok(true) on success. Err(IoError) for any failure — the underlying recursive C copy collapses all failure causes into a single nonzero return, so no finer classification (e.g. NotFound) is available here.

Generated by reefc doc