Struct std::fs::OpenOptions

pub struct OpenOptions(_);

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

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

一般而言，使用 OpenOptions 时，首先要调用 OpenOptions::new，然后链式调用方法以设置每个选项，然后调用 OpenOptions::open，传递要打开的文件的路径。

这将为您提供一个内部带有 File 的 io::Result，您可以对其进行进一步的操作。

Examples

打开一个文件以读取：

use std::fs::OpenOptions;

let file = OpenOptions::new().read(true).open("foo.txt");

打开一个文件进行读写，如果不存在则创建一个文件：

use std::fs::OpenOptions;

let file = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .open("foo.txt");

Implementations

impl OpenOptions

pub fn new() -> Self

创建一组可供配置的空白新选项。

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

Examples

use std::fs::OpenOptions;

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

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

设置读取访问权限的选项。

该选项为 true 时，则表示打开的文件应该是可读的。

Examples

use std::fs::OpenOptions;

let file = OpenOptions::new().read(true).open("foo.txt");

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

设置写访问权限的选项。

此选项为 true 时，则表示打开的文件应该是可写的。

如果该文件已经存在，则对该文件的任何写调用都将覆盖其内容，而不会将其截断。

Examples

use std::fs::OpenOptions;

let file = OpenOptions::new().write(true).open("foo.txt");

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

设置追加模式的选项。

此选项为 true 时，表示写入将追加到文件中，而不是覆盖以前的内容。 请注意，设置 .write(true).append(true) 与仅设置 .append(true) 具有相同的效果。

对于大多数文件系统，操作系统保证所有写操作都是原子的：不会浪费任何写操作，因为另一个进程会同时进行写操作。

使用追加模式时，可能有一个明显的注意事项：确保一次完成将所有在一起的数据写入文件。 这可以通过在将字符串传递给 write() 之前串联字符串，或使用缓冲的 writer (具有足够大小的缓冲区) 并在消息完成后调用 flush() 来完成。

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

Note

如果该函数不存在，则该函数不会创建该文件。使用 OpenOptions::create 方法来执行此操作。

Examples

use std::fs::OpenOptions;

let file = OpenOptions::new().append(true).open("foo.txt");

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

设置截断上一个文件的选项。

如果使用此选项设置成功打开了文件，则如果文件已经存在，它将把文件的长度截断为 0。

该文件必须具有写访问权限才能打开，才能进行截断。

Examples

use std::fs::OpenOptions;

let file = OpenOptions::new().write(true).truncate(true).open("foo.txt");

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

设置选项以创建一个新文件，或者如果已经存在则将其打开。

为了创建文件，必须使用 OpenOptions::write 或 OpenOptions::append 访问。

另请参见 std::fs::write()，了解使用给定数据创建文件的简单函数。

Examples

use std::fs::OpenOptions;

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

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

设置创建新文件的选项，如果该文件已经存在则失败。

目标位置不允许存在任何文件，(dangling) 符号链接也不允许存在。这样，如果调用成功，则保证返回的文件是新文件。

此选项很有用，因为它是原子的。 否则，在检查文件是否存在与创建新文件之间，文件可能是由另一个进程创建的 (TOCTOU 竞态条件 / 攻击)。

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

必须使用写或追加访问权限打开文件才能创建新文件。

Examples

use std::fs::OpenOptions;

let file = OpenOptions::new().write(true)
                             .create_new(true)
                             .open("foo.txt");

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

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

Errors

在许多不同的情况下，此函数将返回错误。其中列出了一些错误条件及其 io::ErrorKind。 映射到 io::ErrorKind 不是函数兼容性契约的一部分。

• NotFound: 指定的文件不存在，并且未设置 create 或 create_new。
• AlreadyExists: 指定了 create_new 并且文件已经存在。
• InvalidInput: 打开选项无效组合 (在没有写访问、没有访问模式设置等情况下截断)。

以下错误目前与任何现有的 io::ErrorKind 都不匹配：

• 实际上，指定文件路径的目录组件之一不是目录。
• 文件系统级错误：已满磁盘，对只读文件系统请求的写许可权，超出磁盘配额，打开的文件过多，文件名太长，指定路径中的符号链接太多 (仅适用于 Unix 系统)，等等。

Examples

use std::fs::OpenOptions;

let file = OpenOptions::new().read(true).open("foo.txt");

Trait Implementations

impl Clone for OpenOptions

fn clone(&self) -> OpenOptions

返回值的副本。

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

从 source 执行复制分配。

impl Debug for OpenOptions

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

使用给定的格式化程序格式化该值。

impl OpenOptionsExt for OpenOptions

Available on WASI only.

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

🔬This is a nightly-only experimental API. (wasi_ext #71213)

将自定义 dirflags 参数传递给 path_open。

fn directory(&mut self, dir: bool) -> &mut OpenOptions

🔬This is a nightly-only experimental API. (wasi_ext #71213)

指示 OpenOptions 是否必须打开目录。

fn dsync(&mut self, enabled: bool) -> &mut OpenOptions

🔬This is a nightly-only experimental API. (wasi_ext #71213)

指示是否在 path_open 的 fs_flags 字段中传递 __WASI_FDFLAG_DSYNC。

fn nonblock(&mut self, enabled: bool) -> &mut OpenOptions

🔬This is a nightly-only experimental API. (wasi_ext #71213)

指示是否在 path_open 的 fs_flags 字段中传递 __WASI_FDFLAG_NONBLOCK。

fn rsync(&mut self, enabled: bool) -> &mut OpenOptions

🔬This is a nightly-only experimental API. (wasi_ext #71213)

指示是否在 path_open 的 fs_flags 字段中传递 __WASI_FDFLAG_RSYNC。

fn sync(&mut self, enabled: bool) -> &mut OpenOptions

🔬This is a nightly-only experimental API. (wasi_ext #71213)

指示是否在 path_open 的 fs_flags 字段中传递 __WASI_FDFLAG_SYNC。

fn fs_rights_base(&mut self, rights: u64) -> &mut OpenOptions

🔬This is a nightly-only experimental API. (wasi_ext #71213)

指示应为 path_open 的 fs_rights_base 参数传递的值。

fn fs_rights_inheriting(&mut self, rights: u64) -> &mut OpenOptions

🔬This is a nightly-only experimental API. (wasi_ext #71213)

指示应为 path_open 的 fs_rights_inheriting 参数传递的值。

fn open_at<P: AsRef<Path>>(&self, file: &File, path: P) -> Result<File>

🔬This is a nightly-only experimental API. (wasi_ext #71213)

打开文件或目录。

impl OpenOptionsExt for OpenOptions

Available on Windows only.

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

将 dwDesiredAccess 参数覆盖为具有指定值的 CreateFile。

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

将 dwShareMode 参数覆盖为具有指定值的 CreateFile。

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

将 dwFileFlags 参数的额外标志设置为 CreateFile2 的指定值 (或将其与 attributes 和 security_qos_flags 组合以将 dwFlagsAndAttributes 设置为 CreateFile)。

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

将 dwFileAttributes 参数设置为 CreateFile2 的指定值 (或将其与 custom_flags 和 security_qos_flags 组合以将 dwFlagsAndAttributes 设置为 CreateFile)。

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

将 dwSecurityQosFlags 参数设置为 CreateFile2 的指定值 (或将其与 custom_flags 和 attributes 组合以将 dwFlagsAndAttributes 设置为 CreateFile)。

impl OpenOptionsExt for OpenOptions

Available on Unix only.

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

设置将用于创建新文件的模式位。

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

将自定义标志传递给 open 的 flags 参数。