//! 文件系统操作
//!
//! 该模块包含一些操作本地文件系统内容的基本方法。
//! 该模块中的所有方法均表示跨平台文件系统操作。
//! 在 `std::os::$platform` 的扩展名 traits 中可以找到特定于平台的其他功能。
//!

#![stable(feature = "rust1", since = "1.0.0")]
#![deny(unsafe_op_in_unsafe_fn)]

#[cfg(all(test, not(any(target_os = "emscripten", target_env = "sgx"))))]
mod tests;

use crate::ffi::OsString;
use crate::fmt;
use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut, Read, Seek, SeekFrom, Write};
use crate::path::{Path, PathBuf};
use crate::sealed::Sealed;
use crate::sys::fs as fs_imp;
use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner};
use crate::time::SystemTime;

/// 提供对文件系统上打开文件的访问权限的对象。
///
/// 可以通过打开 `File` 的选项来读取或者写入 `File` 的实例。文件还实现 [`Seek`]，以更改文件内部包含的逻辑游标。
///
/// 文件离开作用域时将自动关闭。`Drop` 的实现将忽略在关闭时检测到的错误。如果必须手动处理这些错误，请使用方法 [`sync_all`]。
///
/// # Examples
///
/// 创建一个新文件并向其写入字节 (您也可以使用 [`write()`]) ：
///
/// ```no_run
/// use std::fs::File;
/// use std::io::prelude::*;
///
/// fn main() -> std::io::Result<()> {
///     let mut file = File::create("foo.txt")?;
///     file.write_all(b"Hello, world!")?;
///     Ok(())
/// }
/// ```
///
/// 将文件内容读入 [`String`] (也可以使用 [`read`]) ：
///
/// ```no_run
/// use std::fs::File;
/// use std::io::prelude::*;
///
/// fn main() -> std::io::Result<()> {
///     let mut file = File::open("foo.txt")?;
///     let mut contents = String::new();
///     file.read_to_string(&mut contents)?;
///     assert_eq!(contents, "Hello, world!");
///     Ok(())
/// }
/// ```
///
/// 使用缓冲的 [`Read`] 来读取文件的内容可能会更有效。这可以用 [`BufReader<R>`] 完成：
///
/// ```no_run
/// use std::fs::File;
/// use std::io::BufReader;
/// use std::io::prelude::*;
///
/// fn main() -> std::io::Result<()> {
///     let file = File::open("foo.txt")?;
///     let mut buf_reader = BufReader::new(file);
///     let mut contents = String::new();
///     buf_reader.read_to_string(&mut contents)?;
///     assert_eq!(contents, "Hello, world!");
///     Ok(())
/// }
/// ```
///
/// 请注意，虽然读写方法需要一个 `&mut File`，但由于 [`Read`] 和 [`Write`] 的接口，`&File` 的持有者仍然可以修改文件，可以通过采用 `&File` 的方法，也可以通过检索底层操作系统对象并以这种方式修改文件。
///
/// 另外，许多操作系统允许通过不同的进程并发修改文件。避免假定持有 `&File` 意味着文件不会更改。
///
/// # 特定于平台的行为
///
/// 在 Windows 上，`File` 的 [`Read`] 和 [`Write`] traits 的实现执行同步的 I/O 操作。因此，必须没有为异步 I/O 打开底层文件 (例如使用 `FILE_FLAG_OVERLAPPED`)。
///
/// [`BufReader<R>`]: io::BufReader
/// [`sync_all`]: File::sync_all
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "File")]
pub struct File {
    inner: fs_imp::File,
}

/// 有关文件的元数据信息。
///
/// 此结构体是从 [`metadata`] 或 [`symlink_metadata`] 函数或方法返回的，表示有关文件的已知元数据，例如其权限，大小，修改时间等。
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Clone)]
pub struct Metadata(fs_imp::FileAttr);

/// 遍历目录中的条目。
///
/// 该迭代器从该模块的 [`read_dir`] 函数返回，将产生一个 <code>[io::Result]<[DirEntry]></code> 实例。
/// 通过 [`DirEntry`]，可以了解类似条目路径以及可能的其他元数据的信息。
///
/// 该迭代器返回条目的顺序取决于平台和文件系统。
///
/// # Errors
///
/// 如果在迭代过程中出现某种间歇性的 IO 错误，则该 [`io::Result`] 将是 [`Err`]。
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct ReadDir(fs_imp::ReadDir);

/// [`ReadDir`] 迭代器返回的条目。
///
/// `DirEntry` 的实例表示文件系统上目录内的一个条目。
/// 可以通过方法检查每个条目，以通过全平台扩展 traits 了解完整路径或可能的其他元数据。
///
///
/// # 特定于平台的行为
///
/// 在 Unix 上，`DirEntry` 结构体包含对打开目录的内部引用。
/// 即使在 `ReadDir` 迭代器丢弃之后，持有 `DirEntry` 对象也会消耗文件句柄。
///
/// 注意这个 [将来可能会发生变化][changes]。
///
/// [changes]: io#platform-specific-behavior
///
#[stable(feature = "rust1", since = "1.0.0")]
pub struct DirEntry(fs_imp::DirEntry);

/// 可用于配置文件打开方式的选项和标志。
///
/// 此构建器提供了配置 [`File`] 的打开方式以及打开的文件上允许哪些操作的功能。
/// [`File::open`] 和 [`File::create`] 方法是使用此构建器的常用选项的别名。
///
/// 一般而言，使用 `OpenOptions` 时，首先要调用 [`OpenOptions::new`]，然后链式调用方法以设置每个选项，然后调用 [`OpenOptions::open`]，传递要打开的文件的路径。
///
/// 这将为您提供一个内部带有 [`File`] 的 [`io::Result`]，您可以对其进行进一步的操作。
///
/// # Examples
///
/// 打开一个文件以读取：
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new().read(true).open("foo.txt");
/// ```
///
/// 打开一个文件进行读写，如果不存在则创建一个文件：
///
/// ```no_run
/// use std::fs::OpenOptions;
///
/// let file = OpenOptions::new()
///             .read(true)
///             .write(true)
///             .create(true)
///             .open("foo.txt");
/// ```
///
///
///
///
///
#[derive(Clone, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct OpenOptions(fs_imp::OpenOptions);

/// 文件上各种时间戳的表示。
#[derive(Copy, Clone, Debug, Default)]
#[unstable(feature = "file_set_times", issue = "98245")]
pub struct FileTimes(fs_imp::FileTimes);

/// 表示文件上的各种权限。
///
/// 该模块当前仅提供一点信息 [`Permissions::readonly`]，该信息在所有当前支持的平台上公开。
/// 特定于 Unix 的功能 (例如模式位) 可通过 [`PermissionsExt`] trait 获得。
///
/// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt
///
///
#[derive(Clone, PartialEq, Eq, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Permissions(fs_imp::FilePermissions);

/// 表示文件类型的结构体，每个文件类型都有访问器。
/// 通过 [`Metadata::file_type`] 方法返回。
#[stable(feature = "file_type", since = "1.1.0")]
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(not(test), rustc_diagnostic_item = "FileType")]
pub struct FileType(fs_imp::FileType);

/// 用于以各种方式创建目录的构建器。
///
/// 该构建器还支持特定于平台的选项。
#[stable(feature = "dir_builder", since = "1.6.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "DirBuilder")]
#[derive(Debug)]
pub struct DirBuilder {
    inner: fs_imp::DirBuilder,
    recursive: bool,
}

/// 将文件的全部内容读取为字节 vector。
///
/// 这是使用 [`File::open`] 和 [`read_to_end`] 且导入次数较少且没有中间变量的便捷函数。
///
///
/// [`read_to_end`]: Read::read_to_end
///
/// # Errors
///
/// 如果 `path` 还不存在，则此函数将返回错误。
/// 根据 [`OpenOptions::open`]，可能还会返回其他错误。
///
/// 如果在读取 [`io::ErrorKind::Interrupted`] 以外的其他类型的错误时遇到错误，它也会返回错误。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
/// use std::net::SocketAddr;
///
/// fn main() -> Result<(), Box<dyn std::error::Error + 'static>> {
///     let foo: SocketAddr = String::from_utf8_lossy(&fs::read("address.txt")?).parse()?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "fs_read_write_bytes", since = "1.26.0")]
pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> {
    fn inner(path: &Path) -> io::Result<Vec<u8>> {
        let mut file = File::open(path)?;
        let size = file.metadata().map(|m| m.len() as usize).ok();
        let mut bytes = Vec::with_capacity(size.unwrap_or(0));
        io::default_read_to_end(&mut file, &mut bytes, size)?;
        Ok(bytes)
    }
    inner(path.as_ref())
}

