std/fs

Types

Files

@unsafeGuarantee(Copy, Send, Sync)
pub type Files

File system access, obtained from host.files(). Safety: a stateless capability marker; every call it makes is independent, so sharing or duplicating it is free.

Files.writeText

pub fn Files.writeText(self, path: Path, text: String) -> Void!

Creates or truncates the file at path and writes text into it; loops over File.write's short writes to send all of it (std/io's writeAll law).

Files.create

pub fn Files.create(self, path: Path) -> File!

Creates the file at path, truncating an existing one, and opens it for writing.

Files.append

pub fn Files.append(self, path: Path) -> File!

Opens the file at path for writing at its end, creating it when missing; unlike create it never truncates, so a redirected /dev/stdout keeps its content.

Files.createWithMode

pub fn Files.createWithMode(self, path: Path, mode: u32) -> File!

Creates the file at path like create, with permission bits mode (before the umask is applied), for example 0o600 for a file only its owner can read.

Files.remove

pub fn Files.remove(self, path: Path) -> Void!

Deletes the file at path; a directory is an error, removeDir deletes an empty one.

Files.removeDir

pub fn Files.removeDir(self, path: Path) -> Void!

Deletes the empty directory at path.

Files.read

pub fn Files.read(self, path: Path) -> String!

Whole file as UTF-8 text; fails when the file is missing, longer than defaultReadLimit bytes or not valid UTF-8.

Files.readBytes

pub fn Files.readBytes(self, path: Path) -> Bytes!

Whole file as bytes; fails when it is longer than defaultReadLimit bytes.

Files.readBytesUpTo

pub fn Files.readBytesUpTo(self, path: Path, limit: usize) -> Bytes!

Whole file as bytes; fails once it turns out to hold more than limit bytes, so a device such as /dev/zero cannot exhaust memory.

Files.mkdir

pub fn Files.mkdir(self, path: Path) -> Void!

Creates the directory at path and any missing parents; an existing directory is fine, an existing file is an error.

Files.exists

pub fn Files.exists(self, path: Path) -> Bool

Whether something exists at path.

Files.list

pub fn Files.list(self, path: Path) -> Array[Path]!

Paths of the entries directly inside the directory at path, sorted by name.

Files.open

pub fn Files.open(self, path: Path) -> File!

Opens the existing file at path for reading; read it with File.read, or wrap it in an io.BufReader to read line by line.

Path

pub type Path = {
    // private fields omitted
}

Validated file system path.

Path.fromString

pub pure fn Path.fromString(s: String) -> Path!

Parses s as a path; fails when it contains a NUL byte.

Path.fromOsString

pub pure fn Path.fromOsString(s: &os.OsString) -> Path!

Parses an OS string as a path; fails when it contains a NUL byte, and when it is not valid UTF-8 because a Path holds text.

Path.toString

pub pure noalloc fn Path.toString(self) -> String

The path as text.

File

pub type File = resource {
    // private fields omitted
}

Open file, from Files.open (read) or Files.create / Files.append (write); close it explicitly or let the drop close it.

File.write

pub fn File.write(mut self, data: Bytes) -> usize!

Writes data to the file; may write fewer bytes than given (a short write), matching std/io's Writer (writeAll loops for the rest).

File.close

pub fn File.close(move self) -> Void!

Flushes the file and reports any error; the drop then closes it.

File.drop

pub fn File.drop(move self)

Closes the file when it goes out of scope, ignoring errors.

File.read

pub fn File.read(mut self, into: &mut Array[u8], max: usize) -> usize!

Appends up to max bytes read from the file to into and returns how many; 0 means end of file (std/io's Reader).

Constants

defaultReadLimit

pub const defaultReadLimit: usize = 268435456

The most bytes Files.read and Files.readBytes load; Files.readBytesUpTo takes another limit.