Module fs 

The file system: files as File (std’s file in a Handle), OpenOptions, the calls by path (read, write, metadata, rename, copy, …), directories (create_dir_all, DirBuilder, read_dir streamed a page at a time) and links. Calls by path, and a regular file’s calls beside its reads, writes, syncs and Handle::allocate, run on the blocking pool; Handle::try_lock_file, which never waits, runs on the calling thread, and so does File::open on Linux for a regular file on a local file system whose path the kernel’s caches resolve at once.

A regular file’s reads and writes, at the handle’s own cursor or at an offset of the caller’s (Handle::read_at, Handle::write_at and their forms, which many tasks may make at once on one handle, and Handle::read_many_at, many reads in one call), its syncs (Handle::sync_all, Handle::sync_data, Handle::sync_range) and Handle::allocate are operations of the shard’s ring on io_uring and jobs of the blocking pool on the other backends (see file). A file opened for direct IO (O_DIRECT, FILE_FLAG_NO_BUFFERING) is read and written with exactly the caller’s lengths and offsets, never through the handle’s read-ahead or write-behind. A File that is not a regular file (a FIFO, a terminal, a pipe) is a byte stream the shard’s driver serves like a socket (on Windows, through the completion port, or through jobs of the blocking pool for a handle opened for synchronous IO). Reads and writes at the cursor are AsyncRead and AsyncWrite on the handle and on a shared reference to it (both share the cursor, as &File shares its offset); AsyncBufRead and AsyncSeek are on the handle. read_owned, write_owned, read_at_owned, write_at_owned and the vectored read_vectored_owned and write_vectored_owned take the caller’s buffers (any IoBuf or IoBufMut, an AlignedBuf for direct IO) and give them back, so the bytes are read into them and written from them with no copy.

Beside those, a regular file can be asked to change the space a range uses (Handle::allocate: reserve, keep the length, punch a hole, zero), to write a range back (Handle::sync_range), to copy a range into another file in the kernel where the system can (Handle::copy_range_to), and to take an advisory lock without blocking the worker (Handle::lock_file, Handle::try_lock_file, Handle::unlock_file).

A file’s name in its directory needs sync_dir to survive a crash. To replace a file atomically: write a temporary file in the same directory, sync_all it, rename it over the target, then sync_dir the directory.

Structs

DirBuilder

How to create a directory: recursively or not, and with which mode.

DirEntry

An entry of a directory.

FileTimes

Representation of the various timestamps on a file.

FileType

A structure representing a type of file with accessors for each file type. It is returned by Metadata::file_type method.

Metadata

Metadata information about a file.

OpenOptions

How to open a file: the options of std’s OpenOptions, opened on the blocking pool into a Handle.

Permissions

Representation of the various permissions on a file.

ReadDir

A directory’s entries, read a page at a time.

Enums

Allocate

How a call to File::allocate changes the space a range of a file uses.

TryLockError

An enumeration of possible errors which can occur while trying to acquire a lock from the try_lock method and try_lock_shared method on a File.

Functions

canonicalize

The absolute path of path, every link and .. resolved.

copy

Copies the file from to to, with its permissions; answers the bytes copied.

create_dir

Creates the directory path; its parent must exist.

create_dir_all

Creates the directory path and every missing parent.

hard_link

Makes link a new name of the file original (a hard link).

metadata

The metadata of what path names, through links.

read

The whole file at path.

read_dir

The entries of the directory at path, through ReadDir::next_entry or as a [Stream].

read_link

Where the symbolic link path points.

read_to_string

The whole file at path, which must be UTF-8.

remove_dir

Removes the empty directory at path.

remove_dir_all

Removes the directory at path and everything in it.

remove_file

Removes the file at path.

rename

Renames from to to, replacing to if it is a file.

set_permissions

Sets the permissions of what path names.

symlink

Makes link a symbolic link to original.

symlink_metadata

The metadata of what path names, a link itself rather than its target.

sync_dir

Writes the entries of the directory at path through to the device: the names created, removed or renamed in it before the call survive a crash. A file’s own sync_all does not cover its name in the directory, so the name needs this call. It runs on the blocking pool.

try_exists

Whether path names something: Ok(false) when it does not, an error when that cannot be told (no permission, for one).

write

Writes contents as the whole file at path, creating it or cutting it down first.

Type Aliases

File

A file: std’s File in a Handle, with async reads, writes, seeks and calls.