Expand description
Filesystem manipulation operations.
This module contains basic methods to manipulate the contents of the localfilesystem. All methods in this module represent cross-platform filesystemoperations. Extra platform-specific functionality can be found in theextension traits ofstd::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 changedbetween the check and the use.
For example, checking if a file exists and then creating it if it doesn’t is vulnerable toTOCTOU - 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 replacesthe directory with a symbolic link between the check and the removal operation, the removalmight affect the wrong location. This is why operations likeremove_dir_all need to useatomic operations to prevent such race conditions.
To avoid TOCTOU issues:
- Be aware that metadata operations (like
metadataorsymlink_metadata) may be affected bychanges made by other processes. - Use atomic operations when possible (like
File::create_newinstead 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
ReadDiriterator. - File
- An object providing access to an open file on the filesystem.
- File
Times - Representation of the various timestamps on a file.
- File
Type - A structure representing a type of file with accessors for each file type.It is returned by
Metadata::file_typemethod. - Metadata
- Metadata information about a file.
- Open
Options - 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.
Enums§
- TryLock
Error - An enumeration of possible errors which can occur while trying to acquire a lockfrom the
try_lockmethod andtry_lock_sharedmethod on aFile.
Functions§
- canonicalize
- Returns the canonical, absolute form of a path with all intermediatecomponents normalized and symbolic links resolved.
- copy
- Copies the contents of one file to another. This function will alsocopy 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 theyare 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. Usecarefully!
- remove_
file - Removes a file from the filesystem.
- rename
- Renames a file or directory to a new name, replacing the original file if
toalready exists. - set_
permissions - Changes the permissions found on a file or a directory.
- soft_
link Deprecated - 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.