Struct std::fs::File

pub struct File { /* private fields */ }

提供对文件系统上打开文件的访问权限的对象。

可以通过打开 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(())
}

将文件内容读入 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(())
}

使用缓冲的 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(())
}

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

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

特定于平台的行为

在 Windows 上，File 的 Read 和 Write traits 的实现执行同步的 I/O 操作。因此，必须没有为异步 I/O 打开底层文件 (例如使用 FILE_FLAG_OVERLAPPED)。

Implementations

impl File

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

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

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

如果您只需要读取整个文件内容，请考虑使用 std::fs::read() 或 std::fs::read_to_string()。

Errors

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

Examples

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

pub fn create<P: AsRef<Path>>(path: P) -> Result<File>

以只写模式打开文件。

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

根据平台，如果完整目录路径不存在，此函数可能会失败。 有关更多详细信息，请参见 OpenOptions::open 函数。

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

Examples

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

pub fn create_new<P: AsRef<Path>>(path: P) -> Result<File>

🔬This is a nightly-only experimental API. (file_create_new #105135)

以读写模式创建一个新文件; 如果文件存在则出错。

如果文件不存在，此函数将创建一个文件，如果存在则返回错误。 这样，如果调用成功，则保证返回的文件是新的。

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

这也可以使用 File::options().read(true).write(true).create_new(true).open(...) 编写。

Examples

#![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(())
}

pub fn options() -> OpenOptions

返回一个新的 OpenOptions 对象。

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

它相当于 OpenOptions::new()，但允许您编写更具可读性的代码。 您可以写 File::options().append(true).open("example.log")，而不是 OpenOptions::new().append(true).open("example.log")。 这也避免了导入 OpenOptions 的需要。

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

Examples

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

pub fn sync_all(&self) -> Result<()>

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

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

这可用于处理错误，否则这些错误仅在 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(())
}

pub fn sync_data(&self) -> Result<()>

该函数与 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(())
}

pub fn set_len(&self, size: u64) -> Result<()>

截断或扩展底层文件，将此文件的大小更新为 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(())
}

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

pub fn metadata(&self) -> Result<Metadata>

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

Examples

use std::fs::File;

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

pub fn try_clone(&self) -> Result<File>

创建一个新的 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(())
}

假设有一个名为 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(())
}

pub fn set_permissions(&self, perm: Permissions) -> Result<()>

更改底层文件的权限。

特定于平台的行为

该函数当前对应于 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(())
}

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

pub fn set_times(&self, times: FileTimes) -> Result<()>

🔬This is a nightly-only experimental API. (file_set_times #98245)

更改底层文件的时间戳。

特定于平台的行为

该函数目前对应于 Unix 上的 futimens 函数 (在 10.13 之前回退到 macOS 上的 futimes) 和 Windows 上的 SetFileTime 函数。

注意这个 将来可能会发生变化。

Errors

如果用户没有更改底层文件时间戳的权限，此函数将返回错误。 在其他特定于操作系统的未指定情况下，它也可能返回错误。

如果操作系统不支持更改 FileTimes 结构体中设置的一个或多个时间戳，则此函数可能会返回错误。

Examples

#![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(())
}

pub fn set_modified(&self, time: SystemTime) -> Result<()>

