std.fs

The file system: File, a handle on an open file that reads, writes and seeks through std.io's interfaces, opened as OpenOptions say; conveniences that read or write a file whole (readText, readBytes, writeText, writeBytes, appendText) or its lines one by one (lines); what a path names (Metadata, metadata, exists); directories and their entries (createDir, removeDir, readDir, DirEntry); and operations built from those — createDirAll, removeAll, copy, walk, tempDir, tempFile.

Where a scheduler runs, every call on a file runs on the program's I/O pool (std.io's): a few threads, started at the first use, do the system's call while the running task is parked, and the thread it runs on goes on with the other tasks; where no scheduler runs, the call runs on the thread itself. A call on a regular file ends in a bounded time and is not a point of cancellation: a cancellation is seen at the task's next wait. Reads and writes go through the caller's slice, never a copy.

Examples

import std.io { print, println, IoError };
import std.fs;
import std.path;

fn main(): void throws IoError {
    let dir = try fs.tempDir();
    let file = path.join(dir, "notes.txt");
    try fs.writeText(file, "first\nsecond\n");
    try fs.appendText(file, "third\n");
    print(try fs.readText(file));
    try fs.removeAll(dir);
    println(fs.exists(dir));
}

first
second
third
false

Types

OpenOptions struct — How a file is opened: to read, to write, to append at its end, created where it is not there, truncated to nothing where it is.

File class — An open file: read from its position, written there — at the end, where it was opened to append —, its position moved.

FileLinesIter class — The lines of a file, from lines.

Metadata struct — What a path names, through links: its size in bytes, when it was last written, whether it is a file or a directory — neither, for a device or a socket —, whether it cannot be written; and whether the path itself is a link.

DirEntry struct — An entry of a directory, from readDir: its name, its path — the directory's joined with the name —, and what the entry is itself: a link is reported as a link, not as what it leads to.

ReadDirIter class — A directory's entries, from readDir.

WalkIter class — The entries under a directory, from walk.

Functions

pub fn readText(path: StringView): string throws IoError

Returns the whole file at path as UTF-8 text. A byte order mark is kept as text like any other.

Errors

Throws IoError with the path: InvalidData for bytes that are not UTF-8, else the system's failure to open, read or close the file.

pub fn readBytes(path: StringView): uint8[] throws IoError

Returns the whole file at path as bytes.

Errors

Throws IoError with the path when the file cannot be opened, read or closed.

pub fn lines(path: StringView): FileLinesIter throws IoError

Returns an iterator over the lines of the file at path, as TextReader.readLine gives them: without their line ends, and a last line without an end still a line. The iterator closes the file at its end and at an error; a for that leaves it early closes it, and so does close().

Errors

Throws IoError with the path when the file cannot be opened.

pub fn writeText(path: StringView, text: StringView): void throws IoError

Writes text as the file at path, created where it is not there, truncated where it is.

Errors

Throws IoError with the path when the file cannot be created, written or closed.

pub fn writeBytes(path: StringView, bytes: Slice<uint8>): void throws IoError

Writes bytes as the file at path, created where it is not there, truncated where it is.

Errors

Throws IoError with the path when the file cannot be created, written or closed.

pub fn appendText(path: StringView, text: StringView): void throws IoError

Appends text to the end of the file at path, created where it is not there.

Errors

Throws IoError with the path when the file cannot be opened, written or closed.

pub fn metadata(path: StringView): Metadata throws IoError

Returns the Metadata of what path names, following links.

Errors

Throws IoError with the path: NotFound where nothing is there or a link leads nowhere, else the system's failure.

pub fn exists(path: StringView): bool

Returns whether path names anything — false where it cannot be told, and for a link that leads nowhere.

pub fn createDir(path: StringView): void throws IoError

Creates the directory path; its parent must exist.

Errors

Throws IoError with the path: AlreadyExists where something is there, NotFound where the parent is missing, else the system's failure.

pub fn remove(path: StringView): void throws IoError

Removes the file path; a directory is removed with removeDir.

Errors

Throws IoError with the path when the system cannot remove it.

pub fn removeDir(path: StringView): void throws IoError

Removes the directory path, which must be empty.

Errors

Throws IoError with the path when the system cannot remove it; a directory that is not empty is Other with the system's code, since no kind names it.

pub fn rename(from: StringView, to: StringView): void throws IoError

Renames from to to, replacing a file there. Both must be on the same file system.

Errors

Throws IoError with the source path when the system cannot rename it, including across file systems.

pub fn readDir(path: StringView): ReadDirIter throws IoError

Returns an iterator over the entries of the directory path, in the order the system keeps them; . and .. are not among them. The iterator holds the directory open: it releases it at its end and at its first error, a loop that leaves it early releases it, and so does close().

Errors

Throws IoError with the path when the directory cannot be opened.

pub fn canonicalize(path: StringView): string throws IoError

Returns path absolute, its links resolved and its . and .. removed: where the system says the file is.

Errors

Throws IoError with the path: NotFound where nothing is there, InvalidData for a result that is not UTF-8, else the system's failure.

pub fn absolute(path: StringView): string throws IoError

Returns path made absolute against the working directory, then normalized: nothing else is asked of the file system, and links in it stay.

Errors

Throws IoError with the path when the working directory cannot be read, or InvalidData for a result that is not UTF-8.

pub fn createDirAll(path: StringView): void throws IoError

Creates the directory path and every missing directory above it. Where path is already a directory there is nothing to do.

Errors

Throws IoError with the path: NotDirectory where path or a directory above it is something else, else the system's failure.

pub fn removeAll(path: StringView): void throws IoError

Removes path and everything in it: a link is removed, never followed into, and where nothing is there there is nothing to do. It removes all it can.

Errors

Throws the first IoError it met.

pub fn copy(from: StringView, to: StringView): int throws IoError

Copies the bytes of the file from to the file to — created, or truncated where it is there — and returns how many. Permissions and times are not copied.

Errors

Throws IoError with the source path: IsDirectory for a directory, InvalidInput for anything else that is not a file and for a copy onto itself — truncating would lose what it copies —, else the failure of opening, reading or writing.

pub fn walk(path: StringView): WalkIter throws IoError

Returns an iterator over the entries under path, depth first — a directory before what is in it —, each directory's entries in the byte order of their names; path itself is not among them, and links are not followed. Each directory is read whole and closed before its first entry is given, so the walk holds nothing open. An error ends the walk.

Errors

Throws IoError with the path when path cannot be read as a directory.

pub fn tempDir(): string throws IoError

Creates a new directory under the system's directory for temporary files and returns its path. Nothing removes it but removeAll. The system's directory itself is os.tempDir.

Errors

Throws IoError when the directory cannot be created, or after 100 random names that all existed already.

pub fn tempFile(): string throws IoError

Creates a new empty file under the system's directory for temporary files and returns its path, for File.openWith and the conveniences to take from there. Nothing removes it but remove.

Errors

Throws IoError when the file cannot be created or closed, or after 100 random names that all existed already.