std::fs - Rust

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.

DirBuilderA builder used to create directories in various manners.DirEntryEntries returned by the ReadDir iterator.FileAn object providing access to an open file on the filesystem.FileTimesRepresentation of the various timestamps on a file.FileTypeA structure representing a type of file with accessors for each file type. It is returned by Metadata::file_type method.MetadataMetadata information about a file.OpenOptionsOptions and flags which can be used to configure how a file is opened.PermissionsRepresentation of the various permissions on a file.ReadDirIterator over the entries in a directory.TryLockErrorAn 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.canonicalizeReturns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.copyCopies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.create_dirCreates a new, empty directory at the provided pathcreate_dir_allRecursively create a directory and all of its parent components if they are missing.existsReturns Ok(true) if the path points at an existing entity.hard_linkCreates a new hard link on the filesystem.metadataGiven a path, queries the file system to get information about a file, directory, etc.readReads the entire contents of a file into a bytes vector.read_dirReturns an iterator over the entries within a directory.read_linkReads a symbolic link, returning the file that the link points to.read_to_stringReads the entire contents of a file into a string.remove_dirRemoves an empty directory.remove_dir_allRemoves a directory at this path, after removing all its contents. Use carefullyRemoves a file from the filesystem.renameRenames a file or directory to a new name, replacing the original file if to already exists.set_permissionsChanges the permissions found on a file or a directory.soft_link DeprecatedCreates a new symbolic link on the filesystem.symlink_metadataQueries the metadata about a file without following symlinks.writeWrites a slice as the entire contents of a file.