跳转到内容
标准库Zig 0.17.0官方原文
源码std/Io/File.zig

第 1 行

字段

handle: Handle
flags: Flags

std.Io.File.assert

别名

第 9 行

别名目标 std.debug.assert

std.Io.File.Atomic

别名

第 30 行

别名目标 std.Io.File.Atomic

std.Io.File.BlockSize

类型

第 41 行

std.Io.File.builtin

常量

第 3 行

std.Io.File.close

函数

第 212 行

pub fn close(file: File, io: Io) void

参数

file: File
io: Io

std.Io.File.closeMany

函数

第 216 行

pub fn closeMany(io: Io, files: []const File) void

参数

io: Io
files: []const File

std.Io.File.createMemoryMap

函数

第 745 行

pub fn createMemoryMap(file: File, io: Io, options: MemoryMap.CreateOptions) MemoryMap.CreateError!MemoryMap

参数

file: File
io: Io
options: MemoryMap.CreateOptions

错误

AccessDenied

以下任一情况:

  • File.Kind 不是 file。
  • 文件未以读取方式打开,且启用了读取访问保护。
  • 文件未以写入方式打开,且启用了写入访问保护。
Canceled Cancelable

调用方请求停止异步操作。

InputOutput ReadPositionalError
IsDir ReadPositionalError

尝试将目录文件描述符当作普通文件读取。

LockViolation ReadPositionalError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

LockedMemoryLimitExceeded
NotOpenForReading ReadPositionalError

打开文件时未授予读取能力。

OutOfMemory Error
PermissionDenied

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemResources ReadPositionalError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable ReadPositionalError

此文件不支持按位置读取。

WouldBlock ReadPositionalError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.Dir

别名

第 10 行

别名目标 std.Io.Dir

std.Io.File.downgradeLock

函数

第 660 行

假定文件已处于独占锁定模式。 以原子方式将锁改为共享模式,而不释放锁。

pub fn downgradeLock(file: File, io: Io) LockError!void

参数

file: File
io: Io

错误

Canceled Cancelable

调用方请求停止异步操作。

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.DowngradeLockError

错误集合

第 656 行

错误

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.enableAnsiEscapeCodes

函数

第 249 行

pub fn enableAnsiEscapeCodes(file: File, io: Io) EnableAnsiEscapeCodesError!void

参数

file: File
io: Io

错误

Canceled Cancelable

调用方请求停止异步操作。

NotTerminalDevice
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.EnableAnsiEscapeCodesError

错误集合

第 245 行

错误

Canceled Cancelable

调用方请求停止异步操作。

NotTerminalDevice
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.File

别名

第 1 行

别名目标 std.Io.File

std.Io.File.Flags

容器

第 15 行

字段

nonblocking: bool
  • true:
    • windows:以 MODE.IO.ASYNCHRONOUS 打开
    • POSIX:已设置 O_NONBLOCK
  • false:
    • windows:以 SYNCHRONOUS_ALERT 或 SYNCHRONOUS_NONALERT 打开, 或不是文件。
    • POSIX:未设置 O_NONBLOCK

std.Io.File.Gid

别名

第 40 行

别名目标 std.posix.gid_t

std.Io.File.Handle

别名

第 26 行

别名目标 std.posix.fd_t

std.Io.File.hardLink

函数

第 735 行

pub fn hardLink( file: File, io: Io, new_dir: Dir, new_sub_path: []const u8, options: HardLinkOptions, ) HardLinkError!void

参数

file: File
io: Io
new_dir: Dir
new_sub_path: []const u8
options: HardLinkOptions

错误

AccessDenied
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

CrossDevice
DiskQuota
FileNotFound
HardwareFailure
LinkQuotaExceeded
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NoSpaceLeft
NotDir
OperationUnsupported

操作系统或文件系统不支持硬链接。

PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.HardLinkError

错误集合

第 717 行

错误

AccessDenied
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

CrossDevice
DiskQuota
FileNotFound
HardwareFailure
LinkQuotaExceeded
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NoSpaceLeft
NotDir
OperationUnsupported

操作系统或文件系统不支持硬链接。

PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.HardLinkOptions

容器

第 713 行

字段

follow_symlinks: bool = false

std.Io.File.INode

别名

第 37 行

别名目标 std.posix.ino_t

std.Io.File.Io

别名

第 8 行

别名目标 std.Io

std.Io.File.is_windows

常量

第 5 行

std.Io.File.isTty

函数

第 241 行

测试文件是否指向终端(类似于 libc 的 "isatty")。

另见:

pub fn isTty(file: File, io: Io) Io.Cancelable!bool

参数

file: File
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.File.Kind

容器

第 43 行

字段

block_device
character_device
directory
named_pipe
sym_link
file
unix_domain_socket
whiteout
door
event_port
unknown

std.Io.File.length

函数

第 286 行

获取文件末尾的字节索引。

若只需长度,有时比 stat 开销更低。

pub fn length(file: File, io: Io) LengthError!u64

参数

file: File
io: Io

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.LengthError

别名

第 281 行

别名目标 std.Io.File.StatError

std.Io.File.lock

函数

第 637 行

其他进程持有不兼容的锁时阻塞。一个进程对某文件 只能持有一种锁,共享锁或独占锁。进程 以任何方式终止时,锁都会释放。

假定文件未锁定。

pub fn lock(file: File, io: Io, l: Lock) LockError!void

参数

file: File
io: Io
l: Lock

错误

Canceled Cancelable

调用方请求停止异步操作。

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.Lock

容器

第 145 行

字段

none
shared
exclusive

std.Io.File.LockError

错误集合

第 627 行

错误

Canceled Cancelable

调用方请求停止异步操作。

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.MemoryMap

别名

第 32 行

预期与文件内容保持一致的内存。

别名目标 std.Io.File.MemoryMap

std.Io.File.MultiReader

别名

第 35 行

并发读取多个文件流,消除 死锁风险。

别名目标 std.Io.File.MultiReader

std.Io.File.native_os

常量

第 4 行

std.Io.File.NLink

别名

第 38 行