/// 将文件的全部内容读取为字符串。
///
/// 这是使用 [`File::open`] 和 [`read_to_string`] 且导入次数较少且没有中间变量的便捷函数。
///
/// [`read_to_string`]: Read::read_to_string
///
/// # Errors
///
/// 如果 `path` 还不存在，则此函数将返回错误。
/// 根据 [`OpenOptions::open`]，可能还会返回其他错误。
///
/// 如果在读取 [`io::ErrorKind::Interrupted`] 以外的其他错误时遇到错误，或者文件的内容不是有效的 UTF-8，它也会返回错误。
///
///
/// # Examples
///
/// ```no_run
/// use std::fs;
/// use std::net::SocketAddr;
/// use std::error::Error;
///
/// fn main() -> Result<(), Box<dyn Error>> {
///     let foo: SocketAddr = fs::read_to_string("address.txt")?.parse()?;
///     Ok(())
/// }
/// ```
///
///
#[stable(feature = "fs_read_write", since = "1.26.0")]
pub fn read_to_string<P: AsRef<Path>>(path: P) -> io::Result<String> {
    fn inner(path: &Path) -> io::Result<String> {
        let mut file = File::open(path)?;
        let size = file.metadata().map(|m| m.len() as usize).ok();
        let mut string = String::with_capacity(size.unwrap_or(0));
        io::default_read_to_string(&mut file, &mut string, size)?;
        Ok(string)
    }
    inner(path.as_ref())
}

/// 写一个切片作为文件的全部内容。
///
/// 如果该函数不存在，则此函数将创建一个文件，如果存在，则将完全替换其内容。
///
///
/// 根据平台，如果完整目录路径不存在，此函数可能会失败。
///
/// 这是使用 [`File::create`] 和 [`write_all`] 且导入次数较少的便捷函数。
///
/// [`write_all`]: Write::write_all
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::write("foo.txt", b"Lorem ipsum")?;
///     fs::write("bar.txt", "dolor sit")?;
///     Ok(())
/// }
/// ```
///
///
#[stable(feature = "fs_read_write_bytes", since = "1.26.0")]
pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> io::Result<()> {
    fn inner(path: &Path, contents: &[u8]) -> io::Result<()> {
        File::create(path)?.write_all(contents)
    }
    inner(path.as_ref(), contents.as_ref())
}

impl File {
    /// 尝试以只读模式打开文件。
    ///
    /// 有关更多详细信息，请参见 [`OpenOptions::open`] 方法。
    ///
    /// 如果您只需要读取整个文件内容，请考虑使用 [`std::fs::read()`][self::read] 或 [`std::fs::read_to_string()`][self::read_to_string]。
    ///
    ///
    /// # Errors
    ///
    /// 如果 `path` 还不存在，则此函数将返回错误。
    /// 根据 [`OpenOptions::open`]，可能还会返回其他错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::Read;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let mut data = vec![];
    ///     f.read_to_end(&mut data)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn open<P: AsRef<Path>>(path: P) -> io::Result<File> {
        OpenOptions::new().read(true).open(path.as_ref())
    }

    /// 以只写模式打开文件。
    ///
    /// 如果该函数不存在，则此函数将创建一个文件，如果存在则将截断该文件。
    ///
    /// 根据平台，如果完整目录路径不存在，此函数可能会失败。
    /// 有关更多详细信息，请参见 [`OpenOptions::open`] 函数。
    ///
    /// 另请参见 [`std::fs::write()`][self::write]，了解使用给定数据创建文件的简单函数。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::Write;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     f.write_all(&1234_u32.to_be_bytes())?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn create<P: AsRef<Path>>(path: P) -> io::Result<File> {
        OpenOptions::new().write(true).create(true).truncate(true).open(path.as_ref())
    }

    /// 以读写模式创建一个新文件; 如果文件存在则出错。
    ///
    /// 如果文件不存在，此函数将创建一个文件，如果存在则返回错误。
    /// 这样，如果调用成功，则保证返回的文件是新的。
    ///
    /// 此选项很有用，因为它是原子的。
    /// 否则，在检查文件是否存在与创建新文件之间，文件可能是由另一个进程创建的 (TOCTOU 竞态条件 / 攻击)。
    ///
    ///
    /// 这也可以使用 `File::options().read(true).write(true).create_new(true).open(...)` 编写。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// #![feature(file_create_new)]
    ///
    /// use std::fs::File;
    /// use std::io::Write;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create_new("foo.txt")?;
    ///     f.write_all("Hello, world!".as_bytes())?;
    ///     Ok(())
    /// }
    /// ```
    ///
    #[unstable(feature = "file_create_new", issue = "105135")]
    pub fn create_new<P: AsRef<Path>>(path: P) -> io::Result<File> {
        OpenOptions::new().read(true).write(true).create_new(true).open(path.as_ref())
    }

    /// 返回一个新的 OpenOptions 对象。
    ///
    /// 如果不适合使用 `open()` 或 `create()`，则此函数返回一个新的 OpenOptions 对象，可用于打开或创建具有特定选项的文件。
    ///
    ///
    /// 它相当于 `OpenOptions::new()`，但允许您编写更具可读性的代码。
    /// 您可以写 `File::options().append(true).open("example.log")`，而不是 `OpenOptions::new().append(true).open("example.log")`。
    /// 这也避免了导入 `OpenOptions` 的需要。
    ///
    /// 有关更多详细信息，请参见 [`OpenOptions::new`] 函数。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::Write;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::options().append(true).open("example.log")?;
    ///     writeln!(&mut f, "new line")?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    #[must_use]
    #[stable(feature = "with_options", since = "1.58.0")]
    pub fn options() -> OpenOptions {
        OpenOptions::new()
    }

    /// 尝试将所有操作系统内部元数据同步到磁盘。
    ///
    /// 此函数将尝试确保所有内存数据在返回之前都已到达文件系统。
    ///
    ///
    /// 这可用于处理错误，否则这些错误仅在 `File` 关闭时才会被捕获。
    /// 丢弃文件将忽略同步此内存中数据的错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::prelude::*;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     f.write_all(b"Hello, world!")?;
    ///
    ///     f.sync_all()?;
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn sync_all(&self) -> io::Result<()> {
        self.inner.fsync()
    }

    /// 该函数与 [`sync_all`] 类似，不同之处在于它可能不会将文件元数据同步到文件系统。
    ///
    ///
    /// 这适用于必须同步内容但不需要磁盘上元数据的用例。
    /// 此方法的目标是减少磁盘操作。
    ///
    /// 请注意，某些平台可能只是根据 [`sync_all`] 来实现此目的。
    ///
    /// [`sync_all`]: File::sync_all
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::prelude::*;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     f.write_all(b"Hello, world!")?;
    ///
    ///     f.sync_data()?;
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn sync_data(&self) -> io::Result<()> {
        self.inner.datasync()
    }

    /// 截断或扩展底层文件，将此文件的大小更新为 `size`。
    ///
    /// 如果 `size` 小于当前文件的大小，则文件将被缩小。
    /// 如果它大于当前文件的大小，则文件将扩展到 `size`，并且所有中间数据都用 0 填充。
    ///
    /// 文件的游标未更改。特别是，如果游标位于末尾，并且使用此操作将文件缩小了，那么游标现在将超过末尾。
    ///
    /// # Errors
    ///
    /// 如果未打开文件进行写入，则此函数将返回错误。
    /// 此外，如果由于实现细节所需的长度会导致溢出，则将返回 [`std::io::ErrorKind::InvalidInput`](crate::io::ErrorKind::InvalidInput)。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     f.set_len(10)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 请注意，即使使用 `&self` 而不是 `&mut self`，此方法也会更改底层文件的内容。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn set_len(&self, size: u64) -> io::Result<()> {
        self.inner.truncate(size)
    }

    /// 查询有关底层文件的元数据。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::open("foo.txt")?;
    ///     let metadata = f.metadata()?;
    ///     Ok(())
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn metadata(&self) -> io::Result<Metadata> {
        self.inner.file_attr().map(Metadata)
    }

    /// 创建一个新的 `File` 实例，该实例与现有 `File` 实例共享相同的底层文件句柄。
    /// 读取，写入和查找将同时影响两个 `File` 实例。
    ///
    /// # Examples
    ///
    /// 为名为 `foo.txt` 的文件创建两个句柄：
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///     let file_copy = file.try_clone()?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 假设有一个名为 `foo.txt` 的文件，其内容为 `abcdef\n`，创建两个句柄，查找其中一个，然后从另一个句柄读取剩余的字节：
    ///
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use std::io::SeekFrom;
    /// use std::io::prelude::*;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut file = File::open("foo.txt")?;
    ///     let mut file_copy = file.try_clone()?;
    ///
    ///     file.seek(SeekFrom::Start(3))?;
    ///
    ///     let mut contents = vec![];
    ///     file_copy.read_to_end(&mut contents)?;
    ///     assert_eq!(contents, b"def\n");
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "file_try_clone", since = "1.9.0")]
    pub fn try_clone(&self) -> io::Result<File> {
        Ok(File { inner: self.inner.duplicate()? })
    }

    /// 更改底层文件的权限。
    ///
    /// # 特定于平台的行为
    ///
    /// 该函数当前对应于 Unix 上的 `fchmod` 函数和 Windows 上的 `SetFileInformationByHandle` 函数。
    ///
    /// 注意，这个 [将来可能会改变][changes]。
    ///
    /// [changes]: io#platform-specific-behavior
    ///
    /// # Errors
    ///
    /// 如果用户缺少底层文件的权限更改属性，则此函数将返回错误。
    /// 在其他特定于操作系统的未指定情况下，它也可能返回错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs::File;
    ///
    ///     let file = File::open("foo.txt")?;
    ///     let mut perms = file.metadata()?.permissions();
    ///     perms.set_readonly(true);
    ///     file.set_permissions(perms)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 请注意，即使使用 `&self` 而不是 `&mut self`，此方法也会更改底层文件的权限。
    ///
    ///
    #[stable(feature = "set_permissions_atomic", since = "1.16.0")]
    pub fn set_permissions(&self, perm: Permissions) -> io::Result<()> {
        self.inner.set_permissions(perm.0)
    }

    /// 更改底层文件的时间戳。
    ///
    /// # 特定于平台的行为
    ///
    /// 该函数目前对应于 Unix 上的 `futimens` 函数 (在 10.13 之前回退到 macOS 上的 `futimes`) 和 Windows 上的 `SetFileTime` 函数。
    ///
    /// 注意这个 [将来可能会发生变化][changes]。
    ///
    /// [changes]: io#platform-specific-behavior
    ///
    /// # Errors
    ///
    /// 如果用户没有更改底层文件时间戳的权限，此函数将返回错误。
    /// 在其他特定于操作系统的未指定情况下，它也可能返回错误。
    ///
    /// 如果操作系统不支持更改 `FileTimes` 结构体中设置的一个或多个时间戳，则此函数可能会返回错误。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// #![feature(file_set_times)]
    ///
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs::{self, File, FileTimes};
    ///
    ///     let src = fs::metadata("src")?;
    ///     let dest = File::options().write(true).open("dest")?;
    ///     let times = FileTimes::new()
    ///         .set_accessed(src.accessed()?)
    ///         .set_modified(src.modified()?);
    ///     dest.set_times(times)?;
    ///     Ok(())
    /// }
    /// ```
    ///
    #[unstable(feature = "file_set_times", issue = "98245")]
    #[doc(alias = "futimens")]
    #[doc(alias = "futimes")]
    #[doc(alias = "SetFileTime")]
    pub fn set_times(&self, times: FileTimes) -> io::Result<()> {
        self.inner.set_times(times.0)
    }

    /// 更改底层文件的修改时间。
    ///
    /// 这是 `set_times(FileTimes::new().set_modified(time))` 的别名。
    #[unstable(feature = "file_set_times", issue = "98245")]
    #[inline]
    pub fn set_modified(&self, time: SystemTime) -> io::Result<()> {
        self.set_times(FileTimes::new().set_modified(time))
    }
}

