结构体 OpenOptions 

pub struct OpenOptions { /* private fields */ }

可用于配置文件打开方式的选项和标志。

此构建器 提供配置 File 打开方式 以及允许在打开的文件上执行哪些操作的能力。 File::open 和 File::create 方法是 使用此构建器的 常用选项的别名。

一般来说， 使用 OpenOptions 时， 你首先调用 new， 然后 链接调用方法 以设置每个选项， 最后调用 open， 并传入 要打开的文件的路径。 这将为你 返回一个 io::Result， 其中 包含一个 File， 你可以 进一步操作 它。

This is a specialized version of std::fs::OpenOptions for usage from the Tokio 运行时。

为比此处提供的方法 更高级的配置 实现了 From<std::fs::OpenOptions>。

示例

打开一个文件以供读取：

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .read(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

打开一个文件 用于读写， 并在它不存在时创建它：

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

实现

impl OpenOptions

pub fn new() -> OpenOptions

创建一个准备好用于配置的空白选项集合。

所有选项最初都设置为 false。

这是 std::fs::OpenOptions::new 的异步版本

示例

use tokio::fs::OpenOptions;

let mut options = OpenOptions::new();
let future = options.read(true).open("foo.txt");

pub fn read(&mut self, read: bool) -> &mut OpenOptions

设置读访问选项。

当该选项为 true 时，将指示文件在打开后 应可 read。

这是 std::fs::OpenOptions::read 的异步版本

示例

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .read(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

pub fn write(&mut self, write: bool) -> &mut OpenOptions

设置写访问选项。

当该选项为 true 时，将指示文件在打开后 应可 write。

这是 std::fs::OpenOptions::write 的异步版本

示例

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

pub fn append(&mut self, append: bool) -> &mut OpenOptions

设置追加模式选项。

当该选项为 true 时，意味着写入将追加到文件末尾， 而不是覆盖之前的内容。请注意，设置 .write(true).append(true) 的效果与仅设置 .append(true) 相同。

对于大多数文件系统，操作系统保证所有 写入操作都是原子的：不会因为 另一个进程同时写入而导致写入失败。

使用追加模式时有一句话可能很明显但仍然要强调： 确保属于一起的所有数据在一次操作中写入文件。 可以通过在将字符串传递给 write() 之前连接字符串来实现， 或者使用缓冲写入器（缓冲区大小合适）， 并在消息完成时调用 flush()。

如果文件以读和追加访问同时打开，请注意在打开之后以及 每次写入之后，用于读取的位置 可能会被设置在文件末尾。因此，在写入之前， 保存当前位置（使用 seek(SeekFrom::Current(0))），并在下次读取前恢复它。

这是 std::fs::OpenOptions::append 的异步版本

Note

如果文件不存在，此函数不会创建它。使用 create 方法可以做到这一点。

示例

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .append(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

pub fn truncate(&mut self, truncate: bool) -> &mut OpenOptions

设置截断现有文件的选项。

如果设置此选项后成功打开文件， 将在文件已存在时将其截断为 0 长度。

要使截断生效，必须以写入访问打开文件。

这是 std::fs::OpenOptions::truncate 的异步版本

示例

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .truncate(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

pub fn create(&mut self, create: bool) -> &mut OpenOptions

设置创建新文件的选项。

此选项指示在文件尚不存在时是否 将创建新文件。

要创建文件，必须使用 write 或 append 访问。

这是 std::fs::OpenOptions::create 的异步版本

示例

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .create(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

pub fn create_new(&mut self, create_new: bool) -> &mut OpenOptions

设置始终创建新文件的选项。

此选项指示是否将创建新文件。在目标位置 不允许存在任何文件，也不允许（悬空）符号链接。

此选项很有用，因为它是原子操作。否则，在检查 文件是否存在和创建新文件之间，文件 可能被另一个进程创建（TOCTOU 竞争条件 / 攻击）。

如果设置了 .create_new(true)，.create() 和 .truncate() 将被忽略。

要创建新文件，必须以写或追加访问方式打开文件。

这是 std::fs::OpenOptions::create_new 的异步版本

示例

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .create_new(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

pub async fn open(&self, path: impl AsRef<Path>) -> Result<File>

使用 self 指定的选项在 path 打开一个文件。

这是 std::fs::OpenOptions::open 的异步版本

Errors

此函数在许多不同情况下会返回错误。此处列出了部分 错误情况及其 ErrorKind。到 ErrorKind 的映射 不属于该函数的兼容性约定，尤其 Other 种类 将来可能会更改为更具体的种类。

• NotFound: The specified file does not exist and neither create or create_new is set.
• NotFound: One of the directory components of the file path does not exist.
• PermissionDenied: The user lacks permission to get the specified access rights for the file.
• PermissionDenied: The user lacks permission to open one of the directory components of the specified path.
• AlreadyExists: create_new was specified and the file already exists.
• InvalidInput: Invalid combinations of open options (truncate without write access, no access mode set, etc.).
• Other: One of the directory components of the specified file path was not, in fact, a directory.
• Other: Filesystem-level errors: full disk, write permission requested on a read-only file system, exceeded disk quota, too many open files, too long filename, too many symbolic links in the specified path (Unix-like systems only), etc.

io_uring support

在 Linux 上，你还可以使用 io_uring 来执行系统调用。 要启用 io_uring，需要在编译时指定 --cfg tokio_unstable 标志，启用 io-uring cargo 特性， 并设置 Builder::enable_io_uring 运行时选项。

io_uring 支持目前是实验性的，因此其行为 将来版本中可能会改变或被删除。

示例

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new().open("foo.txt").await?;
    Ok(())
}

impl OpenOptions

pub fn access_mode(&mut self, access: u32) -> &mut OpenOptions

将调用 CreateFile 时的 dwDesiredAccess 参数覆盖为指定值。

这将覆盖 OpenOptions 结构上的 read、write、append 标志。此方法提供对读写和追加数据、属性（如隐藏 和系统）以及扩展属性的精细控制。

示例

use tokio::fs::OpenOptions;

// Open without read and write permission, for example if you only need
// to call `stat` on the file
let file = OpenOptions::new().access_mode(0).open("foo.txt").await?;

pub fn share_mode(&mut self, share: u32) -> &mut OpenOptions

将调用 CreateFile 时的 dwShareMode 参数覆盖为指定值。

默认情况下，share_mode 设置为 FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE。这允许 其他进程在文件打开时对同一文件进行读、 写和删除 / 重命名操作。删除任何 标志都会阻止其他进程执行相应的操作， 直到文件句柄关闭为止。

示例

use tokio::fs::OpenOptions;

// Do not allow others to read or modify this file while we have it open
// for writing.
let file = OpenOptions::new()
    .write(true)
    .share_mode(0)
    .open("foo.txt").await?;

pub fn custom_flags(&mut self, flags: u32) -> &mut OpenOptions

将调用 CreateFile2 时的 dwFileFlags 参数的附加标志设置为指定值（或将其与 attributes 和 security_qos_flags 组合，为 CreateFile 设置 dwFlagsAndAttributes）。

自定义标志只能设置标志，不能移除 Rust 选项设置的 标志。此选项会覆盖任何 先前设置的自定义标志。

示例

use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_DELETE_ON_CLOSE;
use tokio::fs::OpenOptions;

let file = OpenOptions::new()
    .create(true)
    .write(true)
    .custom_flags(FILE_FLAG_DELETE_ON_CLOSE)
    .open("foo.txt").await?;

pub fn attributes(&mut self, attributes: u32) -> &mut OpenOptions

将调用 CreateFile2 时的 dwFileAttributes 参数设置为指定值（或将其与 custom_flags 和 security_qos_flags 组合，为 CreateFile 设置 dwFlagsAndAttributes）。

如果因为文件尚不存在而 创建新文件，并且指定了 .create(true) 或 .create_new(true)，则 新文件将具有通过 .attributes() 声明的属性。

如果以 .create(true).truncate(true) 打开现有文件， 其现有属性会保留，并与通过 .attributes() 声明的属性组合。

在所有其他情况下，属性将被忽略。

示例

use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_HIDDEN;
use tokio::fs::OpenOptions;

let file = OpenOptions::new()
    .write(true)
    .create(true)
    .attributes(FILE_ATTRIBUTE_HIDDEN)
    .open("foo.txt").await?;

pub fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions

将调用 CreateFile2 时的 dwSecurityQosFlags 参数设置为指定值（或将其与 custom_flags 和 attributes 组合，为 CreateFile 设置 dwFlagsAndAttributes）。

默认情况下，security_qos_flags 未设置。在打开 命名管道时应指定它，以控制服务器进程可以 代表客户端进程执行操作的程度（安全模拟级别）。

当 security_qos_flags 未设置时，恶意程序 可能会诱使特权 Rust 进程打开用户指定的路径（通过让其打开命名管道）， 从而获得该特权进程的提升权限。因此有人认为 在打开任意路径时也应设置 security_qos_flags。然而这些位 可能与其他标志冲突，特别是 FILE_FLAG_OPEN_NO_RECALL。

有关可能的取值，请参阅 Windows 开发人员中心站点上的 模拟级别。 使用此方法时，SECURITY_SQOS_PRESENT 标志 会自动设置。

示例

use windows_sys::Win32::Storage::FileSystem::SECURITY_IDENTIFICATION;
use tokio::fs::OpenOptions;

let file = OpenOptions::new()
    .write(true)
    .create(true)

    // Sets the flag value to `SecurityIdentification`.
    .security_qos_flags(SECURITY_IDENTIFICATION)

    .open(r"\\.\pipe\MyPipe").await?;

Trait 实现

impl Clone for OpenOptions

fn clone(&self) -> OpenOptions

返回值的副本。 更多信息

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. 更多信息

impl Debug for OpenOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化器格式化此值。 更多信息

impl Default for OpenOptions

fn default() -> Self

Returns the “default value” for a type. 更多信息

impl From<OpenOptions> for OpenOptions

fn from(options: StdOpenOptions) -> OpenOptions

从输入类型转换为此类型。