别名目标 std.posix.nlink_t

std.Io.File.OpenError

错误集合

第 151 行

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
FileBusy

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported
FileNotFound

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

PathAlreadyExists

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

已请求非阻塞模式,但该操作无法立即返回。

std.Io.File.Permissions

常量

第 332 行

文件权限的跨平台表示。

POSIX 系统中对应“mode”,Windows 中对应“attributes”。

std.Io.File.Permissions.default_dir

常量

第 336 行

@This()

std.Io.File.Permissions.default_dir

常量

第 399 行

@This()

std.Io.File.Permissions.executable_file

常量

第 337 行

@This()

std.Io.File.Permissions.executable_file

常量

第 375 行

@This()

std.Io.File.Permissions.executable_file

常量

第 400 行

@This()

std.Io.File.Permissions.fromMode

函数

第 381 行

pub fn fromMode(mode: std.posix.mode_t) @This()

参数

mode: std.posix.mode_t

std.Io.File.Permissions.has_executable_bit

原始类型

第 338 行

std.Io.File.Permissions.has_executable_bit

常量

第 373 行

std.Io.File.Permissions.has_executable_bit

原始类型

第 401 行

std.Io.File.Permissions.readOnly

函数

第 346 行

pub fn readOnly(self: @This()) bool

参数

self: @This()

std.Io.File.Permissions.readOnly

函数

第 386 行

当且仅当所有权限类别均无写权限时返回 true。

pub fn readOnly(self: @This()) bool

参数

self: @This()

std.Io.File.Permissions.setReadOnly

函数

第 351 行

pub fn setReadOnly(self: @This(), read_only: bool) @This()

参数

self: @This()
read_only: bool

std.Io.File.Permissions.setReadOnly

函数

第 392 行

为所有用户类别启用写权限。

pub fn setReadOnly(self: @This(), read_only: bool) @This()

参数

self: @This()
read_only: bool

std.Io.File.Permissions.toAttributes

函数

第 342 行

pub fn toAttributes(self: @This()) windows.FILE.ATTRIBUTE

参数

self: @This()

std.Io.File.Permissions.toMode

函数

第 377 行

pub fn toMode(self: @This()) std.posix.mode_t

参数

self: @This()

std.Io.File.Permissions.windows

别名

第 340 行

别名目标 std.os.windows

std.Io.File.reader

函数

第 563 行

默认使用定位读取,失败时回退到流式读取。

定位读取不影响全局查找位置,因此线程安全性 更高。

另见:

pub fn reader(file: File, io: Io, buffer: []u8) Reader

参数

file: File
io: Io
buffer: []u8

std.Io.File.Reader

别名

第 28 行

别名目标 std.Io.File.Reader

std.Io.File.readerStreaming

函数

第 589 行

定位读取不会影响全局查找位置,因此更便于线程安全使用。 但若相应系统调用不可用,则预先初始化为 流式模式可以省去一次失败的系统调用。

另见:

pub fn readerStreaming(file: File, io: Io, buffer: []u8) Reader

参数

file: File
io: Io
buffer: []u8

std.Io.File.readPositional

函数

第 503 行

流结束或 buffer 没有可用空间时返回 0。

另请参见:

pub fn readPositional(file: File, io: Io, buffer: []const []u8, offset: u64) ReadPositionalError!usize

参数

file: File
io: Io
buffer: []const []u8
offset: u64

错误

AccessDenied

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

InputOutput
IsDir

尝试将目录文件描述符当作普通文件读取。

LockViolation

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading

打开文件时未授予读取能力。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

此文件不支持按位置读取。

WouldBlock

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.readPositionalAll

函数

第 573 行

等价于创建定位读取器并多次读取,以填满 buffer。

返回读入 buffer 的字节数。若小于 buffer.len,表示到达文件末尾。

另见:

pub fn readPositionalAll(file: File, io: Io, buffer: []u8, offset: u64) ReadPositionalError!usize

参数

file: File
io: Io
buffer: []u8
offset: u64

错误

AccessDenied

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

InputOutput
IsDir

尝试将目录文件描述符当作普通文件读取。

LockViolation

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading

打开文件时未授予读取能力。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

此文件不支持按位置读取。

WouldBlock

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.ReadPositionalError

错误集合

第 478 行

错误

AccessDenied

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

InputOutput
IsDir

尝试将目录文件描述符当作普通文件读取。

LockViolation

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading

打开文件时未授予读取能力。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

此文件不支持按位置读取。

WouldBlock

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.readStreaming

函数

第 471 行

返回字节数可能少于缓冲区可用空间,包括 0。 流结束以 error.EndOfStream 表示。

另请参见:

pub fn readStreaming(file: File, io: Io, buffer: []const []u8) ReadStreamingError!usize

参数

file: File
io: Io
buffer: []const []u8

错误

AccessDenied UnendingError

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.ReadStreamingError

错误集合

第 464 行

错误

AccessDenied UnendingError

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.realPath

函数

第 709 行

获取与打开的文件句柄对应的规范化绝对路径名。

此函数的平台支持有限,使用它可能导致 不必要的失败和竞态条件。通常建议 完全避免使用此函数。

pub fn realPath(file: File, io: Io, out_buffer: []u8) RealPathError!usize

参数

file: File
io: Io
out_buffer: []u8

错误

AccessDenied
AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
FileBusy
FileNotFound
FileSystem
FileTooBig
InputOutput
IsDir
NameTooLong

完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft
NotDir
OperationUnsupported

此操作系统、文件系统或 Io 实现 不支持 realpath 操作。

PathAlreadyExists
PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

std.Io.File.RealPathError

错误集合

第 664 行

错误

AccessDenied
AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
FileBusy
FileNotFound
FileSystem
FileTooBig
InputOutput
IsDir
NameTooLong

完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft
NotDir
OperationUnsupported

此操作系统、文件系统或 Io 实现 不支持 realpath 操作。

PathAlreadyExists
PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

std.Io.File.SeekError

错误集合

第 548 行

错误

AccessDenied

文件描述符不具备执行定位所需的权限。

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