// 除了这里的 impl 之外，`File` 还有 `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` 和 `AsRawFd`/`IntoRawFd`/`FromRawFd`、Unix 和 WASI 以及 Windows 上的 `AsHandle`/`From<OwnedHandle>`/`Into<OwnedHandle>` 和 `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` 的 impl。
//
//
//
//

impl AsInner<fs_imp::File> for File {
    #[inline]
    fn as_inner(&self) -> &fs_imp::File {
        &self.inner
    }
}
impl FromInner<fs_imp::File> for File {
    fn from_inner(f: fs_imp::File) -> File {
        File { inner: f }
    }
}
impl IntoInner<fs_imp::File> for File {
    fn into_inner(self) -> fs_imp::File {
        self.inner
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for File {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.inner.fmt(f)
    }
}

/// 指示读取文件的其余部分需要多少额外容量。
fn buffer_capacity_required(mut file: &File) -> Option<usize> {
    let size = file.metadata().map(|m| m.len()).ok()?;
    let pos = file.stream_position().ok()?;
    // 不必担心 `usize` 溢出，因为无论那种情况，读取都会失败。
    //
    Some(size.saturating_sub(pos) as usize)
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Read for File {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        self.inner.read(buf)
    }

    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
        self.inner.read_vectored(bufs)
    }

    fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> {
        self.inner.read_buf(cursor)
    }

    #[inline]
    fn is_read_vectored(&self) -> bool {
        self.inner.is_read_vectored()
    }

    // 根据可用的文件大小在缓冲区中保留空间。
    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
        let size = buffer_capacity_required(self);
        buf.reserve(size.unwrap_or(0));
        io::default_read_to_end(self, buf, size)
    }

    // 根据可用的文件大小在缓冲区中保留空间。
    fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
        let size = buffer_capacity_required(self);
        buf.reserve(size.unwrap_or(0));
        io::default_read_to_string(self, buf, size)
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Write for File {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        self.inner.write(buf)
    }

    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
        self.inner.write_vectored(bufs)
    }

    #[inline]
    fn is_write_vectored(&self) -> bool {
        self.inner.is_write_vectored()
    }

    fn flush(&mut self) -> io::Result<()> {
        self.inner.flush()
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Seek for File {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.inner.seek(pos)
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Read for &File {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        self.inner.read(buf)
    }

    fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> {
        self.inner.read_buf(cursor)
    }

    fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
        self.inner.read_vectored(bufs)
    }

    #[inline]
    fn is_read_vectored(&self) -> bool {
        self.inner.is_read_vectored()
    }

    // 根据可用的文件大小在缓冲区中保留空间。
    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
        let size = buffer_capacity_required(self);
        buf.reserve(size.unwrap_or(0));
        io::default_read_to_end(self, buf, size)
    }

    // 根据可用的文件大小在缓冲区中保留空间。
    fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
        let size = buffer_capacity_required(self);
        buf.reserve(size.unwrap_or(0));
        io::default_read_to_string(self, buf, size)
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Write for &File {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        self.inner.write(buf)
    }

    fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
        self.inner.write_vectored(bufs)
    }

    #[inline]
    fn is_write_vectored(&self) -> bool {
        self.inner.is_write_vectored()
    }

    fn flush(&mut self) -> io::Result<()> {
        self.inner.flush()
    }
}
#[stable(feature = "rust1", since = "1.0.0")]
impl Seek for &File {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.inner.seek(pos)
    }
}

