Module fs
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.
- 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.
- 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.
- 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.