Struct std::fs::File1.0.0[][src]

pub struct File { /* fields omitted */ }
Expand description

对文件系统上打开的文件的引用。

可以通过打开 File 的选项来读取或者写入 File 的实例。文件还实现 Seek,以更改文件内部包含的逻辑游标。

文件离开作用域时将自动关闭。Drop 的实现将忽略在关闭时检测到的错误。如果必须手动处理这些错误,请使用方法 sync_all

Examples

创建一个新文件并向其写入字节 (您也可以使用 write()) :

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(())
}
Run

将文件内容读入 String (也可以使用 read) :

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(())
}
Run

使用缓冲的 Read 来读取文件的内容可能会更有效。这可以用 BufReader<R> 完成:

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(())
}
Run

请注意,虽然读写方法需要一个 &mut File,但由于 ReadWrite 的接口,&File 的持有者仍然可以修改文件,可以通过采用 &File 的方法,也可以通过检索底层操作系统对象并以这种方式修改文件。

另外,许多操作系统允许通过不同的进程并发修改文件。避免假定持有 &File 意味着文件不会更改。

Implementations

尝试以只读模式打开文件。

有关更多详细信息,请参见 OpenOptions::open 方法。

Errors

如果 path 还不存在,则此函数将返回错误。 根据 OpenOptions::open,可能还会返回其他错误。

Examples
use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut f = File::open("foo.txt")?;
    Ok(())
}
Run

以只写模式打开文件。

如果该函数不存在,则此函数将创建一个文件,如果存在则将截断该文件。

有关更多详细信息,请参见 OpenOptions::open 函数。

Examples
use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut f = File::create("foo.txt")?;
    Ok(())
}
Run

返回一个新的 OpenOptions 对象。

如果不适合使用 open()create(),则此函数返回一个新的 OpenOptions 对象,可用于打开或创建具有特定选项的文件。

它等效于 OpenOptions::new(),但允许您编写更具可读性的代码。 您可以编写 File::options().read(true).open("foo.txt") 来代替 OpenOptions::new().read(true).open("foo.txt")。 这也避免了导入 OpenOptions 的需要。

有关更多详细信息,请参见 OpenOptions::new 函数。

Examples
use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut f = File::options().read(true).open("foo.txt")?;
    Ok(())
}
Run

尝试将所有操作系统内部元数据同步到磁盘。

此函数将尝试确保所有内存数据在返回之前都已到达文件系统。

这可用于处理错误,否则这些错误仅在 File 关闭时才会被捕获。 丢弃文件将忽略同步此内存中数据的错误。

Examples
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(())
}
Run

该函数与 sync_all 类似,不同之处在于它可能不会将文件元数据同步到文件系统。

这适用于必须同步内容但不需要磁盘上元数据的用例。 此方法的目标是减少磁盘操作。

请注意,某些平台可能只是根据 sync_all 来实现此目的。

Examples
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(())
}
Run

截断或扩展底层文件,将此文件的大小更新为 size

如果 size 小于当前文件的大小,则文件将被缩小。 如果它大于当前文件的大小,则文件将扩展到 size,并且所有中间数据都用 0 填充。

文件的游标未更改。 特别是,如果游标位于末尾,并且使用此操作将文件缩小了,那么游标现在将超过末尾。

Errors

如果未打开文件进行写入,则此函数将返回错误。 同样,如果期望的长度由于实现细节而导致溢出,则将返回 std::io::ErrorKind::InvalidInput。

Examples
use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut f = File::create("foo.txt")?;
    f.set_len(10)?;
    Ok(())
}
Run

请注意,即使使用 &self 而不是 &mut self,此方法也会更改底层文件的内容。

查询有关底层文件的元数据。

Examples
use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut f = File::open("foo.txt")?;
    let metadata = f.metadata()?;
    Ok(())
}
Run

创建一个新的 File 实例,该实例与现有 File 实例共享相同的底层文件句柄。 读取,写入和查找将同时影响两个 File 实例。

Examples

为名为 foo.txt 的文件创建两个句柄:

use std::fs::File;

fn main() -> std::io::Result<()> {
    let mut file = File::open("foo.txt")?;
    let file_copy = file.try_clone()?;
    Ok(())
}
Run

假设有一个名为 foo.txt 的文件,其内容为 abcdef\n,创建两个句柄,查找其中一个,然后从另一个句柄读取剩余的字节:

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(())
}
Run

更改底层文件的权限。

特定于平台的行为

该函数当前对应于 Unix 上的 fchmod 函数和 Windows 上的 SetFileInformationByHandle 函数。

注意,这个 将来可能会改变

Errors

如果用户缺少底层文件的权限更改属性,则此函数将返回错误。 在其他特定于操作系统的未指定情况下,它也可能返回错误。

Examples
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(())
}
Run

请注意,即使使用 &self 而不是 &mut self,此方法也会更改底层文件的权限。

Trait Implementations