impl OpenOptions {
    /// 创建一组可供配置的空白新选项。
    ///
    /// 所有选项最初都设置为 `false`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let mut options = OpenOptions::new();
    /// let file = options.read(true).open("foo.txt");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    pub fn new() -> Self {
        OpenOptions(fs_imp::OpenOptions::new())
    }

    /// 设置读取访问权限的选项。
    ///
    /// 该选项为 true 时，则表示打开的文件应该是可读的。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().read(true).open("foo.txt");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn read(&mut self, read: bool) -> &mut Self {
        self.0.read(read);
        self
    }

    /// 设置写访问权限的选项。
    ///
    /// 此选项为 true 时，则表示打开的文件应该是可写的。
    ///
    /// 如果该文件已经存在，则对该文件的任何写调用都将覆盖其内容，而不会将其截断。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true).open("foo.txt");
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn write(&mut self, write: bool) -> &mut Self {
        self.0.write(write);
        self
    }

    /// 设置追加模式的选项。
    ///
    /// 此选项为 true 时，表示写入将追加到文件中，而不是覆盖以前的内容。
    /// 请注意，设置 `.write(true).append(true)` 与仅设置 `.append(true)` 具有相同的效果。
    ///
    /// 对于大多数文件系统，操作系统保证所有写操作都是原子的：不会浪费任何写操作，因为另一个进程会同时进行写操作。
    ///
    /// 使用追加模式时，可能有一个明显的注意事项：确保一次完成将所有在一起的数据写入文件。
    /// 这可以通过在将字符串传递给 [`write()`] 之前串联字符串，或使用缓冲的 writer (具有足够大小的缓冲区) 并在消息完成后调用 [`flush()`] 来完成。
    ///
    ///
    /// 如果同时使用读取和追加的访问权限打开文件，请注意，在打开之后以及每次写入之后，读取位置可能设置在文件末尾。
    /// 所以，在写入之前，保存当前位置 (使用 <code>[seek]\([SeekFrom]::[Current]\(0))</code>)，并在下次读取之前恢复它。
    ///
    /// ## Note
    ///
    /// 如果该函数不存在，则该函数不会创建该文件。使用 [`OpenOptions::create`] 方法来执行此操作。
    ///
    /// [`write()`]: Write::write "io::Write::write"
    /// [`flush()`]: Write::flush "io::Write::flush"
    /// [seek]: Seek::seek "io::Seek::seek"
    /// [Current]: SeekFrom::Current "io::SeekFrom::Current"
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().append(true).open("foo.txt");
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn append(&mut self, append: bool) -> &mut Self {
        self.0.append(append);
        self
    }

    /// 设置截断上一个文件的选项。
    ///
    /// 如果使用此选项设置成功打开了文件，则如果文件已经存在，它将把文件的长度截断为 0。
    ///
    ///
    /// 该文件必须具有写访问权限才能打开，才能进行截断。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true).truncate(true).open("foo.txt");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn truncate(&mut self, truncate: bool) -> &mut Self {
        self.0.truncate(truncate);
        self
    }

    /// 设置选项以创建一个新文件，或者如果已经存在则将其打开。
    ///
    /// 为了创建文件，必须使用 [`OpenOptions::write`] 或 [`OpenOptions::append`] 访问。
    ///
    ///
    /// 另请参见 [`std::fs::write()`][self::write]，了解使用给定数据创建文件的简单函数。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true).create(true).open("foo.txt");
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn create(&mut self, create: bool) -> &mut Self {
        self.0.create(create);
        self
    }

    /// 设置创建新文件的选项，如果该文件已经存在则失败。
    ///
    /// 目标位置不允许存在任何文件，(dangling) 符号链接也不允许存在。这样，如果调用成功，则保证返回的文件是新文件。
    ///
    /// 此选项很有用，因为它是原子的。
    /// 否则，在检查文件是否存在与创建新文件之间，文件可能是由另一个进程创建的 (TOCTOU 竞态条件 / 攻击)。
    ///
    ///
    /// 如果设置了 `.create_new(true)`，则忽略 [`.create()`] 和 [`.truncate()`]。
    ///
    /// 必须使用写或追加访问权限打开文件才能创建新文件。
    ///
    /// [`.create()`]: OpenOptions::create
    /// [`.truncate()`]: OpenOptions::truncate
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().write(true)
    ///                              .create_new(true)
    ///                              .open("foo.txt");
    /// ```
    ///
    ///
    ///
    #[stable(feature = "expand_open_options2", since = "1.9.0")]
    pub fn create_new(&mut self, create_new: bool) -> &mut Self {
        self.0.create_new(create_new);
        self
    }

    /// 使用 `self` 指定的选项在 `path` 打开文件。
    ///
    /// # Errors
    ///
    /// 在许多不同的情况下，此函数将返回错误。其中列出了一些错误条件及其 [`io::ErrorKind`]。
    /// 映射到 [`io::ErrorKind`] 不是函数兼容性契约的一部分。
    ///
    /// * [`NotFound`]: 指定的文件不存在，并且未设置 `create` 或 `create_new`。
    /// * [`NotFound`]: 文件路径的目录组件之一不存在。
    /// * [`PermissionDenied`]: 用户缺乏获取文件指定访问权限的权限。
    /// * [`PermissionDenied`]: 用户没有权限打开指定路径的某个目录组件。
    /// * [`AlreadyExists`]: 指定了 `create_new` 并且文件已经存在。
    /// * [`InvalidInput`]: 打开选项无效组合 (在没有写访问、没有访问模式设置等情况下截断)。
    ///
    /// 以下错误目前与任何现有的 [`io::ErrorKind`] 都不匹配：
    /// * 实际上，指定文件路径的目录组件之一不是目录。
    /// * 文件系统级错误：已满磁盘，对只读文件系统请求的写许可权，超出磁盘配额，打开的文件过多，文件名太长，指定路径中的符号链接太多 (仅适用于 Unix 系统)，等等。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::OpenOptions;
    ///
    /// let file = OpenOptions::new().read(true).open("foo.txt");
    /// ```
    ///
    /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists
    /// [`InvalidInput`]: io::ErrorKind::InvalidInput
    /// [`NotFound`]: io::ErrorKind::NotFound
    /// [`PermissionDenied`]: io::ErrorKind::PermissionDenied
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
        self._open(path.as_ref())
    }

    fn _open(&self, path: &Path) -> io::Result<File> {
        fs_imp::File::open(path, &self.0).map(|inner| File { inner })
    }
}

impl AsInner<fs_imp::OpenOptions> for OpenOptions {
    #[inline]
    fn as_inner(&self) -> &fs_imp::OpenOptions {
        &self.0
    }
}

impl AsInnerMut<fs_imp::OpenOptions> for OpenOptions {
    #[inline]
    fn as_inner_mut(&mut self) -> &mut fs_imp::OpenOptions {
        &mut self.0
    }
}

impl Metadata {
    /// 返回此元数据的文件类型。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     println!("{:?}", metadata.file_type());
    ///     Ok(())
    /// }
    /// ```
    #[must_use]
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn file_type(&self) -> FileType {
        FileType(self.0.file_type())
    }

    /// 如果此元数据用于目录，则返回 `true`。
    /// 结果与 [`Metadata::is_file`] 的结果互斥，并且对于从 [`symlink_metadata`] 获得的符号链接元数据将为 false。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert!(!metadata.is_dir());
    ///     Ok(())
    /// }
    /// ```
    ///
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn is_dir(&self) -> bool {
        self.file_type().is_dir()
    }

    /// 如果此元数据用于常规文件，则返回 `true`。
    /// 结果与 [`Metadata::is_dir`] 的结果互斥，并且对于从 [`symlink_metadata`] 获得的符号链接元数据将为 false。
    ///
    ///
    /// 当目标只是读取 (或写入) 源时，可以读取 (或写入) 最可靠的测试源方法是打开它。
    /// 例如，仅使用 `is_file` 才能中断类似 Unix 的系统上的工作流，例如 `diff <( prog_a )`。
    /// 有关更多信息，请参见 [`File::open`] 或 [`OpenOptions::open`]。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert!(metadata.is_file());
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn is_file(&self) -> bool {
        self.file_type().is_file()
    }

    /// 如果此元数据用于符号链接，则返回 `true`。
    ///
    /// # Examples
    ///
    #[cfg_attr(unix, doc = "```no_run")]
    #[cfg_attr(not(unix), doc = "```ignore")]
    /// use std::fs;
    /// use std::path::Path;
    /// use std::os::unix::fs::symlink;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let link_path = Path::new("link");
    ///     symlink("/origin_does_not_exist/", link_path)?;
    ///
    ///     let metadata = fs::symlink_metadata(link_path)?;
    ///
    ///     assert!(metadata.is_symlink());
    ///     Ok(())
    /// }
    /// ```
    #[must_use]
    #[stable(feature = "is_symlink", since = "1.58.0")]
    pub fn is_symlink(&self) -> bool {
        self.file_type().is_symlink()
    }

    /// 返回此元数据用于的文件大小 (以字节为单位)。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert_eq!(0, metadata.len());
    ///     Ok(())
    /// }
    /// ```
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn len(&self) -> u64 {
        self.0.size()
    }

    /// 返回此元数据所针对的文件的权限。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     assert!(!metadata.permissions().readonly());
    ///     Ok(())
    /// }
    /// ```
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn permissions(&self) -> Permissions {
        Permissions(self.0.perm())
    }

    /// 返回此元数据中列出的最后修改时间。
    ///
    /// 返回的值对应于 Unix 平台上的 `stat` 的 `mtime` 字段和 Windows 平台上的 `ftLastWriteTime` 字段。
    ///
    ///
    /// # Errors
    ///
    /// 此字段可能并非在所有平台上都可用，并且在它不可用的平台上将返回 `Err`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     if let Ok(time) = metadata.modified() {
    ///         println!("{time:?}");
    ///     } else {
    ///         println!("Not supported on this platform");
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    #[stable(feature = "fs_time", since = "1.10.0")]
    pub fn modified(&self) -> io::Result<SystemTime> {
        self.0.modified().map(FromInner::from_inner)
    }