std.Io.File.setLength

函数

第 277 行

截短或扩展文件,新增数据填零。

调用后文件偏移量保持不变。

此函数操作已打开的文件句柄。Dir 中没有 按路径操作的等效函数,因为这种 功能通常会引入检查时间与使用时间之间的竞态,即 TOCTOU。 在确实需要此语义的少数情况下,可以 使用截短标志打开文件。

pub fn setLength(file: File, io: Io, new_length: u64) SetLengthError!void

参数

file: File
io: Io
new_length: u64

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileBusy
FileTooBig
InputOutput
NonResizable
PermissionDenied
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.SetLengthError

错误集合

第 259 行

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileBusy
FileTooBig
InputOutput
NonResizable
PermissionDenied
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.setOwner

函数

第 325 行

也称为“chown”。

进程必须具备相应权限才能成功执行此操作。 文件所有者可将所属组改为自己所属的任意组。 若所有者或所属组指定为 null,则不更改对应标识。

pub fn setOwner(file: File, io: Io, owner: ?Uid, group: ?Gid) SetOwnerError!void

参数

file: File
io: Io
owner: ?Uid
group: ?Gid

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.SetOwnerError

错误集合

第 309 行

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.setPermissions

函数

第 305 行

又称“chmod”。

进程必须具有适当权限,或者有效用户 ID 必须与文件所有者匹配, 才能成功执行。

pub fn setPermissions(file: File, io: Io, new_permissions: Permissions) SetPermissionsError!void

参数

file: File
io: Io
new_permissions: Permissions

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.SetPermissionsError

错误集合

第 290 行

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.SetTimestamp

容器

第 431 行

字段

unchanged

保持现有时间戳不变。

now

使用 Io.Clock.real 设置为当前时间。

new: Io.Timestamp

使用 Io.Clock.real 设置为提供的时间戳。

std.Io.File.SetTimestamp.init

函数

第 440 行

便于与 Stat 交互,其中 null 表示 unchanged。

pub fn init(optional: ?Io.Timestamp) SetTimestamp

参数

optional: ?Io.Timestamp

std.Io.File.setTimestamps

函数

第 448 行

最终存储的时间粒度取决于操作系统 与文件系统的组合。若提供的值超出此范围, 则将其限制为最大值。

pub fn setTimestamps(file: File, io: Io, options: SetTimestampsOptions) SetTimestampsError!void

参数

file: File
io: Io
options: SetTimestampsOptions

错误

AccessDenied

times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:

  • 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
  • 文件被标记为不可变,参见 chattr(1)。
Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied

调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:

  • 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
  • 文件被标记为仅追加或不可变,参见 chattr(1)。
ReadOnlyFileSystem
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.SetTimestampsError

错误集合

第 404 行

错误

AccessDenied

times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:

  • 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
  • 文件被标记为不可变,参见 chattr(1)。
Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied

调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:

  • 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
  • 文件被标记为仅追加或不可变,参见 chattr(1)。
ReadOnlyFileSystem
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.setTimestampsNow

函数

第 457 行

将 file 的访问时间戳和修改时间戳设置为当前 挂钟时间。

最终存储的时间粒度由操作系统与 文件系统的组合决定。

pub fn setTimestampsNow(file: File, io: Io) SetTimestampsError!void

参数

file: File
io: Io

错误

AccessDenied

times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:

  • 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
  • 文件被标记为不可变,参见 chattr(1)。
Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied

调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:

  • 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
  • 文件被标记为仅追加或不可变,参见 chattr(1)。
ReadOnlyFileSystem
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.SetTimestampsOptions

容器

第 426 行

字段

access_timestamp: SetTimestamp = .unchanged
modify_timestamp: SetTimestamp = .unchanged

std.Io.File.stat

函数

第 141 行

返回包含 File 基本信息的 Stat。

pub fn stat(file: File, io: Io) StatError!Stat

参数

file: File
io: Io

错误

AccessDenied

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied
Streaming

尝试对非文件流调用 stat。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.Stat

容器

第 57 行

字段

inode: INode

系统用于指向文件元数据的数字。 不保证此数字在时间维度上唯一,因为某些文件 系统会在文件删除后复用其 inode。某些 系统也可能随时间改变文件的 inode。

在 Linux 上,inode 是保存元数据的结构体, 此处看到的是 inode 的编号,即 inode 的索引号。

Windows 上的 FileIndex 类似。它是文件的编号, 在每个文件系统内唯一。

nlink: NLink
size: u64
permissions: Permissions
kind: Kind
atime: ?Io.Timestamp

相对于 UTC 1970-01-01 的最后访问时间,单位为纳秒。

文件系统通常难以持续更新此值,因为 这会把只读的文件系统访问变成文件系统修改。 某些系统报告过时的值,某些系统则明确拒绝 报告此值。后一种情况使用 null 表示。

mtime: Io.Timestamp

最后修改时间,相对于 UTC 1970-01-01,以纳秒表示。

ctime: Io.Timestamp

相对于 UTC 1970-01-01 的最后状态/元数据修改时间,单位为纳秒。

block_size: BlockSize

适合最优 I/O 的最小块长度,以字节计。 对不支持此概念的操作系统或文件系统, 该值设为 1。不一定是二的幂。

std.Io.File.StatError

错误集合

第 130 行

错误

AccessDenied

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied
Streaming

尝试对非文件流调用 stat。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.std

别名

第 7 行

别名目标 std

std.Io.File.stderr

函数

第 104 行

pub fn stderr() File

std.Io.File.stdin

函数

第 117 行

pub fn stdin() File

std.Io.File.stdout

函数

第 91 行

pub fn stdout() File

std.Io.File.supportsAnsiEscapeCodes

函数

第 255 行

测试 ANSI 转义码是否会被当作转义码处理, 但不尝试启用 ANSI 转义码支持。

pub fn supportsAnsiEscapeCodes(file: File, io: Io) Io.Cancelable!bool

参数

file: File
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.File.sync

函数

第 232 行

阻塞,直到此文件所有待处理的内容和元数据修改 均与底层文件系统同步。

