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§
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. - Open
Options - Wrapper around
std::fs::OpenOptions
- ReadDir
- Wrapper around
std::fs::ReadDir
which adds more helpful information to all errors.
Traits§
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_
link Deprecated - 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.