    /// 返回此元数据的最后访问时间。
    ///
    /// 返回的值对应于 Unix 平台上的 `stat` 的 `atime` 字段和 Windows 平台上的 `ftLastAccessTime` 字段。
    ///
    /// 请注意，并非所有平台都会在文件的元数据中保留此字段的更新，例如，Windows 可以选择在访问文件时禁用此更新，而 Linux 同样具有 `noatime`。
    ///
    ///
    /// # Errors
    ///
    /// 此字段可能并非在所有平台上都可用，并且在它不可用的平台上将返回 `Err`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     if let Ok(time) = metadata.accessed() {
    ///         println!("{time:?}");
    ///     } else {
    ///         println!("Not supported on this platform");
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    #[stable(feature = "fs_time", since = "1.10.0")]
    pub fn accessed(&self) -> io::Result<SystemTime> {
        self.0.accessed().map(FromInner::from_inner)
    }

    /// 返回此元数据中列出的创建时间。
    ///
    /// 返回的值与从 4.11 开始的 Linux 内核上的 `statx` 的 `btime` 字段，在其他 Unix 平台上的 `stat` 的 `birthtime` 字段以及在 Windows 平台上的 `ftCreationTime` 字段相对应。
    ///
    ///
    /// # Errors
    ///
    /// 此字段可能并非在所有平台上都可用，并且会在它不可用的平台或文件系统上返回 `Err`。
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::metadata("foo.txt")?;
    ///
    ///     if let Ok(time) = metadata.created() {
    ///         println!("{time:?}");
    ///     } else {
    ///         println!("Not supported on this platform or filesystem");
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "fs_time", since = "1.10.0")]
    pub fn created(&self) -> io::Result<SystemTime> {
        self.0.created().map(FromInner::from_inner)
    }
}

#[stable(feature = "std_debug", since = "1.16.0")]
impl fmt::Debug for Metadata {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Metadata")
            .field("file_type", &self.file_type())
            .field("is_dir", &self.is_dir())
            .field("is_file", &self.is_file())
            .field("permissions", &self.permissions())
            .field("modified", &self.modified())
            .field("accessed", &self.accessed())
            .field("created", &self.created())
            .finish_non_exhaustive()
    }
}

impl AsInner<fs_imp::FileAttr> for Metadata {
    #[inline]
    fn as_inner(&self) -> &fs_imp::FileAttr {
        &self.0
    }
}

impl FromInner<fs_imp::FileAttr> for Metadata {
    fn from_inner(attr: fs_imp::FileAttr) -> Metadata {
        Metadata(attr)
    }
}

impl FileTimes {
    /// 创建一个没有设置时间的新 `FileTimes`。
    ///
    /// 在 [`File::set_times`] 中使用生成的 `FileTimes` 不会修改任何时间戳。
    #[unstable(feature = "file_set_times", issue = "98245")]
    pub fn new() -> Self {
        Self::default()
    }

    /// 设置文件的最后访问时间。
    #[unstable(feature = "file_set_times", issue = "98245")]
    pub fn set_accessed(mut self, t: SystemTime) -> Self {
        self.0.set_accessed(t.into_inner());
        self
    }

    /// 设置文件的最后修改时间。
    #[unstable(feature = "file_set_times", issue = "98245")]
    pub fn set_modified(mut self, t: SystemTime) -> Self {
        self.0.set_modified(t.into_inner());
        self
    }
}

impl AsInnerMut<fs_imp::FileTimes> for FileTimes {
    fn as_inner_mut(&mut self) -> &mut fs_imp::FileTimes {
        &mut self.0
    }
}

// 用于在 `std::os` 中实现操作系统扩展 traits
#[unstable(feature = "file_set_times", issue = "98245")]
impl Sealed for FileTimes {}

impl Permissions {
    /// 如果这些权限描述了只读 (unwritable) 文件，则返回 `true`。
    ///
    /// # Note
    ///
    /// 此函数不考虑访问控制列表 (ACLs) 或 Unix 组成员身份。
    ///
    /// # Windows
    ///
    /// 在 Windows 上，这将返回 [`FILE_ATTRIBUTE_READONLY`](https://docs.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants)。
    ///
    /// 如果设置了 `FILE_ATTRIBUTE_READONLY`，则写入文件将失败，但用户可能仍有更改此标志的权限。
    /// 如果 `FILE_ATTRIBUTE_READONLY` *not* 设置，则由于缺少写入权限，写入仍可能失败。
    /// 目录的此属性的行为取决于 Windows 版本。
    ///
    /// # Unix (包括 macOS)
    ///
    /// 在基于 Unix 的平台上，这会检查是否设置了所有者、组或其他人的写权限位的 *any*。
    /// 它不检查当前用户是否在文件的指定组中。
    /// 它也不检查 ACL。
    /// 因此，即使返回 true，您也可能无法写入文件，反之亦然。
    /// [`PermissionsExt`] trait 提供对权限位的直接访问，但也不读取 ACL。
    /// 如果您需要准确地知道文件是否可写，请使用 libc 中的 `access()` 函数。
    ///
    /// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let mut f = File::create("foo.txt")?;
    ///     let metadata = f.metadata()?;
    ///
    ///     assert_eq!(false, metadata.permissions().readonly());
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[must_use = "call `set_readonly` to modify the readonly flag"]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn readonly(&self) -> bool {
        self.0.readonly()
    }

    /// 修改此权限集的只读标志。如果 `readonly` 参数是 `true`，则使用生成的 `Permission` 将更新文件权限以禁止写入。
    ///
    /// 相反，如果是 `false`，则使用生成的 `Permission` 将更新文件权限以允许写入。
    ///
    /// 此操作**不**修改文件属性。这只会更改此 `Permissions` 实例的这些属性的内存值。
    /// 要修改文件属性，请使用 [`set_permissions`] 函数，它将这些属性更改提交到文件。
    ///
    /// # Note
    ///
    /// `set_readonly(false)` 使 Unix 上的文件 *world-writable*。
    /// 您可以在 Unix 上使用 [`PermissionsExt`] trait 来避免这个问题。
    ///
    /// 它也不考虑访问控制列表 (ACLs) 或 Unix 组成员身份。
    ///
    /// # Windows
    ///
    /// 在 Windows 上，这设置或清除 [`FILE_ATTRIBUTE_READONLY`](https://docs.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants)。
    /// 如果设置了 `FILE_ATTRIBUTE_READONLY`，则写入文件将失败，但用户可能仍有更改此标志的权限。
    /// 如果 `FILE_ATTRIBUTE_READONLY` *not* 设置，那么如果用户没有写入文件的权限，写入可能仍然失败。
    ///
    /// 在 Windows 7 及更早版本中，此属性可防止删除空目录。它不会阻止修改目录内容。
    /// 在更高版本的 Windows 中，此属性对于目录将被忽略。
    ///
    /// # Unix (包括 macOS)
    ///
    /// 在基于 Unix 的平台上，这会设置或清除所有者、组*和*其他人的写访问位，分别相当于 `chmod a+w <file>` 或 `chmod a-w <file>`。
    /// 后者将授予所有用户写入权限! 您可以在 Unix 上使用 [`PermissionsExt`] trait 来避免这个问题。
    ///
    /// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::File;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let f = File::create("foo.txt")?;
    ///     let metadata = f.metadata()?;
    ///     let mut permissions = metadata.permissions();
    ///
    ///     permissions.set_readonly(true);
    ///
    ///     // 文件系统不会改变，只有只读权限的内存状态
    /////
    ///     assert_eq!(false, metadata.permissions().readonly());
    ///
    ///     // 只是这个特殊的 `permissions`。
    ///     assert_eq!(true, permissions.readonly());
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn set_readonly(&mut self, readonly: bool) {
        self.0.set_readonly(readonly)
    }
}

impl FileType {
    /// 测试此文件类型是否代表目录。
    /// 结果与 [`is_file`] 和 [`is_symlink`] 的结果互斥； 这些测试只能通过零或其中一项。
    ///
    ///
    /// [`is_file`]: FileType::is_file
    /// [`is_symlink`]: FileType::is_symlink
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let file_type = metadata.file_type();
    ///
    ///     assert_eq!(file_type.is_dir(), false);
    ///     Ok(())
    /// }
    /// ```
    ///
    #[must_use]
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn is_dir(&self) -> bool {
        self.0.is_dir()
    }

