Crate fs_err 

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`: 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);

Feature flags

• expose_original_error: when enabled, the Error::source() method of errors returned by this crate return the original io::Error. To avoid duplication in error messages, this also suppresses printing its message in their Display implementation, so make sure that you are printing the full error chain.
• debug: Debug filesystem errors faster by exposing more information. When a filesystem command fails, the error message might say “file does not exist.” But it won’t say why it doesn’t exist. Perhaps the programmer misspelled the filename, perhaps that directory doesn’t exist, or if it does, but the current user doesn’t have permissions to see the contents. This feature analyzes the filesystem to output various “facts” that will help a developer debug the root of the current error.
  • Warning: Exposes filesystem metadata. This feature exposes additional metadata about your filesystem such as directory contents and permissions, which may be sensitive. Only enable debug when error messages won’t be displayed to the end user, or they have access to filesystem metadata some other way.
  • Warning: This may slow down your program. This feature will trigger additional filesystem calls when errors occur, which may cause performance issues. Do not use if filesystem errors are common on a performance-sensitive “hotpath.” Use in scenarios where developer hours are more expensive than compute time.
  • To mitigate performance and security concerns, consider only enabling this feature in dev-dependencies:
  • Requires Rust 1.79 or later

[dev-dependencies]
fs-err = { features = ["debug"] }

To use with the tokio feature, use debug_tokio:

[dependencies]
fs-err = { features = ["debug_tokio", "tokio"] }

Minimum Supported Rust Version

The oldest rust version this crate is tested on is 1.40.

This crate will generally be conservative with rust version updates. It uses the autocfg crate to allow wrapping new APIs without incrementing the MSRV.

If the tokio feature is enabled, this crate will inherit the MSRV of the selected tokio version.

Modules

os

OS-specific functionality.

tokiotokio

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.

existsrustc_1_81

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

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.