std::fs - Rust
Description: Filesystem manipulation operations.

## Module fs

1.0.0 · Source
Expand description

Filesystem manipulation operations.

This module contains basic methods to manipulate the contents of the local filesystem. All methods in this module represent cross-platform filesystem operations. Extra platform-specific functionality can be found in the extension traits of `std::os::$platform`.

## §Time of Check to Time of Use (TOCTOU)

Many filesystem operations are subject to a race condition known as “Time of Check to Time of Use” (TOCTOU). This occurs when a program checks a condition (like file existence or permissions) and then uses the result of that check to make a decision, but the condition may have changed between the check and the use.

For example, checking if a file exists and then creating it if it doesn’t is vulnerable to TOCTOU - another process could create the file between your check and creation attempt.

Another example is with symbolic links: when removing a directory, if another process replaces the directory with a symbolic link between the check and the removal operation, the removal might affect the wrong location. This is why operations like `remove_dir_all` need to use atomic operations to prevent such race conditions.

To avoid TOCTOU issues:

- Be aware that metadata operations (like `metadata` or `symlink_metadata`) may be affected by changes made by other processes.
- Use atomic operations when possible (like `File::create_new` instead of checking existence then creating).
- Keep file open for the duration of operations.

## Structs§

DirBuilder
  A builder used to create directories in various manners.
DirEntry
  Entries returned by the `ReadDir` iterator.
File
  An object providing access to an open file on the filesystem.
FileTimes
  Representation of the various timestamps on a file.
FileType
  A structure representing a type of file with accessors for each file type. It is returned by `Metadata::file_type` method.
Metadata
  Metadata information about a file.
OpenOptions
  Options and flags which can be used to configure how a file is opened.
Permissions
  Representation of the various permissions on a file.
ReadDir
  Iterator over the entries in a directory.
DirExperimental
  An object providing access to a directory on the filesystem.

## Enums§

TryLockError
  An enumeration of possible errors which can occur while trying to acquire a lock from the `try_lock` method and `try_lock_shared` method on a `File`.

## 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.
exists
  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, queries the file system to get information about a file, directory, etc.
read
  Reads 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
  Reads 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
  Renames 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
  Creates a new symbolic link on the filesystem.
symlink_metadata
  Queries the metadata about a file without following symlinks.
write
  Writes a slice as the entire contents of a file.
set_permissions_nofollowExperimental
  Set the permissions of a file, unless it is a symlink.
set_timesExperimental
  Changes the timestamps of the file or directory at the specified path.
set_times_nofollowExperimental
  Changes the timestamps of the file or symlink at the specified path.