    /// 测试此文件类型是否代表常规文件。
    /// 结果与 [`is_dir`] 和 [`is_symlink`] 的结果互斥; 这些测试只能通过零或其中一项。
    ///
    /// 当目标只是读取 (或写入) 源时，可以读取 (或写入) 最可靠的测试源方法是打开它。
    /// 例如，仅使用 `is_file` 才能中断类似 Unix 的系统上的工作流，例如 `diff <( prog_a )`。
    /// 有关更多信息，请参见 [`File::open`] 或 [`OpenOptions::open`]。
    ///
    /// [`is_dir`]: FileType::is_dir
    /// [`is_symlink`]: FileType::is_symlink
    ///
    /// # Examples
    ///
    /// ```no_run
    /// fn main() -> std::io::Result<()> {
    ///     use std::fs;
    ///
    ///     let metadata = fs::metadata("foo.txt")?;
    ///     let file_type = metadata.file_type();
    ///
    ///     assert_eq!(file_type.is_file(), true);
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    #[must_use]
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn is_file(&self) -> bool {
        self.0.is_file()
    }

    /// 测试此文件类型是否代表符号链接。
    /// 结果与 [`is_dir`] 和 [`is_file`] 的结果互斥； 这些测试只能通过零或其中一项。
    ///
    /// 需要使用 [`fs::symlink_metadata`] 函数而不是 [`fs::metadata`] 函数来检索底层 [`Metadata`] 结构。
    /// [`fs::metadata`] 函数遵循符号链接，因此 [`is_symlink`] 将始终为目标文件返回 `false`。
    ///
    /// [`fs::metadata`]: metadata
    /// [`fs::symlink_metadata`]: symlink_metadata
    /// [`is_dir`]: FileType::is_dir
    /// [`is_file`]: FileType::is_file
    /// [`is_symlink`]: FileType::is_symlink
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     let metadata = fs::symlink_metadata("foo.txt")?;
    ///     let file_type = metadata.file_type();
    ///
    ///     assert_eq!(file_type.is_symlink(), false);
    ///     Ok(())
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[must_use]
    #[stable(feature = "file_type", since = "1.1.0")]
    pub fn is_symlink(&self) -> bool {
        self.0.is_symlink()
    }
}

impl AsInner<fs_imp::FileType> for FileType {
    #[inline]
    fn as_inner(&self) -> &fs_imp::FileType {
        &self.0
    }
}

impl FromInner<fs_imp::FilePermissions> for Permissions {
    fn from_inner(f: fs_imp::FilePermissions) -> Permissions {
        Permissions(f)
    }
}

impl AsInner<fs_imp::FilePermissions> for Permissions {
    #[inline]
    fn as_inner(&self) -> &fs_imp::FilePermissions {
        &self.0
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Iterator for ReadDir {
    type Item = io::Result<DirEntry>;

    fn next(&mut self) -> Option<io::Result<DirEntry>> {
        self.0.next().map(|entry| entry.map(DirEntry))
    }
}

impl DirEntry {
    /// 返回此条目表示的文件的完整路径。
    ///
    /// 通过将 `read_dir` 的原始路径与该条目的文件名连接起来，可以创建完整路径。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs;
    ///
    /// fn main() -> std::io::Result<()> {
    ///     for entry in fs::read_dir(".")? {
    ///         let dir = entry?;
    ///         println!("{:?}", dir.path());
    ///     }
    ///     Ok(())
    /// }
    /// ```
    ///
    /// 打印输出如下：
    ///
    /// ```text
    /// "./whatever.txt"
    /// "./foo.html"
    /// "./hello_world.rs"
    /// ```
    ///
    /// 当然，确切的文本取决于 `.` 中包含的文件。
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn path(&self) -> PathBuf {
        self.0.path()
    }

    /// 返回此条目指向的文件的元数据。
    ///
    /// 如果此函数指向符号链接，则该函数将不会遍历符号链接。要遍历符号链接，请使用 [`fs::metadata`] 或 [`fs::File::metadata`]。
    ///
    /// [`fs::metadata`]: metadata
    /// [`fs::File::metadata`]: File::metadata
    ///
    /// # 特定于平台的行为
    ///
    /// 在 Windows 上，此函数的调用很便宜 (不需要额外的系统调用)，但是在 Unix 平台上，此函数等效于在路径上调用 `symlink_metadata`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs;
    ///
    /// if let Ok(entries) = fs::read_dir(".") {
    ///     for entry in entries {
    ///         if let Ok(entry) = entry {
    ///             // 在此，`entry` 是 `DirEntry`。
    ///             if let Ok(metadata) = entry.metadata() {
    ///                 // 现在，让我们显示条目的权限！
    ///                 println!("{:?}: {:?}", entry.path(), metadata.permissions());
    ///             } else {
    ///                 println!("Couldn't get metadata for {:?}", entry.path());
    ///             }
    ///         }
    ///     }
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "dir_entry_ext", since = "1.1.0")]
    pub fn metadata(&self) -> io::Result<Metadata> {
        self.0.metadata().map(Metadata)
    }

    /// 返回此条目指向的文件的文件类型。
    ///
    /// 如果此函数指向符号链接，则该函数将不会遍历符号链接。
    ///
    /// # 特定于平台的行为
    ///
    /// 在 Windows 和大多数 Unix 平台上，此函数是免费的 (不需要额外的系统调用)，但是某些 Unix 平台可能需要与 `symlink_metadata` 等效的调用才能了解目标文件类型。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs;
    ///
    /// if let Ok(entries) = fs::read_dir(".") {
    ///     for entry in entries {
    ///         if let Ok(entry) = entry {
    ///             // 在此，`entry` 是 `DirEntry`。
    ///             if let Ok(file_type) = entry.file_type() {
    ///                 // 现在，让我们显示条目的文件类型！
    ///                 println!("{:?}: {:?}", entry.path(), file_type);
    ///             } else {
    ///                 println!("Couldn't get file type for {:?}", entry.path());
    ///             }
    ///         }
    ///     }
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "dir_entry_ext", since = "1.1.0")]
    pub fn file_type(&self) -> io::Result<FileType> {
        self.0.file_type().map(FileType)
    }

    /// 返回此目录条目的裸文件名，不包含任何其他前导路径组件。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs;
    ///
    /// if let Ok(entries) = fs::read_dir(".") {
    ///     for entry in entries {
    ///         if let Ok(entry) = entry {
    ///             // 在此，`entry` 是 `DirEntry`。
    ///             println!("{:?}", entry.file_name());
    ///         }
    ///     }
    /// }
    /// ```
    #[must_use]
    #[stable(feature = "dir_entry_ext", since = "1.1.0")]
    pub fn file_name(&self) -> OsString {
        self.0.file_name()
    }
}

#[stable(feature = "dir_entry_debug", since = "1.13.0")]
impl fmt::Debug for DirEntry {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("DirEntry").field(&self.path()).finish()
    }
}

impl AsInner<fs_imp::DirEntry> for DirEntry {
    #[inline]
    fn as_inner(&self) -> &fs_imp::DirEntry {
        &self.0
    }
}

/// 从文件系统中删除文件。
///
/// 请注意，不能保证立即删除文件 (例如，取决于平台，其他打开的文件描述符可能会阻止立即删除)。
///
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `unlink` 函数和 Windows 上的 `DeleteFile` 函数。
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `path` 指向一个目录。
/// * 该文件不存在。
/// * 用户没有删除文件的权限。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::remove_file("a.txt")?;
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
    fs_imp::unlink(path.as_ref())
}

/// 给定路径，查询文件系统以获取有关文件，目录等的信息。
///
/// 该函数将遍历符号链接以查询有关目标文件的信息。
///
/// # 特定于平台的行为
///
/// 该函数目前对应于 Unix 上的 `stat` 函数和 Windows 上的 `GetFileInformationByHandle` 函数。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * 用户没有权限在 `path` 上执行 `metadata` 调用。
/// * `path` 不存在。
///
/// # Examples
///
/// ```rust,no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let attr = fs::metadata("/some/file/path.txt")?;
///     // 检查属性 ...
///     Ok(())
/// }
/// ```
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
    fs_imp::stat(path.as_ref()).map(Metadata)
}

/// 查询有关文件的元数据，而无需遵循符号链接。
///
/// # 特定于平台的行为
///
/// 该函数目前对应于 Unix 上的 `lstat` 函数和 Windows 上的 `GetFileInformationByHandle` 函数。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * 用户没有权限在 `path` 上执行 `metadata` 调用。
/// * `path` 不存在。
///
/// # Examples
///
/// ```rust,no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let attr = fs::symlink_metadata("/some/file/path.txt")?;
///     // 检查属性 ...
///     Ok(())
/// }
/// ```
///
#[stable(feature = "symlink_metadata", since = "1.1.0")]
pub fn symlink_metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
    fs_imp::lstat(path.as_ref()).map(Metadata)
}