🔬This is a nightly-only experimental API. (file_set_times #98245)

更改底层文件的修改时间。

这是 set_times(FileTimes::new().set_modified(time)) 的别名。

Trait Implementations

impl AsFd for File

fn as_fd(&self) -> BorrowedFd<'_>

借用文件描述符。

impl AsHandle for File

Available on Windows only.

fn as_handle(&self) -> BorrowedHandle<'_>

借用句柄。

impl AsRawFd for File

fn as_raw_fd(&self) -> RawFd

提取原始文件描述符。

impl AsRawHandle for File

Available on Windows only.

fn as_raw_handle(&self) -> RawHandle

提取原始句柄。

impl Debug for File

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

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

impl FileExt for File

Available on WASI only.

fn read_vectored_at( &self, bufs: &mut [IoSliceMut<'_>], offset: u64 ) -> Result<usize>

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

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

fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> Result<usize>

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

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

fn tell(&self) -> Result<u64>

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

返回文件中的当前位置。

fn fdstat_set_flags(&self, flags: u16) -> Result<()>

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

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

fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> Result<()>

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

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

fn advise(&self, offset: u64, len: u64, advice: u8) -> Result<()>

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

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

fn allocate(&self, offset: u64, len: u64) -> Result<()>

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

强制在文件中分配空间。

fn create_directory<P: AsRef<Path>>(&self, dir: P) -> Result<()>

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

创建一个目录。

fn read_link<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

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

读取符号链接的内容。

fn metadata_at<P: AsRef<Path>>( &self, lookup_flags: u32, path: P ) -> Result<Metadata>

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

返回文件或目录的属性。

fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

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

取消链接文件。

fn remove_directory<P: AsRef<Path>>(&self, path: P) -> Result<()>

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

删除目录。

fn read_at(&self, buf: &mut [u8], offset: u64) -> Result<usize>

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

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

fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>

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

fn write_at(&self, buf: &[u8], offset: u64) -> Result<usize>

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

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

fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

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

impl FileExt for File

Available on Windows only.

fn seek_read(&self, buf: &mut [u8], offset: u64) -> Result<usize>

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

fn seek_write(&self, buf: &[u8], offset: u64) -> Result<usize>

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

impl FileExt for File

Available on Unix only.

fn read_at(&self, buf: &mut [u8], offset: u64) -> Result<usize>

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

fn read_vectored_at( &self, bufs: &mut [IoSliceMut<'_>], offset: u64 ) -> Result<usize>

🔬This is a nightly-only experimental API. (unix_file_vectored_at #89517)

与 read_at 类似，只是它读入一片缓冲区。

fn write_at(&self, buf: &[u8], offset: u64) -> Result<usize>

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

fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> Result<usize>

🔬This is a nightly-only experimental API. (unix_file_vectored_at #89517)

与 write_at 类似，只是它从缓冲区的一片中写入。

fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>

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

fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

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

impl From<File> for OwnedFd

fn from(file: File) -> OwnedFd

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

impl From<File> for OwnedHandle

Available on Windows only.

fn from(file: File) -> OwnedHandle

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

impl From<File> for Stdio

fn from(file: File) -> Stdio

将 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");

impl From<OwnedFd> for File

fn from(owned_fd: OwnedFd) -> Self

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

impl From<OwnedHandle> for File

Available on Windows only.

fn from(owned: OwnedHandle) -> Self

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

impl FromRawFd for File

unsafe fn from_raw_fd(fd: RawFd) -> File

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

impl FromRawHandle for File

Available on Windows only.

unsafe fn from_raw_handle(handle: RawHandle) -> File

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

impl IntoRawFd for File

fn into_raw_fd(self) -> RawFd

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

impl IntoRawHandle for File

Available on Windows only.

fn into_raw_handle(self) -> RawHandle

消耗此对象，返回原始底层句柄。

impl IsTerminal for File

fn is_terminal(&self) -> bool

如果 descriptor/handle 引用 terminal/tty，则返回 true。

impl Read for &File

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

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

fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>

🔬This is a nightly-only experimental API. (read_buf #78485)

从此源中提取一些字节到指定的缓冲区中。

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

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

fn is_read_vectored(&self) -> bool

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

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

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

读取所有字节，直到此源中的 EOF 为止，然后将它们放入 buf。

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

读取这个源中的所有字节，直到 EOF 为止，然后将它们追加到 buf。

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

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

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>

🔬This is a nightly-only experimental API. (read_buf #78485)

读取填充 cursor 所需的确切字节数。

fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,

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

fn bytes(self) -> Bytes<Self> where Self: Sized,

将此 Read 实例的字节数转换为 Iterator。

fn chain<R: Read>(self, next: R) -> Chain<Self, R> where Self: Sized,

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

fn take(self, limit: u64) -> Take<Self> where Self: Sized,

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

impl Read for File

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

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

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

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

fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>

🔬This is a nightly-only experimental API. (read_buf #78485)

从此源中提取一些字节到指定的缓冲区中。

fn is_read_vectored(&self) -> bool

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

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

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

读取所有字节，直到此源中的 EOF 为止，然后将它们放入 buf。

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

读取这个源中的所有字节，直到 EOF 为止，然后将它们追加到 buf。

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

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

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<()>

🔬This is a nightly-only experimental API. (read_buf #78485)

读取填充 cursor 所需的确切字节数。

fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,

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

fn bytes(self) -> Bytes<Self> where Self: Sized,

将此 Read 实例的字节数转换为 Iterator。

fn chain<R: Read>(self, next: R) -> Chain<Self, R> where Self: Sized,

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

fn take(self, limit: u64) -> Take<Self> where Self: Sized,

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

impl Seek for &File

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

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

fn rewind(&mut self) -> Result<()>

返回到流的开头。

fn stream_len(&mut self) -> Result<u64>

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

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

fn stream_position(&mut self) -> Result<u64>

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

impl Seek for File

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

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

fn rewind(&mut self) -> Result<()>

返回到流的开头。

fn stream_len(&mut self) -> Result<u64>

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

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

fn stream_position(&mut self) -> Result<u64>

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

impl Write for &File

fn write(&mut self, buf: &[u8]) -> Result<usize>

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

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

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

fn is_write_vectored(&self) -> bool

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

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

fn flush(&mut self) -> Result<()>

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

fn write_all(&mut self, buf: &[u8]) -> Result<()>

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

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

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

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

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

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

fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,

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

impl Write for File

fn write(&mut self, buf: &[u8]) -> Result<usize>

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

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

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

fn is_write_vectored(&self) -> bool

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

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

fn flush(&mut self) -> Result<()>

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

fn write_all(&mut self, buf: &[u8]) -> Result<()>

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

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

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

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

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

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

fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,

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