Adding `fs_err` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add fs-err

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

fs-err = "3.0.0"

The fs_err library will be automatically available globally. Read the fs_err library documentation.

Back to the crate overview.

Readme

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.

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.

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Adding fs_err library as a dependency

Adding `fs_err` library as a dependency