Module

std::fs

Filesystem

Filesystem operations with structured error handling.

All fallible operations return Result<T, Io::IoError> instead of raw errno codes. Import Io alongside Fs to inspect errors.

Module Tree

std::fs                     (this file — hub, re-exports Fs namespace)
  std::fs::sys::mod         (platform dispatch layer)
    std::fs::sys::unix      (POSIX syscall wrappers — Linux/glibc)

Sub-namespaces

Namespace	Description
`Fs::Sys`	Platform syscall wrappers (selected at compile time)

Types

Type	Description
`Fs::Sys::Stat`	File metadata from `stat(2)` / `fstat(2)`
`Fs::Sys::SysDirEntry`	Single directory entry from `readdir(3)`

Constants

Open flags, seek modes, permission bits, and dirent type constants are available under Fs::Sys. See sys/unix.ign for the full list.

Platform

Currently Linux and macOS (POSIX). The Fs::Sys layer is designed so future targets can add sibling backend modules and the dispatch hub (sys/mod.ign) selects at compile time via @configFlag.

Example

import Fs from "std::fs";
import Io from "std::io";

function main(): i32 {
  // stat a file
  let result: Result<Fs::Sys::Stat, Io::IoError> =
    Fs::Sys::stat("/etc/hosts");

  if result.isOk() {
    let st: Fs::Sys::Stat = result.unwrap();
    // st.size, st.mode, st.uid, st.gid, ...
    return 0;
  }
  return 1;
}

import Fs from "std::fs";
import Io from "std::io";

function main(): i32 {
  // write a file
  let fd: Result<i32, Io::IoError> = Fs::Sys::open(
    "/tmp/hello.txt",
    Fs::Sys::O_WRONLY | Fs::Sys::O_CREAT | Fs::Sys::O_TRUNC,
    438,
  );
  if fd.isError() { return 1; }

  let rawFd: i32 = fd.unwrap();
  let msg: *u8 = "hello\n";
  Fs::Sys::write(rawFd, msg as *mut void, 6);
  Fs::Sys::close(rawFd);
  return 0;
}

namespace Fs

Filesystem convenience APIs built on Fs::Sys and safe owned path handling.

Overloads accepting owned String or Path::PathBuf reject interior NULs before crossing into C APIs. Raw str overloads preserve C-string semantics and may stop at the first NUL byte.

Functions

function canonicalize(path: &PathBuf): Result<PathBuf, IoError>

Canonicalizes a PathBuf after path validation.

function canonicalize(path: &PathBuf): Result<PathBuf, IoError>

Canonicalizes a PathBuf after path validation.

function canonicalize(path: &PathBuf): Result<PathBuf, IoError>

Canonicalizes a PathBuf after path validation.

function canonicalizeRaw(path: str): Result<PathBuf, IoError>

Returns the canonical absolute path for an existing filesystem entry.

function createDir(path: &PathBuf, mode: i32): Result<void, IoError>

Creates a single directory for a PathBuf using an i32 mode.

function createDir(path: &PathBuf, mode: i32): Result<void, IoError>

Creates a single directory for a PathBuf using an i32 mode.

function createDir(path: &PathBuf, mode: i32): Result<void, IoError>

Creates a single directory for a PathBuf using an i32 mode.

function createDir(path: &PathBuf, mode: i32): Result<void, IoError>

Creates a single directory for a PathBuf using an i32 mode.

function createDir(path: &PathBuf, mode: i32): Result<void, IoError>

Creates a single directory for a PathBuf using an i32 mode.

function createDir(path: &PathBuf, mode: i32): Result<void, IoError>

Creates a single directory for a PathBuf using an i32 mode.

function createDirAll(path: &PathBuf): Result<void, IoError>

Recursively creates directories for a PathBuf.

function createDirAll(path: &PathBuf): Result<void, IoError>

Recursively creates directories for a PathBuf.

function createDirAll(path: &PathBuf): Result<void, IoError>

Recursively creates directories for a PathBuf.

function createDirAllRaw(path: str): Result<void, IoError>

Recursively creates directories for path (mkdir -p behavior).

function createDirRaw(path: str, mode: u32): Result<void, IoError>

Creates a single directory.

function exists(path: str): boolean

Returns true when path exists.

function invalidPathError(): IoError

Builds the standard invalid-path error used for interior-NUL path inputs.

function metadata(path: &PathBuf): Result<Metadata, IoError>

Reads metadata for a PathBuf after path validation.

function metadata(path: &PathBuf): Result<Metadata, IoError>

Reads metadata for a PathBuf after path validation.

function metadata(path: &PathBuf): Result<Metadata, IoError>

Reads metadata for a PathBuf after path validation.

function metadataRaw(path: str): Result<Metadata, IoError>

Reads raw metadata from a C-string path.

function read(path: &PathBuf): Result<Vector<u8>, IoError>

Reads a PathBuf into bytes after validating C-string safety.