/// 将文件或目录重命名为新名称，如果 `to` 已经存在，则替换原始文件。
///
/// 如果新名称在其他安装点上，则将无法使用。
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `rename` 函数和 Windows 上带有 `MOVEFILE_REPLACE_EXISTING` 标志的 `MoveFileEx` 函数。
///
/// 因此，`from` 和 `to` 都存在时的行为是不同的。在 Unix 上，如果 `from` 是目录，则 `to` 也必须是 (empty) 目录。如果 `from` 不是目录，则 `to` 也必须不是目录。
///
/// 相比之下，在 Windows 上，`from` 可以是任何东西，但是 `to` 一定不是目录。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `from` 不存在。
/// * 用户没有查看内容的权限。
/// * `from` 和 `to` 在不同的文件系统上。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::rename("a.txt", "b.txt")?; // 将 a.txt 重命名为 b.txt
///     Ok(())
/// }
/// ```
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()> {
    fs_imp::rename(from.as_ref(), to.as_ref())
}

/// 将一个文件的内容复制到另一个文件。此函数还将复制原始文件的权限位到目标文件。
///
/// 该函数将覆盖 `to` 的内容。
///
/// 请注意，如果 `from` 和 `to` 都指向同一个文件，则此操作可能会截断该文件。
///
/// 成功后，将返回复制的字节总数，该总数等于 `metadata` 报告的 `to` 文件的长度。
///
/// 如果您想将一个文件的内容复制到另一个文件并且您正在使用 [`File`] s，请参见 [`io::copy()`] 函数。
///
/// # 特定于平台的行为
///
/// 此函数当前与 Unix 中的 `open` 函数相对应，其中 `from` 的 `O_RDONLY` 和 `to` 的 `O_WRONLY`，`O_CREAT` 和 `O_TRUNC`。
///
/// `O_CLOEXEC` 是为返回的文件描述符设置的。
///
/// 在 Linux (包括 Android) 上，该函数尝试使用 `copy_file_range(2)`，如果不可能，则回退到读取和写入。
///
/// 在 Windows 上，此函数当前对应于 `CopyFileEx`。
/// 复制备用 NTFS 流，但此函数仅返回主流的大小。
///
/// 在 MacOS 上，此函数对应于 `fclonefileat` 和 `fcopyfile`。
///
/// 请注意，特定于平台的行为 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `from` 既不是普通文件，也不是普通文件的符号链接。
/// * `from` 不存在。
/// * 当前进程没有读取 `from` 或写入 `to` 的权限。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::copy("foo.txt", "bar.txt")?;  // 将 foo.txt 复制到 bar.txt
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<u64> {
    fs_imp::copy(from.as_ref(), to.as_ref())
}

/// 在文件系统上创建一个新的硬链接。
///
/// `link` 路径将是指向 `original` 路径的链接。请注意，系统通常要求这两个路径都位于同一文件系统上。
///
/// 如果 `original` 命名符号链接，则是否遵循符号链接是特定于平台的。
/// 在可能不遵循它的平台上，它不会被遵循，并且创建的硬链接指向符号链接本身。
///
/// # 特定于平台的行为
///
/// 该函数目前对应于 Windows 上的 `CreateHardLink` 函数。
/// 在大多数 Unix 系统上，它对应于没有标志的 `linkat` 函数。
/// 在 Android、VxWorks 和 Redox 上，它对应于 `link` 函数。
/// 在 MacOS 上，它使用 `linkat` 函数 (如果可用)，但在 `linkat` 不可用的非常旧的系统上，`link` 在运行时被选择。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `original` 路径不是文件或不存在。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::hard_link("a.txt", "b.txt")?; // 硬链接 a.txt 到 b.txt
///     Ok(())
/// }
/// ```
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
    fs_imp::link(original.as_ref(), link.as_ref())
}

/// 在文件系统上创建一个新的符号链接。
///
/// `link` 路径将是指向 `original` 路径的符号链接。
/// 在 Windows 上，这将是文件符号链接，而不是目录符号链接。
/// 因此，应该使用平台特定的 [`std::os::unix::fs::symlink`] 和 [`std::os::windows::fs::symlink_file`] 或 [`symlink_dir`] 来明确意图。
///
///
/// [`std::os::unix::fs::symlink`]: crate::os::unix::fs::symlink
/// [`std::os::windows::fs::symlink_file`]: crate::os::windows::fs::symlink_file
/// [`symlink_dir`]: crate::os::windows::fs::symlink_dir
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::soft_link("a.txt", "b.txt")?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
#[deprecated(
    since = "1.1.0",
    note = "replaced with std::os::unix::fs::symlink and \
            std::os::windows::fs::{symlink_file, symlink_dir}"
)]
pub fn soft_link<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
    fs_imp::symlink(original.as_ref(), link.as_ref())
}

/// 读取符号链接，返回链接指向的文件。
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `readlink` 函数，以及 Windows 上带有 `FILE_FLAG_OPEN_REPARSE_POINT` 和 `FILE_FLAG_BACKUP_SEMANTICS` 标志的 `CreateFile` 函数。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `path` 不是符号链接。
/// * `path` 不存在。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let path = fs::read_link("a.txt")?;
///     Ok(())
/// }
/// ```
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn read_link<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
    fs_imp::readlink(path.as_ref())
}

/// 返回路径的规范，绝对形式，所有中间组件均已规范化且符号链接已解析。
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `realpath` 函数以及 Windows 上的 `CreateFile` 和 `GetFinalPathNameByHandle` 函数。
/// 注意，这个 [将来可能会改变][changes]。
///
/// 在 Windows 上，这会将路径转换为使用 [扩展长度路径][path] 语法，这允许您的程序使用更长的路径名，但是意味着您只能将反斜杠分隔的路径连接到该路径，并且它可能与其他应用程序不兼容 (如果传递给该应用程序，命令行，或写入另一个应用程序可以读取的文件)。
///
///
/// [changes]: io#platform-specific-behavior
/// [path]: https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `path` 不存在。
/// * path 中的非最终组件不是目录。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let path = fs::canonicalize("../a/../foo.txt")?;
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
#[doc(alias = "realpath")]
#[doc(alias = "GetFinalPathNameByHandle")]
#[stable(feature = "fs_canonicalize", since = "1.5.0")]
pub fn canonicalize<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
    fs_imp::canonicalize(path.as_ref())
}

/// 在提供的路径中创建一个新的空目录
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `mkdir` 函数和 Windows 上的 `CreateDirectory` 函数。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// **NOTE**: 如果给定路径的父项不存在，则此函数将返回错误。
/// 要同时创建目录及其所有丢失的父目录，请使用 [`create_dir_all`] 函数。
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * 用户没有权限在 `path` 上创建目录。
/// * 给定路径的父级不存在。
/// (要同时创建目录及其所有丢失的父目录，请使用 [`create_dir_all`] 函数。)
/// * `path` 已经存在。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::create_dir("/some/dir")?;
///     Ok(())
/// }
/// ```
///
///
///
#[doc(alias = "mkdir")]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
    DirBuilder::new().create(path.as_ref())
}

/// 递归创建目录及其所有父组件 (如果缺少)。
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `mkdir` 函数和 Windows 上的 `CreateDirectory` 函数。
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * 如果 `path` 指定的路径中的任何目录都不存在，否则无法创建。
/// [`fs::create_dir`] 概述了创建目录时 (确定目录不存在后) 的特定错误条件。
///
/// 对于在 `path` 中指定的任何目录无法同时创建的情况下，将创建一个明显的例外。
///
/// 这种情况被认为是成功的。
/// 即，保证了从多个线程或进程并发调用 `create_dir_all` 不会由于自身的竞争态而失败。
///
/// [`fs::create_dir`]: create_dir
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::create_dir_all("/some/dir")?;
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn create_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
    DirBuilder::new().recursive(true).create(path.as_ref())
}

/// 删除一个空目录。
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `rmdir` 函数和 Windows 上的 `RemoveDirectory` 函数。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `path` 不存在。
/// * `path` 不是目录。
/// * 用户没有权限删除提供的 `path` 上的目录。
/// * 目录不为空。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::remove_dir("/some/dir")?;
///     Ok(())
/// }
/// ```
///
#[doc(alias = "rmdir")]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
    fs_imp::rmdir(path.as_ref())
}