不保证包含该文件的目录的元数据 也已经写入磁盘。

pub fn sync(file: File, io: Io) SyncError!void

参数

file: File
io: Io

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

DiskQuota
InputOutput
NoSpaceLeft
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.SyncError

错误集合

第 220 行

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

DiskQuota
InputOutput
NoSpaceLeft
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.tryLock

函数

第 652 行

尝试获取锁。获得锁时返回 true,若已有其他不兼容的锁被持有,则返回 false。 进程只能对同一文件持有一种锁,共享锁或排他锁。进程以任意方式结束时,锁都会释放。

假定文件当前未锁定。

pub fn tryLock(file: File, io: Io, l: Lock) LockError!bool

参数

file: File
io: Io
l: Lock

错误

Canceled Cancelable

调用方请求停止异步操作。

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.Uid

别名

第 39 行

别名目标 std.posix.uid_t

std.Io.File.unlock

函数

第 642 行

假定文件已加锁。

pub fn unlock(file: File, io: Io) void

参数

file: File
io: Io

std.Io.File.WriteFilePositionalError

错误集合

第 554 行

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

CorruptedData WriteFileError

在 FreeBSD 上使用 copy_file_range 时可能发生。

DeviceBusy Error
DiskQuota Error
EndOfStream WriteFileError
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
ReadFailed WriteFileError
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unimplemented WriteFileError

描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。

Unseekable
WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.writePositional

函数

第 537 行

另请参见:

pub fn writePositional(file: File, io: Io, buffer: []const []const u8, offset: u64) WritePositionalError!usize

参数

file: File
io: Io
buffer: []const []const u8
offset: u64

错误

AccessDenied

文件描述符没有写入所需的权限。

BrokenPipe

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft
NotOpenForWriting

文件打开时没有写入能力。

PermissionDenied
SystemResources

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

无法对该文件按指定位置写入。

WouldBlock

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.writePositionalAll

函数

第 542 行

等同于创建位置写入器、写入 bytes,然后刷新。

pub fn writePositionalAll(file: File, io: Io, bytes: []const u8, offset: u64) WritePositionalError!void

参数

file: File
io: Io
bytes: []const u8
offset: u64

错误

AccessDenied

文件描述符没有写入所需的权限。

BrokenPipe

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft
NotOpenForWriting

文件打开时没有写入能力。

PermissionDenied
SystemResources

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

无法对该文件按指定位置写入。

WouldBlock

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.WritePositionalError

错误集合

第 507 行

错误

AccessDenied

文件描述符没有写入所需的权限。

BrokenPipe

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft
NotOpenForWriting

文件打开时没有写入能力。

PermissionDenied
SystemResources

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

无法对该文件按指定位置写入。

WouldBlock

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.writer

函数

第 597 行

默认采用定位读取;不可用时退回流式读取。

定位读取不影响全局查找位置, 因此更便于线程安全使用。

pub fn writer(file: File, io: Io, buffer: []u8) Writer

参数

file: File
io: Io
buffer: []u8

std.Io.File.Writer

别名

第 29 行

别名目标 std.Io.File.Writer

std.Io.File.writerStreaming

函数

第 604 行

定位读取不影响全局查找位置,因此更便于线程安全使用。 但若相应系统调用不可用,则预先初始化为 流式模式可省去一次失败的系统调用。

pub fn writerStreaming(file: File, io: Io, buffer: []u8) Writer

参数

file: File
io: Io
buffer: []u8

std.Io.File.writeStreaming

函数

第 610 行

这是直接调用 Io 接口函数的底层 API。 更高层 API 参见 writerStreaming。

pub fn writeStreaming(file: File, io: Io, header: []const u8, data: []const []const u8, splat: usize) Writer.Error!usize

参数

file: File
io: Io
header: []const u8
data: []const []const u8
splat: usize

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy Error
DiskQuota Error
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

std.Io.File.writeStreamingAll

函数

第 620 行

等同于创建流式写入器、写入 bytes,然后刷新。

pub fn writeStreamingAll(file: File, io: Io, bytes: []const u8) Writer.Error!void

参数

file: File
io: Io
bytes: []const u8

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy Error
DiskQuota Error
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

源码

std/Io/File.zig

const File = @This();

const builtin = @import("builtin");
const native_os = builtin.os.tag;
const is_windows = native_os == .windows;

const std = @import("../std.zig");
const Io = std.Io;
const assert = std.debug.assert;
const Dir = std.Io.Dir;

handle: Handle,
flags: Flags,

pub const Flags = struct {
    /// * true:
    ///   - windows:以 MODE.IO.ASYNCHRONOUS 打开
    ///   - POSIX:已设置 O_NONBLOCK
    /// * false:
    ///   - windows:以 SYNCHRONOUS_ALERT 或 SYNCHRONOUS_NONALERT 打开,
    ///     或不是文件。
    ///   - POSIX:未设置 O_NONBLOCK
    nonblocking: bool,
};

pub const Handle = std.posix.fd_t;

pub const Reader = @import("File/Reader.zig");
pub const Writer = @import("File/Writer.zig");
pub const Atomic = @import("File/Atomic.zig");
/// 预期与文件内容保持一致的内存。
pub const MemoryMap = @import("File/MemoryMap.zig");
/// 并发读取多个文件流,消除
/// 死锁风险。
pub const MultiReader = @import("File/MultiReader.zig");

pub const INode = std.posix.ino_t;
pub const NLink = std.posix.nlink_t;
pub const Uid = std.posix.uid_t;
pub const Gid = std.posix.gid_t;
pub const BlockSize = u32;

pub const Kind = enum {
    block_device,
    character_device,
    directory,
    named_pipe,
    sym_link,
    file,
    unix_domain_socket,
    whiteout,
    door,
    event_port,
    unknown,
};

