1//! Filesystem manipulation operations.2//!3//! This module contains basic methods to manipulate the contents of the local4//! filesystem. All methods in this module represent cross-platform filesystem5//! operations. Extra platform-specific functionality can be found in the6//! extension traits of `std::os::$platform`.7//!8//! # Time of Check to Time of Use (TOCTOU)9//!10//! Many filesystem operations are subject to a race condition known as "Time of Check to Time of Use"11//! (TOCTOU). This occurs when a program checks a condition (like file existence or permissions)12//! and then uses the result of that check to make a decision, but the condition may have changed13//! between the check and the use.14//!15//! For example, checking if a file exists and then creating it if it doesn't is vulnerable to16//! TOCTOU - another process could create the file between your check and creation attempt.17//!18//! Another example is with symbolic links: when removing a directory, if another process replaces19//! the directory with a symbolic link between the check and the removal operation, the removal20//! might affect the wrong location. This is why operations like [`remove_dir_all`] need to use21//! atomic operations to prevent such race conditions.22//!23//! To avoid TOCTOU issues:24//! - Be aware that metadata operations (like [`metadata`] or [`symlink_metadata`]) may be affected by25//! changes made by other processes.26//! - Use atomic operations when possible (like [`File::create_new`] instead of checking existence then creating).27//! - Keep file open for the duration of operations.2829#![stable(feature = "rust1", since = "1.0.0")]30#![deny(unsafe_op_in_unsafe_fn)]3132#[cfg(all(33    test,34    not(any(35        target_os = "emscripten",36        target_os = "wasi",37        target_env = "sgx",38        target_os = "xous",39        target_os = "trusty",40    ))41))]42mod tests;4344use crate::ffi::OsString;45use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut, Read, Seek, SeekFrom, Write};46use crate::path::{Path, PathBuf};47use crate::sealed::Sealed;48use crate::sys::{AsInner, AsInnerMut, FromInner, IntoInner, fs as fs_imp};49use crate::time::SystemTime;50use crate::{error, fmt};5152/// An object providing access to an open file on the filesystem.53///54/// An instance of a `File` can be read and/or written depending on what options55/// it was opened with. Files also implement [`Seek`] to alter the logical cursor56/// that the file contains internally.57///58/// Files are automatically closed when they go out of scope.  Errors detected59/// on closing are ignored by the implementation of `Drop`.  Use the method60/// [`sync_all`] if these errors must be manually handled.61///62/// `File` does not buffer reads and writes. For efficiency, consider wrapping the63/// file in a [`BufReader`] or [`BufWriter`] when performing many small [`read`]64/// or [`write`] calls, unless unbuffered reads and writes are required.65///66/// # Examples67///68/// Creates a new file and write bytes to it (you can also use [`write`]):69///70/// ```no_run71/// use std::fs::File;72/// use std::io::prelude::*;73///74/// fn main() -> std::io::Result<()> {75///     let mut file = File::create("foo.txt")?;76///     file.write_all(b"Hello, world!")?;77///     Ok(())78/// }79/// ```80///81/// Reads the contents of a file into a [`String`] (you can also use [`read`]):82///83/// ```no_run84/// use std::fs::File;85/// use std::io::prelude::*;86///87/// fn main() -> std::io::Result<()> {88///     let mut file = File::open("foo.txt")?;89///     let mut contents = String::new();90///     file.read_to_string(&mut contents)?;91///     assert_eq!(contents, "Hello, world!");92///     Ok(())93/// }94/// ```95///96/// Using a buffered [`Read`]er:97///98/// ```no_run99/// use std::fs::File;100/// use std::io::BufReader;101/// use std::io::prelude::*;102///103/// fn main() -> std::io::Result<()> {104///     let file = File::open("foo.txt")?;105///     let mut buf_reader = BufReader::new(file);106///     let mut contents = String::new();107///     buf_reader.read_to_string(&mut contents)?;108///     assert_eq!(contents, "Hello, world!");109///     Ok(())110/// }111/// ```112///113/// Note that, although read and write methods require a `&mut File`, because114/// of the interfaces for [`Read`] and [`Write`], the holder of a `&File` can115/// still modify the file, either through methods that take `&File` or by116/// retrieving the underlying OS object and modifying the file that way.117/// Additionally, many operating systems allow concurrent modification of files118/// by different processes. Avoid assuming that holding a `&File` means that the119/// file will not change.120///121/// # Platform-specific behavior122///123/// On Windows, the implementation of [`Read`] and [`Write`] traits for `File`124/// perform synchronous I/O operations. Therefore the underlying file must not125/// have been opened for asynchronous I/O (e.g. by using `FILE_FLAG_OVERLAPPED`).126///127/// [`BufReader`]: io::BufReader128/// [`BufWriter`]: io::BufWriter129/// [`sync_all`]: File::sync_all130/// [`write`]: File::write131/// [`read`]: File::read132#[stable(feature = "rust1", since = "1.0.0")]133#[cfg_attr(not(test), rustc_diagnostic_item = "File")]134#[diagnostic::on_move(note = "you can use `File::try_clone` to duplicate a `File` instance")]135pub struct File {136    inner: fs_imp::File,137}138139/// An enumeration of possible errors which can occur while trying to acquire a lock140/// from the [`try_lock`] method and [`try_lock_shared`] method on a [`File`].141///142/// [`try_lock`]: File::try_lock143/// [`try_lock_shared`]: File::try_lock_shared144#[stable(feature = "file_lock", since = "1.89.0")]145pub enum TryLockError {146    /// The lock could not be acquired due to an I/O error on the file. The standard library will147    /// not return an [`ErrorKind::WouldBlock`] error inside [`TryLockError::Error`]148    ///149    /// [`ErrorKind::WouldBlock`]: io::ErrorKind::WouldBlock150    Error(io::Error),151    /// The lock could not be acquired at this time because it is held by another handle/process.152    WouldBlock,153}154155/// An object providing access to a directory on the filesystem.156///157/// Directories are automatically closed when they go out of scope.  Errors detected158/// on closing are ignored by the implementation of `Drop`.159///160/// # Platform-specific behavior161///162/// On supported systems (including Windows and some UNIX-based OSes), this function acquires a163/// handle/file descriptor for the directory. This allows functions like [`Dir::open_file`] to164/// avoid [TOCTOU] errors when the directory itself is being moved.165///166/// On other systems, it stores an absolute path (see [`canonicalize()`]). In the latter case, no167/// [TOCTOU] guarantees are made.168///169/// # Examples170///171/// Opens a directory and then a file inside it.172///173/// ```no_run174/// #![feature(dirfd)]175/// use std::{fs::Dir, io};176///177/// fn main() -> std::io::Result<()> {178///     let dir = Dir::open("foo")?;179///     let mut file = dir.open_file("bar.txt")?;180///     let contents = io::read_to_string(file)?;181///     assert_eq!(contents, "Hello, world!");182///     Ok(())183/// }184/// ```185///186/// [TOCTOU]: self#time-of-check-to-time-of-use-toctou187#[unstable(feature = "dirfd", issue = "120426")]188pub struct Dir {189    inner: fs_imp::Dir,190}191192/// Metadata information about a file.193///194/// This structure is returned from the [`metadata`] or195/// [`symlink_metadata`] function or method and represents known196/// metadata about a file such as its permissions, size, modification197/// times, etc.198#[stable(feature = "rust1", since = "1.0.0")]199#[derive(Clone)]200pub struct Metadata(fs_imp::FileAttr);201202/// Iterator over the entries in a directory.203///204/// This iterator is returned from the [`read_dir`] function of this module and205/// will yield instances of <code>[io::Result]<[DirEntry]></code>. Through a [`DirEntry`]206/// information like the entry's path and possibly other metadata can be207/// learned.208///209/// The order in which this iterator returns entries is platform and filesystem210/// dependent.211///212/// # Errors213/// This [`io::Result`] will be an [`Err`] if an error occurred while fetching214/// the next entry from the OS.215#[stable(feature = "rust1", since = "1.0.0")]216#[derive(Debug)]217pub struct ReadDir(fs_imp::ReadDir);218219/// Entries returned by the [`ReadDir`] iterator.220///221/// An instance of `DirEntry` represents an entry inside of a directory on the222/// filesystem. Each entry can be inspected via methods to learn about the full223/// path or possibly other metadata through per-platform extension traits.224///225/// # Platform-specific behavior226///227/// On Unix, the `DirEntry` struct contains an internal reference to the open228/// directory. Holding `DirEntry` objects will consume a file handle even229/// after the `ReadDir` iterator is dropped.230///231/// Note that this [may change in the future][changes].232///233/// [changes]: io#platform-specific-behavior234#[stable(feature = "rust1", since = "1.0.0")]235pub struct DirEntry(fs_imp::DirEntry);236237/// Options and flags which can be used to configure how a file is opened.238///239/// This builder exposes the ability to configure how a [`File`] is opened and240/// what operations are permitted on the open file. The [`File::open`] and241/// [`File::create`] methods are aliases for commonly used options using this242/// builder.243///244/// Generally speaking, when using `OpenOptions`, you'll first call245/// [`OpenOptions::new`], then chain calls to methods to set each option, then246/// call [`OpenOptions::open`], passing the path of the file you're trying to247/// open. This will give you a [`io::Result`] with a [`File`] inside that you248/// can further operate on.249///250/// # Examples251///252/// Opening a file to read:253///254/// ```no_run255/// use std::fs::OpenOptions;256///257/// let file = OpenOptions::new().read(true).open("foo.txt");258/// ```259///260/// Opening a file for both reading and writing, as well as creating it if it261/// doesn't exist:262///263/// ```no_run264/// use std::fs::OpenOptions;265///266/// let file = OpenOptions::new()267///             .read(true)268///             .write(true)269///             .create(true)270///             .open("foo.txt");271/// ```272#[derive(Clone, Debug)]273#[stable(feature = "rust1", since = "1.0.0")]274#[cfg_attr(not(test), rustc_diagnostic_item = "FsOpenOptions")]275pub struct OpenOptions(fs_imp::OpenOptions);276277/// Representation of the various timestamps on a file.278#[derive(Copy, Clone, Debug, Default)]279#[stable(feature = "file_set_times", since = "1.75.0")]280#[must_use = "must be applied to a file via `File::set_times` to have any effect"]281pub struct FileTimes(fs_imp::FileTimes);282283/// Representation of the various permissions on a file.284///285/// This module only currently provides one bit of information,286/// [`Permissions::readonly`], which is exposed on all currently supported287/// platforms. Unix-specific functionality, such as mode bits, is available288/// through the [`PermissionsExt`] trait.289///290/// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt291#[derive(Clone, PartialEq, Eq, Debug)]292#[stable(feature = "rust1", since = "1.0.0")]293#[cfg_attr(not(test), rustc_diagnostic_item = "FsPermissions")]294pub struct Permissions(fs_imp::FilePermissions);295296/// A structure representing a type of file with accessors for each file type.297/// It is returned by [`Metadata::file_type`] method.298#[stable(feature = "file_type", since = "1.1.0")]299#[derive(Copy, Clone, PartialEq, Eq, Hash)]300#[cfg_attr(not(test), rustc_diagnostic_item = "FileType")]301pub struct FileType(fs_imp::FileType);302303/// A builder used to create directories in various manners.304///305/// This builder also supports platform-specific options.306#[stable(feature = "dir_builder", since = "1.6.0")]307#[cfg_attr(not(test), rustc_diagnostic_item = "DirBuilder")]308#[derive(Debug)]309pub struct DirBuilder {310    inner: fs_imp::DirBuilder,311    recursive: bool,312}313314/// Reads the entire contents of a file into a bytes vector.315///316/// This is a convenience function for using [`File::open`] and [`read_to_end`]317/// with fewer imports and without an intermediate variable.318///319/// [`read_to_end`]: Read::read_to_end320///321/// # Errors322///323/// This function will return an error if `path` does not already exist.324/// Other errors may also be returned according to [`OpenOptions::open`].325///326/// While reading from the file, this function handles [`io::ErrorKind::Interrupted`]327/// with automatic retries. See [io::Read] documentation for details.328///329/// # Examples330///331/// ```no_run332/// use std::fs;333///334/// fn main() -> Result<(), Box<dyn std::error::Error + 'static>> {335///     let data: Vec<u8> = fs::read("image.jpg")?;336///     assert_eq!(data[0..3], [0xFF, 0xD8, 0xFF]);337///     Ok(())338/// }339/// ```340#[stable(feature = "fs_read_write_bytes", since = "1.26.0")]341pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {342    fn inner(path: &Path) -> io::Result<Vec<u8>> {343        let mut file = File::open(path)?;344        let size = file.metadata().map(|m| usize::try_from(m.len()).unwrap_or(usize::MAX)).ok();345        let mut bytes = Vec::try_with_capacity(size.unwrap_or(0))?;346        io::default_read_to_end(&mut file, &mut bytes, size)?;347        Ok(bytes)348    }349    inner(path.as_ref())350}351352/// Reads the entire contents of a file into a string.353///354/// This is a convenience function for using [`File::open`] and [`read_to_string`]355/// with fewer imports and without an intermediate variable.356///357/// [`read_to_string`]: Read::read_to_string358///359/// # Errors360///361/// This function will return an error if `path` does not already exist.362/// Other errors may also be returned according to [`OpenOptions::open`].363///364/// If the contents of the file are not valid UTF-8, then an error will also be365/// returned.366///367/// While reading from the file, this function handles [`io::ErrorKind::Interrupted`]368/// with automatic retries. See [io::Read] documentation for details.369///370/// # Examples371///372/// ```no_run373/// use std::fs;374/// use std::error::Error;375///376/// fn main() -> Result<(), Box<dyn Error>> {377///     let message: String = fs::read_to_string("message.txt")?;378///     println!("{}", message);379///     Ok(())380/// }381/// ```382#[stable(feature = "fs_read_write", since = "1.26.0")]383pub fn read_to_string<P: AsRef<Path>>(path: P) -> io::Result<String> {384    fn inner(path: &Path) -> io::Result<String> {385        let mut file = File::open(path)?;386        let size = file.metadata().map(|m| usize::try_from(m.len()).unwrap_or(usize::MAX)).ok();387        let mut string = String::new();388        string.try_reserve_exact(size.unwrap_or(0))?;389        io::default_read_to_string(&mut file, &mut string, size)?;390        Ok(string)391    }392    inner(path.as_ref())393}394395/// Writes a slice as the entire contents of a file.396///397/// This function will create a file if it does not exist,398/// and will entirely replace its contents if it does.399///400/// Depending on the platform, this function may fail if the401/// full directory path does not exist.402///403/// This is a convenience function for using [`File::create`] and [`write_all`]404/// with fewer imports.405///406/// [`write_all`]: Write::write_all407///408/// # Examples409///410/// ```no_run411/// use std::fs;412///413/// fn main() -> std::io::Result<()> {414///     fs::write("foo.txt", b"Lorem ipsum")?;415///     fs::write("bar.txt", "dolor sit")?;416///     Ok(())417/// }418/// ```419#[stable(feature = "fs_read_write_bytes", since = "1.26.0")]420pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> io::Result<()> {421    fn inner(path: &Path, contents: &[u8]) -> io::Result<()> {422        File::create(path)?.write_all(contents)423    }424    inner(path.as_ref(), contents.as_ref())425}426427/// Changes the timestamps of the file or directory at the specified path.428///429/// This function will attempt to set the access and modification times430/// to the times specified. If the path refers to a symbolic link, this function431/// will follow the link and change the timestamps of the target file.432///433/// # Platform-specific behavior434///435/// This function currently corresponds to the `utimensat` function on Unix platforms, the436/// `setattrlist` function on Apple platforms, and the `SetFileTime` function on Windows.437///438/// # Errors439///440/// This function will return an error if the user lacks permission to change timestamps on the441/// target file or symlink. It may also return an error if the OS does not support it.442///443/// # Examples444///445/// ```no_run446/// #![feature(fs_set_times)]447/// use std::fs::{self, FileTimes};448/// use std::time::SystemTime;449///450/// fn main() -> std::io::Result<()> {451///     let now = SystemTime::now();452///     let times = FileTimes::new()453///         .set_accessed(now)454///         .set_modified(now);455///     fs::set_times("foo.txt", times)?;456///     Ok(())457/// }458/// ```459#[unstable(feature = "fs_set_times", issue = "147455")]460#[doc(alias = "utimens")]461#[doc(alias = "utimes")]462#[doc(alias = "utime")]463pub fn set_times<P: AsRef<Path>>(path: P, times: FileTimes) -> io::Result<()> {464    fs_imp::set_times(path.as_ref(), times.0)465}466467/// Changes the timestamps of the file or symlink at the specified path.468///469/// This function will attempt to set the access and modification times470/// to the times specified. Differ from `set_times`, if the path refers to a symbolic link,471/// this function will change the timestamps of the symlink itself, not the target file.472///473/// # Platform-specific behavior474///475/// This function currently corresponds to the `utimensat` function with `AT_SYMLINK_NOFOLLOW` on476/// Unix platforms, the `setattrlist` function with `FSOPT_NOFOLLOW` on Apple platforms, and the477/// `SetFileTime` function on Windows.478///479/// # Errors480///481/// This function will return an error if the user lacks permission to change timestamps on the482/// target file or symlink. It may also return an error if the OS does not support it.483///484/// # Examples485///486/// ```no_run487/// #![feature(fs_set_times)]488/// use std::fs::{self, FileTimes};489/// use std::time::SystemTime;490///491/// fn main() -> std::io::Result<()> {492///     let now = SystemTime::now();493///     let times = FileTimes::new()494///         .set_accessed(now)495///         .set_modified(now);496///     fs::set_times_nofollow("symlink.txt", times)?;497///     Ok(())498/// }499/// ```500#[unstable(feature = "fs_set_times", issue = "147455")]501#[doc(alias = "utimensat")]502#[doc(alias = "lutimens")]503#[doc(alias = "lutimes")]504pub fn set_times_nofollow<P: AsRef<Path>>(path: P, times: FileTimes) -> io::Result<()> {505    fs_imp::set_times_nofollow(path.as_ref(), times.0)506}507508#[stable(feature = "file_lock", since = "1.89.0")]509impl error::Error for TryLockError {}510511#[stable(feature = "file_lock", since = "1.89.0")]512impl fmt::Debug for TryLockError {513    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {514        match self {515            TryLockError::Error(err) => err.fmt(f),516            TryLockError::WouldBlock => "WouldBlock".fmt(f),517        }518    }519}520521#[stable(feature = "file_lock", since = "1.89.0")]522impl fmt::Display for TryLockError {523    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {524        match self {525            TryLockError::Error(_) => "lock acquisition failed due to I/O error",526            TryLockError::WouldBlock => "lock acquisition failed because the operation would block",527        }528        .fmt(f)529    }530}531532#[stable(feature = "file_lock", since = "1.89.0")]533impl From<TryLockError> for io::Error {534    fn from(err: TryLockError) -> io::Error {535        match err {536            TryLockError::Error(err) => err,537            TryLockError::WouldBlock => io::ErrorKind::WouldBlock.into(),538        }539    }540}541542impl File {543    /// Attempts to open a file in read-only mode.544    ///545    /// See the [`OpenOptions::open`] method for more details.546    ///547    /// If you only need to read the entire file contents,548    /// consider [`std::fs::read()`][self::read] or549    /// [`std::fs::read_to_string()`][self::read_to_string] instead.550    ///551    /// # Errors552    ///553    /// This function will return an error if `path` does not already exist.554    /// Other errors may also be returned according to [`OpenOptions::open`].555    ///556    /// # Examples557    ///558    /// ```no_run559    /// use std::fs::File;560    /// use std::io::Read;561    ///562    /// fn main() -> std::io::Result<()> {563    ///     let mut f = File::open("foo.txt")?;564    ///     let mut data = vec![];565    ///     f.read_to_end(&mut data)?;566    ///     Ok(())567    /// }568    /// ```569    #[stable(feature = "rust1", since = "1.0.0")]570    pub fn open<P: AsRef<Path>>(path: P) -> io::Result<File> {571        OpenOptions::new().read(true).open(path.as_ref())572    }573574    /// Attempts to open a file in read-only mode with buffering.575    ///576    /// See the [`OpenOptions::open`] method, the [`BufReader`][io::BufReader] type,577    /// and the [`BufRead`][io::BufRead] trait for more details.578    ///579    /// If you only need to read the entire file contents,580    /// consider [`std::fs::read()`][self::read] or581    /// [`std::fs::read_to_string()`][self::read_to_string] instead.582    ///583    /// # Errors584    ///585    /// This function will return an error if `path` does not already exist,586    /// or if memory allocation fails for the new buffer.587    /// Other errors may also be returned according to [`OpenOptions::open`].588    ///589    /// # Examples590    ///591    /// ```no_run592    /// #![feature(file_buffered)]593    /// use std::fs::File;594    /// use std::io::BufRead;595    ///596    /// fn main() -> std::io::Result<()> {597    ///     let mut f = File::open_buffered("foo.txt")?;598    ///     assert!(f.capacity() > 0);599    ///     for (line, i) in f.lines().zip(1..) {600    ///         println!("{i:6}: {}", line?);601    ///     }602    ///     Ok(())603    /// }604    /// ```605    #[unstable(feature = "file_buffered", issue = "130804")]606    pub fn open_buffered<P: AsRef<Path>>(path: P) -> io::Result<io::BufReader<File>> {607        // Allocate the buffer *first* so we don't affect the filesystem otherwise.608        let buffer = io::BufReader::<Self>::try_new_buffer()?;609        let file = File::open(path)?;610        Ok(io::BufReader::with_buffer(file, buffer))611    }612613    /// Opens a file in write-only mode.614    ///615    /// This function will create a file if it does not exist,616    /// and will truncate it if it does.617    ///618    /// Depending on the platform, this function may fail if the619    /// full directory path does not exist.620    /// See the [`OpenOptions::open`] function for more details.621    ///622    /// See also [`std::fs::write()`][self::write] for a simple function to623    /// create a file with some given data.624    ///625    /// # Examples626    ///627    /// ```no_run628    /// use std::fs::File;629    /// use std::io::Write;630    ///631    /// fn main() -> std::io::Result<()> {632    ///     let mut f = File::create("foo.txt")?;633    ///     f.write_all(&1234_u32.to_be_bytes())?;634    ///     Ok(())635    /// }636    /// ```637    #[stable(feature = "rust1", since = "1.0.0")]638    pub fn create<P: AsRef<Path>>(path: P) -> io::Result<File> {639        OpenOptions::new().write(true).create(true).truncate(true).open(path.as_ref())640    }641642    /// Opens a file in write-only mode with buffering.643    ///644    /// This function will create a file if it does not exist,645    /// and will truncate it if it does.646    ///647    /// Depending on the platform, this function may fail if the648    /// full directory path does not exist.649    ///650    /// See the [`OpenOptions::open`] method and the651    /// [`BufWriter`][io::BufWriter] type for more details.652    ///653    /// See also [`std::fs::write()`][self::write] for a simple function to654    /// create a file with some given data.655    ///656    /// # Examples657    ///658    /// ```no_run659    /// #![feature(file_buffered)]660    /// use std::fs::File;661    /// use std::io::Write;662    ///663    /// fn main() -> std::io::Result<()> {664    ///     let mut f = File::create_buffered("foo.txt")?;665    ///     assert!(f.capacity() > 0);666    ///     for i in 0..100 {667    ///         writeln!(&mut f, "{i}")?;668    ///     }669    ///     f.flush()?;670    ///     Ok(())671    /// }672    /// ```673    #[unstable(feature = "file_buffered", issue = "130804")]674    pub fn create_buffered<P: AsRef<Path>>(path: P) -> io::Result<io::BufWriter<File>> {675        // Allocate the buffer *first* so we don't affect the filesystem otherwise.676        let buffer = io::BufWriter::<Self>::try_new_buffer()?;677        let file = File::create(path)?;678        Ok(io::BufWriter::with_buffer(file, buffer))679    }680681    /// Creates a new file in read-write mode; error if the file exists.682    ///683    /// This function will create a file if it does not exist, or return an error if it does. This684    /// way, if the call succeeds, the file returned is guaranteed to be new.685    /// If a file exists at the target location, creating a new file will fail with [`AlreadyExists`]686    /// or another error based on the situation. See [`OpenOptions::open`] for a687    /// non-exhaustive list of likely errors.688    ///689    /// This option is useful because it is atomic. Otherwise between checking whether a file690    /// exists and creating a new one, the file may have been created by another process (a [TOCTOU]691    /// race condition / attack).692    ///693    /// This can also be written using694    /// `File::options().read(true).write(true).create_new(true).open(...)`.695    ///696    /// [`AlreadyExists`]: crate::io::ErrorKind::AlreadyExists697    /// [TOCTOU]: self#time-of-check-to-time-of-use-toctou698    ///699    /// # Examples700    ///701    /// ```no_run702    /// use std::fs::File;703    /// use std::io::Write;704    ///705    /// fn main() -> std::io::Result<()> {706    ///     let mut f = File::create_new("foo.txt")?;707    ///     f.write_all("Hello, world!".as_bytes())?;708    ///     Ok(())709    /// }710    /// ```711    #[stable(feature = "file_create_new", since = "1.77.0")]712    pub fn create_new<P: AsRef<Path>>(path: P) -> io::Result<File> {713        OpenOptions::new().read(true).write(true).create_new(true).open(path.as_ref())714    }715716    /// Returns a new OpenOptions object.717    ///718    /// This function returns a new OpenOptions object that you can use to719    /// open or create a file with specific options if `open()` or `create()`720    /// are not appropriate.721    ///722    /// It is equivalent to `OpenOptions::new()`, but allows you to write more723    /// readable code. Instead of724    /// `OpenOptions::new().append(true).open("example.log")`,725    /// you can write `File::options().append(true).open("example.log")`. This726    /// also avoids the need to import `OpenOptions`.727    ///728    /// See the [`OpenOptions::new`] function for more details.729    ///730    /// # Examples731    ///732    /// ```no_run733    /// use std::fs::File;734    /// use std::io::Write;735    ///736    /// fn main() -> std::io::Result<()> {737    ///     let mut f = File::options().append(true).open("example.log")?;738    ///     writeln!(&mut f, "new line")?;739    ///     Ok(())740    /// }741    /// ```742    #[must_use]743    #[stable(feature = "with_options", since = "1.58.0")]744    #[cfg_attr(not(test), rustc_diagnostic_item = "file_options")]745    pub fn options() -> OpenOptions {746        OpenOptions::new()747    }748749    /// Attempts to sync all OS-internal file content and metadata to disk.750    ///751    /// This function will attempt to ensure that all in-memory data reaches the752    /// filesystem before returning.753    ///754    /// This can be used to handle errors that would otherwise only be caught755    /// when the `File` is closed, as dropping a `File` will ignore all errors.756    /// Note, however, that `sync_all` is generally more expensive than closing757    /// a file by dropping it, because the latter is not required to block until758    /// the data has been written to the filesystem.759    ///760    /// If synchronizing the metadata is not required, use [`sync_data`] instead.761    ///762    /// [`sync_data`]: File::sync_data763    ///764    /// # Examples765    ///766    /// ```no_run767    /// use std::fs::File;768    /// use std::io::prelude::*;769    ///770    /// fn main() -> std::io::Result<()> {771    ///     let mut f = File::create("foo.txt")?;772    ///     f.write_all(b"Hello, world!")?;773    ///774    ///     f.sync_all()?;775    ///     Ok(())776    /// }777    /// ```778    #[stable(feature = "rust1", since = "1.0.0")]779    #[doc(alias = "fsync")]780    pub fn sync_all(&self) -> io::Result<()> {781        self.inner.fsync()782    }783784    /// This function is similar to [`sync_all`], except that it might not785    /// synchronize file metadata to the filesystem.786    ///787    /// This is intended for use cases that must synchronize content, but don't788    /// need the metadata on disk. The goal of this method is to reduce disk789    /// operations.790    ///791    /// Note that some platforms may simply implement this in terms of792    /// [`sync_all`].793    ///794    /// [`sync_all`]: File::sync_all795    ///796    /// # Examples797    ///798    /// ```no_run799    /// use std::fs::File;800    /// use std::io::prelude::*;801    ///802    /// fn main() -> std::io::Result<()> {803    ///     let mut f = File::create("foo.txt")?;804    ///     f.write_all(b"Hello, world!")?;805    ///806    ///     f.sync_data()?;807    ///     Ok(())808    /// }809    /// ```810    #[stable(feature = "rust1", since = "1.0.0")]811    #[doc(alias = "fdatasync")]812    pub fn sync_data(&self) -> io::Result<()> {813        self.inner.datasync()814    }815816    /// Acquire an exclusive lock on the file. Blocks until the lock can be acquired.817    ///818    /// This acquires an exclusive lock; no other file handle to this file, in this or any other819    /// process, may acquire another lock.820    ///821    /// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],822    /// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with823    /// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not824    /// cause non-lockholders to block.825    ///826    /// If this file handle/descriptor, or a clone of it, already holds a lock the exact behavior827    /// is unspecified and platform dependent, including the possibility that it will deadlock.828    /// However, if this method returns, then an exclusive lock is held.829    ///830    /// If the file is not open for writing, it is unspecified whether this function returns an error.831    ///832    /// The lock will be released when this file (along with any other file descriptors/handles833    /// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.834    ///835    /// # Platform-specific behavior836    ///837    /// This function currently corresponds to the `flock` function on Unix with the `LOCK_EX` flag,838    /// and the `LockFileEx` function on Windows with the `LOCKFILE_EXCLUSIVE_LOCK` flag. Note that,839    /// this [may change in the future][changes].840    ///841    /// On Windows, locking a file will fail if the file is opened only for append. To lock a file,842    /// open it with one of `.read(true)`, `.read(true).append(true)`, or `.write(true)`.843    ///844    /// [changes]: io#platform-specific-behavior845    ///846    /// [`lock`]: File::lock847    /// [`lock_shared`]: File::lock_shared848    /// [`try_lock`]: File::try_lock849    /// [`try_lock_shared`]: File::try_lock_shared850    /// [`unlock`]: File::unlock851    /// [`read`]: Read::read852    /// [`write`]: Write::write853    ///854    /// # Examples855    ///856    /// ```no_run857    /// use std::fs::File;858    ///859    /// fn main() -> std::io::Result<()> {860    ///     let f = File::create("foo.txt")?;861    ///     f.lock()?;862    ///     Ok(())863    /// }864    /// ```865    #[stable(feature = "file_lock", since = "1.89.0")]866    pub fn lock(&self) -> io::Result<()> {867        self.inner.lock()868    }869870    /// Acquire a shared (non-exclusive) lock on the file. Blocks until the lock can be acquired.871    ///872    /// This acquires a shared lock; more than one file handle, in this or any other process, may873    /// hold a shared lock, but none may hold an exclusive lock at the same time.874    ///875    /// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],876    /// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with877    /// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not878    /// cause non-lockholders to block.879    ///880    /// If this file handle/descriptor, or a clone of it, already holds a lock, the exact behavior881    /// is unspecified and platform dependent, including the possibility that it will deadlock.882    /// However, if this method returns, then a shared lock is held.883    ///884    /// The lock will be released when this file (along with any other file descriptors/handles885    /// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.886    ///887    /// # Platform-specific behavior888    ///889    /// This function currently corresponds to the `flock` function on Unix with the `LOCK_SH` flag,890    /// and the `LockFileEx` function on Windows. Note that, this891    /// [may change in the future][changes].892    ///893    /// On Windows, locking a file will fail if the file is opened only for append. To lock a file,894    /// open it with one of `.read(true)`, `.read(true).append(true)`, or `.write(true)`.895    ///896    /// [changes]: io#platform-specific-behavior897    ///898    /// [`lock`]: File::lock899    /// [`lock_shared`]: File::lock_shared900    /// [`try_lock`]: File::try_lock901    /// [`try_lock_shared`]: File::try_lock_shared902    /// [`unlock`]: File::unlock903    /// [`read`]: Read::read904    /// [`write`]: Write::write905    ///906    /// # Examples907    ///908    /// ```no_run909    /// use std::fs::File;910    ///911    /// fn main() -> std::io::Result<()> {912    ///     let f = File::open("foo.txt")?;913    ///     f.lock_shared()?;914    ///     Ok(())915    /// }916    /// ```917    #[stable(feature = "file_lock", since = "1.89.0")]918    pub fn lock_shared(&self) -> io::Result<()> {919        self.inner.lock_shared()920    }921922    /// Try to acquire an exclusive lock on the file.923    ///924    /// Returns `Err(TryLockError::WouldBlock)` if a different lock is already held on this file925    /// (via another handle/descriptor).926    ///927    /// This acquires an exclusive lock; no other file handle to this file, in this or any other928    /// process, may acquire another lock.929    ///930    /// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],931    /// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with932    /// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not933    /// cause non-lockholders to block.934    ///935    /// If this file handle/descriptor, or a clone of it, already holds a lock, the exact behavior936    /// is unspecified and platform dependent, including the possibility that it will deadlock.937    /// However, if this method returns `Ok(())`, then it has acquired an exclusive lock.938    ///939    /// If the file is not open for writing, it is unspecified whether this function returns an error.940    ///941    /// The lock will be released when this file (along with any other file descriptors/handles942    /// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.943    ///944    /// # Platform-specific behavior945    ///946    /// This function currently corresponds to the `flock` function on Unix with the `LOCK_EX` and947    /// `LOCK_NB` flags, and the `LockFileEx` function on Windows with the `LOCKFILE_EXCLUSIVE_LOCK`948    /// and `LOCKFILE_FAIL_IMMEDIATELY` flags. Note that, this949    /// [may change in the future][changes].950    ///951    /// On Windows, locking a file will fail if the file is opened only for append. To lock a file,952    /// open it with one of `.read(true)`, `.read(true).append(true)`, or `.write(true)`.953    ///954    /// [changes]: io#platform-specific-behavior955    ///956    /// [`lock`]: File::lock957    /// [`lock_shared`]: File::lock_shared958    /// [`try_lock`]: File::try_lock959    /// [`try_lock_shared`]: File::try_lock_shared960    /// [`unlock`]: File::unlock961    /// [`read`]: Read::read962    /// [`write`]: Write::write963    ///964    /// # Examples965    ///966    /// ```no_run967    /// use std::fs::{File, TryLockError};968    ///969    /// fn main() -> std::io::Result<()> {970    ///     let f = File::create("foo.txt")?;971    ///     // Explicit handling of the WouldBlock error972    ///     match f.try_lock() {973    ///         Ok(_) => (),974    ///         Err(TryLockError::WouldBlock) => (), // Lock not acquired975    ///         Err(TryLockError::Error(err)) => return Err(err),976    ///     }977    ///     // Alternately, propagate the error as an io::Error978    ///     f.try_lock()?;979    ///     Ok(())980    /// }981    /// ```982    #[stable(feature = "file_lock", since = "1.89.0")]983    pub fn try_lock(&self) -> Result<(), TryLockError> {984        self.inner.try_lock()985    }986987    /// Try to acquire a shared (non-exclusive) lock on the file.988    ///989    /// Returns `Err(TryLockError::WouldBlock)` if a different lock is already held on this file990    /// (via another handle/descriptor).991    ///992    /// This acquires a shared lock; more than one file handle, in this or any other process, may993    /// hold a shared lock, but none may hold an exclusive lock at the same time.994    ///995    /// This lock may be advisory or mandatory. This lock is meant to interact with [`lock`],996    /// [`try_lock`], [`lock_shared`], [`try_lock_shared`], and [`unlock`]. Its interactions with997    /// other methods, such as [`read`] and [`write`] are platform specific, and it may or may not998    /// cause non-lockholders to block.999    ///1000    /// If this file handle, or a clone of it, already holds a lock, the exact behavior is1001    /// unspecified and platform dependent, including the possibility that it will deadlock.1002    /// However, if this method returns `Ok(())`, then it has acquired a shared lock.1003    ///1004    /// The lock will be released when this file (along with any other file descriptors/handles1005    /// duplicated or inherited from it) is closed, or if the [`unlock`] method is called.1006    ///1007    /// # Platform-specific behavior1008    ///1009    /// This function currently corresponds to the `flock` function on Unix with the `LOCK_SH` and1010    /// `LOCK_NB` flags, and the `LockFileEx` function on Windows with the1011    /// `LOCKFILE_FAIL_IMMEDIATELY` flag. Note that, this1012    /// [may change in the future][changes].1013    ///1014    /// On Windows, locking a file will fail if the file is opened only for append. To lock a file,1015    /// open it with one of `.read(true)`, `.read(true).append(true)`, or `.write(true)`.1016    ///1017    /// [changes]: io#platform-specific-behavior1018    ///1019    /// [`lock`]: File::lock1020    /// [`lock_shared`]: File::lock_shared1021    /// [`try_lock`]: File::try_lock1022    /// [`try_lock_shared`]: File::try_lock_shared1023    /// [`unlock`]: File::unlock1024    /// [`read`]: Read::read1025    /// [`write`]: Write::write1026    ///1027    /// # Examples1028    ///1029    /// ```no_run1030    /// use std::fs::{File, TryLockError};1031    ///1032    /// fn main() -> std::io::Result<()> {1033    ///     let f = File::open("foo.txt")?;1034    ///     // Explicit handling of the WouldBlock error1035    ///     match f.try_lock_shared() {1036    ///         Ok(_) => (),1037    ///         Err(TryLockError::WouldBlock) => (), // Lock not acquired1038    ///         Err(TryLockError::Error(err)) => return Err(err),1039    ///     }1040    ///     // Alternately, propagate the error as an io::Error1041    ///     f.try_lock_shared()?;1042    ///1043    ///     Ok(())1044    /// }1045    /// ```1046    #[stable(feature = "file_lock", since = "1.89.0")]1047    pub fn try_lock_shared(&self) -> Result<(), TryLockError> {1048        self.inner.try_lock_shared()1049    }10501051    /// Release all locks on the file.1052    ///1053    /// All locks are released when the file (along with any other file descriptors/handles1054    /// duplicated or inherited from it) is closed. This method allows releasing locks without1055    /// closing the file.1056    ///1057    /// If no lock is currently held via this file descriptor/handle, this method may return an1058    /// error, or may return successfully without taking any action.1059    ///1060    /// # Platform-specific behavior1061    ///1062    /// This function currently corresponds to the `flock` function on Unix with the `LOCK_UN` flag,1063    /// and the `UnlockFile` function on Windows. Note that, this1064    /// [may change in the future][changes].1065    ///1066    /// On Windows, locking a file will fail if the file is opened only for append. To lock a file,1067    /// open it with one of `.read(true)`, `.read(true).append(true)`, or `.write(true)`.1068    ///1069    /// [changes]: io#platform-specific-behavior1070    ///1071    /// # Examples1072    ///1073    /// ```no_run1074    /// use std::fs::File;1075    ///1076    /// fn main() -> std::io::Result<()> {1077    ///     let f = File::open("foo.txt")?;1078    ///     f.lock()?;1079    ///     f.unlock()?;1080    ///     Ok(())1081    /// }1082    /// ```1083    #[stable(feature = "file_lock", since = "1.89.0")]1084    pub fn unlock(&self) -> io::Result<()> {1085        self.inner.unlock()1086    }10871088    /// Truncates or extends the underlying file, updating the size of1089    /// this file to become `size`.1090    ///1091    /// If the `size` is less than the current file's size, then the file will1092    /// be shrunk. If it is greater than the current file's size, then the file1093    /// will be extended to `size` and have all of the intermediate data filled1094    /// in with 0s.1095    ///1096    /// The file's cursor isn't changed. In particular, if the cursor was at the1097    /// end and the file is shrunk using this operation, the cursor will now be1098    /// past the end.1099    ///1100    /// # Errors1101    ///1102    /// This function will return an error if the file is not opened for writing.1103    /// Also, [`std::io::ErrorKind::InvalidInput`](crate::io::ErrorKind::InvalidInput)1104    /// will be returned if the desired length would cause an overflow due to1105    /// the implementation specifics.1106    ///1107    /// # Examples1108    ///1109    /// ```no_run1110    /// use std::fs::File;1111    ///1112    /// fn main() -> std::io::Result<()> {1113    ///     let mut f = File::create("foo.txt")?;1114    ///     f.set_len(10)?;1115    ///     Ok(())1116    /// }1117    /// ```1118    ///1119    /// Note that this method alters the content of the underlying file, even1120    /// though it takes `&self` rather than `&mut self`.1121    #[stable(feature = "rust1", since = "1.0.0")]1122    pub fn set_len(&self, size: u64) -> io::Result<()> {1123        self.inner.truncate(size)1124    }11251126    /// Queries metadata about the underlying file.1127    ///1128    /// # Examples1129    ///1130    /// ```no_run1131    /// use std::fs::File;1132    ///1133    /// fn main() -> std::io::Result<()> {1134    ///     let mut f = File::open("foo.txt")?;1135    ///     let metadata = f.metadata()?;1136    ///     Ok(())1137    /// }1138    /// ```1139    #[stable(feature = "rust1", since = "1.0.0")]1140    pub fn metadata(&self) -> io::Result<Metadata> {1141        self.inner.file_attr().map(Metadata)1142    }11431144    /// Creates a new `File` instance that shares the same underlying file handle1145    /// as the existing `File` instance. Reads, writes, and seeks will affect1146    /// both `File` instances simultaneously.1147    ///1148    /// # Examples1149    ///1150    /// Creates two handles for a file named `foo.txt`:1151    ///1152    /// ```no_run1153    /// use std::fs::File;1154    ///1155    /// fn main() -> std::io::Result<()> {1156    ///     let mut file = File::open("foo.txt")?;1157    ///     let file_copy = file.try_clone()?;1158    ///     Ok(())1159    /// }1160    /// ```1161    ///1162    /// Assuming there’s a file named `foo.txt` with contents `abcdef\n`, create1163    /// two handles, seek one of them, and read the remaining bytes from the1164    /// other handle:1165    ///1166    /// ```no_run1167    /// use std::fs::File;1168    /// use std::io::SeekFrom;1169    /// use std::io::prelude::*;1170    ///1171    /// fn main() -> std::io::Result<()> {1172    ///     let mut file = File::open("foo.txt")?;1173    ///     let mut file_copy = file.try_clone()?;1174    ///1175    ///     file.seek(SeekFrom::Start(3))?;1176    ///1177    ///     let mut contents = vec![];1178    ///     file_copy.read_to_end(&mut contents)?;1179    ///     assert_eq!(contents, b"def\n");1180    ///     Ok(())1181    /// }1182    /// ```1183    #[stable(feature = "file_try_clone", since = "1.9.0")]1184    pub fn try_clone(&self) -> io::Result<File> {1185        Ok(File { inner: self.inner.duplicate()? })1186    }11871188    /// Changes the permissions on the underlying file.1189    ///1190    /// # Platform-specific behavior1191    ///1192    /// This function currently corresponds to the `fchmod` function on Unix and1193    /// the `SetFileInformationByHandle` function on Windows. Note that, this1194    /// [may change in the future][changes].1195    ///1196    /// [changes]: io#platform-specific-behavior1197    ///1198    /// # Errors1199    ///1200    /// This function will return an error if the user lacks permission change1201    /// attributes on the underlying file. It may also return an error in other1202    /// os-specific unspecified cases.1203    ///1204    /// # Examples1205    ///1206    /// ```no_run1207    /// fn main() -> std::io::Result<()> {1208    ///     use std::fs::File;1209    ///1210    ///     let file = File::open("foo.txt")?;1211    ///     let mut perms = file.metadata()?.permissions();1212    ///     perms.set_readonly(true);1213    ///     file.set_permissions(perms)?;1214    ///     Ok(())1215    /// }1216    /// ```1217    ///1218    /// Note that this method alters the permissions of the underlying file,1219    /// even though it takes `&self` rather than `&mut self`.1220    #[doc(alias = "fchmod", alias = "SetFileInformationByHandle")]1221    #[stable(feature = "set_permissions_atomic", since = "1.16.0")]1222    pub fn set_permissions(&self, perm: Permissions) -> io::Result<()> {1223        self.inner.set_permissions(perm.0)1224    }12251226    /// Changes the timestamps of the underlying file.1227    ///1228    /// # Platform-specific behavior1229    ///1230    /// This function currently corresponds to the `futimens` function on Unix (falling back to1231    /// `futimes` on macOS before 10.13) and the `SetFileTime` function on Windows. Note that this1232    /// [may change in the future][changes].1233    ///1234    /// On most platforms, including UNIX and Windows platforms, this function can also change the1235    /// timestamps of a directory. To get a `File` representing a directory in order to call1236    /// `set_times`, open the directory with `File::open` without attempting to obtain write1237    /// permission.1238    ///1239    /// [changes]: io#platform-specific-behavior1240    ///1241    /// # Errors1242    ///1243    /// This function will return an error if the user lacks permission to change timestamps on the1244    /// underlying file. It may also return an error in other os-specific unspecified cases.1245    ///1246    /// This function may return an error if the operating system lacks support to change one or1247    /// more of the timestamps set in the `FileTimes` structure.1248    ///1249    /// # Examples1250    ///1251    /// ```no_run1252    /// fn main() -> std::io::Result<()> {1253    ///     use std::fs::{self, File, FileTimes};1254    ///1255    ///     let src = fs::metadata("src")?;1256    ///     let dest = File::open("dest")?;1257    ///     let times = FileTimes::new()1258    ///         .set_accessed(src.accessed()?)1259    ///         .set_modified(src.modified()?);1260    ///     dest.set_times(times)?;1261    ///     Ok(())1262    /// }1263    /// ```1264    #[stable(feature = "file_set_times", since = "1.75.0")]1265    #[doc(alias = "futimens")]1266    #[doc(alias = "futimes")]1267    #[doc(alias = "SetFileTime")]1268    pub fn set_times(&self, times: FileTimes) -> io::Result<()> {1269        self.inner.set_times(times.0)1270    }12711272    /// Changes the modification time of the underlying file.1273    ///1274    /// This is an alias for `set_times(FileTimes::new().set_modified(time))`.1275    #[stable(feature = "file_set_times", since = "1.75.0")]1276    #[inline]1277    pub fn set_modified(&self, time: SystemTime) -> io::Result<()> {1278        self.set_times(FileTimes::new().set_modified(time))1279    }1280}12811282// In addition to the `impl`s here, `File` also has `impl`s for1283// `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and1284// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and1285// `AsHandle`/`From<OwnedHandle>`/`Into<OwnedHandle>` and1286// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows.12871288impl AsInner<fs_imp::File> for File {1289    #[inline]1290    fn as_inner(&self) -> &fs_imp::File {1291        &self.inner1292    }1293}1294impl FromInner<fs_imp::File> for File {1295    fn from_inner(f: fs_imp::File) -> File {1296        File { inner: f }1297    }1298}1299impl IntoInner<fs_imp::File> for File {1300    fn into_inner(self) -> fs_imp::File {1301        self.inner1302    }1303}13041305#[stable(feature = "rust1", since = "1.0.0")]1306impl fmt::Debug for File {1307    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {1308        self.inner.fmt(f)1309    }1310}13111312/// Indicates how much extra capacity is needed to read the rest of the file.1313fn buffer_capacity_required(mut file: &File) -> Option<usize> {1314    let size = file.metadata().map(|m| m.len()).ok()?;1315    let pos = file.stream_position().ok()?;1316    // Don't worry about `usize` overflow because reading will fail regardless1317    // in that case.1318    Some(size.saturating_sub(pos) as usize)1319}13201321#[stable(feature = "rust1", since = "1.0.0")]1322impl Read for &File {1323    /// Reads some bytes from the file.1324    ///1325    /// See [`Read::read`] docs for more info.1326    ///1327    /// # Platform-specific behavior1328    ///1329    /// This function currently corresponds to the `read` function on Unix and1330    /// the `NtReadFile` function on Windows. Note that this [may change in1331    /// the future][changes].1332    ///1333    /// [changes]: io#platform-specific-behavior1334    #[inline]1335    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {1336        self.inner.read(buf)1337    }13381339    /// Like `read`, except that it reads into a slice of buffers.1340    ///1341    /// See [`Read::read_vectored`] docs for more info.1342    ///1343    /// # Platform-specific behavior1344    ///1345    /// This function currently corresponds to the `readv` function on Unix and1346    /// falls back to the `read` implementation on Windows. Note that this1347    /// [may change in the future][changes].1348    ///1349    /// [changes]: io#platform-specific-behavior1350    #[inline]1351    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {1352        self.inner.read_vectored(bufs)1353    }13541355    #[inline]1356    fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> {1357        self.inner.read_buf(cursor)1358    }13591360    /// Determines if `File` has an efficient `read_vectored` implementation.1361    ///1362    /// See [`Read::is_read_vectored`] docs for more info.1363    ///1364    /// # Platform-specific behavior1365    ///1366    /// This function currently returns `true` on Unix and `false` on Windows.1367    /// Note that this [may change in the future][changes].1368    ///1369    /// [changes]: io#platform-specific-behavior1370    #[inline]1371    fn is_read_vectored(&self) -> bool {1372        self.inner.is_read_vectored()1373    }13741375    // Reserves space in the buffer based on the file size when available.1376    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {1377        let size = buffer_capacity_required(self);1378        buf.try_reserve(size.unwrap_or(0))?;1379        io::default_read_to_end(self, buf, size)1380    }13811382    // Reserves space in the buffer based on the file size when available.1383    fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {1384        let size = buffer_capacity_required(self);1385        buf.try_reserve(size.unwrap_or(0))?;1386        io::default_read_to_string(self, buf, size)1387    }1388}1389#[stable(feature = "rust1", since = "1.0.0")]1390impl Write for &File {1391    /// Writes some bytes to the file.1392    ///1393    /// See [`Write::write`] docs for more info.1394    ///1395    /// # Platform-specific behavior1396    ///1397    /// This function currently corresponds to the `write` function on Unix and1398    /// the `NtWriteFile` function on Windows. Note that this [may change in1399    /// the future][changes].1400    ///1401    /// [changes]: io#platform-specific-behavior1402    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {1403        self.inner.write(buf)1404    }14051406    /// Like `write`, except that it writes into a slice of buffers.1407    ///1408    /// See [`Write::write_vectored`] docs for more info.1409    ///1410    /// # Platform-specific behavior1411    ///1412    /// This function currently corresponds to the `writev` function on Unix1413    /// and falls back to the `write` implementation on Windows. Note that this1414    /// [may change in the future][changes].1415    ///1416    /// [changes]: io#platform-specific-behavior1417    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {1418        self.inner.write_vectored(bufs)1419    }14201421    /// Determines if `File` has an efficient `write_vectored` implementation.1422    ///1423    /// See [`Write::is_write_vectored`] docs for more info.1424    ///1425    /// # Platform-specific behavior1426    ///1427    /// This function currently returns `true` on Unix and `false` on Windows.1428    /// Note that this [may change in the future][changes].1429    ///1430    /// [changes]: io#platform-specific-behavior1431    #[inline]1432    fn is_write_vectored(&self) -> bool {1433        self.inner.is_write_vectored()1434    }14351436    /// Flushes the file, ensuring that all intermediately buffered contents1437    /// reach their destination.1438    ///1439    /// See [`Write::flush`] docs for more info.1440    ///1441    /// # Platform-specific behavior1442    ///1443    /// Since a `File` structure doesn't contain any buffers, this function is1444    /// currently a no-op on Unix and Windows. Note that this [may change in1445    /// the future][changes].1446    ///1447    /// [changes]: io#platform-specific-behavior1448    #[inline]1449    fn flush(&mut self) -> io::Result<()> {1450        self.inner.flush()1451    }1452}1453#[stable(feature = "rust1", since = "1.0.0")]1454impl Seek for &File {1455    /// Seek to an offset, in bytes in a file.1456    ///1457    /// See [`Seek::seek`] docs for more info.1458    ///1459    /// # Platform-specific behavior1460    ///1461    /// This function currently corresponds to the `lseek64` function on Unix1462    /// and the `SetFilePointerEx` function on Windows. Note that this [may1463    /// change in the future][changes].1464    ///1465    /// [changes]: io#platform-specific-behavior1466    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {1467        self.inner.seek(pos)1468    }14691470    /// Returns the length of this file (in bytes).1471    ///1472    /// See [`Seek::stream_len`] docs for more info.1473    ///1474    /// # Platform-specific behavior1475    ///1476    /// This function currently corresponds to the `statx` function on Linux1477    /// (with fallbacks) and the `GetFileSizeEx` function on Windows. Note that1478    /// this [may change in the future][changes].1479    ///1480    /// [changes]: io#platform-specific-behavior1481    fn stream_len(&mut self) -> io::Result<u64> {1482        if let Some(result) = self.inner.size() {1483            return result;1484        }1485        io::stream_len_default(self)1486    }14871488    fn stream_position(&mut self) -> io::Result<u64> {1489        self.inner.tell()1490    }1491}14921493#[stable(feature = "rust1", since = "1.0.0")]1494impl Read for File {1495    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {1496        (&*self).read(buf)1497    }1498    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {1499        (&*self).read_vectored(bufs)1500    }1501    fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> {1502        (&*self).read_buf(cursor)1503    }1504    #[inline]1505    fn is_read_vectored(&self) -> bool {1506        (&&*self).is_read_vectored()1507    }1508    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {1509        (&*self).read_to_end(buf)1510    }1511    fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {1512        (&*self).read_to_string(buf)1513    }1514}1515#[stable(feature = "rust1", since = "1.0.0")]1516impl Write for File {1517    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {1518        (&*self).write(buf)1519    }1520    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {1521        (&*self).write_vectored(bufs)1522    }1523    #[inline]1524    fn is_write_vectored(&self) -> bool {1525        (&&*self).is_write_vectored()1526    }1527    #[inline]1528    fn flush(&mut self) -> io::Result<()> {1529        (&*self).flush()1530    }1531}1532#[stable(feature = "rust1", since = "1.0.0")]1533impl Seek for File {1534    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {1535        (&*self).seek(pos)1536    }1537    fn stream_len(&mut self) -> io::Result<u64> {1538        (&*self).stream_len()1539    }1540    fn stream_position(&mut self) -> io::Result<u64> {1541        (&*self).stream_position()1542    }1543}1544impl crate::io::IoHandle for File {}15451546impl Dir {1547    /// Attempts to open a directory at `path` in read-only mode.1548    ///1549    /// # Errors1550    ///1551    /// This function will return an error if `path` does not point to an existing directory.1552    /// Other errors may also be returned according to [`OpenOptions::open`].1553    ///1554    /// # Examples1555    ///1556    /// ```no_run1557    /// #![feature(dirfd)]1558    /// use std::{fs::Dir, io};1559    ///1560    /// fn main() -> std::io::Result<()> {1561    ///     let dir = Dir::open("foo")?;1562    ///     let mut f = dir.open_file("bar.txt")?;1563    ///     let contents = io::read_to_string(f)?;1564    ///     assert_eq!(contents, "Hello, world!");1565    ///     Ok(())1566    /// }1567    /// ```1568    #[unstable(feature = "dirfd", issue = "120426")]1569    pub fn open<P: AsRef<Path>>(path: P) -> io::Result<Self> {1570        fs_imp::Dir::open(path.as_ref(), &OpenOptions::new().read(true).0)1571            .map(|inner| Self { inner })1572    }15731574    /// Attempts to open a file in read-only mode relative to this directory.1575    ///1576    /// # Errors1577    ///1578    /// This function will return an error if `path` does not point to an existing file.1579    /// Other errors may also be returned according to [`OpenOptions::open`].1580    ///1581    /// # Examples1582    ///1583    /// ```no_run1584    /// #![feature(dirfd)]1585    /// use std::{fs::Dir, io};1586    ///1587    /// fn main() -> std::io::Result<()> {1588    ///     let dir = Dir::open("foo")?;1589    ///     let mut f = dir.open_file("bar.txt")?;1590    ///     let contents = io::read_to_string(f)?;1591    ///     assert_eq!(contents, "Hello, world!");1592    ///     Ok(())1593    /// }1594    /// ```1595    #[unstable(feature = "dirfd", issue = "120426")]1596    pub fn open_file<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {1597        self.inner1598            .open_file(path.as_ref(), &OpenOptions::new().read(true).0)1599            .map(|f| File { inner: f })1600    }1601}16021603impl AsInner<fs_imp::Dir> for Dir {1604    #[inline]1605    fn as_inner(&self) -> &fs_imp::Dir {1606        &self.inner1607    }1608}1609impl FromInner<fs_imp::Dir> for Dir {1610    fn from_inner(f: fs_imp::Dir) -> Dir {1611        Dir { inner: f }1612    }1613}1614impl IntoInner<fs_imp::Dir> for Dir {1615    fn into_inner(self) -> fs_imp::Dir {1616        self.inner1617    }1618}16191620#[unstable(feature = "dirfd", issue = "120426")]1621impl fmt::Debug for Dir {1622    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {1623        self.inner.fmt(f)1624    }1625}16261627impl OpenOptions {1628    /// Creates a blank new set of options ready for configuration.1629    ///1630    /// All options are initially set to `false`.1631    ///1632    /// # Examples1633    ///1634    /// ```no_run1635    /// use std::fs::OpenOptions;1636    ///1637    /// let mut options = OpenOptions::new();1638    /// let file = options.read(true).open("foo.txt");1639    /// ```1640    #[cfg_attr(not(test), rustc_diagnostic_item = "open_options_new")]1641    #[stable(feature = "rust1", since = "1.0.0")]1642    #[must_use]1643    pub fn new() -> Self {1644        OpenOptions(fs_imp::OpenOptions::new())1645    }16461647    /// Sets the option for read access.1648    ///1649    /// This option, when true, will indicate that the file should be1650    /// `read`-able if opened.1651    ///1652    /// # Examples1653    ///1654    /// ```no_run1655    /// use std::fs::OpenOptions;1656    ///1657    /// let file = OpenOptions::new().read(true).open("foo.txt");1658    /// ```1659    #[stable(feature = "rust1", since = "1.0.0")]1660    pub fn read(&mut self, read: bool) -> &mut Self {1661        self.0.read(read);1662        self1663    }16641665    /// Sets the option for write access.1666    ///1667    /// This option, when true, will indicate that the file should be1668    /// `write`-able if opened.1669    ///1670    /// If the file already exists, any write calls on it will overwrite its1671    /// contents, without truncating it.1672    ///1673    /// # Examples1674    ///1675    /// ```no_run1676    /// use std::fs::OpenOptions;1677    ///1678    /// let file = OpenOptions::new().write(true).open("foo.txt");1679    /// ```1680    #[stable(feature = "rust1", since = "1.0.0")]1681    pub fn write(&mut self, write: bool) -> &mut Self {1682        self.0.write(write);1683        self1684    }16851686    /// Sets the option for the append mode.1687    ///1688    /// This option, when true, means that writes will append to a file instead1689    /// of overwriting previous contents.1690    /// Note that setting `.write(true).append(true)` has the same effect as1691    /// setting only `.append(true)`.1692    ///1693    /// Append mode guarantees that writes will be positioned at the current end of file,1694    /// even when there are other processes or threads appending to the same file. This is1695    /// unlike <code>[seek]\([SeekFrom]::[End]\(0))</code> followed by `write()`, which1696    /// has a race between seeking and writing during which another writer can write, with1697    /// our `write()` overwriting their data.1698    ///1699    /// Keep in mind that this does not necessarily guarantee that data appended by1700    /// different processes or threads does not interleave. The amount of data accepted a1701    /// single `write()` call depends on the operating system and file system. A1702    /// successful `write()` is allowed to write only part of the given data, so even if1703    /// you're careful to provide the whole message in a single call to `write()`, there1704    /// is no guarantee that it will be written out in full. If you rely on the filesystem1705    /// accepting the message in a single write, make sure that all data that belongs1706    /// together is written in one operation. This can be done by concatenating strings1707    /// before passing them to [`write()`].1708    ///1709    /// If a file is opened with both read and append access, beware that after1710    /// opening, and after every write, the position for reading may be set at the1711    /// end of the file. So, before writing, save the current position (using1712    /// <code>[Seek]::[stream_position]</code>), and restore it before the next read.1713    ///1714    /// ## Note1715    ///1716    /// This function doesn't create the file if it doesn't exist. Use the1717    /// [`OpenOptions::create`] method to do so.1718    ///1719    /// [`write()`]: Write::write "io::Write::write"1720    /// [`flush()`]: Write::flush "io::Write::flush"1721    /// [stream_position]: Seek::stream_position "io::Seek::stream_position"1722    /// [seek]: Seek::seek "io::Seek::seek"1723    /// [Current]: SeekFrom::Current "io::SeekFrom::Current"1724    /// [End]: SeekFrom::End "io::SeekFrom::End"1725    ///1726    /// # Examples1727    ///1728    /// ```no_run1729    /// use std::fs::OpenOptions;1730    ///1731    /// let file = OpenOptions::new().append(true).open("foo.txt");1732    /// ```1733    #[stable(feature = "rust1", since = "1.0.0")]1734    pub fn append(&mut self, append: bool) -> &mut Self {1735        self.0.append(append);1736        self1737    }17381739    /// Sets the option for truncating a previous file.1740    ///1741    /// If a file is successfully opened with this option set to true, it will truncate1742    /// the file to 0 length if it already exists.1743    ///1744    /// The file must be opened with write access for truncate to work.1745    ///1746    /// # Examples1747    ///1748    /// ```no_run1749    /// use std::fs::OpenOptions;1750    ///1751    /// let file = OpenOptions::new().write(true).truncate(true).open("foo.txt");1752    /// ```1753    #[stable(feature = "rust1", since = "1.0.0")]1754    pub fn truncate(&mut self, truncate: bool) -> &mut Self {1755        self.0.truncate(truncate);1756        self1757    }17581759    /// Sets the option to create a new file, or open it if it already exists.1760    ///1761    /// In order for the file to be created, [`OpenOptions::write`] or1762    /// [`OpenOptions::append`] access must be used.1763    ///1764    /// See also [`std::fs::write()`][self::write] for a simple function to1765    /// create a file with some given data.1766    ///1767    /// # Errors1768    ///1769    /// If `.create(true)` is set without `.write(true)` or `.append(true)`,1770    /// calling [`open`](Self::open) will fail with [`InvalidInput`](io::ErrorKind::InvalidInput) error.1771    /// # Examples1772    ///1773    /// ```no_run1774    /// use std::fs::OpenOptions;1775    ///1776    /// let file = OpenOptions::new().write(true).create(true).open("foo.txt");1777    /// ```1778    #[stable(feature = "rust1", since = "1.0.0")]1779    pub fn create(&mut self, create: bool) -> &mut Self {1780        self.0.create(create);1781        self1782    }17831784    /// Sets the option to create a new file, failing if it already exists.1785    ///1786    /// No file is allowed to exist at the target location, also no (dangling) symlink. In this1787    /// way, if the call succeeds, the file returned is guaranteed to be new.1788    /// If a file exists at the target location, creating a new file will fail with [`AlreadyExists`]1789    /// or another error based on the situation. See [`OpenOptions::open`] for a1790    /// non-exhaustive list of likely errors.1791    ///1792    /// This option is useful because it is atomic. Otherwise between checking1793    /// whether a file exists and creating a new one, the file may have been1794    /// created by another process (a [TOCTOU] race condition / attack).1795    ///1796    /// If `.create_new(true)` is set, [`.create()`] and [`.truncate()`] are1797    /// ignored.1798    ///1799    /// The file must be opened with write or append access in order to create1800    /// a new file.1801    ///1802    /// [`.create()`]: OpenOptions::create1803    /// [`.truncate()`]: OpenOptions::truncate1804    /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists1805    /// [TOCTOU]: self#time-of-check-to-time-of-use-toctou1806    ///1807    /// # Examples1808    ///1809    /// ```no_run1810    /// use std::fs::OpenOptions;1811    ///1812    /// let file = OpenOptions::new().write(true)1813    ///                              .create_new(true)1814    ///                              .open("foo.txt");1815    /// ```1816    #[stable(feature = "expand_open_options2", since = "1.9.0")]1817    pub fn create_new(&mut self, create_new: bool) -> &mut Self {1818        self.0.create_new(create_new);1819        self1820    }18211822    /// Opens a file at `path` with the options specified by `self`.1823    ///1824    /// # Errors1825    ///1826    /// This function will return an error under a number of different1827    /// circumstances. Some of these error conditions are listed here, together1828    /// with their [`io::ErrorKind`]. The mapping to [`io::ErrorKind`]s is not1829    /// part of the compatibility contract of the function.1830    ///1831    /// * [`NotFound`]: The specified file does not exist and neither `create`1832    ///   or `create_new` is set.1833    /// * [`NotFound`]: One of the directory components of the file path does1834    ///   not exist.1835    /// * [`PermissionDenied`]: The user lacks permission to get the specified1836    ///   access rights for the file.1837    /// * [`PermissionDenied`]: The user lacks permission to open one of the1838    ///   directory components of the specified path.1839    /// * [`AlreadyExists`]: `create_new` was specified and the file already1840    ///   exists.1841    /// * [`InvalidInput`]: Invalid combinations of open options (truncate1842    ///   without write access, create without write or append access,1843    ///   no access mode set, etc.).1844    ///1845    /// The following errors don't match any existing [`io::ErrorKind`] at the moment:1846    /// * One of the directory components of the specified file path1847    ///   was not, in fact, a directory.1848    /// * Filesystem-level errors: full disk, write permission1849    ///   requested on a read-only file system, exceeded disk quota, too many1850    ///   open files, too long filename, too many symbolic links in the1851    ///   specified path (Unix-like systems only), etc.1852    ///1853    /// # Examples1854    ///1855    /// ```no_run1856    /// use std::fs::OpenOptions;1857    ///1858    /// let file = OpenOptions::new().read(true).open("foo.txt");1859    /// ```1860    ///1861    /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists1862    /// [`InvalidInput`]: io::ErrorKind::InvalidInput1863    /// [`NotFound`]: io::ErrorKind::NotFound1864    /// [`PermissionDenied`]: io::ErrorKind::PermissionDenied1865    #[stable(feature = "rust1", since = "1.0.0")]1866    pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {1867        self._open(path.as_ref())1868    }18691870    fn _open(&self, path: &Path) -> io::Result<File> {1871        fs_imp::File::open(path, &self.0).map(|inner| File { inner })1872    }1873}18741875impl AsInner<fs_imp::OpenOptions> for OpenOptions {1876    #[inline]1877    fn as_inner(&self) -> &fs_imp::OpenOptions {1878        &self.01879    }1880}18811882impl AsInnerMut<fs_imp::OpenOptions> for OpenOptions {1883    #[inline]1884    fn as_inner_mut(&mut self) -> &mut fs_imp::OpenOptions {1885        &mut self.01886    }1887}18881889impl Metadata {1890    /// Returns the file type for this metadata.1891    ///1892    /// # Examples1893    ///1894    /// ```no_run1895    /// fn main() -> std::io::Result<()> {1896    ///     use std::fs;1897    ///1898    ///     let metadata = fs::metadata("foo.txt")?;1899    ///1900    ///     println!("{:?}", metadata.file_type());1901    ///     Ok(())1902    /// }1903    /// ```1904    #[must_use]1905    #[stable(feature = "file_type", since = "1.1.0")]1906    pub fn file_type(&self) -> FileType {1907        FileType(self.0.file_type())1908    }19091910    /// Returns `true` if this metadata is for a directory. The1911    /// result is mutually exclusive to the result of1912    /// [`Metadata::is_file`], and will be false for symlink metadata1913    /// obtained from [`symlink_metadata`].1914    ///1915    /// # Examples1916    ///1917    /// ```no_run1918    /// fn main() -> std::io::Result<()> {1919    ///     use std::fs;1920    ///1921    ///     let metadata = fs::metadata("foo.txt")?;1922    ///1923    ///     assert!(!metadata.is_dir());1924    ///     Ok(())1925    /// }1926    /// ```1927    #[must_use]1928    #[stable(feature = "rust1", since = "1.0.0")]1929    pub fn is_dir(&self) -> bool {1930        self.file_type().is_dir()1931    }19321933    /// Returns `true` if this metadata is for a regular file. The1934    /// result is mutually exclusive to the result of1935    /// [`Metadata::is_dir`], and will be false for symlink metadata1936    /// obtained from [`symlink_metadata`].1937    ///1938    /// When the goal is simply to read from (or write to) the source, the most1939    /// reliable way to test the source can be read (or written to) is to open1940    /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on1941    /// a Unix-like system for example. See [`File::open`] or1942    /// [`OpenOptions::open`] for more information.1943    ///1944    /// # Examples1945    ///1946    /// ```no_run1947    /// use std::fs;1948    ///1949    /// fn main() -> std::io::Result<()> {1950    ///     let metadata = fs::metadata("foo.txt")?;1951    ///1952    ///     assert!(metadata.is_file());1953    ///     Ok(())1954    /// }1955    /// ```1956    #[must_use]1957    #[stable(feature = "rust1", since = "1.0.0")]1958    pub fn is_file(&self) -> bool {1959        self.file_type().is_file()1960    }19611962    /// Returns `true` if this metadata is for a symbolic link.1963    ///1964    /// # Examples1965    ///1966    #[cfg_attr(unix, doc = "```no_run")]1967    #[cfg_attr(not(unix), doc = "```ignore")]1968    /// use std::fs;1969    /// use std::path::Path;1970    /// use std::os::unix::fs::symlink;1971    ///1972    /// fn main() -> std::io::Result<()> {1973    ///     let link_path = Path::new("link");1974    ///     symlink("/origin_does_not_exist/", link_path)?;1975    ///1976    ///     let metadata = fs::symlink_metadata(link_path)?;1977    ///1978    ///     assert!(metadata.is_symlink());1979    ///     Ok(())1980    /// }1981    /// ```1982    #[must_use]1983    #[stable(feature = "is_symlink", since = "1.58.0")]1984    pub fn is_symlink(&self) -> bool {1985        self.file_type().is_symlink()1986    }19871988    /// Returns the size of the file, in bytes, this metadata is for.1989    ///1990    /// # Examples1991    ///1992    /// ```no_run1993    /// use std::fs;1994    ///1995    /// fn main() -> std::io::Result<()> {1996    ///     let metadata = fs::metadata("foo.txt")?;1997    ///1998    ///     assert_eq!(0, metadata.len());1999    ///     Ok(())2000    /// }