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

第 1 行

字段

handle: Handle

std.Io.Dir.access

函数

第 441 行

测试对 sub_path 的访问。

Windows 上,sub_path 应编码为 WTF-8。 WASI 上,sub_path 应编码为有效 UTF-8。 其他平台上,sub_path 是不规定编码的不透明字节序列。

使用此函数时,请注意检查时间与使用时间之间的竞态。 例如,不要先检查文件是否存在再打开它, 而应直接打开并处理文件不存在的错误。

pub fn access(dir: Dir, io: Io, sub_path: []const u8, options: AccessOptions) AccessError!void

参数

dir: Dir
io: Io
sub_path: []const u8
options: AccessOptions

错误

AccessDenied

文件不允许请求的 AccessOptions,或路径前缀中的 某个目录不允许搜索。

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileNotFound
InputOutput
NameTooLong PathNameError

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

PermissionDenied

请求了写入权限,但文件不可变。

ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.accessAbsolute

函数

第 445 行

pub fn accessAbsolute(io: Io, absolute_path: []const u8, options: AccessOptions) AccessError!void

参数

io: Io
absolute_path: []const u8
options: AccessOptions

错误

AccessDenied

文件不允许请求的 AccessOptions,或路径前缀中的 某个目录不允许搜索。

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileNotFound
InputOutput
NameTooLong PathNameError

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

PermissionDenied

请求了写入权限,但文件不可变。

ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.AccessError

错误集合

第 411 行

错误

AccessDenied

文件不允许请求的 AccessOptions,或路径前缀中的 某个目录不允许搜索。

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileNotFound
InputOutput
NameTooLong PathNameError

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

PermissionDenied

请求了写入权限,但文件不可变。

ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.AccessOptions

容器

第 425 行

字段

follow_symlinks: bool = true
read: bool = false
write: bool = false
execute: bool = false

std.Io.Dir.Allocator

别名

第 11 行

别名目标 std.mem.Allocator

std.Io.Dir.assert

别名

第 10 行

别名目标 std.debug.assert

std.Io.Dir.builtin

常量

第 4 行

std.Io.Dir.close

函数

第 493 行

pub fn close(dir: Dir, io: Io) void

参数

dir: Dir
io: Io

std.Io.Dir.closeMany

函数

第 497 行

pub fn closeMany(io: Io, dirs: []const Dir) void

参数

io: Io
dirs: []const Dir

std.Io.Dir.copyFile

函数

第 1816 行

在 dest_path 原子创建新文件,该路径位于 dest_dir 内, 内容与 source_path 相同,该源路径位于 source_dir 内。

是否覆盖已有文件由 options 决定。

Linux 上,在 https://patchwork.kernel.org/patch/9636735/ 合入 并广泛可用之前,断电或应用 终止可能使临时文件残留在 dest_path 所在的同一目录中。

Windows 上,两条路径均应采用 WTF-8 编码。WASI 上,两条路径均应采用 有效的 UTF-8 编码。其他平台上,两条路径均为 不指定编码的不透明字节序列。

pub fn copyFile( source_dir: Dir, source_path: []const u8, dest_dir: Dir, dest_path: []const u8, io: Io, options: CopyFileOptions, ) CopyFileError!void

参数

source_dir: Dir
source_path: []const u8
dest_dir: Dir
dest_path: []const u8
io: Io
options: CopyFileOptions

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

BrokenPipe Error

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
CrossDevice RenameError
DeviceBusy OpenError
DirNotEmpty RenameError

试图替换非空目录。

DiskQuota RenameError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

HardwareFailure RenameError
InputOutput UnendingError
InvalidFileName
IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LinkQuotaExceeded RenameError
LockViolation UnendingError

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice Error

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

NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForReading UnendingError

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

NotOpenForWriting Error
OperationUnsupported HardLinkError

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

PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SocketUnconnected UnendingError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.copyFileAbsolute

函数

第 1863 行

与 copyFile 相同,但断言 source_path 和 dest_path 均为绝对路径。

Windows 上,两个路径都应采用 WTF-8 编码。 WASI 上,两个路径都应采用有效 UTF-8 编码。 其他平台上,两个路径都是不透明的字节序列,没有特定编码。

pub fn copyFileAbsolute( source_path: []const u8, dest_path: []const u8, io: Io, options: CopyFileOptions, ) !void

参数

source_path: []const u8
dest_path: []const u8
io: Io
options: CopyFileOptions

用法示例

test copyFileAbsolute {}

std.Io.Dir.CopyFileError

错误集合

第 1798 行

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

BrokenPipe Error

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
CrossDevice RenameError
DeviceBusy OpenError
DirNotEmpty RenameError

试图替换非空目录。

DiskQuota RenameError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

HardwareFailure RenameError
InputOutput UnendingError
InvalidFileName
IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LinkQuotaExceeded RenameError
LockViolation UnendingError

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice Error

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

NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForReading UnendingError

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

NotOpenForWriting Error
OperationUnsupported HardLinkError

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

PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SocketUnconnected UnendingError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.CopyFileOptions

容器

第 1791 行

字段

permissions: ?File.Permissions = null

此项为 null 时,从源文件复制权限。

make_path: bool = false
replace: bool = true

std.Io.Dir.createDir

函数

第 800 行

使用相对或绝对路径创建单个目录。

  • Windows 上,sub_path 应采用 WTF-8 编码。
  • WASI 上,sub_path 应采用有效的 UTF-8 编码。
  • 其他平台上,sub_path 是不指定编码的不透明字节序列。

相关函数:

pub fn createDir(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirError!void

参数

dir: Dir
io: Io
sub_path: []const u8
permissions: Permissions

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

DiskQuota
FileNotFound
LinkQuotaExceeded
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.createDirAbsolute

函数

第 812 行

根据绝对路径创建新目录。

断言路径为绝对路径。若需要同时处理 绝对和相对路径,参见 createDir。

Windows 上,absolute_path 应编码为 WTF-8。 WASI 上,absolute_path 应编码为有效 UTF-8。 其他平台上,absolute_path 是不规定编码的不透明字节序列。

pub fn createDirAbsolute(io: Io, absolute_path: []const u8, permissions: Permissions) CreateDirError!void

参数

io: Io
absolute_path: []const u8
permissions: Permissions

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

DiskQuota
FileNotFound
LinkQuotaExceeded
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

用法示例

test createDirAbsolute {}

std.Io.Dir.CreateDirError

错误集合

第 772 行

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

DiskQuota
FileNotFound
LinkQuotaExceeded
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.createDirPath

函数

第 846 行

按需使用默认权限创建父目录,确保 sub_path 作为目录存在。

若路径已存在且是目录,则成功返回。

此函数不一定是原子操作。若返回错误,文件系统 可能已被修改。

路径为空时返回 error.BadPathName,因为空路径 无法创建。

Windows 上,sub_path 应采用 WTF-8 编码。 WASI 上,sub_path 应采用有效的 UTF-8 编码。 其他平台上,sub_path 是不指定编码的不透明字节序列。

包含 .. 分量的路径按平台采用不同的处理方式:

  • Windows 上,在将路径传给 NtCreateFile 之前解析 ..,因此 对于类似 "first/../second" 的 sub_path,会先解析为 "second",只创建 ./second 目录。
  • 其他平台上,.. 在将路径传给 mkdirat 之前不会解析, 因此类似 "first/../second" 的 sub_path 会同时创建 ./first 和 ./second 目录。

另请参见:

pub fn createDirPath(dir: Dir, io: Io, sub_path: []const u8) CreateDirPathError!void

参数

dir: Dir
io: Io
sub_path: []const u8

错误

AccessDenied CreateDirError

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy OpenError
DiskQuota CreateDirError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound CreateDirError

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

NoDevice CreateDirError
NoSpaceLeft OpenError

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

NotDir OpenError

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

PathAlreadyExists OpenError

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

PermissionDenied CreateDirError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem CreateDirError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop CreateDirError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.CreateDirPathError

错误集合

第 819 行

错误

AccessDenied CreateDirError

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy OpenError
DiskQuota CreateDirError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound CreateDirError

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

NoDevice CreateDirError
NoSpaceLeft OpenError

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

NotDir OpenError

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

PathAlreadyExists OpenError

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

PermissionDenied CreateDirError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem CreateDirError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop CreateDirError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.createDirPathOpen

函数

第 873 行

执行等同于先调用 createDirPath、再调用 openDir 的操作,尽可能原子执行。

取消此操作时,文件系统可能处于部分修改状态。

Windows 上,sub_path 应采用 WTF-8 编码。 WASI 上,sub_path 应采用有效 UTF-8 编码。 其他平台上,sub_path 是不透明的字节序列,没有特定编码。

pub fn createDirPathOpen(dir: Dir, io: Io, sub_path: []const u8, options: CreateDirPathOpenOptions) CreateDirPathOpenError!Dir

参数

dir: Dir
io: Io
sub_path: []const u8
options: CreateDirPathOpenOptions

错误

AccessDenied CreateDirError

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy OpenError
DiskQuota CreateDirError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound CreateDirError

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

NoDevice CreateDirError
NoSpaceLeft OpenError

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

NotDir OpenError

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

PathAlreadyExists OpenError

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

PermissionDenied CreateDirError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem CreateDirError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop CreateDirError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.CreateDirPathOpenError

错误集合

第 858 行

错误

AccessDenied CreateDirError

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy OpenError
DiskQuota CreateDirError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound CreateDirError

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

NoDevice CreateDirError
NoSpaceLeft OpenError

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

NotDir OpenError

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

PathAlreadyExists OpenError

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

PermissionDenied CreateDirError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem CreateDirError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop CreateDirError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.CreateDirPathOpenOptions

容器

第 860 行

字段

open_options: OpenOptions = .{}
permissions: Permissions = .default_dir

std.Io.Dir.createDirPathStatus

函数

第 854 行

与 createDirPath 相同,但返回路径原本已存在,还是 已成功创建。

pub fn createDirPathStatus(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirPathError!CreatePathStatus

参数

dir: Dir
io: Io
sub_path: []const u8
permissions: Permissions

错误

AccessDenied CreateDirError

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy OpenError
DiskQuota CreateDirError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound CreateDirError

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

NoDevice CreateDirError
NoSpaceLeft OpenError

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

NotDir OpenError

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

PathAlreadyExists OpenError

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

PermissionDenied CreateDirError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem CreateDirError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop CreateDirError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.createFile

函数

第 641 行

以写入权限创建、打开或覆盖文件。

会分配资源,需通过 File.close 释放。

Windows 上,sub_path 应编码为 WTF-8。 WASI 上,sub_path 应编码为有效 UTF-8。 其他平台上,sub_path 是不规定编码的不透明字节序列。

pub fn createFile(dir: Dir, io: Io, sub_path: []const u8, flags: CreateFileOptions) File.OpenError!File

参数

dir: Dir
io: Io
sub_path: []const u8
flags: CreateFileOptions

错误

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.Dir.createFileAbsolute

函数

第 645 行

pub fn createFileAbsolute(io: Io, absolute_path: []const u8, flags: CreateFileOptions) File.OpenError!File

参数

io: Io
absolute_path: []const u8
flags: CreateFileOptions

错误

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.Dir.createFileAtomic

函数

第 1932 行

创建一个未命名的临时文件,之后可将其原子地实体化为 sub_path。 在该文件完成实体化之前,sub_path 必须保持有效。

返回的 File.Atomic 提供 API,可在底层操作系统不直接支持时模拟此行为。

  • 在 Windows 上,sub_path 应采用 WTF-8 编码。
  • 在 WASI 上,sub_path 应采用有效的 UTF-8 编码。
  • 在其他平台上,sub_path 是不限定编码的不透明字节序列。
pub fn createFileAtomic( dir: Dir, io: Io, sub_path: []const u8, options: CreateFileAtomicOptions, ) CreateFileAtomicError!File.Atomic

参数

dir: Dir
io: Io
sub_path: []const u8
options: CreateFileAtomicOptions

错误

AccessDenied

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

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy

尝试创建的文件是正在运行的可执行文件。

FileNotFound

以下情况之一:

  • 某个路径分量不存在。
  • 使用了 Cwd,但当前工作目录已被删除。
  • 与已打开目录句柄关联的路径已被删除。
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft

设备没有空间容纳新文件,无法创建新路径。

NotDir

路径中作为目录使用的某个组成部分实际上不是目录。

PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources

可用内核内存不足。

Unexpected UnexpectedError

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

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

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

WouldBlock

std.Io.Dir.CreateFileAtomicError

错误集合

第 1888 行

错误

AccessDenied

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

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy

尝试创建的文件是正在运行的可执行文件。

FileNotFound

以下情况之一:

  • 某个路径分量不存在。
  • 使用了 Cwd,但当前工作目录已被删除。
  • 与已打开目录句柄关联的路径已被删除。
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft

设备没有空间容纳新文件,无法创建新路径。

NotDir

路径中作为目录使用的某个组成部分实际上不是目录。

PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources

可用内核内存不足。

Unexpected UnexpectedError

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

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

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

WouldBlock

std.Io.Dir.CreateFileAtomicOptions

容器

第 1877 行

字段

permissions: File.Permissions = .default_file
make_path: bool = false
replace: bool = false

指示无名文件最终将通过 File.Atomic.link 还是 File.Atomic.replace 创建。

如果此值不正确,会在 File.Atomic.replace 中导致断言失败。

std.Io.Dir.CreateFileOptions

容器

第 589 行

字段

read: bool = false

是否创建具有读取访问权限的文件。

truncate: bool = true

若文件已存在且是普通文件,并且访问 模式允许写入,则将其截断为长度 0。

exclusive: bool = false

确保此次打开操作创建文件,否则 返回 error.PathAlreadyExists。

lock: File.Lock = .none

打开文件并获取建议锁,以协调其他同时访问 该文件的进程。独占锁会阻止其他 进程获取锁。共享锁会阻止其他 进程获取独占锁,但不会阻止 其他进程获取各自的共享锁。

除 Linux 上极少数特定情况外,此锁均为建议锁[1]。 也就是说,不遵守锁 API 的进程即使面对已加锁文件, 仍然可以访问文件。

以下操作系统在打开文件的同时 原子地获取锁:

  • Darwin
  • DragonFlyBSD
  • FreeBSD
  • Haiku
  • NetBSD
  • OpenBSD 以下操作系统在打开文件后, 通过单独的系统调用获取锁:
  • Linux
  • Windows

[1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt

lock_nonblocking: bool = false

设置返回前是否等待文件加锁。若为 true, 则返回 error.WouldBlock;否则等待,直至文件 可供继续操作(原文条件如此)。

permissions: Permissions = .default_file
resolve_beneath: bool = false

如果操作系统支持,尝试解析会越出此目录的路径时, 将改为返回 error.AccessDenied。 若不支持,则忽略此选项。

std.Io.Dir.CreatePathStatus

容器

第 850 行

字段

existed
created

std.Io.Dir.cwd

函数

第 88 行

返回当前工作目录的句柄。

该句柄不以迭代能力打开,对结果进行迭代属于非法行为。

关闭返回的 Dir 属于受检查的非法行为。

在 POSIX 目标上,此函数可在编译期调用。

可通过 std.Options.cwd 覆盖此函数。

pub fn cwd() Dir

std.Io.Dir.deleteDir

函数

第 1038 行

如果目录非空,则返回 error.DirNotEmpty。

递归删除目录,参见 deleteTree。

Windows 上,sub_path 应编码为 WTF-8。 WASI 上,sub_path 应编码为有效 UTF-8。 其他平台上,sub_path 是不规定编码的不透明字节序列。

pub fn deleteDir(dir: Dir, io: Io, sub_path: []const u8) DeleteDirError!void

参数

dir: Dir
io: Io
sub_path: []const u8

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

DirNotEmpty
FileBusy
FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteDirAbsolute

函数

第 1047 行

与 deleteDir 相同,但路径为绝对路径。

Windows 上,dir_path 应采用 WTF-8 编码。 WASI 上,dir_path 应采用有效 UTF-8 编码。 其他平台上,dir_path 是不透明的字节序列,没有特定编码。

pub fn deleteDirAbsolute(io: Io, absolute_path: []const u8) DeleteDirError!void

参数

io: Io
absolute_path: []const u8

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

DirNotEmpty
FileBusy
FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.DeleteDirError

错误集合

第 1016 行

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

DirNotEmpty
FileBusy
FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteFile

函数

第 1005 行

根据已打开的目录句柄删除文件名,并可能删除其引用的文件。

Windows 上,sub_path 应编码为 WTF-8。 WASI 上,sub_path 应编码为有效 UTF-8。 其他平台上,sub_path 是不规定编码的不透明字节序列。

断言路径参数不含空字节。

pub fn deleteFile(dir: Dir, io: Io, sub_path: []const u8) DeleteFileError!void

参数

dir: Dir
io: Io
sub_path: []const u8

错误

AccessDenied

在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileNotFound
FileSystem
IsDir
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteFileAbsolute

函数

第 1009 行

pub fn deleteFileAbsolute(io: Io, absolute_path: []const u8) DeleteFileError!void

参数

io: Io
absolute_path: []const u8

错误

AccessDenied

在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileNotFound
FileSystem
IsDir
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

用法示例

test deleteFileAbsolute {}

std.Io.Dir.DeleteFileError

错误集合

第 981 行

错误

AccessDenied

在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileNotFound
FileSystem
IsDir
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteTree

函数

第 1408 行

不论 sub_path 描述的是符号链接、文件还是目录,此函数 都会将其删除。若因目录非空而无法删除, 则先递归删除其条目,再次尝试。

此操作在多数文件系统上不是原子操作。

Windows 上,sub_path 应采用 WTF-8 编码。 WASI 上,sub_path 应采用有效的 UTF-8 编码。 其他平台上,sub_path 是不指定编码的不透明字节序列。

pub fn deleteTree(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void

参数

dir: Dir
io: Io
sub_path: []const u8

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileSystem
FileTooBig
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NotDir

某个路径分量不是目录。 若 sub_path 不包含路径分隔符,则此错误不可达。

PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteTree.closeAll

函数

第 1416 行

fn closeAll(inner_io: Io, items: []@This()) void

参数

inner_io: Io
items: []@This()

std.Io.Dir.DeleteTreeError

错误集合

第 1380 行

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileSystem
FileTooBig
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NotDir

某个路径分量不是目录。 若 sub_path 不包含路径分隔符,则此错误不可达。

PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteTreeMinStackSize

函数

第 1607 行

类似 deleteTree,但每次只保持一个 Iterator 活跃,以最小化函数栈大小。 比 deleteTree 慢,但使用更少栈空间。 Windows 上,sub_path 应采用 WTF-8 编码。 WASI 上,sub_path 应采用有效的 UTF-8 编码。 其他平台上,sub_path 是不指定编码的不透明字节序列。

pub fn deleteTreeMinStackSize(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void

参数

dir: Dir
io: Io
sub_path: []const u8

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileSystem
FileTooBig
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NotDir

某个路径分量不是目录。 若 sub_path 不包含路径分隔符,则此错误不可达。

PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteTreeMinStackSizeWithKindHint

函数

第 1611 行

fn deleteTreeMinStackSizeWithKindHint(parent: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) DeleteTreeError!void

参数

parent: Dir
io: Io
sub_path: []const u8
kind_hint: File.Kind

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy
FileSystem
FileTooBig
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NotDir

某个路径分量不是目录。 若 sub_path 不包含路径分隔符,则此错误不可达。

PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.deleteTreeOpenInitialSubpath

函数

第 1726 行

删除成功时返回 null。

fn deleteTreeOpenInitialSubpath(dir: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) !?Dir

参数

dir: Dir
io: Io
sub_path: []const u8
kind_hint: File.Kind

std.Io.Dir.Dir

别名

第 1 行

别名目标 std.Io.Dir

std.Io.Dir.Entry

容器

第 72 行

字段

name: []const u8
kind: File.Kind
inode: File.INode

std.Io.Dir.File

别名

第 9 行

别名目标 std.Io.File

std.Io.Dir.Handle

别名

第 15 行

别名目标 std.posix.fd_t

std.Io.Dir.hardLink

函数

第 1154 行

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

参数

old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8
io: Io
options: HardLinkOptions

错误

AccessDenied HardLinkError
BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice HardLinkError
DiskQuota HardLinkError
FileNotFound HardLinkError
HardwareFailure HardLinkError
LinkQuotaExceeded HardLinkError
NameTooLong PathNameError

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

NoSpaceLeft HardLinkError
NotDir HardLinkError
OperationUnsupported HardLinkError

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

PathAlreadyExists HardLinkError
PermissionDenied HardLinkError
ReadOnlyFileSystem HardLinkError
SymLinkLoop HardLinkError
SystemResources HardLinkError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.HardLinkError

别名

第 1152 行

别名目标 std.Io.File.HardLinkError

std.Io.Dir.HardLinkOptions

别名

第 1150 行

别名目标 std.Io.File.HardLinkOptions

std.Io.Dir.Io

别名

第 8 行

别名目标 std.Io

std.Io.Dir.iterate

函数

第 211 行

pub fn iterate(dir: Dir) Iterator

参数

dir: Dir

std.Io.Dir.iterateAssumeFirstIteration

函数

第 218 行

类似 iterate,但不会在首次迭代前重置目录游标。 仅应在已知 Dir 的游标尚未被修改时使用, 例如该目录刚刚打开。

pub fn iterateAssumeFirstIteration(dir: Dir) Iterator

参数

dir: Dir

std.Io.Dir.Iterator

容器

第 180 行

此 API 优先考虑便利性,而非性能:

  • 自行选择缓冲区大小,不允许用户提供。
  • 每次仅请求一个 Entry,来源为 Io 实现, 而非批量操作,从而使其可移动。

不过,它仍会尽量减少系统调用开销。 更底层的抽象参见 Reader,更高层的抽象 参见 Walker。

字段

reader: Reader
reader_buffer: [reader_buffer_len]u8 align(@alignOf(usize))

std.Io.Dir.Iterator.Error

别名

第 190 行

别名目标 std.Io.Dir.Reader.Error

std.Io.Dir.Iterator.init

函数

第 192 行

pub fn init(dir: Dir, reader_state: Reader.State) Iterator

参数

dir: Dir
reader_state: Reader.State

std.Io.Dir.Iterator.next

函数

第 205 行

pub fn next(it: *Iterator, io: Io) Error!?Entry

参数

it: *Iterator
io: Io

错误

AccessDenied Error
Canceled Cancelable

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

PermissionDenied Error
SystemResources Error
Unexpected UnexpectedError

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

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

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

std.Io.Dir.Iterator.reader_buffer_len

常量

第 184 行

std.Io.Dir.max_name_bytes

常量

第 54 行

表示平台常见文件系统支持的 []u8 文件名分量 的最大大小。文件系统操作返回的文件名分量 通常可容纳于此长度的 u8 数组中,但 此假设可能不适用于每种配置,具体取决于平台。 字节数不包括空哨兵字节。 Windows 上的 []u8 文件名分量编码为 WTF-8。 WASI 上的文件名分量编码为有效 UTF-8。 其他平台上的 []u8 分量是不规定编码的不透明字节序列。

std.Io.Dir.max_path_bytes

常量

第 33 行

操作系统接受的文件路径最大长度。

路径,包括文件系统操作返回的路径,都可能超过此长度,但这样的路径无法再成功传入其他文件系统操作。不过,假定文件系统操作返回的所有单独路径分量都能放入此长度的 u8 数组。

字节数包含空终止哨兵字节所需的空间。

  • Windows 上,[]u8 文件路径采用 WTF-8 编码。
  • WASI 上,[]u8 文件路径采用有效 UTF-8 编码。
  • 其他平台上,[]u8 文件路径是不透明的字节序列,没有特定编码。

std.Io.Dir.native_os

常量

第 5 行

std.Io.Dir.openDir

函数

第 484 行

打开给定路径的目录。目录是系统资源, 会保持打开,直到对返回结果调用 close。

只有将 iterate 选项设为 true,才能迭代该目录。

Windows 上,sub_path 应采用 WTF-8 编码。 WASI 上,sub_path 应采用有效的 UTF-8 编码。 其他平台上,sub_path 是不指定编码的不透明字节序列。

pub fn openDir(dir: Dir, io: Io, sub_path: []const u8, options: OpenOptions) OpenError!Dir

参数

dir: Dir
io: Io
sub_path: []const u8
options: OpenOptions

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

FileNotFound
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NotDir
PermissionDenied
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.openDirAbsolute

函数

第 488 行

pub fn openDirAbsolute(io: Io, absolute_path: []const u8, options: OpenOptions) OpenError!Dir

参数

io: Io
absolute_path: []const u8
options: OpenOptions

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

FileNotFound
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NotDir
PermissionDenied
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.OpenError

错误集合

第 450 行

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

FileNotFound
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NotDir
PermissionDenied
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.openFile

函数

第 580 行

打开文件以读取或写入,不尝试创建新文件。

创建新文件,参见 createFile。

会分配资源,需通过 File.close 释放。

Windows 上,sub_path 应编码为 WTF-8。 WASI 上,sub_path 应编码为有效 UTF-8。 其他平台上,sub_path 是不规定编码的不透明字节序列。

pub fn openFile(dir: Dir, io: Io, sub_path: []const u8, options: OpenFileOptions) File.OpenError!File

参数

dir: Dir
io: Io
sub_path: []const u8
options: OpenFileOptions

错误

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.Dir.openFileAbsolute

函数

第 584 行

pub fn openFileAbsolute(io: Io, absolute_path: []const u8, options: OpenFileOptions) File.OpenError!File

参数

io: Io
absolute_path: []const u8
options: OpenFileOptions

错误

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.Dir.OpenFileOptions

容器

第 501 行

字段

mode: Mode = .read_only
allow_directory: bool = true

决定打开指向目录的路径时的行为。

若设为 true,可以打开目录,但某些情况下仍可能返回 error.IsDir,例如尝试以写权限打开目录。

若设为 false,打开目录时始终返回 error.IsDir。

设为 false 时:

  • Windows 上无需额外系统调用。
  • 其他操作系统上需要额外执行一次 fstat 系统调用。
path_only: bool = false

表示此已打开文件仅打算用于部分操作:

  • close
  • stat 在 Linux 和 FreeBSD 上,对应 std.posix.O.PATH。
lock: File.Lock = .none

打开文件并获取建议锁,以协调其他同时访问 该文件的进程。独占锁会阻止其他 进程获取锁。共享锁会阻止其他 进程获取独占锁,但不会阻止 其他进程获取各自的共享锁。

除 Linux 上极少数特定情况外,此锁均为建议锁[1]。 也就是说,不遵守锁 API 的进程即使面对已加锁文件, 仍然可以访问文件。

以下操作系统在打开文件的同时 原子地获取锁:

  • Darwin
  • DragonFlyBSD
  • FreeBSD
  • Haiku
  • NetBSD
  • OpenBSD 以下操作系统在打开文件后, 通过单独的系统调用获取锁:
  • Linux
  • Windows

[1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt

lock_nonblocking: bool = false

设置返回前是否等待文件加锁。若为 true, 则返回 error.WouldBlock;否则等待,直至文件 可供继续操作(原文条件如此)。

allow_ctty: bool = false

设置此项,以允许打开的文件自动成为 当前进程的控制 TTY。

follow_symlinks: bool = true
resolve_beneath: bool = false

如果操作系统支持,尝试解析会越出此目录的路径时, 将改为返回 error.AccessDenied。 若不支持,则忽略此选项。

std.Io.Dir.OpenFileOptions.isRead

函数

第 562 行

pub fn isRead(self: OpenFileOptions) bool

参数

std.Io.Dir.OpenFileOptions.isWrite

函数

第 566 行

pub fn isWrite(self: OpenFileOptions) bool

参数

std.Io.Dir.OpenFileOptions.Mode

容器

第 560 行

字段

read_only
write_only
read_write

std.Io.Dir.OpenOptions

容器

第 464 行

字段

access_sub_paths: bool = true

true 表示打开的目录可用作基于已打开目录句柄 进行操作的函数的 Dir 参数。若为 false, 则此类操作属于非法行为。

iterate: bool = false

true 表示可扫描打开的目录,获取其文件和子目录 作为结果,即可以调用 iterate 函数。

follow_symlinks: bool = true

false 表示不解引用符号链接。

std.Io.Dir.path

别名

第 17 行

别名目标 std.fs.path

std.Io.Dir.PathNameError

错误集合

第 401 行

错误

BadPathName

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

NameTooLong

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

std.Io.Dir.Permissions

别名

第 1942 行

别名目标 std.Io.File.Permissions

std.Io.Dir.PrevStatus

容器

第 667 行

字段

stale
fresh

std.Io.Dir.Reader

容器

第 97 行

字段

dir: Dir
state: State
buffer: []align(@alignOf(usize)) u8

存储 I/O 实现专用数据。

index: usize

buffer 中下一条目的索引。

end: usize

填充 buffer 的位置。

std.Io.Dir.Reader.Error

错误集合

第 131 行

错误

AccessDenied
Canceled Cancelable

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

PermissionDenied
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.Reader.init

函数

第 138 行

断言 buffer 长度至少为 min_buffer_len。

pub fn init(dir: Dir, buffer: []align(@alignOf(usize)) u8) Reader

参数

dir: Dir
buffer: []align(@alignOf(usize)) u8

std.Io.Dir.Reader.min_buffer_len

常量

第 108 行

使所有实现均能正常工作的 buffer 长度。

std.Io.Dir.Reader.next

函数

第 156 行

下次调用 read 或 next 时,Entry.name 失效。

pub fn next(r: *Reader, io: Io) Error!?Entry

参数

r: *Reader
io: Io

错误

AccessDenied
Canceled Cancelable

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

PermissionDenied
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.Reader.read

函数

第 151 行

下次调用 read 或 next 时, 所有 Entry.name 均失效。

pub fn read(r: *Reader, io: Io, buffer: []Entry) Error!usize

参数

r: *Reader
io: Io
buffer: []Entry

错误

AccessDenied
Canceled Cancelable

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

PermissionDenied
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.Reader.reset

函数

第 165 行

pub fn reset(r: *Reader) void

参数

r: *Reader

std.Io.Dir.Reader.State

容器

第 123 行

字段

reset

表示下一次调用 read 应回退并重新开始目录列表。

reading
finished

std.Io.Dir.readFile

函数

第 756 行

使用预先分配的缓冲区读取全部文件内容。

返回切片与 buffer 具有相同指针。若长度等于 buffer.len, 则情况存在歧义:既可能表示已读取整个文件,且 恰好填满缓冲区;也可能表示缓冲区不足以容纳 整个文件。

  • Windows 上,file_path 应采用 WTF-8 编码。
  • WASI 上,file_path 应采用有效的 UTF-8 编码。
  • 其他平台上,file_path 是不指定编码的不透明字节序列。
pub fn readFile(dir: Dir, io: Io, file_path: []const u8, buffer: []u8) ReadFileError![]u8

参数

dir: Dir
io: Io
file_path: []const u8
buffer: []u8

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

InputOutput UnendingError
IsDir OpenError

以下任一情况:

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

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForReading UnendingError

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

PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SocketUnconnected UnendingError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.readFileAlloc

函数

第 1333 行

读取指定文件的全部字节。成功时,调用者拥有返回的缓冲区。

若已知文件大小,更好的方式是初始化 File.Reader。

若无法获取文件大小,则返回错误。若实际中可能遇到这种情况,更好的方式是初始化 File.Reader,它可无缝处理该情况。

pub fn readFileAlloc( dir: Dir, io: Io, sub_path: []const u8, gpa: Allocator, limit: Io.Limit, ) ReadFileAllocError![]u8

参数

dir: Dir
io: Io
sub_path: []const u8

在 Windows 上,应编码为 WTF-8。 在 WASI 上,应编码为有效的 UTF-8。 在其他平台上,为不规定编码的不透明字节序列。

gpa: Allocator

用于分配结果。

limit: Io.Limit

如果达到或超过此值,则改为返回 error.StreamTooLong。

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

InputOutput UnendingError
IsDir OpenError

以下任一情况:

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

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForReading UnendingError

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

OutOfMemory Error
PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SocketUnconnected UnendingError
StreamTooLong

文件大小达到或超过提供的限制。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.ReadFileAllocError

错误集合

第 1319 行

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

InputOutput UnendingError
IsDir OpenError

以下任一情况:

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

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForReading UnendingError

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

OutOfMemory Error
PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SocketUnconnected UnendingError
StreamTooLong

文件大小达到或超过提供的限制。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.readFileAllocOptions

函数

第 1353 行

读取指定文件的所有字节。成功时,返回缓冲区的 所有权归调用者。

若文件大小已知,更好的选择是初始化一个 File.Reader。

pub fn readFileAllocOptions( dir: Dir, io: Io, sub_path: []const u8, gpa: Allocator, limit: Io.Limit, comptime alignment: std.mem.Alignment, comptime sentinel: ?u8, ) ReadFileAllocError!(if (sentinel) |s| [:s]align(alignment.toByteUnits()) u8 else []align(alignment.toByteUnits()) u8)

参数

dir: Dir
io: Io
sub_path: []const u8

在 Windows 上,应编码为 WTF-8。 在 WASI 上,应编码为有效的 UTF-8。 在其他平台上,为不规定编码的不透明字节序列。

gpa: Allocator

用于分配结果。

limit: Io.Limit

如果达到或超过此值,则改为返回 error.StreamTooLong。

alignment: std.mem.Alignment
sentinel: ?u8

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

InputOutput UnendingError
IsDir OpenError

以下任一情况:

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

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForReading UnendingError

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

OutOfMemory Error
PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SocketUnconnected UnendingError
StreamTooLong

文件大小达到或超过提供的限制。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.ReadFileError

错误集合

第 744 行

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

InputOutput UnendingError
IsDir OpenError

以下任一情况:

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

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForReading UnendingError

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

PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SocketUnconnected UnendingError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.readLink

函数

第 1305 行

获取符号链接的目标。

返回 buffer 中已填充的字节数。

断言路径参数不含空字节。

Windows 上,sub_path 应采用 WTF-8 编码。 WASI 上,sub_path 应采用有效 UTF-8 编码。 其他平台上,sub_path 是不透明的字节序列,没有特定编码。

pub fn readLink(dir: Dir, io: Io, sub_path: []const u8, buffer: []u8) ReadLinkError!usize

参数

dir: Dir
io: Io
sub_path: []const u8
buffer: []u8

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy

尝试打开的文件是正在运行的可执行文件。

FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
NotLink
PermissionDenied
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

UnsupportedReparsePointType

仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。

std.Io.Dir.readLinkAbsolute

函数

第 1314 行

与 readLink 相同,但断言路径为绝对路径。

Windows 上,path 应采用 WTF-8 编码。 WASI 上,path 应采用有效的 UTF-8 编码。 其他平台上,path 是不指定编码的不透明字节序列。

pub fn readLinkAbsolute(io: Io, absolute_path: []const u8, buffer: []u8) ReadLinkError!usize

参数

io: Io
absolute_path: []const u8
buffer: []u8

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy

尝试打开的文件是正在运行的可执行文件。

FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
NotLink
PermissionDenied
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

UnsupportedReparsePointType

仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。

std.Io.Dir.ReadLinkError

错误集合

第 1270 行

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

FileBusy

尝试打开的文件是正在运行的可执行文件。

FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NotDir
NotLink
PermissionDenied
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

UnsupportedReparsePointType

仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。

std.Io.Dir.realPath

函数

第 913 行

获取 dir 的规范化绝对路径名。

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

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

参数

dir: Dir
io: Io
out_buffer: []u8

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

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

Canceled Cancelable

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

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

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

NetworkNotFound RealPathError

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

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

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

PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume RealPathError

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

std.Io.Dir.RealPathError

别名

第 906 行

别名目标 std.Io.File.RealPathError

std.Io.Dir.realPathFile

函数

第 930 行

取得 sub_path 相对于此 Dir 的规范化绝对路径名。 如果 sub_path 为绝对路径,则忽略此 Dir 句柄, 取得 sub_path 参数的规范化绝对路径名。

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

另请参见:

pub fn realPathFile(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPathFileError!usize

参数

dir: Dir
io: Io
sub_path: []const u8
out_buffer: []u8

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

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

NetworkNotFound RealPathError

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

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

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

PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume RealPathError

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

std.Io.Dir.realPathFileAbsolute

函数

第 961 行

与 realPathFile 相同,但断言 absolute_path 为绝对 路径。

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

另请参见:

pub fn realPathFileAbsolute(io: Io, absolute_path: []const u8, out_buffer: []u8) RealPathFileError!usize

参数

io: Io
absolute_path: []const u8
out_buffer: []u8

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

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

NetworkNotFound RealPathError

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

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

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

PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume RealPathError

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

std.Io.Dir.realPathFileAbsoluteAlloc

函数

第 975 行

与 realPathFileAbsolute 相同,但会分配结果。

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

另请参见:

pub fn realPathFileAbsoluteAlloc(io: Io, absolute_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8

参数

io: Io
absolute_path: []const u8
allocator: Allocator

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

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

NetworkNotFound RealPathError

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

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

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

OutOfMemory Error
PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume RealPathError

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

std.Io.Dir.realPathFileAlloc

函数

第 945 行

与 realPathFile 相同,但会分配结果。

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

另请参见:

pub fn realPathFileAlloc(dir: Dir, io: Io, sub_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8

参数

dir: Dir
io: Io
sub_path: []const u8
allocator: Allocator

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

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

NetworkNotFound RealPathError

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

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

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

OutOfMemory Error
PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume RealPathError

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

std.Io.Dir.RealPathFileAllocError

错误集合

第 934 行

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

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

NetworkNotFound RealPathError

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

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

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

OutOfMemory Error
PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume RealPathError

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

std.Io.Dir.RealPathFileError

错误集合

第 917 行

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

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

NetworkNotFound RealPathError

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

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

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

PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume RealPathError

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

std.Io.Dir.rename

函数

第 1094 行

更改文件或目录的名称或位置。

如果 new_sub_path 已存在,则将其替换。

将文件重命名以覆盖已有目录,或将目录重命名以覆盖已有 文件,都会失败并返回 error.IsDir 或 error.NotDir。

  • Windows 上,两个路径均应编码为 WTF-8。
  • WASI 上,两个路径均应编码为有效 UTF-8。
  • 其他平台上,两个路径均是不规定编码的不透明字节序列。
pub fn rename( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, io: Io, ) RenameError!void

参数

old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8
io: Io

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice
DirNotEmpty

试图替换非空目录。

DiskQuota
FileBusy

尝试移动或替换的文件是正在运行的可执行文件。

FileNotFound
HardwareFailure
IsDir
LinkQuotaExceeded
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
PermissionDenied
PipeBusy
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.renameAbsolute

函数

第 1104 行

pub fn renameAbsolute(old_path: []const u8, new_path: []const u8, io: Io) RenameError!void

参数

old_path: []const u8
new_path: []const u8
io: Io

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice
DirNotEmpty

试图替换非空目录。

DiskQuota
FileBusy

尝试移动或替换的文件是正在运行的可执行文件。

FileNotFound
HardwareFailure
IsDir
LinkQuotaExceeded
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
PermissionDenied
PipeBusy
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.RenameError

错误集合

第 1052 行

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。

AntivirusInterference

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

BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice
DirNotEmpty

试图替换非空目录。

DiskQuota
FileBusy

尝试移动或替换的文件是正在运行的可执行文件。

FileNotFound
HardwareFailure
IsDir
LinkQuotaExceeded
NameTooLong PathNameError

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
PermissionDenied
PipeBusy
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.renamePreserve

函数

第 1140 行

更改文件或目录的名称或位置。

如果 new_sub_path 已存在,将返回 error.PathAlreadyExists。

若操作系统支持,整个操作将以原子方式完成。否则,将回退为先创建硬链接再取消链接;这对 new_sub_path 是原子的,但存在清理 old_sub_path 可能失败的时间窗口。虽然该操作具有较好的可移植性,但严格来说,在某些环境下该回退方案也可能不受支持,此时返回 error.OperationUnsupported。

  • 在 Windows 上,两个路径都应采用 WTF-8 编码。
  • 在 WASI 上,两个路径都应采用有效的 UTF-8 编码。
  • 在其他平台上,两个路径都是不限定编码的不透明字节序列。
pub fn renamePreserve( old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, io: Io, ) RenamePreserveError!void

参数

old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8
io: Io

错误

AccessDenied

在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。

在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。

在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。

AntivirusInterference RenameError

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

BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice RenameError
DirNotEmpty RenameError

试图替换非空目录。

DiskQuota RenameError
FileBusy RenameError

尝试移动或替换的文件是正在运行的可执行文件。

FileNotFound RenameError
HardwareFailure RenameError
IsDir RenameError
LinkQuotaExceeded RenameError
NameTooLong PathNameError

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

NetworkNotFound RenameError

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

NoDevice RenameError
NoSpaceLeft RenameError
NotDir RenameError
OperationUnsupported

操作系统或文件系统不支持原子地执行不替换目标的重命名。

PathAlreadyExists
PermissionDenied RenameError
PipeBusy RenameError
ReadOnlyFileSystem RenameError
SymLinkLoop RenameError
SystemResources RenameError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.RenamePreserveError

错误集合

第 1111 行

错误

AccessDenied

在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。

在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。

在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。

AntivirusInterference RenameError

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

BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice RenameError
DirNotEmpty RenameError

试图替换非空目录。

DiskQuota RenameError
FileBusy RenameError

尝试移动或替换的文件是正在运行的可执行文件。

FileNotFound RenameError
HardwareFailure RenameError
IsDir RenameError
LinkQuotaExceeded RenameError
NameTooLong PathNameError

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

NetworkNotFound RenameError

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

NoDevice RenameError
NoSpaceLeft RenameError
NotDir RenameError
OperationUnsupported

操作系统或文件系统不支持原子地执行不替换目标的重命名。

PathAlreadyExists
PermissionDenied RenameError
PipeBusy RenameError
ReadOnlyFileSystem RenameError
SymLinkLoop RenameError
SystemResources RenameError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.root

常量

第 2 行

std.Io.Dir.SelectiveWalker

容器

第 222 行

字段

stack: std.ArrayList(StackItem)
name_buffer: std.ArrayList(u8)
allocator: Allocator

std.Io.Dir.SelectiveWalker.deinit

函数

第 298 行

pub fn deinit(self: *SelectiveWalker) void

参数

std.Io.Dir.SelectiveWalker.enter

函数

第 278 行

进入目录,继续向下一层遍历。

pub fn enter(self: *SelectiveWalker, io: Io, entry: Walker.Entry) !void

参数

self: *SelectiveWalker
io: Io
entry: Walker.Entry

std.Io.Dir.SelectiveWalker.Error

错误集合

第 227 行

错误

AccessDenied Error
Canceled Cancelable

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

OutOfMemory Error
PermissionDenied Error
SystemResources Error
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SelectiveWalker.leave

函数

第 306 行

离开当前目录,继续向上一级遍历。 若当前条目是目录条目,并在 leave 之前调用了 enter,则“当前目录”指向该条目。

pub fn leave(self: *SelectiveWalker, io: Io) void

参数

self: *SelectiveWalker
io: Io

std.Io.Dir.SelectiveWalker.next

函数

第 237 行

每次调用此函数后,以及调用 deinit() 时, 此函数先前返回的内存均会失效。若要保留 对路径的引用,必须进行拷贝。

pub fn next(self: *SelectiveWalker, io: Io) Error!?Walker.Entry

参数

self: *SelectiveWalker
io: Io

错误

AccessDenied Error
Canceled Cancelable

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

OutOfMemory Error
PermissionDenied Error
SystemResources Error
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SelectiveWalker.StackItem

容器

第 229 行

字段

iter: Iterator
dirname_len: usize

std.Io.Dir.setFileOwner

函数

第 1997 行

也称为 "fchownat"。

pub fn setFileOwner( dir: Dir, io: Io, sub_path: []const u8, owner: ?File.Uid, group: ?File.Gid, options: SetFileOwnerOptions, ) SetFileOwnerError!void

参数

dir: Dir
io: Io
sub_path: []const u8
owner: ?File.Uid
group: ?File.Gid
options: SetFileOwnerOptions

错误

AccessDenied SetOwnerError
BadPathName PathNameError

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

Canceled Cancelable

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

FileNotFound SetOwnerError
InputOutput SetOwnerError
NameTooLong PathNameError

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

PermissionDenied SetOwnerError
ReadOnlyFileSystem SetOwnerError
SymLinkLoop SetOwnerError
SystemResources SetOwnerError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SetFileOwnerError

错误集合

第 1990 行

错误

AccessDenied SetOwnerError
BadPathName PathNameError

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

Canceled Cancelable

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

FileNotFound SetOwnerError
InputOutput SetOwnerError
NameTooLong PathNameError

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

PermissionDenied SetOwnerError
ReadOnlyFileSystem SetOwnerError
SymLinkLoop SetOwnerError
SystemResources SetOwnerError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SetFileOwnerOptions

容器

第 1992 行

字段

follow_symlinks: bool = true

std.Io.Dir.setFilePermissions

函数

第 1967 行

也称为 "fchmodat"。

pub fn setFilePermissions( dir: Dir, io: Io, sub_path: []const u8, new_permissions: File.Permissions, options: SetFilePermissionsOptions, ) SetFilePermissionsError!void

参数

dir: Dir
io: Io
sub_path: []const u8
new_permissions: File.Permissions
options: SetFilePermissionsOptions

错误

AccessDenied SetPermissionsError
BadPathName PathNameError

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

Canceled Cancelable

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

FileNotFound SetPermissionsError
InputOutput SetPermissionsError
NameTooLong PathNameError

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

OperationUnsupported

SetFilePermissionsOptions.follow_symlinks 被设为 false,但文件系统或操作系统不允许。

PermissionDenied SetPermissionsError
ProcessFdQuotaExceeded
ReadOnlyFileSystem SetPermissionsError
SymLinkLoop SetPermissionsError
SystemFdQuotaExceeded
SystemResources SetPermissionsError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SetFilePermissionsError

错误集合

第 1954 行

错误

AccessDenied SetPermissionsError
BadPathName PathNameError

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

Canceled Cancelable

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

FileNotFound SetPermissionsError
InputOutput SetPermissionsError
NameTooLong PathNameError

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

OperationUnsupported

SetFilePermissionsOptions.follow_symlinks 被设为 false,但文件系统或操作系统不允许。

PermissionDenied SetPermissionsError
ProcessFdQuotaExceeded
ReadOnlyFileSystem SetPermissionsError
SymLinkLoop SetPermissionsError
SystemFdQuotaExceeded
SystemResources SetPermissionsError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SetFilePermissionsOptions

容器

第 1962 行

字段

follow_symlinks: bool = true

std.Io.Dir.setOwner

函数

第 1986 行

也称为“chown”。

进程必须具有正确权限才能成功执行。目录所有者可以将所属组改为自身属于的任意组。此外,目录必须在打开时将 OpenOptions.iterate 设为 true。 若所有者或所属组指定为 null,则对应标识不变。

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

参数

dir: Dir
io: Io
owner: ?File.Uid
group: ?File.Gid

错误

AccessDenied SetOwnerError
Canceled Cancelable

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

FileNotFound SetOwnerError
InputOutput SetOwnerError
PermissionDenied SetOwnerError
ReadOnlyFileSystem SetOwnerError
SymLinkLoop SetOwnerError
SystemResources SetOwnerError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SetOwnerError

别名

第 1977 行

别名目标 std.Io.File.SetOwnerError

std.Io.Dir.setPermissions

函数

第 1950 行

也称为 chmod。

进程必须具有适当特权,才能成功执行, 或者有效用户标识符必须与目录 所有者匹配。此外,目录必须在打开时 将 OpenOptions.iterate 设为 true。

pub fn setPermissions(dir: Dir, io: Io, new_permissions: File.Permissions) SetPermissionsError!void

参数

dir: Dir
io: Io
new_permissions: File.Permissions

错误

AccessDenied SetPermissionsError
Canceled Cancelable

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

FileNotFound SetPermissionsError
InputOutput SetPermissionsError
PermissionDenied SetPermissionsError
ReadOnlyFileSystem SetPermissionsError
SymLinkLoop SetPermissionsError
SystemResources SetPermissionsError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SetPermissionsError

别名

第 1941 行

别名目标 std.Io.File.SetPermissionsError

std.Io.Dir.setTimestamps

函数

第 2019 行

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

pub fn setTimestamps( dir: Dir, io: Io, sub_path: []const u8, options: SetTimestampsOptions, ) SetTimestampsError!void

参数

dir: Dir
io: Io
sub_path: []const u8
options: SetTimestampsOptions

错误

AccessDenied SetTimestampsError

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

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

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

Canceled Cancelable

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

NameTooLong PathNameError

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

PermissionDenied SetTimestampsError

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

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

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

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

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

std.Io.Dir.SetTimestampsError

错误集合

第 2008 行

错误

AccessDenied SetTimestampsError

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

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

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

Canceled Cancelable

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

NameTooLong PathNameError

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

PermissionDenied SetTimestampsError

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

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

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

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

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

std.Io.Dir.setTimestampsNow

函数

第 2037 行

将所提供路径的访问时间戳及修改时间戳 设置为当前墙上时钟时间。

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

pub fn setTimestampsNow( dir: Dir, io: Io, sub_path: []const u8, options: SetTimestampsNowOptions, ) SetTimestampsError!void

参数

dir: Dir
io: Io
sub_path: []const u8
options: SetTimestampsNowOptions

错误

AccessDenied SetTimestampsError

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

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

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

Canceled Cancelable

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

NameTooLong PathNameError

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

PermissionDenied SetTimestampsError

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

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

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

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

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

std.Io.Dir.SetTimestampsNowOptions

容器

第 2028 行

字段

follow_symlinks: bool = true

std.Io.Dir.SetTimestampsOptions

容器

第 2010 行

字段

follow_symlinks: bool = true
access_timestamp: File.SetTimestamp = .unchanged
modify_timestamp: File.SetTimestamp = .unchanged

std.Io.Dir.stat

函数

第 880 行

pub fn stat(dir: Dir, io: Io) StatError!Stat

参数

dir: Dir
io: Io

错误

AccessDenied StatError

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

Canceled Cancelable

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

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

std.Io.Dir.Stat

别名

第 877 行

别名目标 std.Io.File.Stat

std.Io.Dir.StatError

别名

第 878 行

别名目标 std.Io.File.StatError

std.Io.Dir.statFile

函数

第 902 行

返回目录内某个文件的元数据。

Windows 上需要三次系统调用。其他操作系统上 只需一次。

会跟随符号链接。

sub_path 可以是绝对路径,此时忽略 self。

  • Windows 上,sub_path 应编码为 WTF-8。
  • WASI 上,sub_path 应编码为有效 UTF-8。
  • 其他平台上,sub_path 是不规定编码的不透明字节序列。
pub fn statFile(dir: Dir, io: Io, sub_path: []const u8, options: StatFileOptions) StatFileError!Stat

参数

dir: Dir
io: Io
sub_path: []const u8
options: StatFileOptions

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.StatFileError

错误集合

第 884 行

错误

AccessDenied OpenError

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

Canceled Cancelable

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

DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

WouldBlock OpenError

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

std.Io.Dir.StatFileOptions

容器

第 886 行

字段

follow_symlinks: bool = true

std.Io.Dir.std

别名

第 7 行

别名目标 std

std.Io.Dir.symLink

函数

第 1202 行

创建名为 sym_link_path、内容为字符串 target_path 的符号链接。

符号链接也称软链接,既可指向已有文件,也可指向不存在的 文件;后者称为悬空链接。

若 sym_link_path 已存在,不会覆盖。

Windows 上,两条路径均应采用 WTF-8 编码。 WASI 上,两条路径均应采用有效的 UTF-8 编码。 其他平台上,两条路径均为不指定编码的不透明字节序列。

pub fn symLink( dir: Dir, io: Io, target_path: []const u8, sym_link_path: []const u8, flags: SymLinkFlags, ) SymLinkError!void

参数

dir: Dir
io: Io
target_path: []const u8
sym_link_path: []const u8
flags: SymLinkFlags

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

DiskQuota
FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.symLinkAbsolute

函数

第 1212 行

pub fn symLinkAbsolute( io: Io, target_path: []const u8, sym_link_path: []const u8, flags: SymLinkFlags, ) SymLinkError!void

参数

io: Io
target_path: []const u8
sym_link_path: []const u8
flags: SymLinkFlags

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

DiskQuota
FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.symLinkAtomic

函数

第 1229 行

与 symLink 相同,但会持续尝试创建符号链接,直到 成功或遇到 error.PathAlreadyExists 之外的错误。

  • Windows 上,两条路径均应采用 WTF-8 编码。
  • WASI 上,两条路径均应采用有效的 UTF-8 编码。
  • 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn symLinkAtomic( dir: Dir, io: Io, target_path: []const u8, sym_link_path: []const u8, flags: SymLinkFlags, ) !void

参数

dir: Dir
io: Io
target_path: []const u8
sym_link_path: []const u8
flags: SymLinkFlags

std.Io.Dir.SymLinkError

错误集合

第 1174 行

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。

BadPathName PathNameError

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

Canceled Cancelable

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

DiskQuota
FileNotFound
FileSystem
NameTooLong PathNameError

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

NetworkNotFound

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

NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dir.SymLinkFlags

容器

第 1170 行

与 symLink、symLinkAtomic 和 symLinkAbsolute 配合使用, 指定符号链接指向文件还是目录。除 Windows 外,所有宿主 均忽略此值;在 Windows 上,创建指向不同 资源类型的符号链接需要不同标志。默认假定 symLinkAbsolute 指向文件。

字段

is_directory: bool = false

std.Io.Dir.updateFile

函数

第 685 行

检查 source_path 和 dest_path 的文件大小、mtime 和权限。若 均相同,则不执行任何操作。否则将 source_path 原子复制到 dest_path,并按需创建父目录层级。 目标文件继承源文件的 mtime、atime 和权限, 因此下次调用 updateFile 时无需再次复制。

返回更新前文件的状态。

  • Windows 上,两条路径均应采用 WTF-8 编码。
  • WASI 上,两条路径均应采用有效的 UTF-8 编码。
  • 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn updateFile( source_dir: Dir, io: Io, source_path: []const u8, dest_dir: Dir, dest_path: []const u8, options: CopyFileOptions, ) !PrevStatus

参数

source_dir: Dir
io: Io
source_path: []const u8
dest_dir: Dir
dest_path: []const u8

若此路径中的目录不存在,则创建它们。

options: CopyFileOptions

std.Io.Dir.UpdateFileError

别名

第 672 行

别名目标 std.Io.File.OpenError

std.Io.Dir.walk

函数

第 397 行

递归遍历目录。

打开 dir 时必须将 OpenOptions.iterate 设为 true。

Walker.deinit 释放已分配的内存和目录句柄。

返回文件系统条目的顺序未定义。

遍历后不会关闭 dir。

另见:

pub fn walk(dir: Dir, allocator: Allocator) Allocator.Error!Walker

参数

dir: Dir
allocator: Allocator

错误

OutOfMemory

std.Io.Dir.Walker

容器

第 342 行

字段

std.Io.Dir.Walker.deinit

函数

第 373 行

pub fn deinit(self: *Walker) void

参数

self: *Walker

std.Io.Dir.Walker.Entry

容器

第 345 行

字段

dir: Dir

所属目录。可直接操作 basename 而非 path,从而避免深层嵌套路径出现 error.NameTooLong。 目录保持打开,直到调用 next 或 deinit。

basename: [:0]const u8
path: [:0]const u8
kind: File.Kind

std.Io.Dir.Walker.Entry.depth

函数

第 357 行

返回条目相对于初始目录的深度。 初始目录的直接子项返回 1,直接子目录内的条目返回 2, 依此类推。

pub fn depth(self: Walker.Entry) usize

参数

self: Walker.Entry

std.Io.Dir.Walker.leave

函数

第 380 行

离开当前目录,继续在上一级遍历。 若当前条目是目录条目,则“当前目录” 指与当前条目对应的目录。

pub fn leave(self: *Walker, io: Io) void

参数

self: *Walker
io: Io

std.Io.Dir.Walker.next

函数

第 365 行

每次调用此函数后,以及调用 deinit() 时, 此函数先前返回的内存均会失效。若要保留 对路径的引用,必须进行拷贝。

pub fn next(self: *Walker, io: Io) !?Walker.Entry

参数

self: *Walker
io: Io

std.Io.Dir.walkSelectively

函数

第 327 行

递归遍历目录,但要求用户对每个目录条目显式选择是否递归进入。

打开 dir 时,必须将 OpenOptions.iterate 设为 true。

Walker.deinit 释放已分配内存与目录句柄。

返回文件系统条目的顺序未定义。

遍历后不会关闭 dir。

另见 walk。

pub fn walkSelectively(dir: Dir, allocator: Allocator) !SelectiveWalker

参数

dir: Dir
allocator: Allocator

std.Io.Dir.writeFile

函数

第 661 行

使用提供的文件创建标志,将内容写入文件系统。

pub fn writeFile(dir: Dir, io: Io, options: WriteFileOptions) WriteFileError!void

参数

dir: Dir
io: Io
options: WriteFileOptions

错误

AccessDenied Error

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

BrokenPipe Error

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

Canceled Cancelable

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

DeviceBusy Error
DiskQuota Error
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

InputOutput Error
IsDir OpenError

以下任一情况:

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

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice Error

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

NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForWriting Error
PathAlreadyExists OpenError

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

PermissionDenied Error
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources Error

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

Unexpected UnexpectedError

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

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

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

WouldBlock Error

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

std.Io.Dir.WriteFileError

错误集合

第 658 行

错误

AccessDenied Error

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

AntivirusInterference OpenError

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

BadPathName PathNameError

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

BrokenPipe Error

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

Canceled Cancelable

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

DeviceBusy Error
DiskQuota Error
FileBusy OpenError

以下三种情况之一:

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

以下任一情况:

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

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

InputOutput Error
IsDir OpenError

以下任一情况:

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

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

NameTooLong PathNameError

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

NetworkNotFound OpenError

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

NoDevice Error

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

NoSpaceLeft OpenError

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

NotDir OpenError

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

NotOpenForWriting Error
PathAlreadyExists OpenError

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

PermissionDenied Error
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources Error

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

Unexpected UnexpectedError

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

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

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

WouldBlock Error

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

std.Io.Dir.WriteFileOptions

容器

第 649 行

字段

sub_path: []const u8

Windows 上,sub_path 应编码为 WTF-8。 WASI 上,sub_path 应编码为有效 UTF-8。 其他平台上,sub_path 是不规定编码的不透明字节序列。

data: []const u8
flags: CreateFileOptions = .{}
源码

std/Io/Dir.zig

const Dir = @This();
const root = @import("root");

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

const std = @import("../std.zig");
const Io = std.Io;
const File = Io.File;
const assert = std.debug.assert;
const Allocator = std.mem.Allocator;

handle: Handle,

pub const Handle = std.posix.fd_t;

pub const path = std.fs.path;

/// 操作系统接受的文件路径最大长度。
///
/// 路径,包括文件系统操作返回的路径,都可能超过此长度,但这样的路径无法再成功传入其他文件系统操作。不过,假定文件系统操作返回的所有单独路径分量都能放入此长度的 `u8` 数组。
///
/// 字节数包含空终止哨兵字节所需的空间。
///
/// * Windows 上,`[]u8` 文件路径采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * WASI 上,`[]u8` 文件路径采用有效 UTF-8 编码。
/// * 其他平台上,`[]u8` 文件路径是不透明的字节序列,没有特定编码。
///
///
///
///
///
pub const max_path_bytes = switch (native_os) {
    .linux, .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos, .freebsd, .openbsd, .netbsd, .dragonfly, .haiku, .illumos, .plan9, .emscripten, .wasi, .serenity => std.posix.PATH_MAX,
    // 每个 WTF-16LE 码元最多可扩展为 3 个 WTF-8 字节。
    // 若需要 4 个 WTF-8 字节,则 WTF-16LE 中必然有一个代理项
    // 对,因此按 3 个字节计算,且会有冗余计数。
    // 末尾的空字符额外占 1 个字节。
    .windows => std.os.windows.PATH_MAX_WIDE * 3 + 1,
    else => if (@hasDecl(root, "os") and @hasDecl(root.os, "PATH_MAX"))
        root.os.PATH_MAX
    else
        @compileError("PATH_MAX not implemented for " ++ @tagName(native_os)),
};

/// 表示平台常见文件系统支持的 `[]u8` 文件名分量
/// 的最大大小。文件系统操作返回的文件名分量
/// 通常可容纳于此长度的 `u8` 数组中,但
/// 此假设可能不适用于每种配置,具体取决于平台。
/// 字节数不包括空哨兵字节。
/// Windows 上的 `[]u8` 文件名分量编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上的文件名分量编码为有效 UTF-8。
/// 其他平台上的 `[]u8` 分量是不规定编码的不透明字节序列。
pub const max_name_bytes = switch (native_os) {
    .linux, .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos, .freebsd, .openbsd, .netbsd, .dragonfly, .illumos, .serenity, .psp => std.posix.NAME_MAX,
    // Haiku 的 NAME_MAX 包含空终止符,因此减去一。
    .haiku => std.posix.NAME_MAX - 1,
    // 每个 WTF-16LE 字符最多展开为 3 个 WTF-8 字节。
    // 若需要 4 个 WTF-8 字节,则 WTF-16LE 中会存在代理对,
    // 按每个码元 3 字节计数时已将其多计入。
    .windows => std.os.windows.NAME_MAX * 3,
    // 对于 WASI,MAX_NAME 取决于宿主操作系统,因此必须
    // 不小于最大的 max_name_bytes(Windows),才能适用于任意宿主操作系统。
    // TODO: 确定此方法是否合理。
    .wasi => std.os.windows.NAME_MAX * 3,
    else => if (@hasDecl(root, "os") and @hasDecl(root.os, "NAME_MAX"))
        root.os.NAME_MAX
    else
        @compileError("NAME_MAX not implemented for " ++ @tagName(native_os)),
};

pub const Entry = struct {
    name: []const u8,
    kind: File.Kind,
    inode: File.INode,
};

/// 返回当前工作目录的句柄。
///
/// 该句柄不以迭代能力打开,对结果进行迭代属于非法行为。
///
/// 关闭返回的 `Dir` 属于受检查的非法行为。
///
/// 在 POSIX 目标上,此函数可在编译期调用。
///
/// 可通过 `std.Options.cwd` 覆盖此函数。
///
pub fn cwd() Dir {
    const cwdFn = std.Options.cwd orelse return switch (native_os) {
        .windows => .{ .handle = std.os.windows.peb().ProcessParameters.CurrentDirectory.Handle },
        .wasi => .{ .handle = 3 }, // 预期第一个预打开目录是当前工作目录。
        else => .{ .handle = std.posix.AT.FDCWD },
    };
    return cwdFn();
}

pub const Reader = struct {
    dir: Dir,
    state: State,
    /// 存储 I/O 实现专用数据。
    buffer: []align(@alignOf(usize)) u8,
    /// `buffer` 中下一条目的索引。
    index: usize,
    /// 填充 `buffer` 的位置。
    end: usize,

    /// 使所有实现均能正常工作的 `buffer` 长度。
    pub const min_buffer_len = switch (native_os) {
        .linux => std.mem.alignForward(usize, @sizeOf(std.os.linux.dirent64), 8) +
            std.mem.alignForward(usize, max_name_bytes, 8),
        .windows => len: {
            const max_info_len = @sizeOf(std.os.windows.FILE_BOTH_DIR_INFORMATION) + std.os.windows.NAME_MAX * 2;
            const info_align = @alignOf(std.os.windows.FILE_BOTH_DIR_INFORMATION);
            const reserved_len = std.mem.alignForward(usize, max_name_bytes, info_align) - max_info_len;
            break :len std.mem.alignForward(usize, reserved_len, info_align) + max_info_len;
        },
        .wasi => @sizeOf(std.os.wasi.dirent_t) +
            std.mem.alignForward(usize, max_name_bytes, @alignOf(std.os.wasi.dirent_t)),
        .openbsd => std.c.S.BLKSIZE,
        else => if (builtin.link_libc) @sizeOf(std.c.dirent) else std.mem.alignForward(usize, max_name_bytes, @alignOf(usize)),
    };

    pub const State = enum {
        /// 表示下一次调用 `read` 应回退并重新开始目录列表。
        ///
        reset,
        reading,
        finished,
    };

    pub const Error = error{
        AccessDenied,
        PermissionDenied,
        SystemResources,
    } || Io.UnexpectedError || Io.Cancelable;

    /// 断言 `buffer` 长度至少为 `min_buffer_len`。
    pub fn init(dir: Dir, buffer: []align(@alignOf(usize)) u8) Reader {
        assert(buffer.len >= min_buffer_len);
        return .{
            .dir = dir,
            .state = .reset,
            .index = 0,
            .end = 0,
            .buffer = buffer,
        };
    }

    /// 下次调用 `read` 或 `next` 时,
    /// 所有 `Entry.name` 均失效。
    pub fn read(r: *Reader, io: Io, buffer: []Entry) Error!usize {
        return io.vtable.dirRead(io.userdata, r, buffer);
    }

    /// 下次调用 `read` 或 `next` 时,`Entry.name` 失效。
    pub fn next(r: *Reader, io: Io) Error!?Entry {
        var buffer: [1]Entry = undefined;
        while (true) {
            const n = try read(r, io, &buffer);
            if (n == 1) return buffer[0];
            if (r.state == .finished) return null;
        }
    }

    pub fn reset(r: *Reader) void {
        r.state = .reset;
        r.index = 0;
        r.end = 0;
    }
};

/// 此 API 优先考虑便利性,而非性能:
/// * 自行选择缓冲区大小,不允许用户提供。
/// * 每次仅请求一个 `Entry`,来源为 `Io` 实现,
///   而非批量操作,从而使其可移动。
///
/// 不过,它仍会尽量减少系统调用开销。
/// 更底层的抽象参见 `Reader`,更高层的抽象
/// 参见 `Walker`。
pub const Iterator = struct {
    reader: Reader,
    reader_buffer: [reader_buffer_len]u8 align(@alignOf(usize)),

    pub const reader_buffer_len = 2048;

    comptime {
        assert(reader_buffer_len >= Reader.min_buffer_len);
    }

    pub const Error = Reader.Error;

    pub fn init(dir: Dir, reader_state: Reader.State) Iterator {
        return .{
            .reader = .{
                .dir = dir,
                .state = reader_state,
                .index = 0,
                .end = 0,
                .buffer = undefined,
            },
            .reader_buffer = undefined,
        };
    }

    pub fn next(it: *Iterator, io: Io) Error!?Entry {
        it.reader.buffer = &it.reader_buffer;
        return it.reader.next(io);
    }
};

pub fn iterate(dir: Dir) Iterator {
    return .init(dir, .reset);
}

/// 类似 `iterate`,但不会在首次迭代前重置目录游标。
/// 仅应在已知 `Dir` 的游标尚未被修改时使用,
/// 例如该目录刚刚打开。
pub fn iterateAssumeFirstIteration(dir: Dir) Iterator {
    return .init(dir, .reading);
}

pub const SelectiveWalker = struct {
    stack: std.ArrayList(StackItem),
    name_buffer: std.ArrayList(u8),
    allocator: Allocator,

    pub const Error = Iterator.Error || Allocator.Error;

    const StackItem = struct {
        iter: Iterator,
        dirname_len: usize,
    };

    /// 每次调用此函数后,以及调用 deinit() 时,
    /// 此函数先前返回的内存均会失效。若要保留
    /// 对路径的引用,必须进行拷贝。
    pub fn next(self: *SelectiveWalker, io: Io) Error!?Walker.Entry {
        while (self.stack.items.len > 0) {
            const top = &self.stack.items[self.stack.items.len - 1];
            var dirname_len = top.dirname_len;
            if (top.iter.next(io) catch |err| {
                // 如果发生错误,我们希望用户仍可选择继续
                // 遍历,因此必须从栈中弹出发生错误的目录。
                // 否则,后续所有 `next` 调用
                // 很可能都会因相同错误而失败。
                var item = self.stack.pop().?;
                if (self.stack.items.len != 0) {
                    item.iter.reader.dir.close(io);
                }
                return err;
            }) |entry| {
                self.name_buffer.shrinkRetainingCapacity(dirname_len);
                if (self.name_buffer.items.len != 0) {
                    try self.name_buffer.append(self.allocator, path.sep);
                    dirname_len += 1;
                }
                try self.name_buffer.ensureUnusedCapacity(self.allocator, entry.name.len + 1);
                self.name_buffer.appendSliceAssumeCapacity(entry.name);
                self.name_buffer.appendAssumeCapacity(0);
                const walker_entry: Walker.Entry = .{
                    .dir = top.iter.reader.dir,
                    .basename = self.name_buffer.items[dirname_len .. self.name_buffer.items.len - 1 :0],
                    .path = self.name_buffer.items[0 .. self.name_buffer.items.len - 1 :0],
                    .kind = entry.kind,
                };
                return walker_entry;
            } else {
                var item = self.stack.pop().?;
                if (self.stack.items.len != 0) {
                    item.iter.reader.dir.close(io);
                }
            }
        }
        return null;
    }

    /// 进入目录,继续向下一层遍历。
    pub fn enter(self: *SelectiveWalker, io: Io, entry: Walker.Entry) !void {
        if (entry.kind != .directory) {
            @branchHint(.cold);
            return;
        }

        var new_dir = entry.dir.openDir(io, entry.basename, .{ .iterate = true }) catch |err| {
            switch (err) {
                error.NameTooLong => unreachable,
                else => |e| return e,
            }
        };
        errdefer new_dir.close(io);

        try self.stack.append(self.allocator, .{
            .iter = new_dir.iterateAssumeFirstIteration(),
            .dirname_len = self.name_buffer.items.len - 1,
        });
    }

    pub fn deinit(self: *SelectiveWalker) void {
        self.name_buffer.deinit(self.allocator);
        self.stack.deinit(self.allocator);
    }

    /// 离开当前目录,继续向上一级遍历。
    /// 若当前条目是目录条目,并在 `leave` 之前调用了
    /// `enter`,则“当前目录”指向该条目。
    pub fn leave(self: *SelectiveWalker, io: Io) void {
        var item = self.stack.pop().?;
        if (self.stack.items.len != 0) {
            @branchHint(.likely);
            item.iter.reader.dir.close(io);
        }
    }
};

/// 递归遍历目录,但要求用户对每个目录条目显式选择是否递归进入。
///
/// 打开 `dir` 时,必须将 `OpenOptions.iterate` 设为 `true`。
///
/// `Walker.deinit` 释放已分配内存与目录句柄。
///
/// 返回文件系统条目的顺序未定义。
///
/// 遍历后不会关闭 `dir`。
///
/// 另见 `walk`。
///
pub fn walkSelectively(dir: Dir, allocator: Allocator) !SelectiveWalker {
    var stack: std.ArrayList(SelectiveWalker.StackItem) = .empty;

    try stack.append(allocator, .{
        .iter = dir.iterate(),
        .dirname_len = 0,
    });

    return .{
        .stack = stack,
        .name_buffer = .empty,
        .allocator = allocator,
    };
}

pub const Walker = struct {
    inner: SelectiveWalker,

    pub const Entry = struct {
        /// 所属目录。可直接操作 `basename`
        /// 而非 `path`,从而避免深层嵌套路径出现 `error.NameTooLong`。
        /// 目录保持打开,直到调用 `next` 或 `deinit`。
        dir: Dir,
        basename: [:0]const u8,
        path: [:0]const u8,
        kind: File.Kind,

        /// 返回条目相对于初始目录的深度。
        /// 初始目录的直接子项返回 1,直接子目录内的条目返回 2,
        /// 依此类推。
        pub fn depth(self: Walker.Entry) usize {
            return std.mem.countScalar(u8, self.path, path.sep) + 1;
        }
    };

    /// 每次调用此函数后,以及调用 deinit() 时,
    /// 此函数先前返回的内存均会失效。若要保留
    /// 对路径的引用,必须进行拷贝。
    pub fn next(self: *Walker, io: Io) !?Walker.Entry {
        const entry = try self.inner.next(io);
        if (entry != null and entry.?.kind == .directory) {
            try self.inner.enter(io, entry.?);
        }
        return entry;
    }

    pub fn deinit(self: *Walker) void {
        self.inner.deinit();
    }

    /// 离开当前目录,继续在上一级遍历。
    /// 若当前条目是目录条目,则“当前目录”
    /// 指与当前条目对应的目录。
    pub fn leave(self: *Walker, io: Io) void {
        self.inner.leave(io);
    }
};

/// 递归遍历目录。
///
/// 打开 `dir` 时必须将 `OpenOptions.iterate` 设为 `true`。
///
/// `Walker.deinit` 释放已分配的内存和目录句柄。
///
/// 返回文件系统条目的顺序未定义。
///
/// 遍历后不会关闭 `dir`。
///
/// 另见:
/// * `walkSelectively`
pub fn walk(dir: Dir, allocator: Allocator) Allocator.Error!Walker {
    return .{ .inner = try walkSelectively(dir, allocator) };
}

pub const PathNameError = error{
    /// 提供的缓冲区过小,
    /// 无法容纳路径名时返回。
    NameTooLong,
    /// 文件系统无法编码请求的文件名字节。
    /// 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、
    /// Windows 上的无效字符等,具体取决于文件系统与操作系统。
    BadPathName,
};

pub const AccessError = error{
    /// 文件不允许请求的 `AccessOptions`,或路径前缀中的
    /// 某个目录不允许搜索。
    AccessDenied,
    /// 请求了写入权限,但文件不可变。
    PermissionDenied,
    FileNotFound,
    InputOutput,
    SystemResources,
    FileBusy,
    SymLinkLoop,
    ReadOnlyFileSystem,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

pub const AccessOptions = packed struct {
    follow_symlinks: bool = true,
    read: bool = false,
    write: bool = false,
    execute: bool = false,
};

/// 测试对 `sub_path` 的访问。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
///
/// 使用此函数时,请注意检查时间与使用时间之间的竞态。
/// 例如,不要先检查文件是否存在再打开它,
/// 而应直接打开并处理文件不存在的错误。
pub fn access(dir: Dir, io: Io, sub_path: []const u8, options: AccessOptions) AccessError!void {
    return io.vtable.dirAccess(io.userdata, dir, sub_path, options);
}

pub fn accessAbsolute(io: Io, absolute_path: []const u8, options: AccessOptions) AccessError!void {
    assert(path.isAbsolute(absolute_path));
    return access(.cwd(), io, absolute_path, options);
}

pub const OpenError = error{
    FileNotFound,
    NotDir,
    AccessDenied,
    PermissionDenied,
    SymLinkLoop,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    NoDevice,
    SystemResources,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

pub const OpenOptions = struct {
    /// `true` 表示打开的目录可用作基于已打开目录句柄
    /// 进行操作的函数的 `Dir` 参数。若为 `false`,
    /// 则此类操作属于非法行为。
    access_sub_paths: bool = true,
    /// `true` 表示可扫描打开的目录,获取其文件和子目录
    /// 作为结果,即可以调用 `iterate` 函数。
    iterate: bool = false,
    /// `false` 表示不解引用符号链接。
    follow_symlinks: bool = true,
};

/// 打开给定路径的目录。目录是系统资源,
/// 会保持打开,直到对返回结果调用 `close`。
///
/// 只有将 `iterate` 选项设为 `true`,才能迭代该目录。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
pub fn openDir(dir: Dir, io: Io, sub_path: []const u8, options: OpenOptions) OpenError!Dir {
    return io.vtable.dirOpenDir(io.userdata, dir, sub_path, options);
}

pub fn openDirAbsolute(io: Io, absolute_path: []const u8, options: OpenOptions) OpenError!Dir {
    assert(path.isAbsolute(absolute_path));
    return openDir(.cwd(), io, absolute_path, options);
}

pub fn close(dir: Dir, io: Io) void {
    return io.vtable.dirClose(io.userdata, (&dir)[0..1]);
}

pub fn closeMany(io: Io, dirs: []const Dir) void {
    return io.vtable.dirClose(io.userdata, dirs);
}

pub const OpenFileOptions = struct {
    mode: Mode = .read_only,
    /// 决定打开指向目录的路径时的行为。
    ///
    /// 若设为 true,可以打开目录,但某些情况下仍可能返回 `error.IsDir`,例如尝试以写权限打开目录。
    ///
    /// 若设为 false,打开目录时始终返回 `error.IsDir`。
    ///
    /// 设为 false 时:
    /// * Windows 上无需额外系统调用。
    /// * 其他操作系统上需要额外执行一次 `fstat` 系统调用。
    ///
    ///
    ///
    allow_directory: bool = true,
    /// 表示此已打开文件仅打算用于部分操作:
    /// * `close`
    /// * `stat`
    /// 在 Linux 和 FreeBSD 上,对应 `std.posix.O.PATH`。
    ///
    path_only: bool = false,
    /// 打开文件并获取建议锁,以协调其他同时访问
    /// 该文件的进程。独占锁会阻止其他
    /// 进程获取锁。共享锁会阻止其他
    /// 进程获取独占锁,但不会阻止
    /// 其他进程获取各自的共享锁。
    ///
    /// 除 Linux 上极少数特定情况外,此锁均为建议锁[1]。
    /// 也就是说,不遵守锁 API 的进程即使面对已加锁文件,
    /// 仍然可以访问文件。
    ///
    /// 以下操作系统在打开文件的同时
    /// 原子地获取锁:
    /// * Darwin
    /// * DragonFlyBSD
    /// * FreeBSD
    /// * Haiku
    /// * NetBSD
    /// * OpenBSD
    /// 以下操作系统在打开文件后,
    /// 通过单独的系统调用获取锁:
    /// * Linux
    /// * Windows
    ///
    /// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
    lock: File.Lock = .none,
    /// 设置返回前是否等待文件加锁。若为 true,
    /// 则返回 `error.WouldBlock`;否则等待,直至文件
    /// 可供继续操作(原文条件如此)。
    lock_nonblocking: bool = false,
    /// 设置此项,以允许打开的文件自动成为
    /// 当前进程的控制 TTY。
    allow_ctty: bool = false,
    follow_symlinks: bool = true,
    /// 如果操作系统支持,尝试解析会越出此目录的路径时,
    /// 将改为返回 `error.AccessDenied`。
    /// 若不支持,则忽略此选项。
    resolve_beneath: bool = false,

    pub const Mode = enum { read_only, write_only, read_write };

    pub fn isRead(self: OpenFileOptions) bool {
        return self.mode != .write_only;
    }

    pub fn isWrite(self: OpenFileOptions) bool {
        return self.mode != .read_only;
    }
};

/// 打开文件以读取或写入,不尝试创建新文件。
///
/// 创建新文件,参见 `createFile`。
///
/// 会分配资源,需通过 `File.close` 释放。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn openFile(dir: Dir, io: Io, sub_path: []const u8, options: OpenFileOptions) File.OpenError!File {
    return io.vtable.dirOpenFile(io.userdata, dir, sub_path, options);
}

pub fn openFileAbsolute(io: Io, absolute_path: []const u8, options: OpenFileOptions) File.OpenError!File {
    assert(path.isAbsolute(absolute_path));
    return openFile(.cwd(), io, absolute_path, options);
}

pub const CreateFileOptions = struct {
    /// 是否创建具有读取访问权限的文件。
    read: bool = false,
    /// 若文件已存在且是普通文件,并且访问
    /// 模式允许写入,则将其截断为长度 0。
    truncate: bool = true,
    /// 确保此次打开操作创建文件,否则
    /// 返回 `error.PathAlreadyExists`。
    exclusive: bool = false,
    /// 打开文件并获取建议锁,以协调其他同时访问
    /// 该文件的进程。独占锁会阻止其他
    /// 进程获取锁。共享锁会阻止其他
    /// 进程获取独占锁,但不会阻止
    /// 其他进程获取各自的共享锁。
    ///
    /// 除 Linux 上极少数特定情况外,此锁均为建议锁[1]。
    /// 也就是说,不遵守锁 API 的进程即使面对已加锁文件,
    /// 仍然可以访问文件。
    ///
    /// 以下操作系统在打开文件的同时
    /// 原子地获取锁:
    /// * Darwin
    /// * DragonFlyBSD
    /// * FreeBSD
    /// * Haiku
    /// * NetBSD
    /// * OpenBSD
    /// 以下操作系统在打开文件后,
    /// 通过单独的系统调用获取锁:
    /// * Linux
    /// * Windows
    ///
    /// [1]: https://www.kernel.org/doc/Documentation/filesystems/mandatory-locking.txt
    lock: File.Lock = .none,
    /// 设置返回前是否等待文件加锁。若为 true,
    /// 则返回 `error.WouldBlock`;否则等待,直至文件
    /// 可供继续操作(原文条件如此)。
    lock_nonblocking: bool = false,
    permissions: Permissions = .default_file,
    /// 如果操作系统支持,尝试解析会越出此目录的路径时,
    /// 将改为返回 `error.AccessDenied`。
    /// 若不支持,则忽略此选项。
    resolve_beneath: bool = false,
};

/// 以写入权限创建、打开或覆盖文件。
///
/// 会分配资源,需通过 `File.close` 释放。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn createFile(dir: Dir, io: Io, sub_path: []const u8, flags: CreateFileOptions) File.OpenError!File {
    return io.vtable.dirCreateFile(io.userdata, dir, sub_path, flags);
}

pub fn createFileAbsolute(io: Io, absolute_path: []const u8, flags: CreateFileOptions) File.OpenError!File {
    return createFile(.cwd(), io, absolute_path, flags);
}

pub const WriteFileOptions = struct {
    /// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
    /// WASI 上,`sub_path` 应编码为有效 UTF-8。
    /// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
    sub_path: []const u8,
    data: []const u8,
    flags: CreateFileOptions = .{},
};

pub const WriteFileError = File.Writer.Error || File.OpenError;

/// 使用提供的文件创建标志,将内容写入文件系统。
pub fn writeFile(dir: Dir, io: Io, options: WriteFileOptions) WriteFileError!void {
    var file = try dir.createFile(io, options.sub_path, options.flags);
    defer file.close(io);
    try file.writeStreamingAll(io, options.data);
}

pub const PrevStatus = enum {
    stale,
    fresh,
};

pub const UpdateFileError = File.OpenError;

/// 检查 `source_path` 和 `dest_path` 的文件大小、mtime 和权限。若
/// 均相同,则不执行任何操作。否则将 `source_path` 原子复制到
/// `dest_path`,并按需创建父目录层级。
/// 目标文件继承源文件的 mtime、atime 和权限,
/// 因此下次调用 `updateFile` 时无需再次复制。
///
/// 返回更新前文件的状态。
///
/// * Windows 上,两条路径均应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * WASI 上,两条路径均应采用有效的 UTF-8 编码。
/// * 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn updateFile(
    source_dir: Dir,
    io: Io,
    source_path: []const u8,
    dest_dir: Dir,
    /// 若此路径中的目录不存在,则创建它们。
    dest_path: []const u8,
    options: CopyFileOptions,
) !PrevStatus {
    var src_file = try source_dir.openFile(io, source_path, .{});
    defer src_file.close(io);

    const src_stat = try src_file.stat(io);
    const actual_permissions = options.permissions orelse src_stat.permissions;
    check_dest_stat: {
        const dest_stat = blk: {
            var dest_file = dest_dir.openFile(io, dest_path, .{}) catch |err| switch (err) {
                error.FileNotFound => break :check_dest_stat,
                else => |e| return e,
            };
            defer dest_file.close(io);

            break :blk try dest_file.stat(io);
        };

        if (src_stat.size == dest_stat.size and
            src_stat.mtime.nanoseconds == dest_stat.mtime.nanoseconds and
            actual_permissions == dest_stat.permissions)
        {
            return .fresh;
        }
    }

    var atomic_file = try dest_dir.createFileAtomic(io, dest_path, .{
        .permissions = actual_permissions,
        .make_path = true,
        .replace = true,
    });
    defer atomic_file.deinit(io);

    var buffer: [1024]u8 = undefined; // 仅当无法直接在 fd 之间传输时使用。
    var file_writer = atomic_file.file.writer(io, &buffer);

    var src_reader: File.Reader = .initSize(src_file, io, &.{}, src_stat.size);
    const dest_writer = &file_writer.interface;

    _ = dest_writer.sendFileAll(&src_reader, .unlimited) catch |err| switch (err) {
        error.ReadFailed => return src_reader.err.?,
        error.WriteFailed => return file_writer.err.?,
    };
    try file_writer.flush();
    try file_writer.file.setTimestamps(io, .{
        .access_timestamp = .init(src_stat.atime),
        .modify_timestamp = .init(src_stat.mtime),
    });
    try atomic_file.replace(io);
    return .stale;
}

pub const ReadFileError = File.OpenError || File.Reader.Error;

/// 使用预先分配的缓冲区读取全部文件内容。
///
/// 返回切片与 `buffer` 具有相同指针。若长度等于 `buffer.len`,
/// 则情况存在歧义:既可能表示已读取整个文件,且
/// 恰好填满缓冲区;也可能表示缓冲区不足以容纳
/// 整个文件。
///
/// * Windows 上,`file_path` 应采用 [WTF-8](https://simonsapin.github.io/wtf-8/) 编码。
/// * WASI 上,`file_path` 应采用有效的 UTF-8 编码。
/// * 其他平台上,`file_path` 是不指定编码的不透明字节序列。
pub fn readFile(dir: Dir, io: Io, file_path: []const u8, buffer: []u8) ReadFileError![]u8 {
    var file = try dir.openFile(io, file_path, .{
        // 在 Windows 上可以利用这一点,因为不会增加系统调用,
        // 从而在打开时而非读取时获得 error.IsDir。
        .allow_directory = if (native_os == .windows) false else true,
    });
    defer file.close(io);

    var reader = file.reader(io, &.{});
    const n = reader.interface.readSliceShort(buffer) catch |err| switch (err) {
        error.ReadFailed => return reader.err.?,
    };

    return buffer[0..n];
}

pub const CreateDirError = error{
    /// 在 WASI 中,当文件描述符不具备相对于自身
    /// 创建新目录所需的权限时,可能发生此错误。
    AccessDenied,
    PermissionDenied,
    DiskQuota,
    PathAlreadyExists,
    SymLinkLoop,
    LinkQuotaExceeded,
    FileNotFound,
    SystemResources,
    NoSpaceLeft,
    NotDir,
    ReadOnlyFileSystem,
    NoDevice,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 使用相对或绝对路径创建单个目录。
///
/// * Windows 上,`sub_path` 应采用 [WTF-8](https://simonsapin.github.io/wtf-8/) 编码。
/// * WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// * 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
///
/// 相关函数:
/// * `createDirPath`
/// * `createDirAbsolute`
pub fn createDir(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirError!void {
    return io.vtable.dirCreateDir(io.userdata, dir, sub_path, permissions);
}

/// 根据绝对路径创建新目录。
///
/// 断言路径为绝对路径。若需要同时处理
/// 绝对和相对路径,参见 `createDir`。
///
/// Windows 上,`absolute_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`absolute_path` 应编码为有效 UTF-8。
/// 其他平台上,`absolute_path` 是不规定编码的不透明字节序列。
pub fn createDirAbsolute(io: Io, absolute_path: []const u8, permissions: Permissions) CreateDirError!void {
    assert(path.isAbsolute(absolute_path));
    return createDir(.cwd(), io, absolute_path, permissions);
}

test createDirAbsolute {}

pub const CreateDirPathError = CreateDirError || StatFileError;

/// 按需使用默认权限创建父目录,确保
/// `sub_path` 作为目录存在。
///
/// 若路径已存在且是目录,则成功返回。
///
/// 此函数不一定是原子操作。若返回错误,文件系统
/// 可能已被修改。
///
/// 路径为空时返回 `error.BadPathName`,因为空路径
/// 无法创建。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://simonsapin.github.io/wtf-8/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
///
/// 包含 `..` 分量的路径按平台采用不同的处理方式:
/// - Windows 上,在将路径传给 NtCreateFile 之前解析 `..`,因此
///   对于类似 "first/../second" 的 `sub_path`,会先解析为 "second",只创建
///   `./second` 目录。
/// - 其他平台上,`..` 在将路径传给 `mkdirat` 之前不会解析,
///   因此类似 "first/../second" 的 `sub_path` 会同时创建 `./first`
///   和 `./second` 目录。
///
/// 另请参见:
/// * `createDirPathStatus`
pub fn createDirPath(dir: Dir, io: Io, sub_path: []const u8) CreateDirPathError!void {
    _ = try io.vtable.dirCreateDirPath(io.userdata, dir, sub_path, .default_dir);
}

pub const CreatePathStatus = enum { existed, created };

/// 与 `createDirPath` 相同,但返回路径原本已存在,还是
/// 已成功创建。
pub fn createDirPathStatus(dir: Dir, io: Io, sub_path: []const u8, permissions: Permissions) CreateDirPathError!CreatePathStatus {
    return io.vtable.dirCreateDirPath(io.userdata, dir, sub_path, permissions);
}

pub const CreateDirPathOpenError = CreateDirError || OpenError || StatFileError;

pub const CreateDirPathOpenOptions = struct {
    open_options: OpenOptions = .{},
    permissions: Permissions = .default_dir,
};

/// 执行等同于先调用 `createDirPath`、再调用 `openDir` 的操作,尽可能原子执行。
///
/// 取消此操作时,文件系统可能处于部分修改状态。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效 UTF-8 编码。
/// 其他平台上,`sub_path` 是不透明的字节序列,没有特定编码。
///
pub fn createDirPathOpen(dir: Dir, io: Io, sub_path: []const u8, options: CreateDirPathOpenOptions) CreateDirPathOpenError!Dir {
    return io.vtable.dirCreateDirPathOpen(io.userdata, dir, sub_path, options.permissions, options.open_options);
}

pub const Stat = File.Stat;
pub const StatError = File.StatError;

pub fn stat(dir: Dir, io: Io) StatError!Stat {
    return io.vtable.dirStat(io.userdata, dir);
}

pub const StatFileError = File.OpenError || File.StatError;

pub const StatFileOptions = struct {
    follow_symlinks: bool = true,
};

/// 返回目录内某个文件的元数据。
///
/// Windows 上需要三次系统调用。其他操作系统上
/// 只需一次。
///
/// 会跟随符号链接。
///
/// `sub_path` 可以是绝对路径,此时忽略 `self`。
///
/// * Windows 上,`sub_path` 应编码为 [WTF-8](https://simonsapin.github.io/wtf-8/)。
/// * WASI 上,`sub_path` 应编码为有效 UTF-8。
/// * 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn statFile(dir: Dir, io: Io, sub_path: []const u8, options: StatFileOptions) StatFileError!Stat {
    return io.vtable.dirStatFile(io.userdata, dir, sub_path, options);
}

pub const RealPathError = File.RealPathError;

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

pub const RealPathFileError = RealPathError || PathNameError;

/// 取得 `sub_path` 相对于此 `Dir` 的规范化绝对路径名。
/// 如果 `sub_path` 为绝对路径,则忽略此 `Dir` 句柄,
/// 取得 `sub_path` 参数的规范化绝对路径名。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFileAlloc`。
/// * `realPathFileAbsolute`。
pub fn realPathFile(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPathFileError!usize {
    return io.vtable.dirRealPathFile(io.userdata, dir, sub_path, out_buffer);
}

pub const RealPathFileAllocError = RealPathFileError || Allocator.Error;

/// 与 `realPathFile` 相同,但会分配结果。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFile`。
/// * `realPathFileAbsolute`。
pub fn realPathFileAlloc(dir: Dir, io: Io, sub_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8 {
    var buffer: [max_path_bytes]u8 = undefined;
    const n = try realPathFile(dir, io, sub_path, &buffer);
    return allocator.dupeSentinel(u8, buffer[0..n], 0);
}

/// 与 `realPathFile` 相同,但断言 `absolute_path` 为绝对
/// 路径。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFile`。
/// * `realPathFileAlloc`。
pub fn realPathFileAbsolute(io: Io, absolute_path: []const u8, out_buffer: []u8) RealPathFileError!usize {
    assert(path.isAbsolute(absolute_path));
    return io.vtable.dirRealPathFile(io.userdata, .cwd(), absolute_path, out_buffer);
}

/// 与 `realPathFileAbsolute` 相同,但会分配结果。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态。通常建议
/// 完全避免使用此函数。
///
/// 另请参见:
/// * `realPathFileAbsolute`。
/// * `realPathFile`。
pub fn realPathFileAbsoluteAlloc(io: Io, absolute_path: []const u8, allocator: Allocator) RealPathFileAllocError![:0]u8 {
    var buffer: [max_path_bytes]u8 = undefined;
    const n = try realPathFileAbsolute(io, absolute_path, &buffer);
    return allocator.dupeSentinel(u8, buffer[0..n], 0);
}

pub const DeleteFileError = error{
    FileNotFound,
    /// 在 WASI 中,若文件描述符不具有通过相对于它的路径
    /// 解除资源链接所需的权限,可能发生此错误。
    AccessDenied,
    PermissionDenied,
    FileBusy,
    FileSystem,
    IsDir,
    SymLinkLoop,
    NotDir,
    SystemResources,
    ReadOnlyFileSystem,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 根据已打开的目录句柄删除文件名,并可能删除其引用的文件。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
///
/// 断言路径参数不含空字节。
pub fn deleteFile(dir: Dir, io: Io, sub_path: []const u8) DeleteFileError!void {
    return io.vtable.dirDeleteFile(io.userdata, dir, sub_path);
}

pub fn deleteFileAbsolute(io: Io, absolute_path: []const u8) DeleteFileError!void {
    assert(path.isAbsolute(absolute_path));
    return deleteFile(.cwd(), io, absolute_path);
}

test deleteFileAbsolute {}

pub const DeleteDirError = error{
    DirNotEmpty,
    FileNotFound,
    AccessDenied,
    PermissionDenied,
    FileBusy,
    FileSystem,
    SymLinkLoop,
    NotDir,
    SystemResources,
    ReadOnlyFileSystem,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 如果目录非空,则返回 `error.DirNotEmpty`。
///
/// 递归删除目录,参见 `deleteTree`。
///
/// Windows 上,`sub_path` 应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// WASI 上,`sub_path` 应编码为有效 UTF-8。
/// 其他平台上,`sub_path` 是不规定编码的不透明字节序列。
pub fn deleteDir(dir: Dir, io: Io, sub_path: []const u8) DeleteDirError!void {
    return io.vtable.dirDeleteDir(io.userdata, dir, sub_path);
}

/// 与 `deleteDir` 相同,但路径为绝对路径。
///
/// Windows 上,`dir_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`dir_path` 应采用有效 UTF-8 编码。
/// 其他平台上,`dir_path` 是不透明的字节序列,没有特定编码。
pub fn deleteDirAbsolute(io: Io, absolute_path: []const u8) DeleteDirError!void {
    assert(path.isAbsolute(absolute_path));
    return deleteDir(.cwd(), io, absolute_path);
}

pub const RenameError = error{
    /// 在 WASI 中,当文件描述符不具备相对于自身
    /// 按路径重命名资源所需的权限时,可能发生此错误。
    AccessDenied,
    /// 试图替换非空目录。
    DirNotEmpty,
    PermissionDenied,
    /// 尝试移动或替换的文件是正在运行的可执行文件。
    FileBusy,
    DiskQuota,
    IsDir,
    SymLinkLoop,
    LinkQuotaExceeded,
    FileNotFound,
    NotDir,
    SystemResources,
    NoSpaceLeft,
    ReadOnlyFileSystem,
    CrossDevice,
    NoDevice,
    PipeBusy,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
    /// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
    /// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
    ///
    ///
    ///
    AntivirusInterference,
    HardwareFailure,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 更改文件或目录的名称或位置。
///
/// 如果 `new_sub_path` 已存在,则将其替换。
///
/// 将文件重命名以覆盖已有目录,或将目录重命名以覆盖已有
/// 文件,都会失败并返回 `error.IsDir` 或 `error.NotDir`。
///
/// * Windows 上,两个路径均应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
/// * WASI 上,两个路径均应编码为有效 UTF-8。
/// * 其他平台上,两个路径均是不规定编码的不透明字节序列。
pub fn rename(
    old_dir: Dir,
    old_sub_path: []const u8,
    new_dir: Dir,
    new_sub_path: []const u8,
    io: Io,
) RenameError!void {
    return io.vtable.dirRename(io.userdata, old_dir, old_sub_path, new_dir, new_sub_path);
}

pub fn renameAbsolute(old_path: []const u8, new_path: []const u8, io: Io) RenameError!void {
    assert(path.isAbsolute(old_path));
    assert(path.isAbsolute(new_path));
    const my_cwd = cwd();
    return io.vtable.dirRename(io.userdata, my_cwd, old_path, my_cwd, new_path);
}

pub const RenamePreserveError = error{
    /// 在 WASI 中,当文件描述符不具有
    /// 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。
    ///
    /// 在 Windows 上,将目录重命名并覆盖已有目录时,
    /// 可能返回此错误,而不是 PathAlreadyExists。
    ///
    /// 在 Darwin 上,如果任一路径中的分量指向需要实体化的
    /// “无数据”目录,而当前线程或进程的 I/O
    /// 策略不允许无数据目录实体化,则可能返回此错误。
    AccessDenied,
    PathAlreadyExists,
    /// 操作系统或文件系统不支持原子地执行不替换目标的重命名。
    OperationUnsupported,
} || RenameError;

/// 更改文件或目录的名称或位置。
///
/// 如果 `new_sub_path` 已存在,将返回 `error.PathAlreadyExists`。
///
/// 若操作系统支持,整个操作将以原子方式完成。否则,将回退为先创建硬链接再取消链接;这对 `new_sub_path` 是原子的,但存在清理 old_sub_path 可能失败的时间窗口。虽然该操作具有较好的可移植性,但严格来说,在某些环境下该回退方案也可能不受支持,此时返回 `error.OperationUnsupported`。
///
/// * 在 Windows 上,两个路径都应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * 在 WASI 上,两个路径都应采用有效的 UTF-8 编码。
/// * 在其他平台上,两个路径都是不限定编码的不透明字节序列。
///
///
///
///
pub fn renamePreserve(
    old_dir: Dir,
    old_sub_path: []const u8,
    new_dir: Dir,
    new_sub_path: []const u8,
    io: Io,
) RenamePreserveError!void {
    return io.vtable.dirRenamePreserve(io.userdata, old_dir, old_sub_path, new_dir, new_sub_path);
}

pub const HardLinkOptions = File.HardLinkOptions;

pub const HardLinkError = File.HardLinkError;

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

/// 与 `symLink`、`symLinkAtomic` 和 `symLinkAbsolute` 配合使用,
/// 指定符号链接指向文件还是目录。除 Windows 外,所有宿主
/// 均忽略此值;在 Windows 上,创建指向不同
/// 资源类型的符号链接需要不同标志。默认假定 `symLinkAbsolute`
/// 指向文件。
pub const SymLinkFlags = struct {
    is_directory: bool = false,
};

pub const SymLinkError = error{
    /// 在 WASI 中,当文件描述符不具备相对于自身
    /// 创建新符号链接所需的权限时,可能发生此错误。
    AccessDenied,
    PermissionDenied,
    DiskQuota,
    PathAlreadyExists,
    FileSystem,
    SymLinkLoop,
    FileNotFound,
    SystemResources,
    NoSpaceLeft,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
    ReadOnlyFileSystem,
    NotDir,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 创建名为 `sym_link_path`、内容为字符串 `target_path` 的符号链接。
///
/// 符号链接也称软链接,既可指向已有文件,也可指向不存在的
/// 文件;后者称为悬空链接。
///
/// 若 `sym_link_path` 已存在,不会覆盖。
///
/// Windows 上,两条路径均应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,两条路径均应采用有效的 UTF-8 编码。
/// 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn symLink(
    dir: Dir,
    io: Io,
    target_path: []const u8,
    sym_link_path: []const u8,
    flags: SymLinkFlags,
) SymLinkError!void {
    return io.vtable.dirSymLink(io.userdata, dir, target_path, sym_link_path, flags);
}

pub fn symLinkAbsolute(
    io: Io,
    target_path: []const u8,
    sym_link_path: []const u8,
    flags: SymLinkFlags,
) SymLinkError!void {
    assert(path.isAbsolute(target_path));
    assert(path.isAbsolute(sym_link_path));
    return symLink(.cwd(), io, target_path, sym_link_path, flags);
}

/// 与 `symLink` 相同,但会持续尝试创建符号链接,直到
/// 成功或遇到 `error.PathAlreadyExists` 之外的错误。
///
/// * Windows 上,两条路径均应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * WASI 上,两条路径均应采用有效的 UTF-8 编码。
/// * 其他平台上,两条路径均为不指定编码的不透明字节序列。
pub fn symLinkAtomic(
    dir: Dir,
    io: Io,
    target_path: []const u8,
    sym_link_path: []const u8,
    flags: SymLinkFlags,
) !void {
    if (dir.symLink(io, target_path, sym_link_path, flags)) {
        return;
    } else |err| switch (err) {
        error.PathAlreadyExists => {},
        else => |e| return e,
    }

    const dirname = path.dirname(sym_link_path) orelse ".";

    const rand_len = @sizeOf(u64) * 2;
    const temp_path_len = dirname.len + 1 + rand_len;
    var temp_path_buf: [max_path_bytes]u8 = undefined;

    if (temp_path_len > temp_path_buf.len) return error.NameTooLong;
    @memcpy(temp_path_buf[0..dirname.len], dirname);
    temp_path_buf[dirname.len] = path.sep;

    const temp_path = temp_path_buf[0..temp_path_len];

    var random_integer: u64 = undefined;

    while (true) {
        io.random(@ptrCast(&random_integer));
        temp_path[dirname.len + 1 ..][0..rand_len].* = std.fmt.hex(random_integer);

        if (dir.symLink(io, target_path, temp_path, flags)) {
            return dir.rename(temp_path, dir, sym_link_path, io);
        } else |err| switch (err) {
            error.PathAlreadyExists => continue,
            else => |e| return e,
        }
    }
}

pub const ReadLinkError = error{
    /// 在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。
    ///
    AccessDenied,
    PermissionDenied,
    FileSystem,
    SymLinkLoop,
    FileNotFound,
    SystemResources,
    NotLink,
    NotDir,
    /// 仅限 Windows。如果打开的重解析点类型不受支持,
    /// 可能发生此错误。
    UnsupportedReparsePointType,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
    /// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
    /// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
    ///
    ///
    ///
    AntivirusInterference,
    /// 尝试打开的文件是正在运行的可执行文件。
    FileBusy,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 获取符号链接的目标。
///
/// 返回 `buffer` 中已填充的字节数。
///
/// 断言路径参数不含空字节。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效 UTF-8 编码。
/// 其他平台上,`sub_path` 是不透明的字节序列,没有特定编码。
pub fn readLink(dir: Dir, io: Io, sub_path: []const u8, buffer: []u8) ReadLinkError!usize {
    return io.vtable.dirReadLink(io.userdata, dir, sub_path, buffer);
}

/// 与 `readLink` 相同,但断言路径为绝对路径。
///
/// Windows 上,`path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`path` 是不指定编码的不透明字节序列。
pub fn readLinkAbsolute(io: Io, absolute_path: []const u8, buffer: []u8) ReadLinkError!usize {
    assert(path.isAbsolute(absolute_path));
    return io.vtable.dirReadLink(io.userdata, .cwd(), absolute_path, buffer);
}

pub const ReadFileAllocError = File.OpenError || File.Reader.Error || Allocator.Error || error{
    /// 文件大小达到或超过提供的限制。
    StreamTooLong,
};

/// 读取指定文件的全部字节。成功时,调用者拥有返回的缓冲区。
///
/// 若已知文件大小,更好的方式是初始化 `File.Reader`。
///
/// 若无法获取文件大小,则返回错误。若实际中可能遇到这种情况,更好的方式是初始化 `File.Reader`,它可无缝处理该情况。
///
///
///
///
pub fn readFileAlloc(
    dir: Dir,
    io: Io,
    /// 在 Windows 上,应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
    /// 在 WASI 上,应编码为有效的 UTF-8。
    /// 在其他平台上,为不规定编码的不透明字节序列。
    sub_path: []const u8,
    /// 用于分配结果。
    gpa: Allocator,
    /// 如果达到或超过此值,则改为返回 `error.StreamTooLong`。
    limit: Io.Limit,
) ReadFileAllocError![]u8 {
    return readFileAllocOptions(dir, io, sub_path, gpa, limit, .of(u8), null);
}

/// 读取指定文件的所有字节。成功时,返回缓冲区的
/// 所有权归调用者。
///
/// 若文件大小已知,更好的选择是初始化一个
/// `File.Reader`。
pub fn readFileAllocOptions(
    dir: Dir,
    io: Io,
    /// 在 Windows 上,应编码为 [WTF-8](https://wtf-8.codeberg.page/)。
    /// 在 WASI 上,应编码为有效的 UTF-8。
    /// 在其他平台上,为不规定编码的不透明字节序列。
    sub_path: []const u8,
    /// 用于分配结果。
    gpa: Allocator,
    /// 如果达到或超过此值,则改为返回 `error.StreamTooLong`。
    limit: Io.Limit,
    comptime alignment: std.mem.Alignment,
    comptime sentinel: ?u8,
) ReadFileAllocError!(if (sentinel) |s| [:s]align(alignment.toByteUnits()) u8 else []align(alignment.toByteUnits()) u8) {
    var file = try dir.openFile(io, sub_path, .{
        // 在 Windows 上可以利用这一点,因为不会增加系统调用,
        // 从而在打开时而非读取时获得 error.IsDir。
        .allow_directory = if (native_os == .windows) false else true,
    });
    defer file.close(io);
    var file_reader = file.reader(io, &.{});
    return file_reader.interface.allocRemainingAlignedSentinel(gpa, limit, alignment, sentinel) catch |err| switch (err) {
        error.ReadFailed => return file_reader.err.?,
        error.OutOfMemory, error.StreamTooLong => |e| return e,
    };
}

pub const DeleteTreeError = error{
    AccessDenied,
    PermissionDenied,
    FileTooBig,
    SymLinkLoop,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    NoDevice,
    SystemResources,
    ReadOnlyFileSystem,
    FileSystem,
    FileBusy,
    /// 某个路径分量不是目录。
    /// 若 `sub_path` 不包含路径分隔符,则此错误不可达。
    NotDir,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
} || PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 不论 `sub_path` 描述的是符号链接、文件还是目录,此函数
/// 都会将其删除。若因目录非空而无法删除,
/// 则先递归删除其条目,再次尝试。
///
/// 此操作在多数文件系统上不是原子操作。
///
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
pub fn deleteTree(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void {
    var initial_iterable_dir = (try dir.deleteTreeOpenInitialSubpath(io, sub_path, .file)) orelse return;

    const StackItem = struct {
        name: []const u8,
        parent_dir: Dir,
        iter: Iterator,

        fn closeAll(inner_io: Io, items: []@This()) void {
            for (items) |*item| item.iter.reader.dir.close(inner_io);
        }
    };

    var stack_buffer: [16]StackItem = undefined;
    var stack = std.ArrayList(StackItem).initBuffer(&stack_buffer);
    defer StackItem.closeAll(io, stack.items);

    stack.appendAssumeCapacity(.{
        .name = sub_path,
        .parent_dir = dir,
        .iter = initial_iterable_dir.iterateAssumeFirstIteration(),
    });

    process_stack: while (stack.items.len != 0) {
        var top = &stack.items[stack.items.len - 1];
        while (try top.iter.next(io)) |entry| {
            var treat_as_dir = entry.kind == .directory;
            handle_entry: while (true) {
                if (treat_as_dir) {
                    if (stack.unusedCapacitySlice().len >= 1) {
                        var iterable_dir = top.iter.reader.dir.openDir(io, entry.name, .{
                            .follow_symlinks = false,
                            .iterate = true,
                        }) catch |err| switch (err) {
                            error.NotDir => {
                                treat_as_dir = false;
                                continue :handle_entry;
                            },
                            error.FileNotFound => {
                                // 没有问题,原本就打算移除此目录。
                                break :handle_entry;
                            },

                            error.AccessDenied,
                            error.PermissionDenied,
                            error.SymLinkLoop,
                            error.ProcessFdQuotaExceeded,
                            error.NameTooLong,
                            error.SystemFdQuotaExceeded,
                            error.NoDevice,
                            error.SystemResources,
                            error.Unexpected,
                            error.BadPathName,
                            error.NetworkNotFound,
                            error.Canceled,
                            => |e| return e,
                        };
                        stack.appendAssumeCapacity(.{
                            .name = entry.name,
                            .parent_dir = top.iter.reader.dir,
                            .iter = iterable_dir.iterateAssumeFirstIteration(),
                        });
                        continue :process_stack;
                    } else {
                        try top.iter.reader.dir.deleteTreeMinStackSizeWithKindHint(io, entry.name, entry.kind);
                        break :handle_entry;
                    }
                } else {
                    if (top.iter.reader.dir.deleteFile(io, entry.name)) {
                        break :handle_entry;
                    } else |err| switch (err) {
                        error.FileNotFound => break :handle_entry,

                        // 不可能发生,因为未传入任何路径分隔符。
                        error.NotDir => unreachable,

                        error.IsDir => {
                            treat_as_dir = true;
                            continue :handle_entry;
                        },

                        error.AccessDenied,
                        error.PermissionDenied,
                        error.SymLinkLoop,
                        error.NameTooLong,
                        error.SystemResources,
                        error.ReadOnlyFileSystem,
                        error.FileSystem,
                        error.FileBusy,
                        error.BadPathName,
                        error.NetworkNotFound,
                        error.Canceled,
                        error.Unexpected,
                        => |e| return e,
                    }
                }
            }
        }

        // 在 Windows 上,关闭目录句柄前无法删除目录,
        // 因此先关闭句柄,再尝试删除。
        top.iter.reader.dir.close(io);

        // 为避免出错时清理栈导致目录被关闭两次,
        // 保存相关部分,并从栈中弹出该值。
        //
        const parent_dir = top.parent_dir;
        const name = top.name;
        stack.items.len -= 1;

        var need_to_retry: bool = false;
        parent_dir.deleteDir(io, name) catch |err| switch (err) {
            error.FileNotFound => {},
            error.DirNotEmpty => need_to_retry = true,
            else => |e| return e,
        };

        if (need_to_retry) {
            // 由于已关闭先前迭代器使用的句柄,
            // 需要重新打开目录并重新创建迭代器。
            var iterable_dir = iterable_dir: {
                var treat_as_dir = true;
                handle_entry: while (true) {
                    if (treat_as_dir) {
                        break :iterable_dir parent_dir.openDir(io, name, .{
                            .follow_symlinks = false,
                            .iterate = true,
                        }) catch |err| switch (err) {
                            error.NotDir => {
                                treat_as_dir = false;
                                continue :handle_entry;
                            },
                            error.FileNotFound => {
                                // 没有问题,原本就打算移除此目录。
                                continue :process_stack;
                            },

                            error.AccessDenied,
                            error.PermissionDenied,
                            error.SymLinkLoop,
                            error.ProcessFdQuotaExceeded,
                            error.NameTooLong,
                            error.SystemFdQuotaExceeded,
                            error.NoDevice,
                            error.SystemResources,
                            error.Unexpected,
                            error.BadPathName,
                            error.NetworkNotFound,
                            error.Canceled,
                            => |e| return e,
                        };
                    } else {
                        if (parent_dir.deleteFile(io, name)) {
                            continue :process_stack;
                        } else |err| switch (err) {
                            error.FileNotFound => continue :process_stack,

                            // 不可能发生,因为未传入任何路径分隔符。
                            error.NotDir => unreachable,

                            error.IsDir => {
                                treat_as_dir = true;
                                continue :handle_entry;
                            },

                            error.AccessDenied,
                            error.PermissionDenied,
                            error.SymLinkLoop,
                            error.NameTooLong,
                            error.SystemResources,
                            error.ReadOnlyFileSystem,
                            error.FileSystem,
                            error.FileBusy,
                            error.BadPathName,
                            error.NetworkNotFound,
                            error.Canceled,
                            error.Unexpected,
                            => |e| return e,
                        }
                    }
                }
            };
            // 已知栈有空间,因为只是重新放入
            // 刚弹出的 StackItem。
            stack.appendAssumeCapacity(.{
                .name = name,
                .parent_dir = parent_dir,
                .iter = iterable_dir.iterateAssumeFirstIteration(),
            });
            continue :process_stack;
        }
    }
}

/// 类似 `deleteTree`,但每次只保持一个 `Iterator` 活跃,以最小化函数栈大小。
/// 比 `deleteTree` 慢,但使用更少栈空间。
/// Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// 其他平台上,`sub_path` 是不指定编码的不透明字节序列。
pub fn deleteTreeMinStackSize(dir: Dir, io: Io, sub_path: []const u8) DeleteTreeError!void {
    return dir.deleteTreeMinStackSizeWithKindHint(io, sub_path, .file);
}

fn deleteTreeMinStackSizeWithKindHint(parent: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) DeleteTreeError!void {
    start_over: while (true) {
        var dir = (try parent.deleteTreeOpenInitialSubpath(io, sub_path, kind_hint)) orelse return;
        var cleanup_dir_parent: ?Dir = null;
        defer if (cleanup_dir_parent) |*d| d.close(io);

        var cleanup_dir = true;
        defer if (cleanup_dir) dir.close(io);

        // 使用 max_path_bytes 是合理的,因为 dir_name_buf
        // 只会存储文件系统返回的单个
        // 路径分量。
        var dir_name_buf: [max_path_bytes]u8 = undefined;
        var dir_name: []const u8 = sub_path;

        // 此处必须避免递归,才能保证此函数使用 O(1) 内存。
        // 逐个处理条目:若不是目录,则删除;若是目录,
        // 则打开该目录,并关闭原目录。重复此过程,随后重新开始整个操作。

        scan_dir: while (true) {
            var dir_it = dir.iterateAssumeFirstIteration();
            dir_it: while (try dir_it.next(io)) |entry| {
                var treat_as_dir = entry.kind == .directory;
                handle_entry: while (true) {
                    if (treat_as_dir) {
                        const new_dir = dir.openDir(io, entry.name, .{
                            .follow_symlinks = false,
                            .iterate = true,
                        }) catch |err| switch (err) {
                            error.NotDir => {
                                treat_as_dir = false;
                                continue :handle_entry;
                            },
                            error.FileNotFound => {
                                // 没有问题,原本就打算移除此目录。
                                continue :dir_it;
                            },

                            error.AccessDenied,
                            error.PermissionDenied,
                            error.SymLinkLoop,
                            error.ProcessFdQuotaExceeded,
                            error.NameTooLong,
                            error.SystemFdQuotaExceeded,
                            error.NoDevice,
                            error.SystemResources,
                            error.Unexpected,
                            error.BadPathName,
                            error.NetworkNotFound,
                            error.Canceled,
                            => |e| return e,
                        };
                        if (cleanup_dir_parent) |*d| d.close(io);
                        cleanup_dir_parent = dir;
                        dir = new_dir;
                        const result = dir_name_buf[0..entry.name.len];
                        @memcpy(result, entry.name);
                        dir_name = result;
                        continue :scan_dir;
                    } else {
                        if (dir.deleteFile(io, entry.name)) {
                            continue :dir_it;
                        } else |err| switch (err) {
                            error.FileNotFound => continue :dir_it,

                            // 不可能发生,因为未传入任何路径分隔符。
                            error.NotDir => unreachable,

                            error.IsDir => {
                                treat_as_dir = true;
                                continue :handle_entry;
                            },

                            error.AccessDenied,
                            error.PermissionDenied,
                            error.SymLinkLoop,
                            error.NameTooLong,
                            error.SystemResources,
                            error.ReadOnlyFileSystem,
                            error.FileSystem,
                            error.FileBusy,
                            error.BadPathName,
                            error.NetworkNotFound,
                            error.Canceled,
                            error.Unexpected,
                            => |e| return e,
                        }
                    }
                }
            }
            // 已到达目录条目末尾,表示成功删除了全部条目。
            // 接下来删除目录本身。
            dir.close(io);
            cleanup_dir = false;

            if (cleanup_dir_parent) |d| {
                d.deleteDir(io, dir_name) catch |err| switch (err) {
                    // 这两种情况都可能因文件系统竞态条件发生。
                    error.FileNotFound, error.DirNotEmpty => continue :start_over,
                    else => |e| return e,
                };
                continue :start_over;
            } else {
                parent.deleteDir(io, sub_path) catch |err| switch (err) {
                    error.FileNotFound => return,
                    error.DirNotEmpty => continue :start_over,
                    else => |e| return e,
                };
                return;
            }
        }
    }
}

/// 删除成功时返回 null。
fn deleteTreeOpenInitialSubpath(dir: Dir, io: Io, sub_path: []const u8, kind_hint: File.Kind) !?Dir {
    return iterable_dir: {
        // 默认按文件处理
        var treat_as_dir = kind_hint == .directory;

        handle_entry: while (true) {
            if (treat_as_dir) {
                break :iterable_dir dir.openDir(io, sub_path, .{
                    .follow_symlinks = false,
                    .iterate = true,
                }) catch |err| switch (err) {
                    error.NotDir => {
                        treat_as_dir = false;
                        continue :handle_entry;
                    },
                    error.FileNotFound => {
                        // 没有问题,原本就打算移除此目录。
                        return null;
                    },

                    error.AccessDenied,
                    error.PermissionDenied,
                    error.SymLinkLoop,
                    error.ProcessFdQuotaExceeded,
                    error.NameTooLong,
                    error.SystemFdQuotaExceeded,
                    error.NoDevice,
                    error.SystemResources,
                    error.Unexpected,
                    error.BadPathName,
                    error.NetworkNotFound,
                    error.Canceled,
                    => |e| return e,
                };
            } else {
                if (dir.deleteFile(io, sub_path)) {
                    return null;
                } else |err| switch (err) {
                    error.FileNotFound => return null,

                    error.IsDir => {
                        treat_as_dir = true;
                        continue :handle_entry;
                    },

                    error.AccessDenied,
                    error.PermissionDenied,
                    error.SymLinkLoop,
                    error.NameTooLong,
                    error.SystemResources,
                    error.ReadOnlyFileSystem,
                    error.NotDir,
                    error.FileSystem,
                    error.FileBusy,
                    error.BadPathName,
                    error.NetworkNotFound,
                    error.Canceled,
                    error.Unexpected,
                    => |e| return e,
                }
            }
        }
    };
}

pub const CopyFileOptions = struct {
    /// 此项为 `null` 时,从源文件复制权限。
    permissions: ?File.Permissions = null,
    make_path: bool = false,
    replace: bool = true,
};

pub const CopyFileError = File.OpenError || File.StatError ||
    CreateFileAtomicError || File.Atomic.ReplaceError || File.Atomic.LinkError ||
    File.Reader.Error || File.Writer.Error || error{InvalidFileName};

/// 在 `dest_path` 原子创建新文件,该路径位于 `dest_dir` 内,
/// 内容与 `source_path` 相同,该源路径位于 `source_dir` 内。
///
/// 是否覆盖已有文件由 `options` 决定。
///
/// Linux 上,在 https://patchwork.kernel.org/patch/9636735/ 合入
/// 并广泛可用之前,断电或应用
/// 终止可能使临时文件残留在
/// dest_path 所在的同一目录中。
///
/// Windows 上,两条路径均应采用
/// [WTF-8](https://wtf-8.codeberg.page/) 编码。WASI 上,两条路径均应采用
/// 有效的 UTF-8 编码。其他平台上,两条路径均为
/// 不指定编码的不透明字节序列。
pub fn copyFile(
    source_dir: Dir,
    source_path: []const u8,
    dest_dir: Dir,
    dest_path: []const u8,
    io: Io,
    options: CopyFileOptions,
) CopyFileError!void {
    const file = try source_dir.openFile(io, source_path, .{});
    var file_reader: File.Reader = .init(file, io, &.{});
    defer file_reader.file.close(io);

    const permissions = options.permissions orelse blk: {
        const st = try file_reader.file.stat(io);
        file_reader.size = st.size;
        break :blk st.permissions;
    };

    var atomic_file = try dest_dir.createFileAtomic(io, dest_path, .{
        .permissions = permissions,
        .make_path = options.make_path,
        .replace = options.replace,
    });
    defer atomic_file.deinit(io);

    var buffer: [1024]u8 = undefined; // 仅当无法直接在 fd 之间传输时使用。
    var file_writer = atomic_file.file.writer(io, &buffer);

    _ = file_writer.interface.sendFileAll(&file_reader, .unlimited) catch |err| switch (err) {
        error.ReadFailed => return file_reader.err.?,
        error.WriteFailed => return file_writer.err.?,
    };

    try file_writer.flush();

    switch (options.replace) {
        true => try atomic_file.replace(io),
        false => try atomic_file.link(io),
    }
}

/// 与 `copyFile` 相同,但断言 `source_path` 和 `dest_path` 均为绝对路径。
///
/// Windows 上,两个路径都应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// WASI 上,两个路径都应采用有效 UTF-8 编码。
/// 其他平台上,两个路径都是不透明的字节序列,没有特定编码。
///
pub fn copyFileAbsolute(
    source_path: []const u8,
    dest_path: []const u8,
    io: Io,
    options: CopyFileOptions,
) !void {
    assert(path.isAbsolute(source_path));
    assert(path.isAbsolute(dest_path));
    const my_cwd = cwd();
    return copyFile(my_cwd, source_path, my_cwd, dest_path, io, options);
}

test copyFileAbsolute {}

pub const CreateFileAtomicOptions = struct {
    permissions: File.Permissions = .default_file,
    make_path: bool = false,
    /// 指示无名文件最终将通过 `File.Atomic.link`
    /// 还是 `File.Atomic.replace` 创建。
    ///
    /// 如果此值不正确,会在
    /// `File.Atomic.replace` 中导致断言失败。
    replace: bool = false,
};

pub const CreateFileAtomicError = error{
    NoDevice,
    /// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
    NetworkNotFound,
    /// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
    /// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
    ///
    ///
    ///
    AntivirusInterference,
    /// 在 WASI 中,若文件描述符不具有相对于它
    /// 打开新资源所需的权限,可能发生此错误。
    AccessDenied,
    PermissionDenied,
    SymLinkLoop,
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    /// 以下情况之一:
    /// * 某个路径分量不存在。
    /// * 使用了 Cwd,但当前工作目录已被删除。
    /// * 与已打开目录句柄关联的路径已被删除。
    FileNotFound,
    /// 可用内核内存不足。
    SystemResources,
    /// 设备没有空间容纳新文件,无法创建新路径。
    NoSpaceLeft,
    /// 路径中作为目录使用的某个组成部分实际上不是目录。
    NotDir,
    WouldBlock,
    ReadOnlyFileSystem,
    /// 尝试创建的文件是正在运行的可执行文件。
    FileBusy,
} || Io.Dir.PathNameError || Io.Cancelable || Io.UnexpectedError;

/// 创建一个未命名的临时文件,之后可将其原子地实体化为 `sub_path`。
/// 在该文件完成实体化之前,`sub_path` 必须保持有效。
///
/// 返回的 `File.Atomic` 提供 API,可在底层操作系统不直接支持时模拟此行为。
///
/// * 在 Windows 上,`sub_path` 应采用 [WTF-8](https://wtf-8.codeberg.page/) 编码。
/// * 在 WASI 上,`sub_path` 应采用有效的 UTF-8 编码。
/// * 在其他平台上,`sub_path` 是不限定编码的不透明字节序列。
///
///
pub fn createFileAtomic(
    dir: Dir,
    io: Io,
    sub_path: []const u8,
    options: CreateFileAtomicOptions,
) CreateFileAtomicError!File.Atomic {
    return io.vtable.dirCreateFileAtomic(io.userdata, dir, sub_path, options);
}

pub const SetPermissionsError = File.SetPermissionsError;
pub const Permissions = File.Permissions;

/// 也称为 chmod。
///
/// 进程必须具有适当特权,才能成功执行,
/// 或者有效用户标识符必须与目录
/// 所有者匹配。此外,目录必须在打开时
/// 将 `OpenOptions.iterate` 设为 `true`。
pub fn setPermissions(dir: Dir, io: Io, new_permissions: File.Permissions) SetPermissionsError!void {
    return io.vtable.dirSetPermissions(io.userdata, dir, new_permissions);
}

pub const SetFilePermissionsError = PathNameError || SetPermissionsError || error{
    ProcessFdQuotaExceeded,
    SystemFdQuotaExceeded,
    /// `SetFilePermissionsOptions.follow_symlinks` 被设为 false,但文件系统或操作系统不允许。
    ///
    OperationUnsupported,
};

pub const SetFilePermissionsOptions = struct {
    follow_symlinks: bool = true,
};

/// 也称为 "fchmodat"。
pub fn setFilePermissions(
    dir: Dir,
    io: Io,
    sub_path: []const u8,
    new_permissions: File.Permissions,
    options: SetFilePermissionsOptions,
) SetFilePermissionsError!void {
    return io.vtable.dirSetFilePermissions(io.userdata, dir, sub_path, new_permissions, options);
}

pub const SetOwnerError = File.SetOwnerError;

/// 也称为“chown”。
///
/// 进程必须具有正确权限才能成功执行。目录所有者可以将所属组改为自身属于的任意组。此外,目录必须在打开时将 `OpenOptions.iterate` 设为 `true`。
/// 若所有者或所属组指定为 `null`,则对应标识不变。
///
///
///
pub fn setOwner(dir: Dir, io: Io, owner: ?File.Uid, group: ?File.Gid) SetOwnerError!void {
    return io.vtable.dirSetOwner(io.userdata, dir, owner, group);
}

pub const SetFileOwnerError = PathNameError || SetOwnerError;

pub const SetFileOwnerOptions = struct {
    follow_symlinks: bool = true,
};

/// 也称为 "fchownat"。
pub fn setFileOwner(
    dir: Dir,
    io: Io,
    sub_path: []const u8,
    owner: ?File.Uid,
    group: ?File.Gid,
    options: SetFileOwnerOptions,
) SetFileOwnerError!void {
    return io.vtable.dirSetFileOwner(io.userdata, dir, sub_path, owner, group, options);
}

pub const SetTimestampsError = File.SetTimestampsError || PathNameError;

pub const SetTimestampsOptions = struct {
    follow_symlinks: bool = true,
    access_timestamp: File.SetTimestamp = .unchanged,
    modify_timestamp: File.SetTimestamp = .unchanged,
};

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

pub const SetTimestampsNowOptions = struct {
    follow_symlinks: bool = true,
};

/// 将所提供路径的访问时间戳及修改时间戳
/// 设置为当前墙上时钟时间。
///
/// 最终存储的时间粒度取决于
/// 操作系统与文件系统的组合。
pub fn setTimestampsNow(
    dir: Dir,
    io: Io,
    sub_path: []const u8,
    options: SetTimestampsNowOptions,
) SetTimestampsError!void {
    return io.vtable.dirSetTimestamps(io.userdata, dir, sub_path, .{
        .follow_symlinks = options.follow_symlinks,
        .access_timestamp = .now,
        .modify_timestamp = .now,
    });
}

test {
    _ = &setFileOwner;
    _ = &setTimestampsNow;
}