pub const Stat = struct {
    /// 系统用于指向文件元数据的数字。
    /// 不保证此数字在时间维度上唯一,因为某些文件
    /// 系统会在文件删除后复用其 inode。某些
    /// 系统也可能随时间改变文件的 inode。
    ///
    /// 在 Linux 上,inode 是保存元数据的结构体,
    /// 此处看到的是 inode 的编号,即
    /// inode 的索引号。
    ///
    /// Windows 上的 FileIndex 类似。它是文件的编号,
    /// 在每个文件系统内唯一。
    inode: INode,
    nlink: NLink,
    size: u64,
    permissions: Permissions,
    kind: Kind,
    /// 相对于 UTC 1970-01-01 的最后访问时间,单位为纳秒。
    ///
    /// 文件系统通常难以持续更新此值,因为
    /// 这会把只读的文件系统访问变成文件系统修改。
    /// 某些系统报告过时的值,某些系统则明确拒绝
    /// 报告此值。后一种情况使用 `null` 表示。
    atime: ?Io.Timestamp,
    /// 最后修改时间,相对于 UTC 1970-01-01,以纳秒表示。
    mtime: Io.Timestamp,
    /// 相对于 UTC 1970-01-01 的最后状态/元数据修改时间,单位为纳秒。
    ctime: Io.Timestamp,
    /// 适合最优 I/O 的最小块长度,以字节计。
    /// 对不支持此概念的操作系统或文件系统,
    /// 该值设为 `1`。不一定是二的幂。
    block_size: BlockSize,
};

pub fn stdout() File {
    return switch (native_os) {
        .windows => .{
            .handle = std.os.windows.peb().ProcessParameters.hStdOutput,
            .flags = .{ .nonblocking = false },
        },
        else => .{
            .handle = std.posix.STDOUT_FILENO,
            .flags = .{ .nonblocking = false },
        },
    };
}

pub fn stderr() File {
    return switch (native_os) {
        .windows => .{
            .handle = std.os.windows.peb().ProcessParameters.hStdError,
            .flags = .{ .nonblocking = false },
        },
        else => .{
            .handle = std.posix.STDERR_FILENO,
            .flags = .{ .nonblocking = false },
        },
    };
}

pub fn stdin() File {
    return switch (native_os) {
        .windows => .{
            .handle = std.os.windows.peb().ProcessParameters.hStdInput,
            .flags = .{ .nonblocking = false },
        },
        else => .{
            .handle = std.posix.STDIN_FILENO,
            .flags = .{ .nonblocking = false },
        },
    };
}

pub const StatError = error{
    SystemResources,
    /// 在 WASI 中,当文件描述符不具备获取自身 filestat
    /// 信息所需的权限时,可能发生此错误。
    AccessDenied,
    PermissionDenied,
    /// 尝试对非文件流调用 stat。
    Streaming,
} || Io.Cancelable || Io.UnexpectedError;

/// 返回包含 `File` 基本信息的 `Stat`。
pub fn stat(file: File, io: Io) StatError!Stat {
    return io.vtable.fileStat(io.userdata, file);
}

pub const Lock = enum {
    none,
    shared,
    exclusive,
};

pub const OpenError = error{
    PipeBusy,
    NoDevice,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
    /// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
    /// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
    ///
    ///
    ///
    AntivirusInterference,
    /// 在 WASI 中,若文件描述符不具有相对于它
    /// 打开新资源所需的权限,可能发生此错误。
    AccessDenied,
    PermissionDenied,
    SymLinkLoop,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    /// 以下任一情况:
    /// * 某个路径分量不存在。
    /// * 使用了当前工作目录,但该目录已被删除。
    /// * 已打开目录句柄所关联的路径已被删除。
    /// * macOS 上,多个进程或线程将 `O.EXCL` 设为 `false`,并发争相创建同一文件。
    ///
    FileNotFound,
    /// 路径超过 `max_path_bytes` 字节。
    /// 可用内核内存不足;或者
    /// 指定文件为 FIFO,且达到每用户
    /// 管道内存分配的硬限制。
    SystemResources,
    /// 文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
    ///
    FileTooBig,
    /// 以下任一情况:
    /// * 路径指向目录,但请求了写权限。
    /// * 路径指向目录,但 `allow_directory` 被设为 false。
    IsDir,
    /// 设备没有空间容纳新文件,无法创建新路径。
    /// 仅在提供 `CREAT` 标志时才可能出现此错误。
    NoSpaceLeft,
    /// 路径中用作目录的某个部分实际上不是目录,
    /// 或者指定了 `DIRECTORY`,但路径不是目录。
    NotDir,
    /// 路径已存在,且提供了 `CREAT` 和 `EXCL` 标志。
    PathAlreadyExists,
    ReadOnlyFileSystem,
    DeviceBusy,
    FileLocksUnsupported,
    /// 以下三种情况之一:
    /// * pathname 指向正在执行的可执行映像,
    ///   且请求写访问。
    /// * pathname 指向当前用作交换
    ///   文件的文件,且指定了 O_TRUNC 标志。
    /// * pathname 指向内核正在读取的文件,
    ///   例如用于加载模块或固件,且请求
    ///   写访问。
    FileBusy,
    /// 已请求非阻塞模式,但该操作无法立即返回。
    WouldBlock,
} || Dir.PathNameError || Io.Cancelable || Io.UnexpectedError;

pub fn close(file: File, io: Io) void {
    return io.vtable.fileClose(io.userdata, (&file)[0..1]);
}

pub fn closeMany(io: Io, files: []const File) void {
    return io.vtable.fileClose(io.userdata, files);
}

pub const SyncError = error{
    InputOutput,
    NoSpaceLeft,
    DiskQuota,
    AccessDenied,
} || Io.Cancelable || Io.UnexpectedError;

/// 阻塞,直到此文件所有待处理的内容和元数据修改
/// 均与底层文件系统同步。
///
/// 不保证包含该文件的目录的元数据
/// 也已经写入磁盘。
pub fn sync(file: File, io: Io) SyncError!void {
    return io.vtable.fileSync(io.userdata, file);
}

/// 测试文件是否指向终端(类似于 libc 的 "isatty")。
///
/// 另见:
/// * `enableAnsiEscapeCodes`
/// * `supportsAnsiEscapeCodes`。
pub fn isTty(file: File, io: Io) Io.Cancelable!bool {
    return io.vtable.fileIsTty(io.userdata, file);
}