🔬 This is a nightly-only experimental API. (io_safety #87074)
This is supported on Unix only.

借用文件描述符。 Read more

🔬 This is a nightly-only experimental API. (io_safety #87074)

借用句柄。 Read more

This is supported on Unix only.

提取原始文件描述符。 Read more

提取原始句柄,无需任何所有权。

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

从给定的偏移量开始读取多个字节。 Read more

从给定的偏移量开始写入多个字节。 Read more

从给定的偏移量读取填充 buf 所需的确切字节数。 Read more

尝试从给定的偏移量开始写入整个缓冲区。 Read more

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

从给定的偏移量开始读取多个字节。 Read more

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

从给定的偏移量开始写入多个字节。 Read more

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

返回文件中的当前位置。 Read more

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

调整与此文件关联的标志。 Read more

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

调整与此文件关联的权限。 Read more

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

提供有关文件描述符的文件咨询信息。 Read more

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

强制在文件中分配空间。 Read more

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

创建一个目录。 Read more

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

读取符号链接的内容。 Read more

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

返回文件或目录的属性。 Read more

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

取消链接文件。 Read more

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

删除目录。 Read more

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

从给定的偏移量开始读取多个字节。 Read more

从给定的偏移量读取填充 buf 所需的确切字节数。 Read more

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

从给定的偏移量开始写入多个字节。 Read more

尝试从给定的偏移量开始写入整个缓冲区。 Read more

搜寻到给定位置并读取多个字节。 Read more

搜寻到给定位置并写入多个字节。 Read more

执行转换。

执行转换。

File 转换为 Stdio

Examples

File 将在引擎盖下使用 Stdio::from 转换为 Stdio

use std::fs::File;
use std::process::Command;

// 使用包含 `Hello,world! ` 的 `foo.txt` 文件。
let file = File::open("foo.txt").unwrap();

let reverse = Command::new("rev")
    .stdin(file)  // 隐式文件转换为 Stdio
    .output()
    .expect("failed reverse command");

assert_eq!(reverse.stdout, b"!dlrow ,olleH");
Run

执行转换。

执行转换。

This is supported on Unix only.

根据给定的原始文件描述符构造 Self 的新实例。 Read more

从指定的原始句柄创建一个新的 I/O 对象。 Read more

This is supported on Unix only.

消费这个对象,返回原始的底层文件描述符。 Read more

消耗此对象,返回原始底层句柄。 Read more

从该源中提取一些字节到指定的缓冲区中,返回读取的字节数。 Read more

read 相似,不同之处在于它读入缓冲区的一部分。 Read more

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Read 是否具有有效的 read_vectored 实现。 Read more

🔬 This is a nightly-only experimental API. (read_initializer #42788)

确定此 Reader 是否可以使用未初始化内存的缓冲区。 Read more

读取所有字节,直到此源中的 EOF 为止,然后将它们放入 bufRead more

读取这个源中的所有字节,直到 EOF 为止,然后将它们追加到 bufRead more

读取填充 buf 所需的确切字节数。 Read more

为这个 Read 实例创建一个基于引用的适配器。 Read more

将此 Read 实例的字节数转换为 IteratorRead more

创建一个适配器,将这个流与另一个链接起来。 Read more

创建一个适配器,最多从中读取 limit 个字节。 Read more

从该源中提取一些字节到指定的缓冲区中,返回读取的字节数。 Read more

read 相似,不同之处在于它读入缓冲区的一部分。 Read more

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Read 是否具有有效的 read_vectored 实现。 Read more

🔬 This is a nightly-only experimental API. (read_initializer #42788)

确定此 Reader 是否可以使用未初始化内存的缓冲区。 Read more

读取所有字节,直到此源中的 EOF 为止,然后将它们放入 bufRead more

读取这个源中的所有字节,直到 EOF 为止,然后将它们追加到 bufRead more

读取填充 buf 所需的确切字节数。 Read more

为这个 Read 实例创建一个基于引用的适配器。 Read more

将此 Read 实例的字节数转换为 IteratorRead more

创建一个适配器,将这个流与另一个链接起来。 Read more

创建一个适配器,最多从中读取 limit 个字节。 Read more

在流中寻找以字节为单位的偏移量。 Read more

返回到流的开头。 Read more

🔬 This is a nightly-only experimental API. (seek_stream_len #59359)

返回此流的长度 (以字节为单位)。 Read more

从流的开头返回当前查找位置。 Read more

在流中寻找以字节为单位的偏移量。 Read more

返回到流的开头。 Read more

🔬 This is a nightly-only experimental API. (seek_stream_len #59359)

返回此流的长度 (以字节为单位)。 Read more

从流的开头返回当前查找位置。 Read more

在此 writer 中写入一个缓冲区,返回写入的字节数。 Read more

类似于 write,不同之处在于它是从缓冲区切片中写入数据的。 Read more

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Writer 是否具有有效的 write_vectored 实现。 Read more

刷新此输出流,确保所有中间缓冲的内容均到达其目的地。 Read more

尝试将整个缓冲区写入此 writer。 Read more

🔬 This is a nightly-only experimental API. (write_all_vectored #70436)

尝试将多个缓冲区写入此 writer。 Read more

将格式化的字符串写入此 writer,返回遇到的任何错误。 Read more

为这个 Write 实例创建一个 “by reference” 适配器。 Read more

在此 writer 中写入一个缓冲区,返回写入的字节数。 Read more

类似于 write,不同之处在于它是从缓冲区切片中写入数据的。 Read more

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Writer 是否具有有效的 write_vectored 实现。 Read more

刷新此输出流,确保所有中间缓冲的内容均到达其目的地。 Read more

尝试将整个缓冲区写入此 writer。 Read more

🔬 This is a nightly-only experimental API. (write_all_vectored #70436)

尝试将多个缓冲区写入此 writer。 Read more

将格式化的字符串写入此 writer,返回遇到的任何错误。 Read more

为这个 Write 实例创建一个 “by reference” 适配器。 Read more

Auto Trait Implementations

Blanket Implementations

获取 selfTypeIdRead more

从拥有的值中一成不变地借用。 Read more

从拥有的值中借用。 Read more

执行转换。

执行转换。

发生转换错误时返回的类型。

执行转换。

发生转换错误时返回的类型。

执行转换。