/// 删除目录中的所有内容后，将在此路径中删除该目录。小心使用！
///
/// 此函数不跟随符号链接，它会简单地删除符号链接本身。
///
/// # 特定于平台的行为
///
/// 该函数目前对应于 Unix 上的 `openat`、`fdopendir`、`unlinkat` 和 `lstat` 函数 (10.10 和 REDOX 之前版本的 macOS 除外) 和 Windows 上的 `CreateFileW`、`GetFileInformationByHandleEx`、`SetFileInformationByHandle` 和 `NtCreateFile` 函数。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// 在 10.10 和 REDOX 之前版本的 macOS 上，以及在 Miri 中针对任何目标运行时，此函数不受 time-of-check to time-of-use (TOCTOU) 竞争状态的保护，不应在安全敏感代码中使用在那些平台上。
/// 所有其他平台都受到保护。
///
/// # Errors
///
/// 请参见 [`fs::remove_file`] 和 [`fs::remove_dir`]。
///
/// 如果 `remove_dir` 或 `remove_file` 在任何组成路径 (包括根路径) 上失败，则 `remove_dir_all` 将失败。
/// 因此，您要删除的目录必须存在，这意味着此功能不是幂等的。
///
/// 如果您的用例不需要验证删除，请考虑忽略该错误。
///
/// [`fs::remove_file`]: remove_file
/// [`fs::remove_dir`]: remove_dir
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     fs::remove_dir_all("/some/dir")?;
///     Ok(())
/// }
/// ```
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn remove_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
    fs_imp::remove_dir_all(path.as_ref())
}

/// 返回目录中条目的迭代器。
///
/// 迭代器将产生 <code>[io::Result]<[DirEntry]></code> 实例。
/// 最初构造迭代器后，可能会遇到新的错误。
/// 当前目录和父目录 (通常为 `.` 和 `..`) 的条目将被跳过。
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `opendir` 函数和 Windows 上的 `FindFirstFile` 函数。
/// 推进迭代器当前对应于 Unix 上的 `readdir` 和 Windows 上的 `FindNextFile`。
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// 该迭代器返回条目的顺序取决于平台和文件系统。
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * 提供的 `path` 不存在。
/// * 该进程没有查看内容的权限。
/// * `path` 指向非目录文件。
///
/// # Examples
///
/// ```
/// use std::io;
/// use std::fs::{self, DirEntry};
/// use std::path::Path;
///
/// // 一种仅通过访问文件来遍历目录的可能实现方式
/// fn visit_dirs(dir: &Path, cb: &dyn Fn(&DirEntry)) -> io::Result<()> {
///     if dir.is_dir() {
///         for entry in fs::read_dir(dir)? {
///             let entry = entry?;
///             let path = entry.path();
///             if path.is_dir() {
///                 visit_dirs(&path, cb)?;
///             } else {
///                 cb(&entry);
///             }
///         }
///     }
///     Ok(())
/// }
/// ```
///
/// ```rust,no_run
/// use std::{fs, io};
///
/// fn main() -> io::Result<()> {
///     let mut entries = fs::read_dir(".")?
///         .map(|res| res.map(|e| e.path()))
///         .collect::<Result<Vec<_>, io::Error>>()?;
///
///     // 不保证 `read_dir` 返回条目的顺序。
///     // 如果需要可重复的排序，则应对条目进行显式排序。
///
///     entries.sort();
///
///     // 现在，条目已经按照路径进行了排序。
///
///     Ok(())
/// }
/// ```
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn read_dir<P: AsRef<Path>>(path: P) -> io::Result<ReadDir> {
    fs_imp::readdir(path.as_ref()).map(ReadDir)
}

/// 更改在文件或目录上找到的权限。
///
/// # 特定于平台的行为
///
/// 该函数当前对应于 Unix 上的 `chmod` 函数和 Windows 上的 `SetFileAttributes` 函数。
///
/// 注意，这个 [将来可能会改变][changes]。
///
/// [changes]: io#platform-specific-behavior
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不仅限于这些情况：
///
/// * `path` 不存在。
/// * 用户没有更改文件属性的权限。
///
/// # Examples
///
/// ```no_run
/// use std::fs;
///
/// fn main() -> std::io::Result<()> {
///     let mut perms = fs::metadata("foo.txt")?.permissions();
///     perms.set_readonly(true);
///     fs::set_permissions("foo.txt", perms)?;
///     Ok(())
/// }
/// ```
///
#[stable(feature = "set_permissions", since = "1.1.0")]
pub fn set_permissions<P: AsRef<Path>>(path: P, perm: Permissions) -> io::Result<()> {
    fs_imp::set_perm(path.as_ref(), perm.0)
}

impl DirBuilder {
    /// 使用所有平台的默认 mode/security 设置创建一组新选项，并且这些选项也是非递归的。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs::DirBuilder;
    ///
    /// let builder = DirBuilder::new();
    /// ```
    #[stable(feature = "dir_builder", since = "1.6.0")]
    #[must_use]
    pub fn new() -> DirBuilder {
        DirBuilder { inner: fs_imp::DirBuilder::new(), recursive: false }
    }

    /// 指示应递归创建目录，并创建所有父目录。
    /// 使用相同的安全性和权限设置创建不存在的父级。
    ///
    /// 此选项默认为 `false`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::fs::DirBuilder;
    ///
    /// let mut builder = DirBuilder::new();
    /// builder.recursive(true);
    /// ```
    ///
    #[stable(feature = "dir_builder", since = "1.6.0")]
    pub fn recursive(&mut self, recursive: bool) -> &mut Self {
        self.recursive = recursive;
        self
    }

    /// 使用在此构建器中配置的选项来创建指定的目录。
    ///
    /// 如果目录已经存在，除非启用了递归模式，否则将被视为错误。
    ///
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use std::fs::{self, DirBuilder};
    ///
    /// let path = "/tmp/foo/bar/baz";
    /// DirBuilder::new()
    ///     .recursive(true)
    ///     .create(path).unwrap();
    ///
    /// assert!(fs::metadata(path).unwrap().is_dir());
    /// ```
    ///
    #[stable(feature = "dir_builder", since = "1.6.0")]
    pub fn create<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self._create(path.as_ref())
    }

    fn _create(&self, path: &Path) -> io::Result<()> {
        if self.recursive { self.create_dir_all(path) } else { self.inner.mkdir(path) }
    }

    fn create_dir_all(&self, path: &Path) -> io::Result<()> {
        if path == Path::new("") {
            return Ok(());
        }

        match self.inner.mkdir(path) {
            Ok(()) => return Ok(()),
            Err(ref e) if e.kind() == io::ErrorKind::NotFound => {}
            Err(_) if path.is_dir() => return Ok(()),
            Err(e) => return Err(e),
        }
        match path.parent() {
            Some(p) => self.create_dir_all(p)?,
            None => {
                return Err(io::const_io_error!(
                    io::ErrorKind::Uncategorized,
                    "failed to create whole tree",
                ));
            }
        }
        match self.inner.mkdir(path) {
            Ok(()) => Ok(()),
            Err(_) if path.is_dir() => Ok(()),
            Err(e) => Err(e),
        }
    }
}

impl AsInnerMut<fs_imp::DirBuilder> for DirBuilder {
    #[inline]
    fn as_inner_mut(&mut self) -> &mut fs_imp::DirBuilder {
        &mut self.inner
    }
}

/// 如果路径指向现有实体，则返回 `Ok(true)`。
///
/// 该函数将遍历符号链接以查询有关目标文件的信息。
/// 如果符号链接断开，则将返回 `Ok(false)`。
///
/// 与 [`Path::exists`] 方法相反，如果验证路径存在或不存在，这只会返回 `Ok(true)` 或 `Ok(false)`。
///
/// 如果既不能确认也不能否认它的存在，则将传播 `Err(_)`。
/// 这可能是这种情况，例如
/// 对其中一个父目录的列表权限被拒绝。
///
/// 请注意，虽然这避免了 `exists()` 方法的一些缺陷，但它仍然无法防止时间检查到使用时间 (TOCTOU) 错误。
/// 您应该只在这些错误不是问题的情况下使用它。
///
/// # Examples
///
/// ```no_run
/// #![feature(fs_try_exists)]
/// use std::fs;
///
/// assert!(!fs::try_exists("does_not_exist.txt").expect("Can't check existence of file does_not_exist.txt"));
/// assert!(fs::try_exists("/root/secret_file.txt").is_err());
/// ```
///
/// [`Path::exists`]: crate::path::Path::exists
// FIXME: 稳定性应修改 `exists()` 的文档以推荐此方法。
//
#[unstable(feature = "fs_try_exists", issue = "83186")]
#[inline]
pub fn try_exists<P: AsRef<Path>>(path: P) -> io::Result<bool> {
    fs_imp::try_exists(path.as_ref())
}