pub const EnableAnsiEscapeCodesError = error{
    NotTerminalDevice,
} || Io.Cancelable || Io.UnexpectedError;

pub fn enableAnsiEscapeCodes(file: File, io: Io) EnableAnsiEscapeCodesError!void {
    return io.vtable.fileEnableAnsiEscapeCodes(io.userdata, file);
}

/// 测试 ANSI 转义码是否会被当作转义码处理,
/// 但不尝试启用 ANSI 转义码支持。
pub fn supportsAnsiEscapeCodes(file: File, io: Io) Io.Cancelable!bool {
    return io.vtable.fileSupportsAnsiEscapeCodes(io.userdata, file);
}

pub const SetLengthError = error{
    FileTooBig,
    InputOutput,
    FileBusy,
    AccessDenied,
    PermissionDenied,
    NonResizable,
} || Io.Cancelable || Io.UnexpectedError;

/// 截短或扩展文件,新增数据填零。
///
/// 调用后文件偏移量保持不变。
///
/// 此函数操作已打开的文件句柄。`Dir` 中没有
/// 按路径操作的等效函数,因为这种
/// 功能通常会引入检查时间与使用时间之间的竞态,即 TOCTOU。
/// 在确实需要此语义的少数情况下,可以
/// 使用截短标志打开文件。
pub fn setLength(file: File, io: Io, new_length: u64) SetLengthError!void {
    return io.vtable.fileSetLength(io.userdata, file, new_length);
}

pub const LengthError = StatError;

/// 获取文件末尾的字节索引。
///
/// 若只需长度,有时比 `stat` 开销更低。
pub fn length(file: File, io: Io) LengthError!u64 {
    return io.vtable.fileLength(io.userdata, file);
}

