Crate fs_err

Source
Expand description

fs-err is a drop-in replacement for std::fs that provides more helpful messages on errors. Extra information includes which operations was attempted and any involved paths.

§Error Messages

Using std::fs, if this code fails:

let file = File::open("does not exist.txt")?;

The error message that Rust gives you isn’t very useful:

The system cannot find the file specified. (os error 2)

…but if we use fs-err instead, our error contains more actionable information:

failed to open file `does not exist.txt`
    caused by: The system cannot find the file specified. (os error 2)

§Usage

fs-err’s API is the same as std::fs, so migrating code to use it is easy.

// use std::fs;
use fs_err as fs;

let contents = fs::read_to_string("foo.txt")?;

println!("Read foo.txt: {}", contents);

fs-err uses std::io::Error for all errors. This helps fs-err compose well with traits from the standard library like std::io::Read and crates that use them like serde_json:

use fs_err::File;

let file = File::open("my-config.json")?;

// If an I/O error occurs inside serde_json, the error will include a file path
// as well as what operation was being performed.
let decoded: Vec<String> = serde_json::from_reader(file)?;

println!("Program config: {:?}", decoded);

Modules§

os
OS-specific functionality.
tokio
Tokio-specific wrappers that use fs_err error messages.

Structs§

DirEntry
Wrapper around std::fs::DirEntry which adds more helpful information to all errors.
File
Wrapper around std::fs::File which adds more helpful information to all errors.
OpenOptions
Wrapper around std::fs::OpenOptions
ReadDir
Wrapper around std::fs::ReadDir which adds more helpful information to all errors.

Traits§

PathExt
Defines aliases on Path for fs_err functions.

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.
create_dir
Creates a new, empty directory at the provided path.
create_dir_all
Recursively create 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, query the file system to get information about a file, directory, etc.
read
Read the entire contents of a file into a bytes vector.
read_dir
Returns an iterator over the entries within a directory.
read_link
Reads a symbolic link, returning the file that the link points to.
read_to_string
Read the entire contents of a file into a string.
remove_dir
Removes an 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
Rename 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.
soft_linkDeprecated
Wrapper for fs::soft_link.
symlink_metadata
Query the metadata about a file without following symlinks.
write
Write a slice as the entire contents of a file.