Skip to content
Tutorials Center
My learning

Topics

Lesson 87 of 132 ยท Standard Library Tour

Files and the Filesystem

Read and write files in Rust with std::fs, File, BufReader and BufWriter, Path and PathBuf, OpenOptions, io::Error kinds, and a recursive directory walk, all runnable.

Programs keep data in files: configuration, logs, caches, documents, exports. Rust's std::fs module gives you everything for that without any crate: one-line helpers for small files, a File type with buffered readers and writers for big ones, Path and PathBuf for names, and a rich io::Error type that tells you why something failed.

Every function that touches the disk can fail (the file may not exist, be locked, or be unreadable), so everything returns io::Result<T>, a shortcut for Result<T, std::io::Error>. You already know how to handle those with Result and the ? operator. This lesson shows the whole toolbox in order: whole-file helpers, paths, streaming with buffers, finer control with OpenOptions, error kinds, and walking directories. The next lesson looks at the Read and Write traits behind it all.

In our editor, a program runs on a server in a scratch folder. Files you create really exist during the run, but disappear afterwards, and you can only use relative paths in the current directory. Every example below creates its own small folder, works in it, and removes it at the end, so it is safe to run again and again. On your own machine, the same code works with any path you are allowed to access.

Whole files in one call

For small files, three functions do the job. fs::write creates (or replaces) a file with the given bytes or text, fs::read_to_string reads a whole text file into a String, and fs::read reads raw bytes into a Vec<u8>.

Rust write, read_to_string and read

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

main returns io::Result<()>, so every ? that fails ends the program with an error message instead of a panic. fs::exists (Rust 1.81) returns a Result<bool>: Ok(false) for a missing file, and an Err only when it cannot tell, for example because of permissions. Older code uses Path::exists, which swallows those errors and returns false.

fs::write truncates an existing file before writing. If the program crashes in the middle, you can be left with a half-written file. For important data, use the write to a temporary file, then fs::rename pattern shown near the end of this lesson. Also, read_to_string loads the whole file into memory; for a 10 GB log, stream it with BufReader instead.

When it goes wrong: io::Error

An io::Error has a kind() (an ErrorKind enum such as NotFound, PermissionDenied, AlreadyExists, InvalidData) and a message from the operating system. Match on the kind when you want to react differently, for instance to treat "file not found" as "use the defaults".

Rust Matching on ErrorKind

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The two messages to remember are No such file or directory (os error 2) for NotFound and stream did not contain valid UTF-8 for InvalidData. If you simply unwrap() an error, you get the Debug form, which is long and unfriendly:

Rust unwrap on a missing file (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The panic message reads called Result::unwrap()on anErr value: Os { code: 2, kind: NotFound, message: "No such file or directory" }. In real programs, return the error with ? (as in the previous example) or wrap it with context using map_err, so that the user sees which file failed. A bare "No such file or directory" without a file name is one of the most frustrating error messages there is; see error handling design.

Paths: Path and PathBuf

File names are not plain Strings. Operating systems allow file names that are not valid UTF-8 (on Unix, any bytes except / and NUL), and use different separators (/ on Linux and macOS, \ on Windows). So std has dedicated types, which mirror str/String:

  • &Path is a borrowed path (like &str).
  • PathBuf is an owned, growable path (like String).

Most functions accept impl AsRef<Path>, so you can pass a &str, a String, a &Path or a PathBuf. Path manipulation itself is purely text work and never touches the disk, so it runs anywhere:

Rust Building and taking apart paths

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Three points deserve attention. extension() of 2024-summary.final.csv is just csv (the part after the last dot) and file_stem() is everything before it. display() is the way to print a path, because Path does not implement Display (it might not be valid text). And joining an absolute path onto another one throws the first part away, which is a real security hazard when the second part comes from a user: never join an untrusted name without checking it, or someone can send /etc/passwd or ../../secret. A defensive check is to reject any path whose components() contain ParentDir or a root.

Streaming with File, BufReader and BufWriter

fs::read_to_string is great until the file is large. A File is a handle that implements the Read and Write traits, so you can process data in chunks. But raw File reads and writes go straight to the operating system, one system call each, which is slow if you read line by line. The fix is a buffer: BufReader reads big blocks and hands out small pieces, BufWriter collects small writes and sends them in big blocks.

Rust Writing and reading line by line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Notes on this program:

  • writeln!(out, ...) works with any Write, exactly like println! works with the screen.
  • A BufWriter flushes when it is dropped, but it ignores errors at that point. Always call flush() explicitly if you care whether the data was really written.
  • lines() allocates a new String for every line. For hot loops, reuse one buffer with read_line(&mut buf) and call buf.clear() between lines.
  • Option::is_none_or (Rust 1.82) returns true for None or when the closure holds for the value.
  • Parse errors are converted into an io::Error of kind InvalidData so that the whole function can use ? with one error type. Larger programs define their own error enum instead (custom errors).

OpenOptions: choosing exactly how to open

File::open opens for reading, File::create creates or truncates for writing. When you need anything else, such as appending, creating only if the file does not exist, or reading and writing at once, you use the builder OpenOptions.

Rust Append, create_new and seek

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

create_new(true) is more than convenience: the check and the creation happen as one atomic operation in the operating system, so two programs cannot both succeed. That makes it the basis of lock files and safe temporary files. Compare it with "check exists(), then create", which has a race: another process can create the file between your two steps.

A File is closed when it is dropped, so there is no close() method. fs::File::sync_all() asks the OS to push the data to the physical disk, which matters only when you must survive a power failure.

Directories and walking a tree

fs::read_dir returns an iterator of io::Result<DirEntry>. The order is whatever the filesystem gives you, so it is not alphabetical and may differ between machines; always collect and sort when the order matters (for output, for tests, for reproducible builds). To go through a whole tree, write a recursive function.

Rust A recursive directory walk

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

DirEntry::file_type() is cheaper than metadata() because many filesystems report the type while listing, and it does not follow symbolic links. That matters for safety: a recursive walk that follows links can loop forever on a cycle. For production tools, the walkdir crate (read-only here) handles links, errors and filters:

Rust
// read-only: needs the walkdir crate
use walkdir::WalkDir;

for entry in WalkDir::new("src").into_iter().filter_map(Result::ok) {
    println!("{}", entry.path().display());
}

Safe saving: write to a temp file, then rename

A crash during fs::write can leave a half-written file. The standard remedy is to write the complete new content to a temporary file next to the target, and then rename it over the target. On the same filesystem, rename replaces the old file in one atomic step: a reader sees either the old content or the new content, never a mixture.

Rust Atomic save with a temporary file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Good habits

  • Return errors, add context. Include the path in your error message.
  • Prefer &Path/impl AsRef<Path> parameters over String, as with &str.
  • Buffer small reads and writes with BufReader/BufWriter.
  • Never trust user-supplied paths (.., absolute paths, symlinks) when you build a path from them.
  • Use the tempfile crate (read-only here) for real temporary files; it picks safe unique names and deletes them for you.
  • Do not check then act. Calling exists() and then opening the file is a race. Just try the operation and handle the error.
  • Text is UTF-8 only. For other encodings, read bytes and decode with a crate such as encoding_rs.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does fs::write do if the file already exists?

    fs::write creates the file or truncates an existing one. Use OpenOptions with append(true) to add to the end, or create_new(true) to fail if the file exists.
  2. 2. Why does Path not implement Display?

    On Unix, file names are arbitrary bytes. display() gives a lossy, printable version, and to_str() returns an Option that is None for invalid UTF-8.
  3. 3. What is Path::new("data").join("/etc/passwd")?

    Joining an absolute path replaces the whole base path. That is why you must validate user-provided path parts before joining them.
  4. 4. Why should you call flush() on a BufWriter before it goes out of scope?

    BufWriter flushes in its Drop implementation, but Drop cannot return an error. An explicit flush() returns the io::Result so you can handle it.
  5. 5. What is a guaranteed property of fs::read_dir?

    The order depends on the filesystem. Collect and sort the entries whenever the order matters.

Summary

  • fs::read_to_string, fs::read and fs::write handle small files in one call; write replaces existing content.
  • Everything returns io::Result. Match on err.kind() (NotFound, AlreadyExists, InvalidData, ...) to react to specific problems, and add the file name to your messages.
  • Path and PathBuf work on names without touching the disk: join, file_name, extension, with_extension, strip_prefix. Never join untrusted input blindly.
  • Use File with BufReader (lines(), read_line) and BufWriter (call flush()) for large files.
  • OpenOptions gives control: append, create_new (atomic), read + write, plus Seek to move around.
  • read_dir returns entries in unspecified order; sort them, and recurse for a tree walk.
  • Save safely by writing a temporary file and renaming it over the target.

Next: Read, Write and BufRead Traits