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`
    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.
• 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.
• 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.