pub const SetPermissionsError = error{
    AccessDenied,
    PermissionDenied,
    InputOutput,
    SymLinkLoop,
    FileNotFound,
    SystemResources,
    ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;

/// 又称“chmod”。
///
/// 进程必须具有适当权限,或者有效用户 ID
/// 必须与文件所有者匹配,
/// 才能成功执行。
pub fn setPermissions(file: File, io: Io, new_permissions: Permissions) SetPermissionsError!void {
    return io.vtable.fileSetPermissions(io.userdata, file, new_permissions);
}

pub const SetOwnerError = error{
    AccessDenied,
    PermissionDenied,
    InputOutput,
    SymLinkLoop,
    FileNotFound,
    SystemResources,
    ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;

/// 也称为“chown”。
///
/// 进程必须具备相应权限才能成功执行此操作。
/// 文件所有者可将所属组改为自己所属的任意组。
/// 若所有者或所属组指定为
/// `null`,则不更改对应标识。
pub fn setOwner(file: File, io: Io, owner: ?Uid, group: ?Gid) SetOwnerError!void {
    return io.vtable.fileSetOwner(io.userdata, file, owner, group);
}

/// 文件权限的跨平台表示。
///
/// POSIX 系统中对应“mode”,Windows 中对应“attributes”。
pub const Permissions = std.Options.FilePermissions orelse if (is_windows) enum(std.os.windows.DWORD) {
    default_file = 0,
    _,

    pub const default_dir: @This() = .default_file;
    pub const executable_file: @This() = .default_file;
    pub const has_executable_bit = false;

    const windows = std.os.windows;

    pub fn toAttributes(self: @This()) windows.FILE.ATTRIBUTE {
        return @bitCast(@backingInt(self));
    }

    pub fn readOnly(self: @This()) bool {
        const attributes = toAttributes(self);
        return attributes & windows.FILE_ATTRIBUTE_READONLY != 0;
    }

    pub fn setReadOnly(self: @This(), read_only: bool) @This() {
        const attributes = toAttributes(self);
        return @fromBackingInt(@intCast(if (read_only)
            attributes | windows.FILE_ATTRIBUTE_READONLY
        else
            attributes & ~@as(windows.DWORD, windows.FILE_ATTRIBUTE_READONLY)));
    }
} else if (std.posix.mode_t != u0) enum(std.posix.mode_t) {
    /// 这是在 POSIX 操作系统上创建
    /// 文件时使用的默认模式。`0o666` 表示 "-rw-rw-rw-",乍看违反直觉,
    /// 因为多数人会期望 "-rw-r--r--",例如使用
    /// `touch` 命令时,该权限对应 `0o644`。但 POSIX
    /// libc 实现将 `0o666` 用于 `fopen`,再依赖
    /// 进程级的 "umask" 设置调整创建文件时的权限值。
    default_file = 0o666,
    /// 这是在 POSIX 操作系统上创建目录时传递的
    /// 默认权限模式。`0o777` 为“-rwxrwxrwx”,初看可能不合直觉,
    /// 因为多数人期望的是“-rwxr-xr-x”,例如使用
    /// `touch` 命令时,对应 `0o755`。
    default_dir = 0o777,
    _,

    pub const has_executable_bit = native_os != .wasi;

    pub const executable_file: @This() = .default_dir;

    pub fn toMode(self: @This()) std.posix.mode_t {
        return @backingInt(self);
    }

    pub fn fromMode(mode: std.posix.mode_t) @This() {
        return @fromBackingInt(@intCast(mode));
    }

    /// 当且仅当所有权限类别均无写权限时返回 `true`。
    pub fn readOnly(self: @This()) bool {
        const mode = toMode(self);
        return mode & 0o222 == 0;
    }

    /// 为所有用户类别启用写权限。
    pub fn setReadOnly(self: @This(), read_only: bool) @This() {
        const mode = toMode(self);
        const o222 = @as(std.posix.mode_t, 0o222);
        return @fromBackingInt(@intCast(if (read_only) mode & ~o222 else mode | o222));
    }
} else enum(u0) {
    default_file = 0,
    pub const default_dir: @This() = .default_file;
    pub const executable_file: @This() = .default_file;
    pub const has_executable_bit = false;
};

pub const SetTimestampsError = error{
    /// times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
    /// *  调用方的有效用户标识符与文件
    ///    所有者不匹配,调用方不具有该文件的
    ///    写入权限,且调用方不具有特权;Linux 上即不具备
    ///    CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力;
    ///    或者,
    /// *  文件被标记为不可变,参见 chattr(1)。
    AccessDenied,
    /// 调用方尝试将一个或两个时间戳设置为当前时间
    /// 以外的值,或将一个时间戳
    /// 设为当前时间而保持另一个不变,
    /// 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW,
    /// 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
    /// * 调用方的有效用户 ID 不等于文件
    ///    所有者,且调用方无特权;Linux 上
    ///    指不具备 CAP_FOWNER 能力。
    /// * 文件被标记为仅追加或不可变,参见 chattr(1)。
    PermissionDenied,
    ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;

pub const SetTimestampsOptions = struct {
    access_timestamp: SetTimestamp = .unchanged,
    modify_timestamp: SetTimestamp = .unchanged,
};

pub const SetTimestamp = union(enum) {
    /// 保持现有时间戳不变。
    unchanged,
    /// 使用 `Io.Clock.real` 设置为当前时间。
    now,
    /// 使用 `Io.Clock.real` 设置为提供的时间戳。
    new: Io.Timestamp,

    /// 便于与 `Stat` 交互,其中 `null` 表示 `unchanged`。
    pub fn init(optional: ?Io.Timestamp) SetTimestamp {
        return if (optional) |t| .{ .new = t } else .unchanged;
    }
};

/// 最终存储的时间粒度取决于操作系统
/// 与文件系统的组合。若提供的值超出此范围,
/// 则将其限制为最大值。
pub fn setTimestamps(file: File, io: Io, options: SetTimestampsOptions) SetTimestampsError!void {
    return io.vtable.fileSetTimestamps(io.userdata, file, options);
}

/// 将 `file` 的访问时间戳和修改时间戳设置为当前
/// 挂钟时间。
///
/// 最终存储的时间粒度由操作系统与
/// 文件系统的组合决定。
pub fn setTimestampsNow(file: File, io: Io) SetTimestampsError!void {
    return io.vtable.fileSetTimestamps(io.userdata, file, .{
        .access_timestamp = .now,
        .modify_timestamp = .now,
    });
}

pub const ReadStreamingError = error{EndOfStream} || Reader.Error;

/// 返回字节数可能少于缓冲区可用空间,包括 0。
/// 流结束以 `error.EndOfStream` 表示。
///
/// 另请参见:
/// * `reader`
pub fn readStreaming(file: File, io: Io, buffer: []const []u8) ReadStreamingError!usize {
    return (try io.operate(.{ .file_read_streaming = .{
        .file = file,
        .data = buffer,
    } })).file_read_streaming;
}

pub const ReadPositionalError = error{
    InputOutput,
    SystemResources,
    /// 尝试将目录文件描述符当作普通文件读取。
    IsDir,
    /// 已启用非阻塞模式,且从该文件描述符读取会阻塞。
    ///
    WouldBlock,
    /// 在 WASI 中,当文件描述符不具有读取
    /// 所需的权限时发生此错误。
    AccessDenied,
    /// 由于锁定而无法读取文件。根据 `Io` 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。
    ///
    ///
    LockViolation,
    /// 此文件不支持按位置读取。
    Unseekable,
    /// 打开文件时未授予读取能力。
    NotOpenForReading,
} || Io.Cancelable || Io.UnexpectedError;

/// 流结束或 `buffer` 没有可用空间时返回 0。
///
/// 另请参见:
/// * `reader`
pub fn readPositional(file: File, io: Io, buffer: []const []u8, offset: u64) ReadPositionalError!usize {
    return io.vtable.fileReadPositional(io.userdata, file, buffer, offset);
}

pub const WritePositionalError = error{
    DiskQuota,
    FileTooBig,
    InputOutput,
    NoSpaceLeft,
    DeviceBusy,
    /// 文件描述符没有写入所需的权限。
    AccessDenied,
    PermissionDenied,
    /// 文件为未连接的套接字,或其读取端已关闭。
    BrokenPipe,
    /// 内核内存不足,无法从 in_fd 读取。
    SystemResources,
    /// 进程无法访问文件,因为另一进程已锁定
    /// 文件的一部分。仅限 Windows。
    LockViolation,
    /// 已启用非阻塞模式,而此操作将阻塞。
    WouldBlock,
    /// 写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
    ///
    NoDevice,
    FileBusy,
    /// 无法对该文件按指定位置写入。
    Unseekable,
    /// 文件打开时没有写入能力。
    NotOpenForWriting,
} || Io.Cancelable || Io.UnexpectedError;

/// 另请参见:
/// * `writer`
pub fn writePositional(file: File, io: Io, buffer: []const []const u8, offset: u64) WritePositionalError!usize {
    return io.vtable.fileWritePositional(io.userdata, file, &.{}, buffer, 1, offset);
}

/// 等同于创建位置写入器、写入 `bytes`,然后刷新。
pub fn writePositionalAll(file: File, io: Io, bytes: []const u8, offset: u64) WritePositionalError!void {
    var index: usize = 0;
    while (index < bytes.len)
        index += try io.vtable.fileWritePositional(io.userdata, file, &.{}, &.{bytes[index..]}, 1, offset + index);
}

pub const SeekError = error{
    Unseekable,
    /// 文件描述符不具备执行定位所需的权限。
    AccessDenied,
} || Io.Cancelable || Io.UnexpectedError;

pub const WriteFilePositionalError = Writer.WriteFileError || error{Unseekable};

/// 默认使用定位读取,失败时回退到流式读取。
///
/// 定位读取不影响全局查找位置,因此线程安全性
/// 更高。
///
/// 另见:
/// * `readerStreaming`
pub fn reader(file: File, io: Io, buffer: []u8) Reader {
    return .init(file, io, buffer);
}

/// 等价于创建定位读取器并多次读取,以填满 `buffer`。
///
/// 返回读入 `buffer` 的字节数。若小于 `buffer.len`,表示到达文件末尾。
///
/// 另见:
/// * `reader`
pub fn readPositionalAll(file: File, io: Io, buffer: []u8, offset: u64) ReadPositionalError!usize {
    var index: usize = 0;
    while (index != buffer.len) {
        const amt = try file.readPositional(io, &.{buffer[index..]}, offset + index);
        if (amt == 0) break;
        index += amt;
    }
    return index;
}

/// 定位读取不会影响全局查找位置,因此更便于线程安全使用。
/// 但若相应系统调用不可用,则预先初始化为
/// 流式模式可以省去一次失败的系统调用。
///
/// 另见:
/// * `reader`
pub fn readerStreaming(file: File, io: Io, buffer: []u8) Reader {
    return .initStreaming(file, io, buffer);
}

/// 默认采用定位读取;不可用时退回流式读取。
///
/// 定位读取不影响全局查找位置,
/// 因此更便于线程安全使用。
pub fn writer(file: File, io: Io, buffer: []u8) Writer {
    return .init(file, io, buffer);
}

/// 定位读取不影响全局查找位置,因此更便于线程安全使用。
/// 但若相应系统调用不可用,则预先初始化为
/// 流式模式可省去一次失败的系统调用。
pub fn writerStreaming(file: File, io: Io, buffer: []u8) Writer {
    return .initStreaming(file, io, buffer);
}

/// 这是直接调用 `Io` 接口函数的底层 API。
/// 更高层 API 参见 `writerStreaming`。
pub fn writeStreaming(file: File, io: Io, header: []const u8, data: []const []const u8, splat: usize) Writer.Error!usize {
    return (try io.operate(.{ .file_write_streaming = .{
        .file = file,
        .header = header,
        .data = data,
        .splat = splat,
    } })).file_write_streaming;
}

/// 等同于创建流式写入器、写入 `bytes`,然后刷新。
pub fn writeStreamingAll(file: File, io: Io, bytes: []const u8) Writer.Error!void {
    var index: usize = 0;
    while (index < bytes.len) {
        index += try writeStreaming(file, io, &.{}, &.{bytes[index..]}, 1);
    }
}

pub const LockError = error{
    SystemResources,
    FileLocksUnsupported,
} || Io.Cancelable || Io.UnexpectedError;

/// 其他进程持有不兼容的锁时阻塞。一个进程对某文件
/// 只能持有一种锁,共享锁或独占锁。进程
/// 以任何方式终止时,锁都会释放。
///
/// 假定文件未锁定。
pub fn lock(file: File, io: Io, l: Lock) LockError!void {
    return io.vtable.fileLock(io.userdata, file, l);
}

/// 假定文件已加锁。
pub fn unlock(file: File, io: Io) void {
    return io.vtable.fileUnlock(io.userdata, file);
}

/// 尝试获取锁。获得锁时返回 `true`,若已有其他不兼容的锁被持有,则返回 `false`。
/// 进程只能对同一文件持有一种锁,共享锁或排他锁。进程以任意方式结束时,锁都会释放。
///
/// 假定文件当前未锁定。
///
///
pub fn tryLock(file: File, io: Io, l: Lock) LockError!bool {
    return io.vtable.fileTryLock(io.userdata, file, l);
}

pub const DowngradeLockError = Io.Cancelable || Io.UnexpectedError;

/// 假定文件已处于独占锁定模式。
/// 以原子方式将锁改为共享模式,而不释放锁。
pub fn downgradeLock(file: File, io: Io) LockError!void {
    return io.vtable.fileDowngradeLock(io.userdata, file);
}

pub const RealPathError = error{
    /// 此操作系统、文件系统或 `Io` 实现
    /// 不支持 realpath 操作。
    OperationUnsupported,
    /// 完整文件系统路径无法放入所提供的缓冲区,或
    /// 由于路径过长,无论提供多大的缓冲区,
    /// 均无法通过 realpath 函数获取。
    NameTooLong,
    FileNotFound,
    AccessDenied,
    PermissionDenied,
    NotDir,
    SymLinkLoop,
    InputOutput,
    FileTooBig,
    IsDir,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    NoDevice,
    SystemResources,
    NoSpaceLeft,
    FileSystem,
    DeviceBusy,
    FileBusy,
    PipeBusy,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
    PathAlreadyExists,
    /// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
    /// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
    ///
    ///
    ///
    AntivirusInterference,
    /// 在 Windows 上,卷不包含可识别的文件系统。文件
    /// 系统驱动可能未加载,或卷可能已损坏。
    UnrecognizedVolume,
} || Io.Cancelable || Io.UnexpectedError;

/// 获取与打开的文件句柄对应的规范化绝对路径名。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态条件。通常建议
/// 完全避免使用此函数。
///
pub fn realPath(file: File, io: Io, out_buffer: []u8) RealPathError!usize {
    return io.vtable.fileRealPath(io.userdata, file, out_buffer);
}

pub const HardLinkOptions = struct {
    follow_symlinks: bool = false,
};

pub const HardLinkError = error{
    AccessDenied,
    PermissionDenied,
    DiskQuota,
    PathAlreadyExists,
    HardwareFailure,
    /// 操作系统或文件系统不支持硬链接。
    OperationUnsupported,
    SymLinkLoop,
    LinkQuotaExceeded,
    FileNotFound,
    SystemResources,
    NoSpaceLeft,
    ReadOnlyFileSystem,
    CrossDevice,
    NotDir,
} || Io.Cancelable || Dir.PathNameError || Io.UnexpectedError;

pub fn hardLink(
    file: File,
    io: Io,
    new_dir: Dir,
    new_sub_path: []const u8,
    options: HardLinkOptions,
) HardLinkError!void {
    return io.vtable.fileHardLink(io.userdata, file, new_dir, new_sub_path, options);
}

pub fn createMemoryMap(file: File, io: Io, options: MemoryMap.CreateOptions) MemoryMap.CreateError!MemoryMap {
    return .create(io, file, options);
}

test {
    _ = Reader;
    _ = Writer;
    _ = Atomic;
    _ = MemoryMap;
}