Module `std::fs`

Files as an effect: code reaches the file system only through an Fs capability in its row, and only beneath the directory descriptors it is handed: every path is resolved beneath a dir: &Fd, and an absolute one or a .. that would leave it fails EXDEV (18). The root hands a program its first directory, cwd, and the program hands it on. Paths are bytes (&[u8]). Errors are the kernel's errno values (Err(Int)).

A descriptor is a bare linear Fd: Fs::close consumes it and answers the error closing reports (a write the disk refused); there is no File whose drop would have to lose it. Install Blocking (one system call per op) or Evented (ops on the root's reactor); std::net::Net's executors serve Fs too, and a test uses std::memfs::MemFs. A bare with Fs is Fs portable migrates cross, the bound under which a function runs under each.

Source: std/fs.weir; committed interface: std/fs.iface. Index

const READ: Fs::open flag: open for reading.
const WRITE: Fs::open flag: open for writing.
const CREATE: Fs::open flag: create the file if missing (needs WRITE).
const TRUNC: Fs::open flag: truncate the file to empty (needs WRITE).
const EXCL: Fs::open flag: with CREATE, the file must not exist yet.
const DIR: Fs::open flag: open a directory (with nothing else but READ); flags not combined as these docs say are EINVAL (22).
effect Fs: The file operations, each a once op answering Err(errno) on failure; an executor may park the task while the op runs. Every path is resolved beneath its dir.
fn cwd: The process's working directory, opened as a directory: the root's first directory, from which a program reaches every file it may. Needs the root's Sys, so main calls it.
fn preopen: The directory the root was handed under name (weir run --dir <path>:<name>, a native binary's --dir), opened anew. A name it was not handed is ENOENT (2), as is every name in the simulated world.
handler Blocking: The blocking executor: each op is one system call on the calling thread. Install it as with Blocking { … } where the root's Sys is in scope (main).
handler Evented: The completion executor: each op is submitted to the root's reactor and the body parks until it completes, so a file op never blocks a worker's loop. Install it as with Evented(slots()) { … } (needs Reactor); slots() is its table. The with body is its one strand: there are no tasks, so at most one op is in flight.
fn read_all: The whole of the file path beneath dir (with Alloc for the buffer). The read's error comes first, then the close's.
fn write_all: Makes path beneath dir hold exactly data, creating it if missing. The write's error comes first, then the close's, which reports what the device refused after accepting the write; a write that makes no progress is EIO (5).
fn names: The names in the directory dir but . and .., sorted bytewise, each its own Buf.

const `READ`

pub const READ: Int = 1;

Fs::open flag: open for reading.

const `WRITE`

pub const WRITE: Int = 2;

Fs::open flag: open for writing.

const `CREATE`

pub const CREATE: Int = 4;

Fs::open flag: create the file if missing (needs WRITE).

const `TRUNC`

pub const TRUNC: Int = 8;

Fs::open flag: truncate the file to empty (needs WRITE).

const `EXCL`

pub const EXCL: Int = 16;

Fs::open flag: with CREATE, the file must not exist yet.

const `DIR`

pub const DIR: Int = 32;

Fs::open flag: open a directory (with nothing else but READ); flags not combined as these docs say are EINVAL (22).

effect `Fs`

pub effect Fs default portable migrates cross {
    once fn open(dir: &Fd, path: &[u8], flags: Int) -> Result<Fd, Int>;
    once fn read_at(f: &Fd, b: &mut [u8], off: usize) -> Result<usize, Int>;
    once fn write_at(f: &Fd, b: &[u8], off: usize) -> Result<usize, Int>;
    once fn sync(f: &Fd) -> Result<Unit, Int>;
    once fn size(f: &Fd) -> Result<usize, Int>;
    once fn mkdir(dir: &Fd, path: &[u8]) -> Result<Unit, Int>;
    once fn remove(dir: &Fd, path: &[u8]) -> Result<Unit, Int>;
    once fn rename(dir: &Fd, from: &[u8], to: &[u8]) -> Result<Unit, Int>;
    once fn list(dir: &Fd, b: &mut [u8], at: usize) -> Result<usize, Int>;
    linear fn close(fd: Fd) -> Result<Unit, Int>;
}

The file operations, each a once op answering Err(errno) on failure; an executor may park the task while the op runs. Every path is resolved beneath its dir.