Module fs

Available on crate feature fs only.

Asynchronous file and standard stream adaptation.

This module contains utility methods and adapter types for input/output to files or standard streams (Stdin, Stdout, Stderr), and filesystem manipulation, for use within (and only within) a Tokio runtime.

Tasks run by worker threads should not block, as this could delay servicing reactor events. Portable filesystem operations are blocking, however. This module offers adapters which use a blocking annotation to inform the runtime that a blocking operation is required. When necessary, this allows the runtime to convert the current thread from a worker to a backup thread, where blocking is acceptable.

Usage

Where possible, users should prefer the provided asynchronous-specific traits such as AsyncRead, or methods returning a Future or Poll type. Adaptions also extend to traits like std::io::Read where methods return std::io::Result. Be warned that these adapted methods may return std::io::ErrorKind::WouldBlock if a worker thread can not be converted to a backup thread immediately.

Warning: These adapters may create a large number of temporary tasks, especially when reading large files. When performing a lot of operations in one batch, it may be significantly faster to use spawn_blocking directly:

use tokio::fs::File;
use std::io::{BufReader, BufRead};
async fn count_lines(file: File) -> Result<usize, std::io::Error> {
    let file = file.into_std().await;
    tokio::task::spawn_blocking(move || {
        let line_count = BufReader::new(file).lines().count();
        Ok(line_count)
    }).await?
}

Structs

DirBuilder

A builder for creating directories in various manners.

DirEntry

Entries returned by the ReadDir stream.

File

A reference to an open file on the filesystem.

OpenOptions

Options and flags which can be used to configure how a file is opened.

ReadDir

Reads the entries in a directory.

Functions

canonicalize

Returns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.

copy

Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file. This function will overwrite the contents of to.

create_dir

Creates a new, empty directory at the provided path.

create_dir_all

Recursively creates a directory and all of its parent components if they are missing.

hard_link

Creates a new hard link on the filesystem.

metadata

Given a path, queries the file system to get information about a file, directory, etc.

read

Reads the entire contents of a file into a bytes vector.

read_dir

Returns a stream over the entries within a directory.

read_link

Reads a symbolic link, returning the file that the link points to.

read_to_string

Creates a future which will open a file for reading and read the entire contents into a string and return said string.

remove_dir

Removes an existing, empty directory.

remove_dir_all

Removes a directory at this path, after removing all its contents. Use carefully!

remove_file

Removes a file from the filesystem.

rename

Renames a file or directory to a new name, replacing the original file if to already exists.

set_permissions

Changes the permissions found on a file or a directory.

symlinkUnix

Creates a new symbolic link on the filesystem.

symlink_dirWindows

Creates a new directory symlink on the filesystem.

symlink_fileWindows

Creates a new file symbolic link on the filesystem.

symlink_metadata

Queries the file system metadata for a path.

try_exists

Returns Ok(true) if the path points at an existing entity.

write

Creates a future that will open a file for writing and write the entire contents of contents to it.