function read(path: &PathBuf): Result<Vector<u8>, IoError>

Reads a PathBuf into bytes after validating C-string safety.

function read(path: &PathBuf): Result<Vector<u8>, IoError>

Reads a PathBuf into bytes after validating C-string safety.

function readRaw(path: str): Result<Vector<u8>, IoError>

Reads a raw C-string path into bytes with buffered file reads.

function readToBytes(path: &PathBuf): Result<Vector<u8>, IoError>

Alias for read(&PathBuf).

function readToBytes(path: &PathBuf): Result<Vector<u8>, IoError>

Alias for read(&PathBuf).

function readToBytes(path: &PathBuf): Result<Vector<u8>, IoError>

Alias for read(&PathBuf).

function readToString(path: &PathBuf): Result<String, IoError>

Reads a PathBuf into an owned String after path validation.

function readToString(path: &PathBuf): Result<String, IoError>

Reads a PathBuf into an owned String after path validation.

function readToString(path: &PathBuf): Result<String, IoError>

Reads a PathBuf into an owned String after path validation.

function readToStringBytes(bytes: Vector<u8>): Result<String, IoError>

Converts a byte vector into an owned String, preserving interior NULs.

function removeDir(path: &PathBuf): Result<void, IoError>

Removes an empty directory at a PathBuf.

function removeDir(path: &PathBuf): Result<void, IoError>

Removes an empty directory at a PathBuf.

function removeDir(path: &PathBuf): Result<void, IoError>

Removes an empty directory at a PathBuf.

function removeDirAll(path: &PathBuf): Result<void, IoError>

Recursively removes a directory tree at a PathBuf.

function removeDirAll(path: &PathBuf): Result<void, IoError>

Recursively removes a directory tree at a PathBuf.

function removeDirAll(path: &PathBuf): Result<void, IoError>

Recursively removes a directory tree at a PathBuf.

function removeDirAllRaw(path: str): Result<void, IoError>

Removes a directory tree without following symlink directories.

function removeDirRaw(path: str): Result<void, IoError>

Removes an empty directory.

function removeFile(path: &PathBuf): Result<void, IoError>

Removes a file at a PathBuf.

function removeFile(path: &PathBuf): Result<void, IoError>

Removes a file at a PathBuf.

function removeFile(path: &PathBuf): Result<void, IoError>

Removes a file at a PathBuf.

function removeFileRaw(path: str): Result<void, IoError>

Removes a file.

function tempDir(): Result<PathBuf, IoError>

Returns the host temporary-directory root.

function validatedPath(path: &PathBuf): Result<CString, IoError>

Converts a PathBuf to CString, rejecting interior NUL bytes.

function validatedPath(path: &PathBuf): Result<CString, IoError>

Converts a PathBuf to CString, rejecting interior NUL bytes.

function walk(path: &PathBuf): Result<Vector<String>, IoError>

Walks a PathBuf after path validation.

function walk(path: &PathBuf): Result<Vector<String>, IoError>

Walks a PathBuf after path validation.

function walk(path: &PathBuf): Result<Vector<String>, IoError>

Walks a PathBuf after path validation.

function walkRaw(path: str): Result<Vector<String>, IoError>

Returns a depth-first directory walker that treats symlinks as leaves.

function write(path: &PathBuf, text: str): Result<void, IoError>

Writes a NUL-terminated text view to a PathBuf.

function write(path: &PathBuf, text: str): Result<void, IoError>

Writes a NUL-terminated text view to a PathBuf.

function write(path: &PathBuf, text: str): Result<void, IoError>

Writes a NUL-terminated text view to a PathBuf.

function write(path: &PathBuf, text: str): Result<void, IoError>

Writes a NUL-terminated text view to a PathBuf.

function write(path: &PathBuf, text: str): Result<void, IoError>

Writes a NUL-terminated text view to a PathBuf.

function write(path: &PathBuf, text: str): Result<void, IoError>

Writes a NUL-terminated text view to a PathBuf.

function writeBytes(path: &PathBuf, data: *void, len: u64): Result<void, IoError>

Writes raw bytes to a PathBuf after path validation.

function writeBytes(path: &PathBuf, data: *void, len: u64): Result<void, IoError>

Writes raw bytes to a PathBuf after path validation.

function writeBytes(path: &PathBuf, data: *void, len: u64): Result<void, IoError>

Writes raw bytes to a PathBuf after path validation.

function writeBytesRaw(path: str, data: *void, len: u64): Result<void, IoError>

Creates/truncates a file and writes all bytes from data.

function writeString(path: &PathBuf, s: &String): Result<void, IoError>

Writes all bytes from an owned string to a PathBuf.

function writeString(path: &PathBuf, s: &String): Result<void, IoError>

Writes all bytes from an owned string to a PathBuf.

function writeString(path: &PathBuf, s: &String): Result<void, IoError>

Writes all bytes from an owned string to a PathBuf.

Constants

const DEFAULT_CREATE_DIR_MODE: u32