跳转到内容

std.Io.Dispatch

标准库Zig 0.17.0官方原文
源码std/Io/Dispatch.zig

第 1 行

字段

queue: c.dispatch.queue_t
backing_allocator_needs_mutex: bool
backing_allocator_mutex: Mutex
backing_allocator: Allocator

若未在其他地方使用,则无需线程安全。

main_fiber: Fiber
main_loop_stack: [*]align(builtin.target.stackAlignment()) u8
exit_semaphore: c.dispatch.semaphore_t
use_sendfile: UseSendfile
use_fcopyfile: UseFcopyfile
leeway: u64
futexes: [1 << 8]Futex
init_stderr_writer: c.dispatch.once_t
stderr_mutex: Mutex
stderr_writer: File.Writer
stderr_mode: Io.Terminal.Mode
scan_environ: c.dispatch.once_t
environ: Environ
open_dev_null: c.dispatch.once_t
dev_null_file: File.OpenError!File
csprng_mutex: Mutex
csprng: Csprng

std.Io.Dispatch.addBuf

函数

第 4970 行

fn addBuf( comptime is_const: bool, vec: []if (is_const) iovec_const else iovec, vec_len: *iovlen_t, remaining: *Io.Limit, bytes: if (is_const) []const u8 else []u8, ) void

参数

is_const: bool
vec: []if (is_const) iovec_const else iovec
vec_len: *iovlen_t
remaining: *Io.Limit
bytes: if (is_const) []const u8 else []u8

std.Io.Dispatch.addConstBuf

函数

第 4962 行

fn addConstBuf(v: []iovec_const, i: *iovlen_t, remaining: ?*usize, bytes: []const u8) void

参数

v: []iovec_const
i: *iovlen_t
remaining: ?*usize
bytes: []const u8

std.Io.Dispatch.Alignment

别名

第 1 行

别名目标 std.mem.Alignment

std.Io.Dispatch.alloc

函数

第 304 行

fn alloc(userdata: *anyopaque, len: usize, alignment: std.mem.Alignment, ret_addr: usize) ?[*]u8

参数

userdata: *anyopaque
len: usize
alignment: std.mem.Alignment
ret_addr: usize

std.Io.Dispatch.allocator

函数

第 292 行

pub fn allocator(ev: *Evented) std.mem.Allocator

参数

ev: *Evented

std.Io.Dispatch.Allocator

别名

第 2 行

别名目标 std.mem.Allocator

std.Io.Dispatch.Argv0

别名

第 3 行

别名目标 std.Io.Threaded.Argv0

std.Io.Dispatch.assert

别名

第 4 行

别名目标 std.debug.assert

std.Io.Dispatch.async

函数

第 1034 行

fn async( userdata: ?*anyopaque, result: []u8, result_alignment: Alignment, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque, result: *anyopaque) void, ) ?*std.Io.AnyFuture

参数

userdata: ?*anyopaque
result: []u8
result_alignment: Alignment
context: []const u8
context_alignment: Alignment
start: *const fn (context: *const anyopaque, result: *anyopaque) void

std.Io.Dispatch.AsyncClosure

容器

第 985 行

字段

evented: *Evented
fiber: *Fiber
start: *const fn (context: *const anyopaque, result: *anyopaque) void
result_align: Alignment

std.Io.Dispatch.AsyncClosure.call

函数

第 1019 行

fn call( closure: *AsyncClosure, message: *const SwitchMessage, ) callconv(.withStackAlign(.c, @alignOf(AsyncClosure))) noreturn

参数

closure: *AsyncClosure
message: *const SwitchMessage

std.Io.Dispatch.AsyncClosure.contextPointer

函数

第 997 行

fn contextPointer(closure: *AsyncClosure) [*]align(Fiber.max_context_align.toByteUnits()) u8

参数

closure: *AsyncClosure

std.Io.Dispatch.AsyncClosure.entry

函数

第 1001 行

fn entry() callconv(.naked) void

std.Io.Dispatch.AsyncClosure.fromFiber

函数

第 991 行

fn fromFiber(fiber: *Fiber) *AsyncClosure

参数

fiber: *Fiber

std.Io.Dispatch.atomicFileInit

函数

第 2567 行

fn atomicFileInit( ev: *Evented, dest_basename: []const u8, permissions: File.Permissions, dir: Dir, close_dir_on_deinit: bool, ) Dir.CreateFileAtomicError!File.Atomic

参数

ev: *Evented
dest_basename: []const u8
permissions: File.Permissions
dir: Dir
close_dir_on_deinit: bool

错误

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.Dispatch.await

函数

第 1101 行

fn await( userdata: ?*anyopaque, future: *std.Io.AnyFuture, result: []u8, result_alignment: Alignment, ) void

参数

userdata: ?*anyopaque
future: *std.Io.AnyFuture
result: []u8
result_alignment: Alignment

std.Io.Dispatch.batchAwaitAsync

函数

第 1932 行

fn batchAwaitAsync(userdata: ?*anyopaque, batch: *Io.Batch) Io.Cancelable!void

参数

userdata: ?*anyopaque
batch: *Io.Batch

错误

Canceled

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

std.Io.Dispatch.batchAwaitConcurrent

函数

第 1948 行

fn batchAwaitConcurrent( userdata: ?*anyopaque, batch: *Io.Batch, timeout: Io.Timeout, ) Io.Batch.AwaitConcurrentError!void

参数

userdata: ?*anyopaque
batch: *Io.Batch
timeout: Io.Timeout

错误

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

Timeout Error

std.Io.Dispatch.batchCancel

函数

第 1978 行

fn batchCancel(userdata: ?*anyopaque, batch: *Io.Batch) void

参数

userdata: ?*anyopaque
batch: *Io.Batch

std.Io.Dispatch.batchDrainSubmitted

函数

第 2043 行

若 concurrency 为 false,则 error.ConcurrencyUnavailable 不可达。

fn batchDrainSubmitted( ev: *Evented, batch: *Io.Batch, concurrency: bool, ) (Io.ConcurrentError || Io.Cancelable)!?c.dispatch.queue_t

参数

ev: *Evented
batch: *Io.Batch
concurrency: bool

std.Io.Dispatch.BatchOperationUserdata

容器

第 2002 行

字段

batch: *Io.Batch
source: c.dispatch.source_t
operation: extern union {
    file_read_streaming: extern struct {
        data_ptr: [*]const []u8,
        data_len: usize,
    },
    file_write_streaming: extern struct {
        header_ptr: [*]const u8,
        header_len: usize,
        data_ptr: [*]const []const u8,
        data_len: usize,
        splat: usize,

        fn header(operation: *const @This()) []const u8 {
            return operation.header_ptr[0..operation.header_len];
        }

        fn data(operation: *const @This()) []const []const u8 {
            return operation.data_ptr[0..operation.data_len];
        }
    },
}

std.Io.Dispatch.BatchOperationUserdata.data

函数

第 2021 行

fn data(operation: *const @This()) []const []const u8

参数

operation: *const @This()

std.Io.Dispatch.BatchOperationUserdata.Erased

别名

第 2027 行

别名目标 std.Io.Operation.Storage.Pending.Userdata

std.Io.Dispatch.BatchOperationUserdata.fromErased

函数

第 2037 行

fn fromErased(erased: *Erased) *BatchOperationUserdata

参数

erased: *Erased

std.Io.Dispatch.BatchOperationUserdata.header

函数

第 2017 行

fn header(operation: *const @This()) []const u8

参数

operation: *const @This()

std.Io.Dispatch.BatchOperationUserdata.toErased

函数

第 2033 行

fn toErased(userdata: *BatchOperationUserdata) *Erased

参数

std.Io.Dispatch.batchSourceCancel

函数

第 2227 行

fn batchSourceCancel(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.batchSourceEvent

函数

第 2164 行

fn batchSourceEvent(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.BatchWaiter

容器

第 1901 行

字段

sleeper: Sleeper
queue: c.dispatch.queue_t
timer: ?c.dispatch.source_t = null

std.Io.Dispatch.BatchWaiter.@"suspend"

函数

第 1918 行

fn @"suspend"(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.BatchWaiter.already_signaled

常量

第 1906 行

c.dispatch.source_t

std.Io.Dispatch.BatchWaiter.signal

函数

第 1908 行

fn signal(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.BatchWaiter.wake

函数

第 1925 行

fn wake(waiter: *BatchWaiter) void

参数

waiter: *BatchWaiter

std.Io.Dispatch.builtin

常量

第 5 行

std.Io.Dispatch.c

别名

第 6 行

别名目标 std.c

std.Io.Dispatch.cancel

函数

第 1115 行

fn cancel( userdata: ?*anyopaque, future: *std.Io.AnyFuture, result: []u8, result_alignment: Alignment, ) void

参数

userdata: ?*anyopaque
future: *std.Io.AnyFuture
result: []u8
result_alignment: Alignment

std.Io.Dispatch.Cancelable

容器

第 715 行

字段

required_align: void align(2) = {}
queue: c.dispatch.queue_t
cancel: c.dispatch.function_t

std.Io.Dispatch.Cancelable.acknowledge

函数

第 784 行

fn acknowledge(cancelable: *Cancelable, fiber: *Fiber) Io.Cancelable!void

参数

cancelable: *Cancelable
fiber: *Fiber

错误

Canceled

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

std.Io.Dispatch.Cancelable.async

函数

第 764 行

fn async(cancelable: *Cancelable) void

参数

cancelable: *Cancelable

std.Io.Dispatch.Cancelable.blocked

常量

第 724 行

Cancelable

std.Io.Dispatch.Cancelable.enter

函数

第 728 行

fn enter(cancelable: *Cancelable, fiber: *Fiber) RequestedError!void

参数

cancelable: *Cancelable
fiber: *Fiber

错误

CancelRequested

std.Io.Dispatch.Cancelable.fn_ptr_align

常量

第 720 行

std.Io.Dispatch.Cancelable.is_blocked

常量

第 721 行

c.dispatch.function_t

std.Io.Dispatch.Cancelable.is_requested

常量

第 722 行

c.dispatch.function_t

std.Io.Dispatch.Cancelable.leave

函数

第 749 行

fn leave(cancelable: *Cancelable, fiber: *Fiber) RequestedError!void

参数

cancelable: *Cancelable
fiber: *Fiber

错误

CancelRequested

std.Io.Dispatch.Cancelable.requested

函数

第 770 行

fn requested(cancelable: *Cancelable, fiber: *Fiber) void

参数

cancelable: *Cancelable
fiber: *Fiber

std.Io.Dispatch.Cancelable.RequestedError

错误集合

第 726 行

错误

CancelRequested

std.Io.Dispatch.ChdirError

别名

第 7 行

别名目标 std.Io.Threaded.ChdirError

std.Io.Dispatch.checkCancel

函数

第 1470 行

fn checkCancel(userdata: ?*anyopaque) Io.Cancelable!void

参数

userdata: ?*anyopaque

错误

Canceled

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

std.Io.Dispatch.childCleanup

函数

第 4619 行

fn childCleanup(ev: *Evented, child: *process.Child) void

参数

ev: *Evented
child: *process.Child

std.Io.Dispatch.childKill

函数

第 4598 行

fn childKill(userdata: ?*anyopaque, child: *process.Child) void

参数

userdata: ?*anyopaque
child: *process.Child

std.Io.Dispatch.childWait

函数

第 4570 行

fn childWait(userdata: ?*anyopaque, child: *process.Child) process.Child.WaitError!process.Child.Term

参数

userdata: ?*anyopaque
child: *process.Child

错误

AccessDenied
Canceled Cancelable

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

Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.clockResolution

函数

第 4657 行

fn clockResolution(userdata: ?*anyopaque, clock: Io.Clock) Io.Clock.ResolutionError!Io.Duration

参数

userdata: ?*anyopaque
clock: Io.Clock

错误

ClockUnavailable
Unexpected

std.Io.Dispatch.clockToPosix

别名

第 8 行

别名目标 std.Io.Threaded.clockToPosix

std.Io.Dispatch.closeFd

别名

第 9 行

别名目标 std.Io.Threaded.closeFd

std.Io.Dispatch.concurrent

函数

第 1049 行

fn concurrent( userdata: ?*anyopaque, result_len: usize, result_alignment: Alignment, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque, result: *anyopaque) void, ) Io.ConcurrentError!*std.Io.AnyFuture

参数

userdata: ?*anyopaque
result_len: usize
result_alignment: Alignment
context: []const u8
context_alignment: Alignment
start: *const fn (context: *const anyopaque, result: *anyopaque) void

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.Dispatch.contextSwitch

函数

第 711 行

inline fn contextSwitch(message: *const SwitchMessage) *const SwitchMessage

参数

message: *const SwitchMessage

std.Io.Dispatch.crashHandler

函数

第 969 行

fn crashHandler(userdata: ?*anyopaque) void

参数

userdata: ?*anyopaque

std.Io.Dispatch.Csprng

别名

第 10 行

别名目标 std.Io.Threaded.Csprng

std.Io.Dispatch.default_PATH

别名

第 11 行

别名目标 std.Io.Threaded.default_PATH

std.Io.Dispatch.deinit

函数

第 573 行

pub fn deinit(ev: *Evented) void

参数

ev: *Evented

std.Io.Dispatch.destroyPipe

函数

第 4470 行

fn destroyPipe(pipe: [2]c.fd_t) void

参数

pipe: [2]c.fd_t

std.Io.Dispatch.deviceIoControl

函数

第 1890 行

fn deviceIoControl(o: *const Io.Operation.DeviceIoControl) Io.Cancelable!i32

参数

错误

Canceled

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

std.Io.Dispatch.Dir

别名

第 12 行

别名目标 std.Io.Dir

std.Io.Dispatch.dirAccess

函数

第 2433 行

fn dirAccess( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.AccessOptions, ) Dir.AccessError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.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.Dispatch.dirClose

函数

第 2686 行

fn dirClose(userdata: ?*anyopaque, dirs: []const Dir) void

参数

userdata: ?*anyopaque
dirs: []const Dir

std.Io.Dispatch.dirCreateDir

函数

第 2260 行

fn dirCreateDir( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, ) Dir.CreateDirError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.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.Dispatch.dirCreateDirPath

函数

第 2296 行

fn dirCreateDirPath( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, ) Dir.CreateDirPathError!Dir.CreatePathStatus

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.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.Dispatch.dirCreateDirPathOpen

函数

第 2328 行

fn dirCreateDirPathOpen( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.OpenOptions, ) Dir.CreateDirPathOpenError!Dir

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions
options: Dir.OpenOptions

错误

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.Dispatch.dirCreateFile

函数

第 2472 行

fn dirCreateFile( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.CreateFileOptions, ) File.OpenError!File

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
flags: Dir.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.Dispatch.dirCreateFileAtomic

函数

第 2536 行

fn dirCreateFileAtomic( userdata: ?*anyopaque, dir: Dir, dest_path: []const u8, options: Dir.CreateFileAtomicOptions, ) Dir.CreateFileAtomicError!File.Atomic

参数

userdata: ?*anyopaque
dir: Dir
dest_path: []const u8
options: Dir.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.Dispatch.dirDeleteDir

函数

第 2917 行

fn dirDeleteDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void

参数

userdata: ?*anyopaque
dir: Dir
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.Dispatch.dirDeleteFile

函数

第 2869 行

fn dirDeleteFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void

参数

userdata: ?*anyopaque
dir: Dir
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.Dispatch.dirHardLink

函数

第 3226 行

fn dirHardLink( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, options: Dir.HardLinkOptions, ) Dir.HardLinkError!void

参数

userdata: ?*anyopaque
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8
options: Dir.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.Dispatch.dirOpenDir

函数

第 2345 行

fn dirOpenDir( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenOptions, ) Dir.OpenError!Dir

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.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.Dispatch.dirOpenFile

函数

第 2605 行

fn dirOpenFile( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.OpenFileOptions, ) File.OpenError!File

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
flags: Dir.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.Dispatch.dirRead

函数

第 2692 行

fn dirRead(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize

参数

userdata: ?*anyopaque
dr: *Dir.Reader
buffer: []Dir.Entry

错误

AccessDenied
Canceled Cancelable

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

PermissionDenied
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.dirReadLink

函数

第 3045 行

fn dirReadLink( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, buffer: []u8, ) Dir.ReadLinkError!usize

参数

userdata: ?*anyopaque
dir: Dir
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.Dispatch.dirRealPath

函数

第 2767 行

fn dirRealPath(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize

参数

userdata: ?*anyopaque
dir: Dir
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.Dispatch.dirRealPathFile

函数

第 2795 行

fn dirRealPathFile( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, out_buffer: []u8, ) Dir.RealPathFileError!usize

参数

userdata: ?*anyopaque
dir: Dir
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.Dispatch.dirRename

函数

第 2948 行

fn dirRename( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenameError!void

参数

userdata: ?*anyopaque
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8

错误

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.Dispatch.dirRenamePreserve

函数

第 2991 行

fn dirRenamePreserve( userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, ) Dir.RenamePreserveError!void

参数

userdata: ?*anyopaque
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8

错误

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.Dispatch.dirSetFileOwner

函数

第 3107 行

fn dirSetFileOwner( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, owner: ?File.Uid, group: ?File.Gid, options: Dir.SetFileOwnerOptions, ) Dir.SetFileOwnerError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
owner: ?File.Uid
group: ?File.Gid
options: Dir.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.Dispatch.dirSetFilePermissions

函数

第 3152 行

fn dirSetFilePermissions( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.SetFilePermissionsOptions, ) Dir.SetFilePermissionsError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions
options: Dir.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.Dispatch.dirSetOwner

函数

第 3075 行

fn dirSetOwner( userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid, ) Dir.SetOwnerError!void

参数

userdata: ?*anyopaque
dir: Dir
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.Dispatch.dirSetPermissions

函数

第 3143 行

fn dirSetPermissions( userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions, ) Dir.SetPermissionsError!void

参数

userdata: ?*anyopaque
dir: Dir
permissions: Dir.Permissions

错误

AccessDenied SetPermissionsError
Canceled Cancelable

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

FileNotFound SetPermissionsError
InputOutput SetPermissionsError
PermissionDenied SetPermissionsError
ReadOnlyFileSystem SetPermissionsError
SymLinkLoop SetPermissionsError
SystemResources SetPermissionsError
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.dirSetTimestamps

函数

第 3190 行

fn dirSetTimestamps( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.SetTimestampsOptions, ) Dir.SetTimestampsError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.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.Dispatch.dirStat

函数

第 2390 行

fn dirStat(userdata: ?*anyopaque, dir: Dir) Dir.StatError!Dir.Stat

参数

userdata: ?*anyopaque
dir: Dir

错误

AccessDenied StatError

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

Canceled Cancelable

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

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.dirStatFile

函数

第 2398 行

fn dirStatFile( userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions, ) Dir.StatFileError!File.Stat

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.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.Dispatch.dirSymLink

函数

第 3006 行

fn dirSymLink( userdata: ?*anyopaque, dir: Dir, target_path: []const u8, sym_link_path: []const u8, flags: Dir.SymLinkFlags, ) Dir.SymLinkError!void

参数

userdata: ?*anyopaque
dir: Dir
target_path: []const u8
sym_link_path: []const u8
flags: Dir.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.Dispatch.dup2

函数

第 4479 行

fn dup2(ev: *Evented, old_fd: c.fd_t, new_fd: c.fd_t) DupError!void

参数

ev: *Evented
old_fd: c.fd_t
new_fd: c.fd_t

错误

Canceled Cancelable

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

ProcessFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.DupError

错误集合

第 4475 行

错误

Canceled Cancelable

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

ProcessFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.Environ

别名

第 13 行

别名目标 std.Io.Threaded.Environ

std.Io.Dispatch.errnoBug

别名

第 14 行

别名目标 std.Io.Threaded.errnoBug

std.Io.Dispatch.Evented

别名

第 15 行

别名目标 std.Io.Dispatch

std.Io.Dispatch.execv

函数

第 4492 行

fn execv( ev: *Evented, arg0_expand: process.ArgExpansion, file: [*:0]const u8, child_argv: [*:null]?[*:0]const u8, env_block: process.Environ.PosixBlock, PATH: []const u8, ) process.ReplaceError

参数

ev: *Evented
arg0_expand: process.ArgExpansion
file: [*:0]const u8
child_argv: [*:null]?[*:0]const u8
env_block: process.Environ.PosixBlock
PATH: []const u8

std.Io.Dispatch.execvPath

函数

第 4540 行

此函数忽略 PATH 环境变量。

fn execvPath( ev: *Evented, path: [*:0]const u8, child_argv: [*:null]const ?[*:0]const u8, env_block: process.Environ.PosixBlock, ) process.ReplaceError

参数

ev: *Evented
path: [*:0]const u8
child_argv: [*:null]const ?[*:0]const u8
env_block: process.Environ.PosixBlock

std.Io.Dispatch.fallbackSeed

别名

第 16 行

别名目标 std.Io.Threaded.fallbackSeed

std.Io.Dispatch.fchmod

函数

第 3660 行

fn fchmod(ev: *Evented, fd: c.fd_t, mode: c.mode_t) File.SetPermissionsError!void

参数

ev: *Evented
fd: c.fd_t
mode: c.mode_t

错误

AccessDenied
Canceled Cancelable

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

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fchown

函数

第 3086 行

fn fchown(fd: c.fd_t, owner: ?File.Uid, group: ?File.Gid) File.SetOwnerError!void

参数

fd: c.fd_t
owner: ?File.Uid
group: ?File.Gid

错误

AccessDenied
Canceled Cancelable

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

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.Fiber

容器

第 99 行

字段

required_align: void align(4)
evented: *Evented
context: Io.fiber.Context
link: union {
    awaiter: ?*Fiber,
    group: struct { prev: ?*Fiber, next: ?*Fiber },
}
awaiting_group: Group
cancel_status: CancelStatus
cancel_protection: CancelProtection

std.Io.Dispatch.Fiber.@"resume"

函数

第 278 行

fn @"resume"(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Fiber.allocatedEnd

函数

第 221 行

fn allocatedEnd(f: *Fiber) [*]u8

参数

f: *Fiber

std.Io.Dispatch.Fiber.allocatedSlice

函数

第 217 行

fn allocatedSlice(f: *Fiber) []align(@alignOf(Fiber)) u8

参数

f: *Fiber

std.Io.Dispatch.Fiber.allocation_size

常量

第 201 行

std.Io.Dispatch.Fiber.CancelProtection

容器

第 153 行

字段

user: Io.CancelProtection
acknowledged: bool

std.Io.Dispatch.Fiber.CancelProtection.acknowledge

函数

第 163 行

fn acknowledge(cancel_protection: *CancelProtection) void

参数

cancel_protection: *CancelProtection

std.Io.Dispatch.Fiber.CancelProtection.check

函数

第 159 行

fn check(cancel_protection: CancelProtection) Io.CancelProtection

参数

cancel_protection: CancelProtection

用法示例

test check {
    try std.testing.expectEqual(Io.CancelProtection.unblocked, check(.unblocked));
    try std.testing.expectEqual(Io.CancelProtection.blocked, check(.{
        .user = .unblocked,
        .acknowledged = true,
    }));
    try std.testing.expectEqual(Io.CancelProtection.blocked, check(.{
        .user = .blocked,
        .acknowledged = false,
    }));
    try std.testing.expectEqual(Io.CancelProtection.blocked, check(.{
        .user = .blocked,
        .acknowledged = true,
    }));
}

std.Io.Dispatch.Fiber.CancelProtection.recancel

函数

第 168 行

fn recancel(cancel_protection: *CancelProtection) void

参数

cancel_protection: *CancelProtection

std.Io.Dispatch.Fiber.CancelProtection.unblocked

常量

第 157 行

CancelProtection

std.Io.Dispatch.Fiber.CancelStatus

容器

第 113 行

字段

requested: bool
awaiting: Awaiting

std.Io.Dispatch.Fiber.CancelStatus.Awaiting

容器

第 119 行

字段

nothing = 0
group = 1
_

std.Io.Dispatch.Fiber.CancelStatus.Awaiting.fromCancelable

函数

第 130 行

fn fromCancelable(cancelable: *Cancelable) Awaiting

参数

cancelable: *Cancelable

std.Io.Dispatch.Fiber.CancelStatus.Awaiting.shift

常量

第 124 行

std.Io.Dispatch.Fiber.CancelStatus.Awaiting.subWrap

函数

第 126 行

fn subWrap(lhs: Awaiting, rhs: Awaiting) Awaiting

参数

lhs: Awaiting
rhs: Awaiting

std.Io.Dispatch.Fiber.CancelStatus.Awaiting.toCancelable

函数

第 134 行

fn toCancelable(awaiting: Awaiting) *Cancelable

参数

awaiting: Awaiting

std.Io.Dispatch.Fiber.CancelStatus.changeAwaiting

函数

第 139 行

fn changeAwaiting( cancel_status: *CancelStatus, old_awaiting: Awaiting, new_awaiting: Awaiting, ) bool

参数

cancel_status: *CancelStatus
old_awaiting: Awaiting
new_awaiting: Awaiting

std.Io.Dispatch.Fiber.CancelStatus.unrequested

常量

第 117 行

CancelStatus

std.Io.Dispatch.Fiber.create

函数

第 209 行

fn create(ev: *Evented) error{OutOfMemory}!*Fiber

参数

ev: *Evented

错误

OutOfMemory

std.Io.Dispatch.Fiber.destroy

函数

第 213 行

fn destroy(fiber: *Fiber, ev: *Evented) void

参数

fiber: *Fiber
ev: *Evented

std.Io.Dispatch.Fiber.finished

常量

第 190 行

?*Fiber

std.Io.Dispatch.Fiber.max_closure_align

常量

第 200 行

Alignment

std.Io.Dispatch.Fiber.max_closure_size

常量

第 199 行

usize

std.Io.Dispatch.Fiber.max_context_align

常量

第 197 行

Alignment

std.Io.Dispatch.Fiber.max_context_size

常量

第 198 行

std.Io.Dispatch.Fiber.max_result_align

常量

第 192 行

Alignment

std.Io.Dispatch.Fiber.max_result_size

常量

第 193 行

std.Io.Dispatch.Fiber.min_stack_size

常量

第 196 行

包含所需的全部栈重新对齐,以及初始帧返回地址槽和参数帧,具体取决于目标。

std.Io.Dispatch.Fiber.next_name

变量

第 111 行

u64

std.Io.Dispatch.Fiber.PackedPtr

容器

第 238 行

类似 *Fiber,但比指针少 2 位(由于对齐,最低有效位始终为 0), 以便将这两位用于 packed struct。

字段

null = 0
all_ones = std.math.maxInt(@Int(.unsigned, @bitSizeOf(usize) - 2))
_

std.Io.Dispatch.Fiber.PackedPtr.pack

函数

第 244 行

fn pack(ptr: ?*Fiber) PackedPtr

参数

ptr: ?*Fiber

std.Io.Dispatch.Fiber.PackedPtr.Split

容器

第 243 行

字段

low: u2
high: PackedPtr

std.Io.Dispatch.Fiber.PackedPtr.unpack

函数

第 249 行

fn unpack(ptr: PackedPtr) ?*Fiber

参数

ptr: PackedPtr

std.Io.Dispatch.Fiber.Queue

容器

第 234 行

字段

head: *Fiber
tail: *Fiber

std.Io.Dispatch.Fiber.requestCancel

函数

第 255 行

fn requestCancel(fiber: *Fiber, ev: *Evented) void

参数

fiber: *Fiber
ev: *Evented

std.Io.Dispatch.Fiber.resultBytes

函数

第 230 行

fn resultBytes(f: *Fiber, alignment: Alignment) [*]u8

参数

f: *Fiber
alignment: Alignment

std.Io.Dispatch.Fiber.resultPointer

函数

第 226 行

fn resultPointer(f: *Fiber, comptime Result: type) *Result

参数

f: *Fiber
Result: type

std.Io.Dispatch.File

别名

第 17 行

别名目标 std.Io.File

std.Io.Dispatch.fileClose

函数

第 3270 行

fn fileClose(userdata: ?*anyopaque, files: []const File) void

参数

userdata: ?*anyopaque
files: []const File

std.Io.Dispatch.fileDowngradeLock

函数

第 3765 行

fn fileDowngradeLock(userdata: ?*anyopaque, file: File) File.DowngradeLockError!void

参数

userdata: ?*anyopaque
file: File

错误

Canceled Cancelable

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

Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileEnableAnsiEscapeCodes

函数

第 3615 行

fn fileEnableAnsiEscapeCodes(userdata: ?*anyopaque, file: File) File.EnableAnsiEscapeCodesError!void

参数

userdata: ?*anyopaque
file: File

错误

Canceled Cancelable

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

NotTerminalDevice
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileHardLink

函数

第 3805 行

fn fileHardLink( userdata: ?*anyopaque, file: File, new_dir: Dir, new_sub_path: []const u8, options: File.HardLinkOptions, ) File.HardLinkError!void

参数

userdata: ?*anyopaque
file: File
new_dir: Dir
new_sub_path: []const u8
options: File.HardLinkOptions

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice
DiskQuota
FileNotFound
HardwareFailure
LinkQuotaExceeded
NameTooLong PathNameError

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

NoSpaceLeft
NotDir
OperationUnsupported

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

PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileIsTty

函数

第 3602 行

fn fileIsTty(userdata: ?*anyopaque, file: File) Io.Cancelable!bool

参数

userdata: ?*anyopaque
file: File

错误

Canceled

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

std.Io.Dispatch.fileLength

函数

第 3264 行

fn fileLength(userdata: ?*anyopaque, file: File) File.LengthError!u64

参数

userdata: ?*anyopaque
file: File

错误

AccessDenied StatError

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

Canceled Cancelable

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

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileLock

函数

第 3710 行

fn fileLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!void

参数

userdata: ?*anyopaque
file: File
lock: File.Lock

错误

Canceled Cancelable

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

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileMemoryMapCreate

函数

第 3852 行

fn fileMemoryMapCreate( userdata: ?*anyopaque, file: File, options: File.MemoryMap.CreateOptions, ) File.MemoryMap.CreateError!File.MemoryMap

参数

userdata: ?*anyopaque
file: File
options: File.MemoryMap.CreateOptions

错误

AccessDenied

以下任一情况:

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

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

InputOutput ReadPositionalError
IsDir ReadPositionalError

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

LockViolation ReadPositionalError

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

LockedMemoryLimitExceeded
NotOpenForReading ReadPositionalError

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

OutOfMemory Error
PermissionDenied

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

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemResources ReadPositionalError
Unexpected UnexpectedError

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

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

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

Unseekable ReadPositionalError

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

WouldBlock ReadPositionalError

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

std.Io.Dispatch.fileMemoryMapDestroy

函数

第 3898 行

fn fileMemoryMapDestroy(userdata: ?*anyopaque, mm: *File.MemoryMap) void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap

std.Io.Dispatch.fileMemoryMapRead

函数

第 3930 行

fn fileMemoryMapRead(userdata: ?*anyopaque, mm: *File.MemoryMap) File.ReadPositionalError!void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap

错误

AccessDenied

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

Canceled Cancelable

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

InputOutput
IsDir

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

LockViolation

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

NotOpenForReading

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

SystemResources
Unexpected UnexpectedError

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

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

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

Unseekable

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

WouldBlock

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

std.Io.Dispatch.fileMemoryMapSetLength

函数

第 3911 行

fn fileMemoryMapSetLength( userdata: ?*anyopaque, mm: *File.MemoryMap, new_len: usize, ) File.MemoryMap.SetLengthError!void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap
new_len: usize

错误

AccessDenied

以下任一情况:

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

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

FileBusy SetLengthError
FileTooBig SetLengthError
InputOutput SetLengthError
LockedMemoryLimitExceeded
NonResizable SetLengthError
OperationUnsupported

无法原子地更改映射长度。调用方必须 使用 destroy 和 create 调整映射大小。

OutOfMemory Error
PermissionDenied

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

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileMemoryMapWrite

函数

第 3936 行

fn fileMemoryMapWrite(userdata: ?*anyopaque, mm: *File.MemoryMap) File.WritePositionalError!void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap

错误

AccessDenied

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

BrokenPipe

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

Canceled Cancelable

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

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

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

NoDevice

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

NoSpaceLeft
NotOpenForWriting

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

PermissionDenied
SystemResources

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

Unexpected UnexpectedError

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

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

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

Unseekable

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

WouldBlock

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

std.Io.Dispatch.fileReadPositional

函数

第 3526 行

fn fileReadPositional( userdata: ?*anyopaque, file: File, data: []const []u8, offset: u64, ) File.ReadPositionalError!usize

参数

userdata: ?*anyopaque
file: File
data: []const []u8
offset: u64

错误

AccessDenied

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

Canceled Cancelable

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

InputOutput
IsDir

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

LockViolation

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

NotOpenForReading

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

SystemResources
Unexpected UnexpectedError

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

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

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

Unseekable

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

WouldBlock

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

std.Io.Dispatch.fileReadStreaming

函数

第 1720 行

fn fileReadStreaming(ev: *Evented, file: File, data: []const []u8) File.ReadStreamingError!usize

参数

ev: *Evented
file: File
data: []const []u8

错误

AccessDenied UnendingError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

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

LockViolation UnendingError

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

NotOpenForReading UnendingError

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

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

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

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

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

WouldBlock UnendingError

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

std.Io.Dispatch.fileReadStreamingLimit

函数

第 1750 行

fn fileReadStreamingLimit( handle: File.Handle, data: []const []u8, limit: Io.Limit, ) File.ReadStreamingError!usize

参数

handle: File.Handle
data: []const []u8
limit: Io.Limit

错误

AccessDenied UnendingError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

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

LockViolation UnendingError

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

NotOpenForReading UnendingError

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

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

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

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

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

WouldBlock UnendingError

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

std.Io.Dispatch.fileRealPath

函数

第 3781 行

fn fileRealPath(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize

参数

userdata: ?*anyopaque
file: File
out_buffer: []u8

错误

AccessDenied
AntivirusInterference

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

Canceled Cancelable

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

DeviceBusy
FileBusy
FileNotFound
FileSystem
FileTooBig
InputOutput
IsDir
NameTooLong

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
OperationUnsupported

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

PathAlreadyExists
PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume

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

std.Io.Dispatch.fileSeekBy

函数

第 3562 行

fn fileSeekBy(userdata: ?*anyopaque, file: File, offset: i64) File.SeekError!void

参数

userdata: ?*anyopaque
file: File
offset: i64

错误

AccessDenied

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

Canceled Cancelable

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

Unexpected UnexpectedError

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

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

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

Unseekable

std.Io.Dispatch.fileSeekTo

函数

第 3567 行

fn fileSeekTo(userdata: ?*anyopaque, file: File, offset: u64) File.SeekError!void

参数

userdata: ?*anyopaque
file: File
offset: u64

错误

AccessDenied

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

Canceled Cancelable

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

Unexpected UnexpectedError

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

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

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

Unseekable

std.Io.Dispatch.fileSetLength

函数

第 3620 行

fn fileSetLength(userdata: ?*anyopaque, file: File, length: u64) File.SetLengthError!void

参数

userdata: ?*anyopaque
file: File
length: u64

错误

AccessDenied
Canceled Cancelable

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

FileBusy
FileTooBig
InputOutput
NonResizable
PermissionDenied
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileSetOwner

函数

第 3640 行

fn fileSetOwner( userdata: ?*anyopaque, file: File, owner: ?File.Uid, group: ?File.Gid, ) File.SetOwnerError!void

参数

userdata: ?*anyopaque
file: File
owner: ?File.Uid
group: ?File.Gid

错误

AccessDenied
Canceled Cancelable

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

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileSetPermissions

函数

第 3651 行

fn fileSetPermissions( userdata: ?*anyopaque, file: File, permissions: File.Permissions, ) File.SetPermissionsError!void

参数

userdata: ?*anyopaque
file: File
permissions: File.Permissions

错误

AccessDenied
Canceled Cancelable

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

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileSetTimestamps

函数

第 3680 行

fn fileSetTimestamps( userdata: ?*anyopaque, file: File, options: File.SetTimestampsOptions, ) File.SetTimestampsError!void

参数

userdata: ?*anyopaque
file: File
options: File.SetTimestampsOptions

错误

AccessDenied

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

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

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

PermissionDenied

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

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

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

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

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

std.Io.Dispatch.fileStat

函数

第 3247 行

fn fileStat(userdata: ?*anyopaque, file: File) File.StatError!File.Stat

参数

userdata: ?*anyopaque
file: File

错误

AccessDenied

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

Canceled Cancelable

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

PermissionDenied
Streaming

尝试对非文件流调用 stat。

SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileSync

函数

第 3586 行

fn fileSync(userdata: ?*anyopaque, file: File) File.SyncError!void

参数

userdata: ?*anyopaque
file: File

错误

AccessDenied
Canceled Cancelable

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

DiskQuota
InputOutput
NoSpaceLeft
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileTryLock

函数

第 3730 行

fn fileTryLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!bool

参数

userdata: ?*anyopaque
file: File
lock: File.Lock

错误

Canceled Cancelable

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

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.fileUnlock

函数

第 3750 行

fn fileUnlock(userdata: ?*anyopaque, file: File) void

参数

userdata: ?*anyopaque
file: File

std.Io.Dispatch.fileWriteFilePositional

函数

第 3439 行

fn fileWriteFilePositional( userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *File.Reader, limit: Io.Limit, offset: u64, ) File.WriteFilePositionalError!usize

参数

userdata: ?*anyopaque
file: File
header: []const u8
file_reader: *File.Reader
limit: Io.Limit
offset: u64

错误

AccessDenied Error

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

BrokenPipe Error

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

Canceled Cancelable

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

CorruptedData WriteFileError

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

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

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

NoDevice Error

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

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
ReadFailed WriteFileError
SystemResources Error

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

Unexpected UnexpectedError

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

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

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

Unimplemented WriteFileError

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

Unseekable
WouldBlock Error

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

std.Io.Dispatch.fileWriteFileStreaming

函数

第 3346 行

fn fileWriteFileStreaming( userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *File.Reader, limit: Io.Limit, ) File.Writer.WriteFileError!usize

参数

userdata: ?*anyopaque
file: File
header: []const u8
file_reader: *File.Reader
limit: Io.Limit

错误

AccessDenied Error

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

BrokenPipe Error

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

Canceled Cancelable

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

CorruptedData

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

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

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

NoDevice Error

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

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
ReadFailed
SystemResources Error

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

Unexpected UnexpectedError

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

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

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

Unimplemented

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

WouldBlock Error

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

std.Io.Dispatch.fileWritePositional

函数

第 3276 行

fn fileWritePositional( userdata: ?*anyopaque, file: File, header: []const u8, data: []const []const u8, splat: usize, offset: u64, ) File.WritePositionalError!usize

参数

userdata: ?*anyopaque
file: File
header: []const u8
data: []const []const u8
splat: usize
offset: u64

错误

AccessDenied

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

BrokenPipe

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

Canceled Cancelable

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

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

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

NoDevice

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

NoSpaceLeft
NotOpenForWriting

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

PermissionDenied
SystemResources

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

Unexpected UnexpectedError

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

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

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

Unseekable

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

WouldBlock

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

std.Io.Dispatch.fileWriteStreaming

函数

第 1782 行

fn fileWriteStreaming( ev: *Evented, file: File, header: []const u8, data: []const []const u8, splat: usize, ) File.Writer.Error!usize

参数

ev: *Evented
file: File
header: []const u8
data: []const []const u8
splat: usize

错误

AccessDenied Error

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

BrokenPipe Error

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

Canceled Cancelable

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

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

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

NoDevice Error

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

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

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

Unexpected UnexpectedError

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

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

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

WouldBlock Error

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

std.Io.Dispatch.fileWriteStreamingLimit

函数

第 1826 行

fn fileWriteStreamingLimit( handle: File.Handle, header: []const u8, data: []const []const u8, splat: usize, limit: Io.Limit, ) File.Writer.Error!usize

参数

handle: File.Handle
header: []const u8
data: []const []const u8
splat: usize
limit: Io.Limit

错误

AccessDenied Error

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

BrokenPipe Error

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

Canceled Cancelable

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

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

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

NoDevice Error

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

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
SystemResources Error

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

Unexpected UnexpectedError

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

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

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

WouldBlock Error

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

std.Io.Dispatch.ForkBailError

错误集合

第 4321 行

fork() 与 execv() 之间可能发生的错误。

错误

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,并发争相创建同一文件。
FileSystem SetCurrentDirError
FileTooBig OpenError

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

InvalidBatchScriptArg SpawnError

仅限 Windows。执行 .bat 或 .cmd 脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。

  • NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
  • CR 会被 cmd.exe 移除,因此执行后所有 CR 码点都会丢失。
InvalidExe SpawnError
InvalidName SpawnError
InvalidProcessGroupId SpawnError
InvalidUserId SpawnError
InvalidWtf8 SpawnError

仅限 Windows。提供的 cwd 或 argv 为无效 WTF-8。 https://wtf-8.codeberg.page/

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound OpenError

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

NoDevice SpawnError

仅限 POSIX。选择了 StdIo.ignore,且打开 /dev/null 时返回 ENODEV。

NoSpaceLeft OpenError

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

NotDir OpenError

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

OperationUnsupported SpawnError

操作系统不支持创建子进程。

OutOfMemory SpawnError
PathAlreadyExists OpenError

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

PermissionDenied SpawnError
PipeBusy OpenError
ProcessAlreadyExec SpawnError

尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。

ProcessFdQuotaExceeded SpawnError
ReadOnlyFileSystem OpenError
ResourceLimitReached SpawnError
SymLinkLoop ChdirError
SystemFdQuotaExceeded SpawnError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

UnrecognizedVolume SpawnError

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

WouldBlock OpenError

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

std.Io.Dispatch.free

函数

第 337 行

fn free(userdata: *anyopaque, memory: []u8, alignment: std.mem.Alignment, ret_addr: usize) void

参数

userdata: *anyopaque
memory: []u8
alignment: std.mem.Alignment
ret_addr: usize

std.Io.Dispatch.Futex

容器

第 1488 行

字段

num_waiters: usize
queue: c.dispatch.queue_t
waiters: std.DoublyLinkedList

std.Io.Dispatch.Futex.deinit

函数

第 1622 行

fn deinit(futex: *Futex) void

参数

futex: *Futex

std.Io.Dispatch.Futex.init

函数

第 1610 行

fn init(futex: *Futex, queue: c.dispatch.queue_t) error{SystemResources}!void

参数

futex: *Futex
queue: c.dispatch.queue_t

错误

SystemResources

std.Io.Dispatch.Futex.Waiter

容器

第 1493 行

字段

sleeper: Sleeper = undefined
cancelable: Cancelable
futex: *Futex
node: std.DoublyLinkedList.Node = .{}
ptr: *const u32
expected: u32
timeout: c.dispatch.time_t = .FOREVER
leeway: u64
timer: ?c.dispatch.source_t = null

std.Io.Dispatch.Futex.Waiter.add

函数

第 1506 行

fn add(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Futex.Waiter.already_signaled

常量

第 1504 行

c.dispatch.source_t

std.Io.Dispatch.Futex.Waiter.canceled

函数

第 1541 行

fn canceled(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Futex.Waiter.remove

函数

第 1564 行

fn remove(waiter: *Waiter) void

参数

waiter: *Waiter

std.Io.Dispatch.Futex.Waiter.timedOut

函数

第 1550 行

fn timedOut(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Futex.Waiter.tryAdd

函数

第 1518 行

fn tryAdd(waiter: *Waiter) Cancelable.RequestedError!void

参数

waiter: *Waiter

错误

CancelRequested

std.Io.Dispatch.Futex.Waiter.tryRemove

函数

第 1559 行

fn tryRemove(waiter: *Waiter) Cancelable.RequestedError!void

参数

waiter: *Waiter

错误

CancelRequested

std.Io.Dispatch.Futex.Waiter.wake

函数

第 1569 行

fn wake(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Futex.Waker

容器

第 1576 行

字段

sleeper: Sleeper = undefined
futex: *Futex
ptr: *const u32
max_waiters: u32

std.Io.Dispatch.Futex.Waker.remove

函数

第 1582 行

fn remove(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.futexForAddress

函数

第 1629 行

fn futexForAddress(ev: *Evented, address: usize) *Futex

参数

ev: *Evented
address: usize

std.Io.Dispatch.futexWait

函数

第 1642 行

fn futexWait( userdata: ?*anyopaque, ptr: *const u32, expected: u32, timeout: Io.Timeout, ) Io.Cancelable!void

参数

userdata: ?*anyopaque
ptr: *const u32
expected: u32
timeout: Io.Timeout

错误

Canceled

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

std.Io.Dispatch.futexWaitUncancelable

函数

第 1662 行

fn futexWaitUncancelable(userdata: ?*anyopaque, ptr: *const u32, expected: u32) void

参数

userdata: ?*anyopaque
ptr: *const u32
expected: u32

std.Io.Dispatch.futexWake

函数

第 1678 行

fn futexWake(userdata: ?*anyopaque, ptr: *const u32, max_waiters: u32) void

参数

userdata: ?*anyopaque
ptr: *const u32
max_waiters: u32

std.Io.Dispatch.Group

容器

第 1127 行

字段

ptr: *Io.Group

std.Io.Dispatch.Group.addFiber

函数

第 1210 行

fn addFiber(group: Group, ev: *Evented, fiber: *Fiber) void

参数

group: Group
ev: *Evented
fiber: *Fiber

std.Io.Dispatch.Group.AsyncClosure

容器

第 1327 行

字段

evented: *Evented
group: Group
fiber: *Fiber
start: *const fn (context: *const anyopaque) void

std.Io.Dispatch.Group.AsyncClosure.call

函数

第 1363 行

fn call( closure: *Group.AsyncClosure, message: *const SwitchMessage, ) callconv(.withStackAlign(.c, @alignOf(Group.AsyncClosure))) noreturn

参数

closure: *Group.AsyncClosure
message: *const SwitchMessage

std.Io.Dispatch.Group.AsyncClosure.contextPointer

函数

第 1339 行

fn contextPointer( closure: *Group.AsyncClosure, ) [*]align(Fiber.max_context_align.toByteUnits()) u8

参数

closure: *Group.AsyncClosure

std.Io.Dispatch.Group.AsyncClosure.entry

函数

第 1345 行

fn entry() callconv(.naked) void

std.Io.Dispatch.Group.AsyncClosure.fromFiber

函数

第 1333 行

fn fromFiber(fiber: *Fiber) *Group.AsyncClosure

参数

fiber: *Fiber

std.Io.Dispatch.Group.await

函数

第 1265 行

fn await(group: Group, ev: *Evented, awaiter: *Fiber) bool

参数

group: Group
ev: *Evented
awaiter: *Fiber

std.Io.Dispatch.Group.Awaiter

容器

第 1153 行

字段

locked: bool
contended: bool
awaiter: Fiber.PackedPtr

std.Io.Dispatch.Group.awaiterPtr

函数

第 1158 行

fn awaiterPtr(group: Group) *Awaiter

参数

group: Group

std.Io.Dispatch.Group.cancel

函数

第 1279 行

fn cancel(group: Group, ev: *Evented, maybe_awaiter: ?*Fiber) bool

参数

group: Group
ev: *Evented
maybe_awaiter: ?*Fiber

std.Io.Dispatch.Group.cancelLocked

函数

第 1286 行

假定互斥锁已被持有。

fn cancelLocked(group: Group, ev: *Evented, maybe_awaiter: ?*Fiber) bool

参数

group: Group
ev: *Evented
maybe_awaiter: ?*Fiber

std.Io.Dispatch.Group.List

容器

第 1130 行

字段

cancel_requested: bool
awaiter_delayed: bool
fibers: Fiber.PackedPtr

std.Io.Dispatch.Group.listPtr

函数

第 1135 行

fn listPtr(group: Group) *List

参数

group: Group

std.Io.Dispatch.Group.lock

函数

第 1162 行

fn lock(group: Group, ev: *Evented) void

参数

group: Group
ev: *Evented

std.Io.Dispatch.Group.Mutex

容器

第 1139 行

字段

locked: bool
contended: bool
shared2: u30

std.Io.Dispatch.Group.mutexPtr

函数

第 1144 行

fn mutexPtr(group: Group) *Group.Mutex

参数

group: Group

std.Io.Dispatch.Group.registerAwaiter

函数

第 1315 行

假定互斥锁已被持有。

fn registerAwaiter(group: Group, awaiter: *Fiber) bool

参数

group: Group
awaiter: *Fiber

std.Io.Dispatch.Group.removeFiber

函数

第 1226 行

fn removeFiber(group: Group, ev: *Evented, fiber: *Fiber) ?*Fiber

参数

group: Group
ev: *Evented
fiber: *Fiber

std.Io.Dispatch.Group.unlock

函数

第 1197 行

fn unlock(group: Group, ev: *Evented) void

参数

group: Group
ev: *Evented

std.Io.Dispatch.groupAsync

函数

第 1378 行

fn groupAsync( userdata: ?*anyopaque, type_erased: *Io.Group, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque) void, ) void

参数

userdata: ?*anyopaque
type_erased: *Io.Group
context: []const u8
context_alignment: Alignment
start: *const fn (context: *const anyopaque) void

std.Io.Dispatch.groupAwait

函数

第 1440 行

fn groupAwait( userdata: ?*anyopaque, type_erased: *Io.Group, initial_token: *anyopaque, ) Io.Cancelable!void

参数

userdata: ?*anyopaque
type_erased: *Io.Group
initial_token: *anyopaque

错误

Canceled

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

std.Io.Dispatch.groupCancel

函数

第 1450 行

fn groupCancel(userdata: ?*anyopaque, type_erased: *Io.Group, initial_token: *anyopaque) void

参数

userdata: ?*anyopaque
type_erased: *Io.Group
initial_token: *anyopaque

std.Io.Dispatch.groupConcurrent

函数

第 1391 行

fn groupConcurrent( userdata: ?*anyopaque, type_erased: *Io.Group, context: []const u8, context_alignment: Alignment, start: *const fn (context: *const anyopaque) void, ) Io.ConcurrentError!void

参数

userdata: ?*anyopaque
type_erased: *Io.Group
context: []const u8
context_alignment: Alignment
start: *const fn (context: *const anyopaque) void

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.Dispatch.init

函数

第 487 行

pub fn init(ev: *Evented, backing_allocator: Allocator, options: InitOptions) !void

参数

ev: *Evented
backing_allocator: Allocator
options: InitOptions

std.Io.Dispatch.initLockedStderr

函数

第 3991 行

fn initLockedStderr(ev: *Evented, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr

参数

ev: *Evented
terminal_mode: ?Io.Terminal.Mode

错误

Canceled

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

std.Io.Dispatch.InitOptions

容器

第 471 行

字段

backing_allocator_needs_mutex: bool = true
target_queue: ?c.dispatch.queue_t = .TARGET_DEFAULT
leeway: Io.Duration = .fromMilliseconds(10)

允许延迟处理超时的上限,用于改善功耗 和系统性能。

argv0: Argv0 = .empty

影响以下操作:

environ: process.Environ = .empty

std.Io.Dispatch.initStderrWriter

函数

第 3999 行

fn initStderrWriter(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.io

函数

第 344 行

pub fn io(ev: *Evented) Io

参数

ev: *Evented

std.Io.Dispatch.Io

别名

第 18 行

别名目标 std.Io

std.Io.Dispatch.iovec

别名

第 19 行

别名目标 std.posix.iovec

std.Io.Dispatch.iovec_const

别名

第 20 行

别名目标 std.posix.iovec_const

std.Io.Dispatch.iovlen_t

常量

第 4960 行

此处为 usize 或 u32,二者均可。因此对写入文件 和发送网络消息均使用同一个 addBuf 函数。

std.Io.Dispatch.linkat

函数

第 3821 行

fn linkat( old_dir: c.fd_t, old_path: [*:0]const u8, new_dir: c.fd_t, new_path: [*:0]const u8, flags: u32, ) File.HardLinkError!void

参数

old_dir: c.fd_t
old_path: [*:0]const u8
new_dir: c.fd_t
new_path: [*:0]const u8
flags: u32

错误

AccessDenied
BadPathName PathNameError

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

Canceled Cancelable

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

CrossDevice
DiskQuota
FileNotFound
HardwareFailure
LinkQuotaExceeded
NameTooLong PathNameError

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

NoSpaceLeft
NotDir
OperationUnsupported

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

PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.lockStderr

函数

第 3974 行

fn lockStderr(userdata: ?*anyopaque, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr

参数

userdata: ?*anyopaque
terminal_mode: ?Io.Terminal.Mode

错误

Canceled

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

std.Io.Dispatch.log

类型

第 21 行

std.Io.Dispatch.lseek

函数

第 3572 行

fn lseek(ev: *Evented, fd: c.fd_t, offset: u64, whence: i32) File.SeekError!void

参数

ev: *Evented
fd: c.fd_t
offset: u64
whence: i32

错误

AccessDenied

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

Canceled Cancelable

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

Unexpected UnexpectedError

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

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

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

Unseekable

std.Io.Dispatch.main_loop_stack_size

常量

第 39 行

实际观察到 llvm aarch64 后端使用超过 4KB。

std.Io.Dispatch.mainLoop

函数

第 618 行

fn mainLoop(ev: *Evented, message: *const SwitchMessage) callconv(.c) noreturn

参数

ev: *Evented
message: *const SwitchMessage

std.Io.Dispatch.mainLoopEntry

函数

第 598 行

fn mainLoopEntry() callconv(.naked) void

std.Io.Dispatch.max_iovecs_len

别名

第 22 行

别名目标 std.Io.Threaded.max_iovecs_len

std.Io.Dispatch.Mutex

容器

第 811 行

字段

state: State
queue: c.dispatch.queue_t
waiters: std.DoublyLinkedList

std.Io.Dispatch.Mutex.deinit

函数

第 922 行

fn deinit(mutex: *Mutex) void

参数

mutex: *Mutex

std.Io.Dispatch.Mutex.init

函数

第 910 行

fn init(mutex: *Mutex, queue: c.dispatch.queue_t) error{SystemResources}!void

参数

mutex: *Mutex
queue: c.dispatch.queue_t

错误

SystemResources

std.Io.Dispatch.Mutex.lock

函数

第 938 行

fn lock(mutex: *Mutex, ev: *Evented) Io.Cancelable!void

参数

mutex: *Mutex
ev: *Evented

错误

Canceled

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

std.Io.Dispatch.Mutex.lockUncancelable

函数

第 948 行

fn lockUncancelable(mutex: *Mutex, ev: *Evented) void

参数

mutex: *Mutex
ev: *Evented

std.Io.Dispatch.Mutex.State

容器

第 816 行

字段

locked: bool
num_waiters: NumWaiters

std.Io.Dispatch.Mutex.State.NumWaiters

常量

第 820 行

std.Io.Dispatch.Mutex.tryLock

函数

第 929 行

fn tryLock(mutex: *Mutex) bool

参数

mutex: *Mutex

std.Io.Dispatch.Mutex.unlock

函数

第 957 行

fn unlock(mutex: *Mutex) void

参数

mutex: *Mutex

std.Io.Dispatch.Mutex.Waiter

容器

第 823 行

字段

sleeper: Sleeper = undefined
cancelable: Cancelable
mutex: *Mutex
node: std.DoublyLinkedList.Node = .{}

std.Io.Dispatch.Mutex.Waiter.add

函数

第 829 行

fn add(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Mutex.Waiter.canceled

函数

第 855 行

fn canceled(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Mutex.Waiter.remove

函数

第 872 行

fn remove(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.Mutex.Waiter.wake

函数

第 905 行

fn wake(waiter: *Waiter) void

参数

waiter: *Waiter

std.Io.Dispatch.nanosecondsFromPosix

别名

第 23 行

别名目标 std.Io.Threaded.nanosecondsFromPosix

std.Io.Dispatch.net

别名

第 24 行

别名目标 std.Io.net

std.Io.Dispatch.netAcceptUnavailable

函数

第 4806 行

fn netAcceptUnavailable( userdata: ?*anyopaque, listen_handle: net.Socket.Handle, options: net.Server.AcceptOptions, ) net.Server.AcceptError!net.Socket

参数

userdata: ?*anyopaque
listen_handle: net.Socket.Handle
options: net.Server.AcceptOptions

错误

BlockedByFirewall

防火墙规则禁止连接。

Canceled Cancelable

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

ConnectionAborted

曾有传入连接,但在接受调用之前, 远端对等方已将其终止。

NetworkDown

网络子系统已失败。

ProcessFdQuotaExceeded

已达到每个进程可打开的文件描述符数量限制。

ProtocolFailure
SocketNotListening

从未调用 listen,或已调用 shutdown,后者可能发生于 本调用阻塞期间。因此,可将 shutdown 用作 并发取消机制。

SystemFdQuotaExceeded

已达到系统范围内打开文件总数的上限。

SystemResources

可用内存不足。这通常意味着内存分配受限于 套接字缓冲区上限,而非系统内存。

Unexpected UnexpectedError

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

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

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

WouldBlock

没有已排队且可立即接受的连接, 而套接字配置为非阻塞模式。

std.Io.Dispatch.netBindIpUnavailable

函数

第 4818 行

fn netBindIpUnavailable( userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.BindOptions, ) net.IpAddress.BindError!net.Socket

参数

userdata: ?*anyopaque
address: *const net.IpAddress
options: net.IpAddress.BindOptions

错误

AccessDenied

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported

该地址对于套接字的地址族无效。

AddressInUse

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

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

NetworkDown

用于到达目标的本地网络接口已离线。

OptionUnsupported

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内已打开文件的总数上限。

SystemResources

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.netClose

函数

第 4889 行

fn netClose(userdata: ?*anyopaque, sockets: []const net.Socket) void

参数

userdata: ?*anyopaque
sockets: []const net.Socket

std.Io.Dispatch.netConnectIpUnavailable

函数

第 4830 行

fn netConnectIpUnavailable( userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ConnectOptions, ) net.IpAddress.ConnectError!net.Socket

参数

userdata: ?*anyopaque
address: *const net.IpAddress
options: net.IpAddress.ConnectOptions

错误

AccessDenied

用户尝试连接广播地址,但未启用套接字广播标志;或 连接请求因本地防火墙规则而失败。

AddressFamilyUnsupported
AddressUnavailable
Canceled Cancelable

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

ConnectionPending
ConnectionRefused
ConnectionResetByPeer
HostUnreachable
NetworkDown
NetworkUnreachable
OptionUnsupported

Io 实现不支持某个 ConnectOptions 选项。

ProcessFdQuotaExceeded

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内已打开文件的总数上限。

SystemResources

操作系统内部内存或其他资源不足。

Timeout
Unexpected UnexpectedError

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

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

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

WouldBlock

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

std.Io.Dispatch.netConnectUnixUnavailable

函数

第 4854 行

fn netConnectUnixUnavailable( userdata: ?*anyopaque, address: *const net.UnixAddress, ) net.UnixAddress.ConnectError!net.Socket.Handle

参数

userdata: ?*anyopaque
address: *const net.UnixAddress

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

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

ConnectionRefused
FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ProtocolUnsupportedBySystem
ReadOnlyFileSystem
SocketModeUnsupported
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

WouldBlock

std.Io.Dispatch.netInterfaceNameResolveUnavailable

函数

第 4907 行

fn netInterfaceNameResolveUnavailable( userdata: ?*anyopaque, name: *const net.Interface.Name, ) net.Interface.Name.ResolveError!net.Interface

参数

userdata: ?*anyopaque
name: *const net.Interface.Name

错误

AccessDenied
Canceled Cancelable

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

InterfaceNotFound
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.netInterfaceNameUnavailable

函数

第 4917 行

fn netInterfaceNameUnavailable( userdata: ?*anyopaque, interface: net.Interface, ) net.Interface.NameError!net.Interface.Name

参数

userdata: ?*anyopaque
interface: net.Interface

错误

Canceled Cancelable

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

InterfaceNotFound

index 超出范围。

NameTooLong

接口名称长于 Name.max_len。

Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.netListenIpUnavailable

函数

第 4794 行

fn netListenIpUnavailable( userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ListenOptions, ) net.IpAddress.ListenError!net.Socket

参数

userdata: ?*anyopaque
address: *const net.IpAddress
options: net.IpAddress.ListenOptions

错误

AccessDenied

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported

操作系统不支持请求的地址族(IPv4 或 IPv6)。

AddressInUse

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

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

NetworkDown

用于到达目标的本地网络接口已离线。

OptionUnsupported

Io 实现不支持某个 ListenOptions。

ProcessFdQuotaExceeded

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内已打开文件的总数上限。

SystemResources

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.netListenUnixUnavailable

函数

第 4842 行

fn netListenUnixUnavailable( userdata: ?*anyopaque, address: *const net.UnixAddress, options: net.UnixAddress.ListenOptions, ) net.UnixAddress.ListenError!net.Socket.Handle

参数

userdata: ?*anyopaque
address: *const net.UnixAddress
options: net.UnixAddress.ListenOptions

错误

AccessDenied
AddressFamilyUnsupported
AddressInUse
AddressUnavailable
Canceled Cancelable

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

FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.netLookupUnavailable

函数

第 4927 行

fn netLookupUnavailable( userdata: ?*anyopaque, host_name: net.HostName, resolved: *Io.Queue(net.HostName.LookupResult), options: net.HostName.LookupOptions, ) net.HostName.LookupError!void

参数

userdata: ?*anyopaque
host_name: net.HostName
resolved: *Io.Queue(net.HostName.LookupResult)
options: net.HostName.LookupOptions

错误

AccessDenied BindError

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported BindError

该地址对于套接字的地址族无效。

AddressInUse BindError

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable BindError

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

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

DetectingNetworkConfigurationFailed

无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。

InvalidDnsAAAARecord
InvalidDnsARecord
InvalidDnsCnameRecord
NameServerFailure
NetworkDown BindError

用于到达目标的本地网络接口已离线。

NoAddressReturned
OptionUnsupported BindError

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded BindError

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

已达到系统范围内已打开文件的总数上限。

SystemResources BindError

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

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

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

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

UnknownHostName

std.Io.Dispatch.netShutdownUnavailable

函数

第 4895 行

fn netShutdownUnavailable( userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow, ) net.ShutdownError!void

参数

userdata: ?*anyopaque
handle: net.Socket.Handle
how: net.ShutdownHow

错误

Canceled Cancelable

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

ConnectionAborted
ConnectionResetByPeer
NetworkDown
SocketUnconnected
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.netSocketCreatePairUnavailable

函数

第 4864 行

fn netSocketCreatePairUnavailable( userdata: ?*anyopaque, options: net.Socket.CreatePairOptions, ) net.Socket.CreatePairError![2]net.Socket

参数

userdata: ?*anyopaque
options: net.Socket.CreatePairOptions

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

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

OperationUnsupported
ProcessFdQuotaExceeded

已达到每个进程可打开的文件描述符数量限制。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内打开文件总数的上限。

SystemResources

可用内存不足。在释放足够资源前, 无法创建套接字。

Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.netWriteFileUnavailable

函数

第 4873 行

fn netWriteFileUnavailable( userdata: ?*anyopaque, socket_handle: net.Socket.Handle, header: []const u8, file_reader: *File.Reader, limit: Io.Limit, ) net.Stream.Writer.WriteFileError!usize

参数

userdata: ?*anyopaque
socket_handle: net.Socket.Handle
header: []const u8
file_reader: *File.Reader
limit: Io.Limit

错误

AddressFamilyUnsupported Error

传入地址的 sa_family 字段未包含正确的地址族。

Canceled Cancelable

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

ConnectionRefused Error

目标地址未在监听。

ConnectionResetByPeer Error

网络会话被接收方意外关闭。

ConnectionTimedOut Error

远端对等方未响应正在进行的通信,导致 操作系统中止连接。

EndOfStream

已到达正在读取的文件末尾。

FastOpenAlreadyInProgress Error

另一个 TCP 快速打开已在进行。

HostUnreachable Error

可到达网络,但没有到主机的路由。

NetworkDown Error

用于到达目标的本地网络接口已关闭。

NetworkUnreachable Error

没有到网络的路由。

ReadFailed

源 File.Reader 失败; 详细诊断信息见该结构体。

SocketNotBound Error
SocketUnconnected Error

面向连接的套接字的本地端已关闭,或 该套接字从未连接。

SystemResources Error

网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。

可用内核内存不足时也会发生此错误。

Unexpected UnexpectedError

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

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

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

Unimplemented

Io 实现无法提供更高效的文件到套接字传输路径; 调用者应退回基于读取的复制。参见 Io.Writer.sendFile。

std.Io.Dispatch.now

函数

第 4646 行

fn now(userdata: ?*anyopaque, clock: Io.Clock) Io.Timestamp

参数

userdata: ?*anyopaque
clock: Io.Clock

std.Io.Dispatch.openDevNullFile

函数

第 4315 行

fn openDevNullFile(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.operate

函数

第 1692 行

fn operate(userdata: ?*anyopaque, operation: Io.Operation) Io.Cancelable!Io.Operation.Result

参数

userdata: ?*anyopaque
operation: Io.Operation

错误

Canceled

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

std.Io.Dispatch.pathToPosix

别名

第 25 行

别名目标 std.Io.Threaded.pathToPosix

std.Io.Dispatch.pipe2

函数

第 4427 行

fn pipe2(flags: c.O) PipeError![2]c.fd_t

参数

flags: c.O

错误

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.PipeError

错误集合

第 4422 行

错误

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.process

别名

第 26 行

别名目标 std.process

std.Io.Dispatch.processCurrentPath

函数

第 4031 行

fn processCurrentPath(userdata: ?*anyopaque, buffer: []u8) process.CurrentPathError!usize

参数

userdata: ?*anyopaque
buffer: []u8

错误

Canceled Cancelable

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

CurrentDirUnlinked

在 Windows 上不可能发生。在 WASI 上始终返回。

NameTooLong

缓冲区过小,无法容纳当前路径。

PathExceedsLimit

受底层 libc 或系统调用实现限制,无法获取当前路径。换用更大缓冲区重试也不会成功。

Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.processExecutableOpen

函数

第 3942 行

fn processExecutableOpen( userdata: ?*anyopaque, flags: Dir.OpenFileOptions, ) process.OpenExecutableError!File

参数

userdata: ?*anyopaque
flags: Dir.OpenFileOptions

错误

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,并发争相创建同一文件。
FileSystem ExecutablePathBaseError
FileTooBig OpenError

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

InputOutput ExecutablePathBaseError
IsDir OpenError

以下任一情况:

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

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

NetworkNotFound OpenError

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

NoDevice OpenError
NoSpaceLeft OpenError

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

NotDir OpenError

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

NotLink ExecutablePathBaseError
OperationUnsupported ExecutablePathBaseError

操作系统不支持可执行文件获取自身 路径。

PathAlreadyExists OpenError

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

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ProcessNotFound ExecutablePathBaseError
ReadOnlyFileSystem OpenError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

UnrecognizedVolume ExecutablePathBaseError

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

WouldBlock OpenError

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

std.Io.Dispatch.processExecutablePath

函数

第 3957 行

fn processExecutablePath(userdata: ?*anyopaque, out_buffer: []u8) process.ExecutablePathError!usize

参数

userdata: ?*anyopaque
out_buffer: []u8

错误

AccessDenied ExecutablePathBaseError
AntivirusInterference ExecutablePathBaseError

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

BadPathName ExecutablePathBaseError
Canceled Cancelable

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

DeviceBusy ExecutablePathBaseError
FileNotFound ExecutablePathBaseError
FileSystem ExecutablePathBaseError
FileTooBig ExecutablePathBaseError
InputOutput ExecutablePathBaseError
IsDir ExecutablePathBaseError
NameTooLong
NetworkNotFound ExecutablePathBaseError

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

NoDevice ExecutablePathBaseError
NoSpaceLeft ExecutablePathBaseError
NotDir ExecutablePathBaseError
NotLink ExecutablePathBaseError
OperationUnsupported ExecutablePathBaseError

操作系统不支持可执行文件获取自身 路径。

PathAlreadyExists ExecutablePathBaseError
PermissionDenied ExecutablePathBaseError
PipeBusy ExecutablePathBaseError
ProcessFdQuotaExceeded ExecutablePathBaseError
ProcessNotFound ExecutablePathBaseError
SymLinkLoop ExecutablePathBaseError
SystemFdQuotaExceeded ExecutablePathBaseError
SystemResources ExecutablePathBaseError
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume ExecutablePathBaseError

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

std.Io.Dispatch.processReplace

函数

第 4081 行

fn processReplace(userdata: ?*anyopaque, options: process.ReplaceOptions) process.ReplaceError

参数

userdata: ?*anyopaque
options: process.ReplaceOptions

std.Io.Dispatch.processReplacePath

函数

第 4109 行

fn processReplacePath( userdata: ?*anyopaque, dir: Dir, options: process.ReplaceOptions, ) process.ReplaceError

参数

userdata: ?*anyopaque
dir: Dir
options: process.ReplaceOptions

std.Io.Dispatch.processSetCurrentDir

函数

第 4045 行

fn processSetCurrentDir(userdata: ?*anyopaque, dir: Dir) process.SetCurrentDirError!void

参数

userdata: ?*anyopaque
dir: Dir

错误

AccessDenied
BadPathName
Canceled Cancelable

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

FileNotFound
FileSystem
NameTooLong
NoDevice
NotDir
OperationUnsupported
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume

std.Io.Dispatch.processSetCurrentPath

函数

第 4060 行

fn processSetCurrentPath(userdata: ?*anyopaque, dir_path: []const u8) process.SetCurrentPathError!void

参数

userdata: ?*anyopaque
dir_path: []const u8

错误

AccessDenied
BadPathName
Canceled Cancelable

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

FileNotFound
FileSystem
InvalidWtf8

仅限 Windows。路径不是有效的 WTF-8。 https://wtf-8.codeberg.page/

NameTooLong
NoDevice
NotDir
OperationUnsupported
SymLinkLoop
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.Dispatch.processSpawn

函数

第 4121 行

fn processSpawn(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child

参数

userdata: ?*anyopaque
options: process.SpawnOptions

错误

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,并发争相创建同一文件。
FileSystem
FileTooBig OpenError

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

InvalidBatchScriptArg

仅限 Windows。执行 .bat 或 .cmd 脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。

  • NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
  • CR 会被 cmd.exe 移除,因此执行后所有 CR 码点都会丢失。
InvalidExe
InvalidName
InvalidProcessGroupId
InvalidUserId
InvalidWtf8

仅限 Windows。提供的 cwd 或 argv 为无效 WTF-8。 https://wtf-8.codeberg.page/

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound OpenError

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

NoDevice

仅限 POSIX。选择了 StdIo.ignore,且打开 /dev/null 时返回 ENODEV。

NoSpaceLeft OpenError

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

NotDir OpenError

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

OperationUnsupported

操作系统不支持创建子进程。

OutOfMemory
PathAlreadyExists OpenError

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

PermissionDenied
PipeBusy OpenError
ProcessAlreadyExec

尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。

ProcessFdQuotaExceeded
ReadOnlyFileSystem OpenError
ResourceLimitReached
SymLinkLoop
SystemFdQuotaExceeded
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

UnrecognizedVolume

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

WouldBlock OpenError

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

std.Io.Dispatch.processSpawnPath

函数

第 4153 行

fn processSpawnPath( userdata: ?*anyopaque, dir: Dir, options: process.SpawnOptions, ) process.SpawnError!process.Child

参数

userdata: ?*anyopaque
dir: Dir
options: process.SpawnOptions

错误

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,并发争相创建同一文件。
FileSystem
FileTooBig OpenError

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

InvalidBatchScriptArg

仅限 Windows。执行 .bat 或 .cmd 脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。

  • NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
  • CR 会被 cmd.exe 移除,因此执行后所有 CR 码点都会丢失。
InvalidExe
InvalidName
InvalidProcessGroupId
InvalidUserId
InvalidWtf8

仅限 Windows。提供的 cwd 或 argv 为无效 WTF-8。 https://wtf-8.codeberg.page/

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound OpenError

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

NoDevice

仅限 POSIX。选择了 StdIo.ignore,且打开 /dev/null 时返回 ENODEV。

NoSpaceLeft OpenError

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

NotDir OpenError

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

OperationUnsupported

操作系统不支持创建子进程。

OutOfMemory
PathAlreadyExists OpenError

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

PermissionDenied
PipeBusy OpenError
ProcessAlreadyExec

尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。

ProcessFdQuotaExceeded
ReadOnlyFileSystem OpenError
ResourceLimitReached
SymLinkLoop
SystemFdQuotaExceeded
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

UnrecognizedVolume

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

WouldBlock OpenError

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

std.Io.Dispatch.prog_fileno

常量

第 4165 行

std.Io.Dispatch.progressParentFile

函数

第 4635 行

fn progressParentFile(userdata: ?*anyopaque) std.Progress.ParentFileError!File

参数

userdata: ?*anyopaque

错误

EnvironmentVariableMissing
UnrecognizedFormat
UnsupportedOperation

std.Io.Dispatch.random

函数

第 4779 行

fn random(userdata: ?*anyopaque, buffer: []u8) void

参数

userdata: ?*anyopaque
buffer: []u8

std.Io.Dispatch.Random

容器

第 4751 行

字段

evented: *Evented
thread: *Thread
buffer: []u8

std.Io.Dispatch.Random.seed

函数

第 4756 行

fn seed(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.randomSecure

函数

第 4788 行

fn randomSecure(userdata: ?*anyopaque, buffer: []u8) Io.RandomSecureError!void

参数

userdata: ?*anyopaque
buffer: []u8

错误

Canceled Cancelable

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

EntropyUnavailable

std.Io.Dispatch.readAll

函数

第 4940 行

fn readAll(ev: *Evented, file: File, buffer: []u8) File.ReadStreamingError!void

参数

ev: *Evented
file: File
buffer: []u8

错误

AccessDenied UnendingError

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

Canceled Cancelable

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

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

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

LockViolation UnendingError

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

NotOpenForReading UnendingError

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

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

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

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

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

WouldBlock UnendingError

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

std.Io.Dispatch.realPath

函数

第 2772 行

fn realPath(ev: *Evented, fd: c.fd_t, out_buffer: []u8) File.RealPathError!usize

参数

ev: *Evented
fd: c.fd_t
out_buffer: []u8

错误

AccessDenied
AntivirusInterference

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

Canceled Cancelable

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

DeviceBusy
FileBusy
FileNotFound
FileSystem
FileTooBig
InputOutput
IsDir
NameTooLong

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

NetworkNotFound

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

NoDevice
NoSpaceLeft
NotDir
OperationUnsupported

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

PathAlreadyExists
PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

UnrecognizedVolume

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

std.Io.Dispatch.recancel

函数

第 1456 行

fn recancel(userdata: ?*anyopaque) void

参数

userdata: ?*anyopaque

std.Io.Dispatch.recoverableOsBugDetected

别名

第 27 行

别名目标 std.Io.Threaded.recoverableOsBugDetected

std.Io.Dispatch.remap

函数

第 324 行

fn remap( userdata: *anyopaque, memory: []u8, alignment: Alignment, new_len: usize, ret_addr: usize, ) ?[*]u8

参数

userdata: *anyopaque
memory: []u8
alignment: Alignment
new_len: usize
ret_addr: usize

std.Io.Dispatch.resize

函数

第 311 行

fn resize( userdata: *anyopaque, memory: []u8, alignment: std.mem.Alignment, new_len: usize, ret_addr: usize, ) bool

参数

userdata: *anyopaque
memory: []u8
alignment: std.mem.Alignment
new_len: usize
ret_addr: usize

std.Io.Dispatch.scanEnviron

函数

第 4641 行

fn scanEnviron(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.setTimestampToPosix

别名

第 28 行

别名目标 std.Io.Threaded.setTimestampToPosix

std.Io.Dispatch.setUpChild

函数

第 4323 行

fn setUpChild(ev: *Evented, options: struct { stdin_pipe: c.fd_t, stdout_pipe: c.fd_t, stderr_pipe: c.fd_t, dev_null_fd: c.fd_t, prog_pipe: c.fd_t, argv_buf: [:null]?[*:0]const u8, env_block: process.Environ.Block, PATH: []const u8, spawn: process.SpawnOptions, }) ForkBailError

参数

ev: *Evented
options: struct {
    stdin_pipe: c.fd_t,
    stdout_pipe: c.fd_t,
    stderr_pipe: c.fd_t,
    dev_null_fd: c.fd_t,
    prog_pipe: c.fd_t,
    argv_buf: [:null]?[*:0]const u8,
    env_block: process.Environ.Block,
    PATH: []const u8,
    spawn: process.SpawnOptions,
}

std.Io.Dispatch.setUpChildIo

函数

第 4406 行

fn setUpChildIo( ev: *Evented, stdio: process.SpawnOptions.StdIo, pipe_fd: c.fd_t, std_fileno: i32, dev_null_fd: c.fd_t, ) !void

参数

ev: *Evented
stdio: process.SpawnOptions.StdIo
pipe_fd: c.fd_t
std_fileno: i32
dev_null_fd: c.fd_t

std.Io.Dispatch.sleep

函数

第 4706 行

fn sleep(userdata: ?*anyopaque, timeout: Io.Timeout) Io.Cancelable!void

参数

userdata: ?*anyopaque
timeout: Io.Timeout

错误

Canceled

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

std.Io.Dispatch.Sleeper

容器

第 793 行

字段

queue: c.dispatch.queue_t
fiber: *Fiber

std.Io.Dispatch.Sleeper.init

函数

第 797 行

fn init(queue: c.dispatch.queue_t, fiber: *Fiber) Sleeper

参数

queue: c.dispatch.queue_t
fiber: *Fiber

std.Io.Dispatch.Sleeper.wake

函数

第 802 行

fn wake(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.SleepWaiter

容器

第 4669 行

字段

sleeper: Sleeper = undefined
cancelable: Cancelable
timer: c.dispatch.source_t
started: bool = false

std.Io.Dispatch.SleepWaiter.canceled

函数

第 4691 行

fn canceled(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.SleepWaiter.start

函数

第 4675 行

fn start(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.SleepWaiter.timedOut

函数

第 4683 行

fn timedOut(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.SleepWaiter.wake

函数

第 4698 行

fn wake(context: ?*anyopaque) callconv(.c) void

参数

context: ?*anyopaque

std.Io.Dispatch.spawn

函数

第 4174 行

fn spawn(ev: *Evented, options: process.SpawnOptions) process.SpawnError!Spawned

参数

ev: *Evented
options: process.SpawnOptions

错误

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,并发争相创建同一文件。
FileSystem
FileTooBig OpenError

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

InvalidBatchScriptArg

仅限 Windows。执行 .bat 或 .cmd 脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。

  • NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
  • CR 会被 cmd.exe 移除,因此执行后所有 CR 码点都会丢失。
InvalidExe
InvalidName
InvalidProcessGroupId
InvalidUserId
InvalidWtf8

仅限 Windows。提供的 cwd 或 argv 为无效 WTF-8。 https://wtf-8.codeberg.page/

IsDir OpenError

以下任一情况:

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

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

NetworkNotFound OpenError

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

NoDevice

仅限 POSIX。选择了 StdIo.ignore,且打开 /dev/null 时返回 ENODEV。

NoSpaceLeft OpenError

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

NotDir OpenError

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

OperationUnsupported

操作系统不支持创建子进程。

OutOfMemory
PathAlreadyExists OpenError

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

PermissionDenied
PipeBusy OpenError
ProcessAlreadyExec

尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。

ProcessFdQuotaExceeded
ReadOnlyFileSystem OpenError
ResourceLimitReached
SymLinkLoop
SystemFdQuotaExceeded
SystemResources OpenError

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

Unexpected UnexpectedError

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

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

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

UnrecognizedVolume

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

WouldBlock OpenError

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

std.Io.Dispatch.Spawned

容器

第 4167 行

字段

pid: c.pid_t
err_pipe: File
stdin: ?File
stdout: ?File
stderr: ?File

std.Io.Dispatch.splat_buffer_size

别名

第 29 行

别名目标 std.Io.Threaded.splat_buffer_size

std.Io.Dispatch.statFromPosix

别名

第 30 行

别名目标 std.Io.Threaded.statFromPosix

std.Io.Dispatch.statusToTerm

别名

第 31 行

别名目标 std.Io.Threaded.statusToTerm

std.Io.Dispatch.std

别名

第 32 行

别名目标 std

std.Io.Dispatch.swapCancelProtection

函数

第 1462 行

fn swapCancelProtection(userdata: ?*anyopaque, new: Io.CancelProtection) Io.CancelProtection

参数

userdata: ?*anyopaque
new: Io.CancelProtection

std.Io.Dispatch.SwitchMessage

容器

第 625 行

字段

contexts: Io.fiber.Switch
pending_task: PendingTask

std.Io.Dispatch.SwitchMessage.handle

函数

第 645 行

fn handle(message: *const SwitchMessage, ev: *Evented) void

参数

message: *const SwitchMessage
ev: *Evented

std.Io.Dispatch.SwitchMessage.PendingTask

容器

第 629 行

字段

nothing
await: *Fiber
activate: c.dispatch.object_t
@"resume": c.dispatch.object_t
group_await: Group
group_cancel: Group
mutex_wait: *Mutex.Waiter
futex_wait: *Futex.Waiter
futex_wake: *Futex.Waker
sleep_wait: *SleepWaiter
after: c.dispatch.time_t
destroy
exit

std.Io.Dispatch.Thread

容器

第 70 行

字段

main_context: Io.fiber.Context
current_context: ?*Io.fiber.Context
seed_csprng: c.dispatch.once_t
csprng: Csprng

std.Io.Dispatch.Thread.current

函数

第 83 行

noinline fn current() *Thread

std.Io.Dispatch.Thread.currentFiber

函数

第 87 行

fn currentFiber(thread: *Thread) *Fiber

参数

thread: *Thread

std.Io.Dispatch.Thread.List

容器

第 92 行

字段

allocated: []Thread
reserved: u32
active: u32

std.Io.Dispatch.Thread.self

变量

第 76 行

Thread

std.Io.Dispatch.timeFromTimeout

函数

第 4734 行

fn timeFromTimeout(ev: *Evented, timeout: Io.Timeout) c.dispatch.time_t

参数

ev: *Evented
timeout: Io.Timeout

std.Io.Dispatch.timestampFromPosix

别名

第 33 行

别名目标 std.Io.Threaded.timestampFromPosix

std.Io.Dispatch.tryLockStderr

函数

第 3981 行

fn tryLockStderr( userdata: ?*anyopaque, terminal_mode: ?Io.Terminal.Mode, ) Io.Cancelable!?Io.LockedStderr

参数

userdata: ?*anyopaque
terminal_mode: ?Io.Terminal.Mode

错误

Canceled

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

std.Io.Dispatch.unexpectedErrno

别名

第 34 行

别名目标 std.posix.unexpectedErrno

std.Io.Dispatch.unlockStderr

函数

第 4016 行

fn unlockStderr(userdata: ?*anyopaque) void

参数

userdata: ?*anyopaque

std.Io.Dispatch.UseFcopyfile

别名

第 36 行

别名目标 std.Io.Threaded.UseFcopyfile

std.Io.Dispatch.UseSendfile

别名

第 35 行

别名目标 std.Io.Threaded.UseSendfile

std.Io.Dispatch.writeAll

函数

第 4949 行

fn writeAll(ev: *Evented, file: File, buffer: []const u8) (File.Writer.Error || error{EndOfStream})!void

参数

ev: *Evented
file: File
buffer: []const u8

std.Io.Dispatch.yield

函数

第 586 行

fn yield(ev: *Evented, pending_task: SwitchMessage.PendingTask) void

参数

ev: *Evented
pending_task: SwitchMessage.PendingTask
源码

std/Io/Dispatch.zig

const Alignment = std.mem.Alignment;
const Allocator = std.mem.Allocator;
const Argv0 = Io.Threaded.Argv0;
const assert = std.debug.assert;
const builtin = @import("builtin");
const c = std.c;
const ChdirError = Io.Threaded.ChdirError;
const clockToPosix = Io.Threaded.clockToPosix;
const closeFd = Io.Threaded.closeFd;
const Csprng = Io.Threaded.Csprng;
const default_PATH = Io.Threaded.default_PATH;
const Dir = Io.Dir;
const Environ = Io.Threaded.Environ;
const errnoBug = Io.Threaded.errnoBug;
const Evented = @This();
const fallbackSeed = Io.Threaded.fallbackSeed;
const File = Io.File;
const Io = std.Io;
const iovec = std.posix.iovec;
const iovec_const = std.posix.iovec_const;
const log = std.log.scoped(.dispatch);
const max_iovecs_len = Io.Threaded.max_iovecs_len;
const nanosecondsFromPosix = Io.Threaded.nanosecondsFromPosix;
const net = Io.net;
const pathToPosix = Io.Threaded.pathToPosix;
const process = std.process;
const recoverableOsBugDetected = Io.Threaded.recoverableOsBugDetected;
const setTimestampToPosix = Io.Threaded.setTimestampToPosix;
const splat_buffer_size = Io.Threaded.splat_buffer_size;
const statFromPosix = Io.Threaded.statFromPosix;
const statusToTerm = Io.Threaded.statusToTerm;
const std = @import("std");
const timestampFromPosix = Io.Threaded.timestampFromPosix;
const unexpectedErrno = std.posix.unexpectedErrno;
const UseSendfile = Io.Threaded.UseSendfile;
const UseFcopyfile = Io.Threaded.UseFcopyfile;

/// 实际观察到 llvm aarch64 后端使用超过 4KB。
const main_loop_stack_size = 8 * 1024;

queue: c.dispatch.queue_t,
backing_allocator_needs_mutex: bool,
backing_allocator_mutex: Mutex,
/// 若未在其他地方使用,则无需线程安全。
backing_allocator: Allocator,
main_fiber: Fiber,
main_loop_stack: [*]align(builtin.target.stackAlignment()) u8,
exit_semaphore: c.dispatch.semaphore_t,

use_sendfile: UseSendfile,
use_fcopyfile: UseFcopyfile,
leeway: u64,

futexes: [1 << 8]Futex,

init_stderr_writer: c.dispatch.once_t,
stderr_mutex: Mutex,
stderr_writer: File.Writer,
stderr_mode: Io.Terminal.Mode,

scan_environ: c.dispatch.once_t,
environ: Environ,

open_dev_null: c.dispatch.once_t,
dev_null_file: File.OpenError!File,

csprng_mutex: Mutex,
csprng: Csprng,

const Thread = struct {
    main_context: Io.fiber.Context,
    current_context: ?*Io.fiber.Context,
    seed_csprng: c.dispatch.once_t,
    csprng: Csprng,

    threadlocal var self: Thread = .{
        .main_context = undefined,
        .current_context = null,
        .seed_csprng = .init,
        .csprng = undefined,
    };

    noinline fn current() *Thread {
        return &self;
    }

    fn currentFiber(thread: *Thread) *Fiber {
        assert(thread.current_context != &thread.main_context);
        return @fieldParentPtr("context", thread.current_context.?);
    }

    const List = struct {
        allocated: []Thread,
        reserved: u32,
        active: u32,
    };
};

const Fiber = struct {
    required_align: void align(4),
    evented: *Evented,
    context: Io.fiber.Context,
    link: union {
        awaiter: ?*Fiber,
        group: struct { prev: ?*Fiber, next: ?*Fiber },
    },
    awaiting_group: Group,
    cancel_status: CancelStatus,
    cancel_protection: CancelProtection,

    var next_name: u64 = 0;

    const CancelStatus = packed struct(usize) {
        requested: bool,
        awaiting: Awaiting,

        const unrequested: CancelStatus = .{ .requested = false, .awaiting = .nothing };

        const Awaiting = enum(@Int(.unsigned, @bitSizeOf(usize) - shift)) {
            nothing = 0,
            group = 1,
            _,

            const shift = 1;

            fn subWrap(lhs: Awaiting, rhs: Awaiting) Awaiting {
                return @fromBackingInt(@intCast(@backingInt(lhs) -% @backingInt(rhs)));
            }

            fn fromCancelable(cancelable: *Cancelable) Awaiting {
                return @fromBackingInt(@intCast(@shrExact(@intFromPtr(cancelable), shift)));
            }

            fn toCancelable(awaiting: Awaiting) *Cancelable {
                return @ptrFromInt(@shlExact(@as(usize, @backingInt(awaiting)), shift));
            }
        };

        fn changeAwaiting(
            cancel_status: *CancelStatus,
            old_awaiting: Awaiting,
            new_awaiting: Awaiting,
        ) bool {
            const old_cancel_status = @atomicRmw(CancelStatus, cancel_status, .Add, .{
                .requested = false,
                .awaiting = new_awaiting.subWrap(old_awaiting),
            }, .release);
            assert(old_cancel_status.awaiting == old_awaiting);
            return old_cancel_status.requested;
        }
    };

    const CancelProtection = packed struct {
        user: Io.CancelProtection,
        acknowledged: bool,

        const unblocked: CancelProtection = .{ .user = .unblocked, .acknowledged = false };

        fn check(cancel_protection: CancelProtection) Io.CancelProtection {
            return @fromBackingInt(@intCast(@intFromBool(cancel_protection != unblocked)));
        }

        fn acknowledge(cancel_protection: *CancelProtection) void {
            assert(!cancel_protection.acknowledged);
            cancel_protection.acknowledged = true;
        }

        fn recancel(cancel_protection: *CancelProtection) void {
            assert(cancel_protection.acknowledged);
            cancel_protection.acknowledged = false;
        }

        test check {
            try std.testing.expectEqual(Io.CancelProtection.unblocked, check(.unblocked));
            try std.testing.expectEqual(Io.CancelProtection.blocked, check(.{
                .user = .unblocked,
                .acknowledged = true,
            }));
            try std.testing.expectEqual(Io.CancelProtection.blocked, check(.{
                .user = .blocked,
                .acknowledged = false,
            }));
            try std.testing.expectEqual(Io.CancelProtection.blocked, check(.{
                .user = .blocked,
                .acknowledged = true,
            }));
        }
    };

    const finished: ?*Fiber = @ptrFromInt(@alignOf(Fiber));

    const max_result_align: Alignment = .@"16";
    const max_result_size = max_result_align.forward(512);
    /// 包含所需的全部栈重新对齐,以及初始帧返回地址槽和参数帧,具体取决于目标。
    ///
    const min_stack_size = 60 * 1024 * 1024;
    const max_context_align: Alignment = .@"16";
    const max_context_size = max_context_align.forward(1024);
    const max_closure_size: usize = @sizeOf(AsyncClosure);
    const max_closure_align: Alignment = .of(AsyncClosure);
    const allocation_size = std.mem.alignForward(
        usize,
        max_closure_align.max(max_context_align).forward(
            max_result_align.forward(@sizeOf(Fiber)) + max_result_size + min_stack_size,
        ) + max_closure_size + max_context_size,
        std.heap.page_size_max,
    );

    fn create(ev: *Evented) error{OutOfMemory}!*Fiber {
        return @ptrCast(try ev.allocator().alignedAlloc(u8, .of(Fiber), allocation_size));
    }

    fn destroy(fiber: *Fiber, ev: *Evented) void {
        ev.allocator().free(fiber.allocatedSlice());
    }

    fn allocatedSlice(f: *Fiber) []align(@alignOf(Fiber)) u8 {
        return @as([*]align(@alignOf(Fiber)) u8, @ptrCast(f))[0..allocation_size];
    }

    fn allocatedEnd(f: *Fiber) [*]u8 {
        const allocated_slice = f.allocatedSlice();
        return allocated_slice[allocated_slice.len..].ptr;
    }

    fn resultPointer(f: *Fiber, comptime Result: type) *Result {
        return @ptrCast(@alignCast(f.resultBytes(.of(Result))));
    }

    fn resultBytes(f: *Fiber, alignment: Alignment) [*]u8 {
        return @ptrFromInt(alignment.forward(@intFromPtr(f) + @sizeOf(Fiber)));
    }

    const Queue = struct { head: *Fiber, tail: *Fiber };

    /// 类似 `*Fiber`,但比指针少 2 位(由于对齐,最低有效位始终为 0),
    /// 以便将这两位用于 `packed struct`。
    const PackedPtr = enum(@Int(.unsigned, @bitSizeOf(usize) - 2)) {
        null = 0,
        all_ones = std.math.maxInt(@Int(.unsigned, @bitSizeOf(usize) - 2)),
        _,

        const Split = packed struct(usize) { low: u2, high: PackedPtr };
        fn pack(ptr: ?*Fiber) PackedPtr {
            const split: Split = @bitCast(@intFromPtr(ptr));
            assert(split.low == 0);
            return split.high;
        }
        fn unpack(ptr: PackedPtr) ?*Fiber {
            const split: Split = .{ .low = 0, .high = ptr };
            return @ptrFromInt(@as(usize, @bitCast(split)));
        }
    };

    fn requestCancel(fiber: *Fiber, ev: *Evented) void {
        const cancel_status = @atomicRmw(
            Fiber.CancelStatus,
            &fiber.cancel_status,
            .Or,
            .{ .requested = true, .awaiting = .nothing },
            .acquire,
        );
        assert(!cancel_status.requested);
        switch (cancel_status.awaiting) {
            .nothing => {},
            .group => {
                // 等待方在等待组期间收到取消请求,
                // 因此将取消传播到该组。
                if (fiber.awaiting_group.cancel(ev, null)) {
                    fiber.awaiting_group = undefined;
                    ev.queue.async(fiber, &Fiber.@"resume");
                }
            },
            _ => |awaiting| awaiting.toCancelable().async(),
        }
    }

    fn @"resume"(context: ?*anyopaque) callconv(.c) void {
        const fiber: *Fiber = @ptrCast(@alignCast(context));
        const thread: *Thread = .current();
        const message: SwitchMessage = .{
            .contexts = .{
                .old = &thread.main_context,
                .new = &fiber.context,
            },
            .pending_task = .nothing,
        };
        contextSwitch(&message).handle(fiber.evented);
    }
};

pub fn allocator(ev: *Evented) std.mem.Allocator {
    return if (ev.backing_allocator_needs_mutex) .{
        .ptr = ev,
        .vtable = &.{
            .alloc = alloc,
            .resize = resize,
            .remap = remap,
            .free = free,
        },
    } else ev.backing_allocator;
}

fn alloc(userdata: *anyopaque, len: usize, alignment: std.mem.Alignment, ret_addr: usize) ?[*]u8 {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    ev.backing_allocator_mutex.lockUncancelable(ev);
    defer ev.backing_allocator_mutex.unlock();
    return ev.backing_allocator.rawAlloc(len, alignment, ret_addr);
}

fn resize(
    userdata: *anyopaque,
    memory: []u8,
    alignment: std.mem.Alignment,
    new_len: usize,
    ret_addr: usize,
) bool {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    ev.backing_allocator_mutex.lockUncancelable(ev);
    defer ev.backing_allocator_mutex.unlock();
    return ev.backing_allocator.rawResize(memory, alignment, new_len, ret_addr);
}

fn remap(
    userdata: *anyopaque,
    memory: []u8,
    alignment: Alignment,
    new_len: usize,
    ret_addr: usize,
) ?[*]u8 {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    ev.backing_allocator_mutex.lockUncancelable(ev);
    defer ev.backing_allocator_mutex.unlock();
    return ev.backing_allocator.rawRemap(memory, alignment, new_len, ret_addr);
}

fn free(userdata: *anyopaque, memory: []u8, alignment: std.mem.Alignment, ret_addr: usize) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    ev.backing_allocator_mutex.lockUncancelable(ev);
    defer ev.backing_allocator_mutex.unlock();
    return ev.backing_allocator.rawFree(memory, alignment, ret_addr);
}

pub fn io(ev: *Evented) Io {
    return .{
        .userdata = ev,
        .vtable = &.{
            .crashHandler = crashHandler,

            .async = async,
            .concurrent = concurrent,
            .await = await,
            .cancel = cancel,

            .groupAsync = groupAsync,
            .groupConcurrent = groupConcurrent,
            .groupAwait = groupAwait,
            .groupCancel = groupCancel,

            .recancel = recancel,
            .swapCancelProtection = swapCancelProtection,
            .checkCancel = checkCancel,

            .futexWait = futexWait,
            .futexWaitUncancelable = futexWaitUncancelable,
            .futexWake = futexWake,

            .operate = operate,
            .batchAwaitAsync = batchAwaitAsync,
            .batchAwaitConcurrent = batchAwaitConcurrent,
            .batchCancel = batchCancel,

            .dirCreateDir = dirCreateDir,
            .dirCreateDirPath = dirCreateDirPath,
            .dirCreateDirPathOpen = dirCreateDirPathOpen,
            .dirOpenDir = dirOpenDir,
            .dirStat = dirStat,
            .dirStatFile = dirStatFile,
            .dirAccess = dirAccess,
            .dirCreateFile = dirCreateFile,
            .dirCreateFileAtomic = dirCreateFileAtomic,
            .dirOpenFile = dirOpenFile,
            .dirClose = dirClose,
            .dirRead = dirRead,
            .dirRealPath = dirRealPath,
            .dirRealPathFile = dirRealPathFile,
            .dirDeleteFile = dirDeleteFile,
            .dirDeleteDir = dirDeleteDir,
            .dirRename = dirRename,
            .dirRenamePreserve = dirRenamePreserve,
            .dirSymLink = dirSymLink,
            .dirReadLink = dirReadLink,
            .dirSetOwner = dirSetOwner,
            .dirSetFileOwner = dirSetFileOwner,
            .dirSetPermissions = dirSetPermissions,
            .dirSetFilePermissions = dirSetFilePermissions,
            .dirSetTimestamps = dirSetTimestamps,
            .dirHardLink = dirHardLink,

            .fileStat = fileStat,
            .fileLength = fileLength,
            .fileClose = fileClose,
            .fileWritePositional = fileWritePositional,
            .fileWriteFileStreaming = fileWriteFileStreaming,
            .fileWriteFilePositional = fileWriteFilePositional,
            .fileReadPositional = fileReadPositional,
            .fileSeekBy = fileSeekBy,
            .fileSeekTo = fileSeekTo,
            .fileSync = fileSync,
            .fileIsTty = fileIsTty,
            .fileEnableAnsiEscapeCodes = fileEnableAnsiEscapeCodes,
            .fileSupportsAnsiEscapeCodes = fileIsTty,
            .fileSetLength = fileSetLength,
            .fileSetOwner = fileSetOwner,
            .fileSetPermissions = fileSetPermissions,
            .fileSetTimestamps = fileSetTimestamps,
            .fileLock = fileLock,
            .fileTryLock = fileTryLock,
            .fileUnlock = fileUnlock,
            .fileDowngradeLock = fileDowngradeLock,
            .fileRealPath = fileRealPath,
            .fileHardLink = fileHardLink,

            .fileMemoryMapCreate = fileMemoryMapCreate,
            .fileMemoryMapDestroy = fileMemoryMapDestroy,
            .fileMemoryMapSetLength = fileMemoryMapSetLength,
            .fileMemoryMapRead = fileMemoryMapRead,
            .fileMemoryMapWrite = fileMemoryMapWrite,

            .processExecutableOpen = processExecutableOpen,
            .processExecutablePath = processExecutablePath,
            .lockStderr = lockStderr,
            .tryLockStderr = tryLockStderr,
            .unlockStderr = unlockStderr,
            .processCurrentPath = processCurrentPath,
            .processSetCurrentDir = processSetCurrentDir,
            .processSetCurrentPath = processSetCurrentPath,
            .processReplace = processReplace,
            .processReplacePath = processReplacePath,
            .processSpawn = processSpawn,
            .processSpawnPath = processSpawnPath,
            .childWait = childWait,
            .childKill = childKill,

            .progressParentFile = progressParentFile,

            .now = now,
            .clockResolution = clockResolution,
            .sleep = sleep,

            .random = random,
            .randomSecure = randomSecure,

            .netListenIp = netListenIpUnavailable,
            .netAccept = netAcceptUnavailable,
            .netBindIp = netBindIpUnavailable,
            .netConnectIp = netConnectIpUnavailable,
            .netListenUnix = netListenUnixUnavailable,
            .netConnectUnix = netConnectUnixUnavailable,
            .netSocketCreatePair = netSocketCreatePairUnavailable,
            .netWriteFile = netWriteFileUnavailable,
            .netClose = netClose,
            .netShutdown = netShutdownUnavailable,
            .netInterfaceNameResolve = netInterfaceNameResolveUnavailable,
            .netInterfaceName = netInterfaceNameUnavailable,
            .netLookup = netLookupUnavailable,
        },
    };
}

pub const InitOptions = struct {
    backing_allocator_needs_mutex: bool = true,
    target_queue: ?c.dispatch.queue_t = .TARGET_DEFAULT,
    /// 允许延迟处理超时的上限,用于改善功耗
    /// 和系统性能。
    leeway: Io.Duration = .fromMilliseconds(10),

    /// 影响以下操作:
    /// * OpenBSD 和 Haiku 上的 `processExecutablePath`。
    argv0: Argv0 = .empty,
    /// 影响以下操作:
    /// * `fileIsTty`
    /// * `processSpawn`、`processSpawnPath`、`processReplace`、`processReplacePath`
    environ: process.Environ = .empty,
};

pub fn init(ev: *Evented, backing_allocator: Allocator, options: InitOptions) !void {
    const queue = c.dispatch.queue_create_with_target(
        "org.ziglang.std.Io.Dispatch",
        .CONCURRENT(),
        options.target_queue,
    ) orelse return error.SystemResources;
    errdefer queue.as_object().release();
    const main_loop_stack = try backing_allocator.alignedAlloc(
        u8,
        .fromByteUnits(builtin.target.stackAlignment()),
        main_loop_stack_size,
    );
    errdefer backing_allocator.free(main_loop_stack);
    const exit_semaphore = c.dispatch.semaphore_create(0) orelse return error.SystemResources;
    errdefer exit_semaphore.as_object().release();
    ev.* = .{
        .queue = queue,
        .backing_allocator_needs_mutex = options.backing_allocator_needs_mutex,
        .backing_allocator_mutex = undefined,
        .backing_allocator = backing_allocator,
        .main_fiber = .{
            .required_align = {},
            .evented = ev,
            .context = undefined,
            .link = .{ .awaiter = null },
            .awaiting_group = undefined,
            .cancel_status = .unrequested,
            .cancel_protection = .unblocked,
        },
        .main_loop_stack = main_loop_stack.ptr,
        .exit_semaphore = exit_semaphore,

        .use_fcopyfile = .default,
        .use_sendfile = .default,
        .leeway = std.math.lossyCast(u64, options.leeway.toNanoseconds()),

        .futexes = undefined,

        .init_stderr_writer = .init,
        .stderr_mutex = undefined,
        .stderr_writer = .{
            .io = ev.io(),
            .interface = Io.File.Writer.initInterface(&.{}),
            .file = .stderr(),
            .mode = .streaming,
        },
        .stderr_mode = .no_color,

        .scan_environ = if (options.environ.block.isEmpty()) .done else .init,
        .environ = .{ .process_environ = options.environ },

        .open_dev_null = .init,
        .dev_null_file = error.FileNotFound,

        .csprng_mutex = undefined,
        .csprng = .uninitialized,
    };
    try ev.backing_allocator_mutex.init(queue);
    errdefer ev.backing_allocator_mutex.deinit();
    var initialized_futexes: usize = 0;
    errdefer for (ev.futexes[0..initialized_futexes]) |*futex| futex.deinit();
    for (&ev.futexes) |*futex| {
        try futex.init(queue);
        initialized_futexes += 1;
    }
    try ev.stderr_mutex.init(queue);
    errdefer ev.stderr_mutex.deinit();
    try ev.csprng_mutex.init(queue);
    errdefer ev.csprng_mutex.deinit();
    const thread: *Thread = .current();
    thread.main_context = switch (builtin.cpu.arch) {
        .aarch64 => .{
            .sp = @intFromPtr(main_loop_stack[main_loop_stack_size..].ptr),
            .fp = @intFromPtr(ev),
            .pc = @intFromPtr(&mainLoopEntry),
        },
        .x86_64 => .{
            .rsp = @intFromPtr(main_loop_stack[main_loop_stack_size..].ptr) - 8,
            .rbp = @intFromPtr(ev),
            .rip = @intFromPtr(&mainLoopEntry),
        },
        else => |arch| @compileError("unimplemented architecture: " ++ @tagName(arch)),
    };
    thread.current_context = &ev.main_fiber.context;
}

pub fn deinit(ev: *Evented) void {
    assert(Thread.current().currentFiber() == &ev.main_fiber);
    ev.yield(.exit);
    ev.csprng_mutex.deinit();
    if (ev.dev_null_file) |file| fileClose(ev, &.{file}) else |_| {}
    ev.stderr_mutex.deinit();
    for (&ev.futexes) |*futex| futex.deinit();
    ev.exit_semaphore.as_object().release();
    ev.backing_allocator_mutex.deinit();
    ev.backing_allocator.free(ev.main_loop_stack[0..main_loop_stack_size]);
    ev.queue.as_object().release();
}

fn yield(ev: *Evented, pending_task: SwitchMessage.PendingTask) void {
    const thread: *Thread = .current();
    const message: SwitchMessage = .{
        .contexts = .{
            .old = thread.current_context.?,
            .new = &thread.main_context,
        },
        .pending_task = pending_task,
    };
    contextSwitch(&message).handle(ev);
}

fn mainLoopEntry() callconv(.naked) void {
    switch (builtin.cpu.arch) {
        .aarch64 => asm volatile (
            \\ mov x0, fp
            \\ mov fp, #0
            \\ b %[mainLoop]
            :
            : [mainLoop] "X" (&mainLoop),
        ),
        .x86_64 => asm volatile (
            \\ movq %%rbp, %%rdi
            \\ xor %%ebp, %%ebp
            \\ jmp %[mainLoop:P]
            :
            : [mainLoop] "X" (&mainLoop),
        ),
        else => |arch| @compileError("unimplemented architecture: " ++ @tagName(arch)),
    }
}

fn mainLoop(ev: *Evented, message: *const SwitchMessage) callconv(.c) noreturn {
    message.handle(ev);
    assert(ev.exit_semaphore.wait(.FOREVER) == 0);
    Fiber.@"resume"(&ev.main_fiber);
    unreachable; // 切换至已终止的纤程
}

const SwitchMessage = struct {
    contexts: Io.fiber.Switch,
    pending_task: PendingTask,

    const PendingTask = union(enum) {
        nothing,
        await: *Fiber,
        activate: c.dispatch.object_t,
        @"resume": c.dispatch.object_t,
        group_await: Group,
        group_cancel: Group,
        mutex_wait: *Mutex.Waiter,
        futex_wait: *Futex.Waiter,
        futex_wake: *Futex.Waker,
        sleep_wait: *SleepWaiter,
        after: c.dispatch.time_t,
        destroy,
        exit,
    };

    fn handle(message: *const SwitchMessage, ev: *Evented) void {
        const thread: *Thread = .current();
        thread.current_context = message.contexts.new;
        switch (message.pending_task) {
            .nothing => {},
            .await => |awaiting| {
                const awaiter: *Fiber = @alignCast(@fieldParentPtr("context", message.contexts.old));
                if (@atomicRmw(?*Fiber, &awaiting.link.awaiter, .Xchg, awaiter, .acq_rel) ==
                    Fiber.finished) ev.queue.async(awaiter, &Fiber.@"resume");
            },
            .activate => |object| object.activate(),
            .@"resume" => |object| object.@"resume"(),
            .group_await => |group| {
                const fiber: *Fiber = @alignCast(@fieldParentPtr("context", message.contexts.old));
                if (group.await(ev, fiber)) ev.queue.async(fiber, &Fiber.@"resume");
            },
            .group_cancel => |group| {
                const fiber: *Fiber = @alignCast(@fieldParentPtr("context", message.contexts.old));
                if (group.cancel(ev, fiber)) ev.queue.async(fiber, &Fiber.@"resume");
            },
            .mutex_wait => |waiter| {
                waiter.sleeper =
                    .init(ev.queue, @alignCast(@fieldParentPtr("context", message.contexts.old)));
                switch (waiter.sleeper.fiber.cancel_protection.check()) {
                    .unblocked => {},
                    .blocked => waiter.cancelable = .blocked,
                }
                waiter.mutex.queue.async(waiter, &Mutex.Waiter.add);
            },
            .futex_wait => |waiter| {
                waiter.sleeper =
                    .init(ev.queue, @alignCast(@fieldParentPtr("context", message.contexts.old)));
                switch (waiter.sleeper.fiber.cancel_protection.check()) {
                    .unblocked => {},
                    .blocked => waiter.cancelable = .blocked,
                }
                waiter.futex.queue.async(waiter, &Futex.Waiter.add);
            },
            .futex_wake => |waker| {
                waker.sleeper =
                    .init(ev.queue, @alignCast(@fieldParentPtr("context", message.contexts.old)));
                waker.futex.queue.async(waker, &Futex.Waker.remove);
            },
            .sleep_wait => |waiter| {
                waiter.sleeper =
                    .init(ev.queue, @alignCast(@fieldParentPtr("context", message.contexts.old)));
                const queue = waiter.cancelable.queue;
                switch (waiter.sleeper.fiber.cancel_protection.check()) {
                    .unblocked => {},
                    .blocked => waiter.cancelable = .blocked,
                }
                queue.async(waiter, &SleepWaiter.start);
            },
            .after => |when| {
                const fiber: *Fiber = @alignCast(@fieldParentPtr("context", message.contexts.old));
                when.after(ev.queue, fiber, &Fiber.@"resume");
            },
            .destroy => {
                const fiber: *Fiber = @alignCast(@fieldParentPtr("context", message.contexts.old));
                fiber.destroy(ev);
            },
            .exit => _ = ev.exit_semaphore.signal(),
        }
    }
};

inline fn contextSwitch(message: *const SwitchMessage) *const SwitchMessage {
    return @fieldParentPtr("contexts", Io.fiber.contextSwitch(&message.contexts));
}

const Cancelable = struct {
    required_align: void align(2) = {},
    queue: c.dispatch.queue_t,
    cancel: c.dispatch.function_t,

    const fn_ptr_align = std.meta.alignment(c.dispatch.function_t);
    const is_blocked: c.dispatch.function_t = @ptrFromInt(fn_ptr_align * 1);
    const is_requested: c.dispatch.function_t = @ptrFromInt(fn_ptr_align * 2);

    const blocked: Cancelable = .{ .queue = undefined, .cancel = is_blocked };

    const RequestedError = error{CancelRequested};

    fn enter(cancelable: *Cancelable, fiber: *Fiber) RequestedError!void {
        const function = cancelable.cancel;
        assert(function != is_requested);
        if (function == is_blocked) {
            @branchHint(.unlikely);
            return;
        }
        if (@cmpxchgStrong(
            Fiber.CancelStatus,
            &fiber.cancel_status,
            .{ .requested = false, .awaiting = .nothing },
            .{ .requested = false, .awaiting = .fromCancelable(cancelable) },
            .release,
            .monotonic,
        )) |cancel_status| {
            assert(cancel_status.requested and cancel_status.awaiting == .nothing);
            cancelable.cancel = is_requested;
            return error.CancelRequested;
        }
    }

    fn leave(cancelable: *Cancelable, fiber: *Fiber) RequestedError!void {
        const function = cancelable.cancel;
        assert(function != is_requested);
        if (function == is_blocked) {
            @branchHint(.unlikely);
            return;
        }
        const cancel_status = @atomicRmw(Fiber.CancelStatus, &fiber.cancel_status, .And, .{
            .requested = true,
            .awaiting = .nothing,
        }, .monotonic);
        assert(cancel_status.awaiting.toCancelable() == cancelable);
        if (cancel_status.requested) return error.CancelRequested;
    }

    fn async(cancelable: *Cancelable) void {
        const function = cancelable.cancel;
        assert(function != is_blocked and function != is_requested);
        cancelable.queue.async(cancelable, function);
    }

    fn requested(cancelable: *Cancelable, fiber: *Fiber) void {
        const function = cancelable.cancel;
        assert(function != is_blocked and function != is_requested);
        assert(@atomicLoad(Fiber.CancelStatus, &fiber.cancel_status, .monotonic) == Fiber.CancelStatus{
            .requested = true,
            .awaiting = .fromCancelable(cancelable),
        });
        cancelable.cancel = is_requested;
        @atomicStore(Fiber.CancelStatus, &fiber.cancel_status, .{
            .requested = true,
            .awaiting = .nothing,
        }, .monotonic);
    }

    fn acknowledge(cancelable: *Cancelable, fiber: *Fiber) Io.Cancelable!void {
        if (cancelable.cancel == is_requested) {
            @branchHint(.unlikely);
            fiber.cancel_protection.acknowledge();
            return error.Canceled;
        }
    }
};

const Sleeper = struct {
    queue: c.dispatch.queue_t,
    fiber: *Fiber,

    fn init(queue: c.dispatch.queue_t, fiber: *Fiber) Sleeper {
        queue.as_object().retain();
        return .{ .queue = queue, .fiber = fiber };
    }

    fn wake(context: ?*anyopaque) callconv(.c) void {
        const sleeper: *Sleeper = @ptrCast(@alignCast(context));
        const queue = sleeper.queue;
        sleeper.queue = undefined;
        queue.async(sleeper.fiber, &Fiber.@"resume");
        queue.as_object().release();
    }
};

const Mutex = struct {
    state: State,
    queue: c.dispatch.queue_t,
    waiters: std.DoublyLinkedList,

    const State = packed struct(usize) {
        locked: bool,
        num_waiters: NumWaiters,

        const NumWaiters = @Int(.unsigned, @bitSizeOf(usize) - 1);
    };

    const Waiter = struct {
        sleeper: Sleeper = undefined,
        cancelable: Cancelable,
        mutex: *Mutex,
        node: std.DoublyLinkedList.Node = .{},

        fn add(context: ?*anyopaque) callconv(.c) void {
            const waiter: *Waiter = @ptrCast(@alignCast(context));
            waiter.cancelable.enter(waiter.sleeper.fiber) catch |err| switch (err) {
                error.CancelRequested => return waiter.wake(),
            };
            var state = @atomicRmw(State, &waiter.mutex.state, .Add, .{
                .locked = false,
                .num_waiters = 1,
            }, .monotonic);
            state.num_waiters += 1;
            while (!state.locked) {
                @branchHint(.unlikely);
                state = @cmpxchgWeak(State, &waiter.mutex.state, state, .{
                    .locked = true,
                    .num_waiters = state.num_waiters - 1,
                }, .acquire, .monotonic) orelse break;
            } else return waiter.mutex.waiters.append(&waiter.node);
            waiter.cancelable.leave(waiter.sleeper.fiber) catch |err| switch (err) {
                error.CancelRequested => {
                    waiter.node.next = &waiter.node;
                    return;
                },
            };
            waiter.wake();
        }

        fn canceled(context: ?*anyopaque) callconv(.c) void {
            const cancelable: *Cancelable = @ptrCast(@alignCast(context));
            const waiter: *Waiter = @fieldParentPtr("cancelable", cancelable);
            cancelable.requested(waiter.sleeper.fiber);
            const mutex = waiter.mutex;
            if (waiter.node.next != &waiter.node) {
                @branchHint(.likely);
                mutex.waiters.remove(&waiter.node);
                assert(@atomicRmw(State, &mutex.state, .Sub, .{
                    .locked = false,
                    .num_waiters = 1,
                }, .monotonic).num_waiters >= 1);
            }
            waiter.node = undefined;
            waiter.wake();
        }

        fn remove(context: ?*anyopaque) callconv(.c) void {
            const mutex: *Mutex = @ptrCast(@alignCast(context));
            var state = @atomicLoad(State, &mutex.state, .monotonic);
            while (!state.locked and state.num_waiters > 0) {
                @branchHint(.likely);
                state = @cmpxchgWeak(State, &mutex.state, state, .{
                    .locked = true,
                    .num_waiters = state.num_waiters - 1,
                }, .acquire, .monotonic) orelse break;
            } else return;
            var num_removed: State.NumWaiters = 0;
            while (mutex.waiters.popFirst()) |node| {
                @branchHint(.likely);
                const waiter: *Waiter = @fieldParentPtr("node", node);
                node.* = undefined;
                waiter.cancelable.leave(waiter.sleeper.fiber) catch |err| switch (err) {
                    error.CancelRequested => {
                        num_removed += 1;
                        node.next = node;
                        continue;
                    },
                };
                break;
            }
            if (num_removed > 0) {
                @branchHint(.unlikely);
                assert(@atomicRmw(State, &mutex.state, .Sub, .{
                    .locked = false,
                    .num_waiters = num_removed,
                }, .monotonic).num_waiters >= num_removed);
            }
        }

        fn wake(waiter: *Waiter) void {
            Sleeper.wake(&waiter.sleeper);
        }
    };

    fn init(mutex: *Mutex, queue: c.dispatch.queue_t) error{SystemResources}!void {
        mutex.* = .{
            .state = .{ .locked = false, .num_waiters = 0 },
            .queue = c.dispatch.queue_create_with_target(
                "org.ziglang.std.Io.Dispatch.Mutex",
                .SERIAL(),
                queue,
            ) orelse return error.SystemResources,
            .waiters = .{},
        };
    }

    fn deinit(mutex: *Mutex) void {
        assert(mutex.state == State{ .locked = false, .num_waiters = 0 });
        assert(mutex.waiters.first == null and mutex.waiters.last == null);
        mutex.queue.as_object().release();
        mutex.* = undefined;
    }

    fn tryLock(mutex: *Mutex) bool {
        const state =
            @atomicRmw(State, &mutex.state, .Or, .{ .locked = true, .num_waiters = 0 }, .acquire);
        if (state.locked) {
            @branchHint(.unlikely);
        }
        return !state.locked;
    }

    fn lock(mutex: *Mutex, ev: *Evented) Io.Cancelable!void {
        if (mutex.tryLock()) return;
        var waiter: Waiter = .{
            .cancelable = .{ .queue = mutex.queue, .cancel = &Mutex.Waiter.canceled },
            .mutex = mutex,
        };
        ev.yield(.{ .mutex_wait = &waiter });
        try waiter.cancelable.acknowledge(waiter.sleeper.fiber);
    }

    fn lockUncancelable(mutex: *Mutex, ev: *Evented) void {
        if (mutex.tryLock()) return;
        var waiter: Waiter = .{ .cancelable = .blocked, .mutex = mutex };
        ev.yield(.{ .mutex_wait = &waiter });
        waiter.cancelable.acknowledge(waiter.sleeper.fiber) catch |err| switch (err) {
            error.Canceled => unreachable, // 已阻塞
        };
    }

    fn unlock(mutex: *Mutex) void {
        const state = @atomicRmw(State, &mutex.state, .And, .{
            .locked = false,
            .num_waiters = std.math.maxInt(State.NumWaiters),
        }, .release);
        if (state.num_waiters > 0) {
            @branchHint(.unlikely);
            mutex.queue.async(mutex, &Waiter.remove);
        }
    }
};

fn crashHandler(userdata: ?*anyopaque) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const thread = &Thread.self;
    if (thread.current_context == null) std.process.abort();
    if (thread.current_context == &thread.main_context) std.process.abort();
    const fiber = thread.currentFiber();
    @atomicStore(
        Fiber.CancelStatus,
        &fiber.cancel_status,
        .{ .requested = true, .awaiting = .nothing },
        .monotonic,
    );
    fiber.cancel_protection = .{ .user = .blocked, .acknowledged = true };
}

const AsyncClosure = struct {
    evented: *Evented,
    fiber: *Fiber,
    start: *const fn (context: *const anyopaque, result: *anyopaque) void,
    result_align: Alignment,

    fn fromFiber(fiber: *Fiber) *AsyncClosure {
        return @ptrFromInt(Fiber.max_context_align.max(.of(AsyncClosure)).backward(
            @intFromPtr(fiber.allocatedEnd()) - Fiber.max_context_size,
        ) - @sizeOf(AsyncClosure));
    }

    fn contextPointer(closure: *AsyncClosure) [*]align(Fiber.max_context_align.toByteUnits()) u8 {
        return @alignCast(@as([*]u8, @ptrCast(closure)) + @sizeOf(AsyncClosure));
    }

    fn entry() callconv(.naked) void {
        switch (builtin.cpu.arch) {
            .aarch64 => asm volatile (
                \\ mov x0, sp
                \\ b %[call]
                :
                : [call] "X" (&call),
            ),
            .x86_64 => asm volatile (
                \\ leaq 8(%%rsp), %%rdi
                \\ jmp %[call:P]
                :
                : [call] "X" (&call),
            ),
            else => |arch| @compileError("unimplemented architecture: " ++ @tagName(arch)),
        }
    }

    fn call(
        closure: *AsyncClosure,
        message: *const SwitchMessage,
    ) callconv(.withStackAlign(.c, @alignOf(AsyncClosure))) noreturn {
        const ev = closure.evented;
        const fiber = closure.fiber;
        message.handle(ev);
        closure.start(closure.contextPointer(), fiber.resultBytes(closure.result_align));
        if (@atomicRmw(?*Fiber, &fiber.link.awaiter, .Xchg, Fiber.finished, .acq_rel)) |awaiter|
            ev.queue.async(awaiter, &Fiber.@"resume");
        ev.yield(.nothing);
        unreachable; // 切换至已终止的纤程
    }
};

fn async(
    userdata: ?*anyopaque,
    result: []u8,
    result_alignment: Alignment,
    context: []const u8,
    context_alignment: Alignment,
    start: *const fn (context: *const anyopaque, result: *anyopaque) void,
) ?*std.Io.AnyFuture {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return concurrent(ev, result.len, result_alignment, context, context_alignment, start) catch {
        start(context.ptr, result.ptr);
        return null;
    };
}

fn concurrent(
    userdata: ?*anyopaque,
    result_len: usize,
    result_alignment: Alignment,
    context: []const u8,
    context_alignment: Alignment,
    start: *const fn (context: *const anyopaque, result: *anyopaque) void,
) Io.ConcurrentError!*std.Io.AnyFuture {
    assert(result_alignment.compare(.lte, Fiber.max_result_align)); // TODO
    assert(context_alignment.compare(.lte, Fiber.max_context_align)); // TODO
    assert(result_len <= Fiber.max_result_size); // TODO
    assert(context.len <= Fiber.max_context_size); // TODO

    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const fiber = Fiber.create(ev) catch |err| switch (err) {
        error.OutOfMemory => return error.ConcurrencyUnavailable,
    };

    const closure: *AsyncClosure = .fromFiber(fiber);
    fiber.* = .{
        .required_align = {},
        .evented = ev,
        .context = switch (builtin.cpu.arch) {
            .aarch64 => .{
                .sp = @intFromPtr(closure),
                .fp = 0,
                .pc = @intFromPtr(&AsyncClosure.entry),
            },
            .x86_64 => .{
                .rsp = @intFromPtr(closure) - 8,
                .rbp = 0,
                .rip = @intFromPtr(&AsyncClosure.entry),
            },
            else => |arch| @compileError("unimplemented architecture: " ++ @tagName(arch)),
        },
        .link = .{ .awaiter = null },
        .awaiting_group = undefined,
        .cancel_status = .unrequested,
        .cancel_protection = .unblocked,
    };
    closure.* = .{
        .evented = ev,
        .fiber = fiber,
        .start = start,
        .result_align = result_alignment,
    };
    @memcpy(closure.contextPointer(), context);

    ev.queue.async(fiber, &Fiber.@"resume");
    return @ptrCast(fiber);
}

fn await(
    userdata: ?*anyopaque,
    future: *std.Io.AnyFuture,
    result: []u8,
    result_alignment: Alignment,
) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const awaiting: *Fiber = @ptrCast(@alignCast(future));
    if (@atomicLoad(?*Fiber, &awaiting.link.awaiter, .acquire) != Fiber.finished)
        ev.yield(.{ .await = awaiting });
    @memcpy(result, awaiting.resultBytes(result_alignment));
    awaiting.destroy(ev);
}

fn cancel(
    userdata: ?*anyopaque,
    future: *std.Io.AnyFuture,
    result: []u8,
    result_alignment: Alignment,
) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const future_fiber: *Fiber = @ptrCast(@alignCast(future));
    future_fiber.requestCancel(ev);
    await(ev, future, result, result_alignment);
}

const Group = struct {
    ptr: *Io.Group,

    const List = packed struct(usize) {
        cancel_requested: bool,
        awaiter_delayed: bool,
        fibers: Fiber.PackedPtr,
    };
    fn listPtr(group: Group) *List {
        return @ptrCast(&group.ptr.token);
    }

    const Mutex = packed struct(u32) {
        locked: bool,
        contended: bool,
        shared2: u30,
    };
    fn mutexPtr(group: Group) *Group.Mutex {
        return switch (comptime builtin.cpu.arch.endian()) {
            .little => @ptrCast(&group.ptr.state),
            .big => @ptrCast(@alignCast(
                @as([*]u8, @ptrCast(&group.ptr.state)) + @sizeOf(usize) - @sizeOf(u32),
            )),
        };
    }

    const Awaiter = packed struct(usize) {
        locked: bool,
        contended: bool,
        awaiter: Fiber.PackedPtr,
    };
    fn awaiterPtr(group: Group) *Awaiter {
        return @ptrCast(&group.ptr.state);
    }

    fn lock(group: Group, ev: *Evented) void {
        const mutex = group.mutexPtr();
        {
            const old_state = @atomicRmw(
                Group.Mutex,
                mutex,
                .Or,
                .{ .locked = true, .contended = false, .shared2 = 0 },
                .acquire,
            );
            if (!old_state.locked) {
                @branchHint(.likely);
                return;
            }
            if (old_state.contended) {
                futexWaitUncancelable(ev, @ptrCast(mutex), @bitCast(old_state));
            }
        }
        while (true) {
            var old_state = @atomicRmw(
                Group.Mutex,
                mutex,
                .Or,
                .{ .locked = true, .contended = true, .shared2 = 0 },
                .acquire,
            );
            if (!old_state.locked) {
                @branchHint(.likely);
                return;
            }
            old_state.contended = true;
            futexWaitUncancelable(ev, @ptrCast(mutex), @bitCast(old_state));
        }
    }

    fn unlock(group: Group, ev: *Evented) void {
        const mutex = group.mutexPtr();
        const old_state = @atomicRmw(
            Group.Mutex,
            mutex,
            .And,
            .{ .locked = false, .contended = false, .shared2 = std.math.maxInt(u30) },
            .release,
        );
        assert(old_state.locked);
        if (old_state.contended) futexWake(ev, @ptrCast(mutex), 1);
    }

    fn addFiber(group: Group, ev: *Evented, fiber: *Fiber) void {
        group.lock(ev);
        defer group.unlock(ev);
        const list_ptr = group.listPtr();
        const list = @atomicLoad(List, list_ptr, .monotonic);
        if (list.cancel_requested) fiber.cancel_status = .{ .requested = true, .awaiting = .nothing };
        const old_head = list.fibers.unpack();
        if (old_head) |head| head.link.group.prev = fiber;
        fiber.link.group.next = old_head;
        @atomicStore(List, list_ptr, .{
            .cancel_requested = list.cancel_requested,
            .awaiter_delayed = list.awaiter_delayed,
            .fibers = .pack(fiber),
        }, .monotonic);
    }

    fn removeFiber(group: Group, ev: *Evented, fiber: *Fiber) ?*Fiber {
        group.lock(ev);
        defer group.unlock(ev);
        const list_ptr = group.listPtr();
        const list = @atomicLoad(List, list_ptr, .monotonic);
        if (fiber.link.group.next) |next| next.link.group.prev = fiber.link.group.prev;
        if (fiber.link.group.prev) |prev| {
            prev.link.group.next = fiber.link.group.next;
        } else if (fiber.link.group.next) |new_head| {
            @atomicStore(List, list_ptr, .{
                .cancel_requested = list.cancel_requested,
                .awaiter_delayed = list.awaiter_delayed,
                .fibers = .pack(new_head),
            }, .monotonic);
        } else if (@atomicLoad(Awaiter, group.awaiterPtr(), .monotonic).awaiter.unpack()) |awaiter| {
            if (!awaiter.cancel_status.changeAwaiting(.group, .nothing) or list.cancel_requested) {
                @atomicStore(List, list_ptr, .{
                    .cancel_requested = false,
                    .awaiter_delayed = false,
                    .fibers = .null,
                }, .release);
                assert(awaiter.awaiting_group.ptr == group.ptr);
                awaiter.awaiting_group = undefined;
                return awaiter;
            }
            // 与 `Fiber.requestCancel` 发生竞态
            @atomicStore(List, list_ptr, .{
                .cancel_requested = false,
                .awaiter_delayed = true,
                .fibers = .null,
            }, .monotonic);
        } else @atomicStore(List, list_ptr, .{
            .cancel_requested = false,
            .awaiter_delayed = false,
            .fibers = .null,
        }, .release);
        return null;
    }

    fn await(group: Group, ev: *Evented, awaiter: *Fiber) bool {
        group.lock(ev);
        defer group.unlock(ev);
        if (@atomicLoad(List, group.listPtr(), .monotonic).fibers.unpack()) |_| {
            if (group.registerAwaiter(awaiter) and awaiter.cancel_protection.check() == .unblocked) {
                // 等待方在尝试等待组之前,已经存在未确认的取消请求,
                // 因此将取消传播到该组。
                assert(!group.cancelLocked(ev, null));
            }
            return false;
        }
        return true;
    }

    fn cancel(group: Group, ev: *Evented, maybe_awaiter: ?*Fiber) bool {
        group.lock(ev);
        defer group.unlock(ev);
        return group.cancelLocked(ev, maybe_awaiter);
    }

    /// 假定互斥锁已被持有。
    fn cancelLocked(group: Group, ev: *Evented, maybe_awaiter: ?*Fiber) bool {
        const list_ptr = group.listPtr();
        const list = @atomicRmw(
            List,
            list_ptr,
            .Add,
            .{ .cancel_requested = true, .awaiter_delayed = false, .fibers = .null },
            .monotonic,
        );
        assert(!list.cancel_requested);
        if (list.fibers.unpack()) |head| {
            var maybe_fiber: ?*Fiber = head;
            while (maybe_fiber) |fiber| {
                fiber.requestCancel(ev);
                maybe_fiber = fiber.link.group.next;
            }
            if (maybe_awaiter) |awaiter| _ = group.registerAwaiter(awaiter);
            return false;
        }
        @atomicStore(
            List,
            list_ptr,
            .{ .cancel_requested = false, .awaiter_delayed = false, .fibers = .null },
            .release,
        );
        return if (maybe_awaiter) |_| true else list.awaiter_delayed;
    }

    /// 假定互斥锁已被持有。
    fn registerAwaiter(group: Group, awaiter: *Fiber) bool {
        awaiter.awaiting_group = group;
        assert(@atomicRmw(
            Awaiter,
            group.awaiterPtr(),
            .Add,
            .{ .locked = false, .contended = false, .awaiter = .pack(awaiter) },
            .monotonic,
        ).awaiter == .null);
        return awaiter.cancel_status.changeAwaiting(.nothing, .group);
    }

    const AsyncClosure = struct {
        evented: *Evented,
        group: Group,
        fiber: *Fiber,
        start: *const fn (context: *const anyopaque) void,

        fn fromFiber(fiber: *Fiber) *Group.AsyncClosure {
            return @ptrFromInt(Fiber.max_context_align.max(.of(Group.AsyncClosure)).backward(
                @intFromPtr(fiber.allocatedEnd()) - Fiber.max_context_size,
            ) - @sizeOf(Group.AsyncClosure));
        }

        fn contextPointer(
            closure: *Group.AsyncClosure,
        ) [*]align(Fiber.max_context_align.toByteUnits()) u8 {
            return @alignCast(@as([*]u8, @ptrCast(closure)) + @sizeOf(Group.AsyncClosure));
        }

        fn entry() callconv(.naked) void {
            switch (builtin.cpu.arch) {
                .aarch64 => asm volatile (
                    \\ mov x0, sp
                    \\ b %[call]
                    :
                    : [call] "X" (&call),
                ),
                .x86_64 => asm volatile (
                    \\ leaq 8(%%rsp), %%rdi
                    \\ jmp %[call:P]
                    :
                    : [call] "X" (&call),
                ),
                else => |arch| @compileError("unimplemented architecture: " ++ @tagName(arch)),
            }
        }

        fn call(
            closure: *Group.AsyncClosure,
            message: *const SwitchMessage,
        ) callconv(.withStackAlign(.c, @alignOf(Group.AsyncClosure))) noreturn {
            const ev = closure.evented;
            const fiber = closure.fiber;
            message.handle(ev);
            closure.start(closure.contextPointer());
            if (closure.group.removeFiber(ev, fiber)) |awaiter| ev.queue.async(awaiter, &Fiber.@"resume");
            ev.yield(.destroy);
            unreachable; // 切换至已终止的纤程
        }
    };
};

fn groupAsync(
    userdata: ?*anyopaque,
    type_erased: *Io.Group,
    context: []const u8,
    context_alignment: Alignment,
    start: *const fn (context: *const anyopaque) void,
) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return groupConcurrent(ev, type_erased, context, context_alignment, start) catch {
        start(context.ptr);
    };
}

fn groupConcurrent(
    userdata: ?*anyopaque,
    type_erased: *Io.Group,
    context: []const u8,
    context_alignment: Alignment,
    start: *const fn (context: *const anyopaque) void,
) Io.ConcurrentError!void {
    assert(context_alignment.compare(.lte, Fiber.max_context_align)); // TODO
    assert(context.len <= Fiber.max_context_size); // TODO

    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const group: Group = .{ .ptr = type_erased };
    const fiber = Fiber.create(ev) catch |err| switch (err) {
        error.OutOfMemory => return error.ConcurrencyUnavailable,
    };

    const closure: *Group.AsyncClosure = .fromFiber(fiber);
    fiber.* = .{
        .required_align = {},
        .evented = ev,
        .context = switch (builtin.cpu.arch) {
            .aarch64 => .{
                .sp = @intFromPtr(closure),
                .fp = 0,
                .pc = @intFromPtr(&Group.AsyncClosure.entry),
            },
            .x86_64 => .{
                .rsp = @intFromPtr(closure) - 8,
                .rbp = 0,
                .rip = @intFromPtr(&Group.AsyncClosure.entry),
            },
            else => |arch| @compileError("unimplemented architecture: " ++ @tagName(arch)),
        },
        .link = .{ .group = .{ .prev = null, .next = null } },
        .awaiting_group = undefined,
        .cancel_status = .unrequested,
        .cancel_protection = .unblocked,
    };
    closure.* = .{
        .evented = ev,
        .group = group,
        .fiber = fiber,
        .start = start,
    };
    @memcpy(closure.contextPointer(), context);
    group.addFiber(ev, fiber);
    ev.queue.async(fiber, &Fiber.@"resume");
}

fn groupAwait(
    userdata: ?*anyopaque,
    type_erased: *Io.Group,
    initial_token: *anyopaque,
) Io.Cancelable!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = initial_token;
    ev.yield(.{ .group_await = .{ .ptr = type_erased } });
}

fn groupCancel(userdata: ?*anyopaque, type_erased: *Io.Group, initial_token: *anyopaque) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = initial_token;
    ev.yield(.{ .group_cancel = .{ .ptr = type_erased } });
}

fn recancel(userdata: ?*anyopaque) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    Thread.current().currentFiber().cancel_protection.recancel();
}

fn swapCancelProtection(userdata: ?*anyopaque, new: Io.CancelProtection) Io.CancelProtection {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const cancel_protection = &Thread.current().currentFiber().cancel_protection;
    defer cancel_protection.user = new;
    return cancel_protection.user;
}

fn checkCancel(userdata: ?*anyopaque) Io.Cancelable!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const fiber = Thread.current().currentFiber();
    switch (fiber.cancel_protection.check()) {
        .unblocked => {
            const cancel_status = @atomicLoad(Fiber.CancelStatus, &fiber.cancel_status, .monotonic);
            assert(cancel_status.awaiting == .nothing);
            if (cancel_status.requested) {
                @branchHint(.unlikely);
                fiber.cancel_protection.acknowledge();
                return error.Canceled;
            }
        },
        .blocked => {},
    }
}

const Futex = struct {
    num_waiters: usize,
    queue: c.dispatch.queue_t,
    waiters: std.DoublyLinkedList,

    const Waiter = struct {
        sleeper: Sleeper = undefined,
        cancelable: Cancelable,
        futex: *Futex,
        node: std.DoublyLinkedList.Node = .{},
        ptr: *const u32,
        expected: u32,
        timeout: c.dispatch.time_t = .FOREVER,
        leeway: u64,
        timer: ?c.dispatch.source_t = null,

        const already_signaled: c.dispatch.source_t = @ptrFromInt(1);

        fn add(context: ?*anyopaque) callconv(.c) void {
            const waiter: *Waiter = @ptrCast(@alignCast(context));
            const futex = waiter.futex;
            _ = @atomicRmw(usize, &futex.num_waiters, .Add, 1, .acquire);
            waiter.tryAdd() catch |err| switch (err) {
                error.CancelRequested => {
                    wake(waiter);
                    assert(@atomicRmw(usize, &futex.num_waiters, .Sub, 1, .monotonic) >= 1);
                },
            };
        }

        fn tryAdd(waiter: *Waiter) Cancelable.RequestedError!void {
            if (@atomicLoad(u32, waiter.ptr, .monotonic) != waiter.expected)
                return error.CancelRequested;
            try waiter.cancelable.enter(waiter.sleeper.fiber);
            const futex = waiter.futex;
            switch (waiter.timeout) {
                .FOREVER => {},
                else => |timeout| {
                    const timer = c.dispatch.source_create(.TIMER, 0, .none, futex.queue) orelse {
                        log.warn("failed to create timer for futex timeout", .{});
                        return error.CancelRequested;
                    };
                    timer.as_object().set_context(waiter);
                    timer.set_event_handler(&timedOut);
                    timer.set_cancel_handler(&wake);
                    timer.set_timer(timeout, c.dispatch.TIME_FOREVER, waiter.leeway);
                    timer.as_object().activate();
                    waiter.timer = timer;
                },
            }
            futex.waiters.append(&waiter.node);
        }

        fn canceled(context: ?*anyopaque) callconv(.c) void {
            const cancelable: *Cancelable = @ptrCast(@alignCast(context));
            const waiter: *Waiter = @fieldParentPtr("cancelable", cancelable);
            cancelable.requested(waiter.sleeper.fiber);
            const futex = waiter.futex;
            waiter.remove();
            assert(@atomicRmw(usize, &futex.num_waiters, .Sub, 1, .monotonic) >= 1);
        }

        fn timedOut(context: ?*anyopaque) callconv(.c) void {
            const waiter: *Waiter = @ptrCast(@alignCast(context));
            const futex = waiter.futex;
            waiter.tryRemove() catch |err| switch (err) {
                error.CancelRequested => return,
            };
            assert(@atomicRmw(usize, &futex.num_waiters, .Sub, 1, .monotonic) >= 1);
        }

        fn tryRemove(waiter: *Waiter) Cancelable.RequestedError!void {
            try waiter.cancelable.leave(waiter.sleeper.fiber);
            waiter.remove();
        }

        fn remove(waiter: *Waiter) void {
            waiter.futex.waiters.remove(&waiter.node);
            if (waiter.timer) |timer| timer.cancel() else wake(waiter);
        }

        fn wake(context: ?*anyopaque) callconv(.c) void {
            const waiter: *Waiter = @ptrCast(@alignCast(context));
            if (waiter.timer) |timer| timer.as_object().release();
            Sleeper.wake(&waiter.sleeper);
        }
    };

    const Waker = struct {
        sleeper: Sleeper = undefined,
        futex: *Futex,
        ptr: *const u32,
        max_waiters: u32,

        fn remove(context: ?*anyopaque) callconv(.c) void {
            const waker: *Waker = @ptrCast(@alignCast(context));
            const futex = waker.futex;
            const ptr = waker.ptr;
            const max_waiters = waker.max_waiters;

            var num_removed: usize = 0;
            var next_node = futex.waiters.first;
            while (num_removed < max_waiters) {
                const waiter: *Waiter = @fieldParentPtr("node", next_node orelse break);
                next_node = waiter.node.next;
                if (waiter.ptr != ptr) {
                    @branchHint(.unlikely);
                    continue;
                }
                waiter.tryRemove() catch |err| switch (err) {
                    error.CancelRequested => continue,
                };
                num_removed += 1;
            }
            assert(@atomicRmw(usize, &futex.num_waiters, .Sub, num_removed, .monotonic) >= num_removed);

            var sleeper = waker.sleeper;
            waker.* = undefined;
            Sleeper.wake(&sleeper);
        }
    };

    fn init(futex: *Futex, queue: c.dispatch.queue_t) error{SystemResources}!void {
        futex.* = .{
            .num_waiters = 0,
            .queue = c.dispatch.queue_create_with_target(
                "org.ziglang.std.Io.Dispatch.Futex",
                .SERIAL(),
                queue,
            ) orelse return error.SystemResources,
            .waiters = .{},
        };
    }

    fn deinit(futex: *Futex) void {
        assert(futex.num_waiters == 0 and futex.waiters.first == null and futex.waiters.last == null);
        futex.queue.as_object().release();
        futex.* = undefined;
    }
};

fn futexForAddress(ev: *Evented, address: usize) *Futex {
    // 此处使用斐波那契哈希:黄金比例可将输入值均匀重新分布到某个范围,
    // 得到质量较差但计算极快的哈希。

    // 此字面量是“2^64 / phi”的舍入值,其中 phi 为黄金比例。
    // 随后移位将其转换为“2^b / phi”,其中 b 为指针位宽。
    const fibonacci_multiplier = 0x9E3779B97F4A7C15 >> (64 - @bitSizeOf(usize));
    const hashed = address *% fibonacci_multiplier;
    comptime assert(std.math.isPowerOfTwo(ev.futexes.len));
    // `hashed` 的高位比低位具有更好的熵。
    return &ev.futexes[hashed >> @clz(ev.futexes.len - 1)];
}

fn futexWait(
    userdata: ?*anyopaque,
    ptr: *const u32,
    expected: u32,
    timeout: Io.Timeout,
) Io.Cancelable!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const futex = ev.futexForAddress(@intFromPtr(ptr));
    var waiter: Futex.Waiter = .{
        .cancelable = .{ .queue = futex.queue, .cancel = &Futex.Waiter.canceled },
        .futex = futex,
        .ptr = ptr,
        .expected = expected,
        .timeout = ev.timeFromTimeout(timeout),
        .leeway = ev.leeway,
    };
    ev.yield(.{ .futex_wait = &waiter });
    try waiter.cancelable.acknowledge(waiter.sleeper.fiber);
}

fn futexWaitUncancelable(userdata: ?*anyopaque, ptr: *const u32, expected: u32) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const futex = ev.futexForAddress(@intFromPtr(ptr));
    var waiter: Futex.Waiter = .{
        .cancelable = .blocked,
        .futex = futex,
        .ptr = ptr,
        .expected = expected,
        .leeway = ev.leeway,
    };
    ev.yield(.{ .futex_wait = &waiter });
    waiter.cancelable.acknowledge(waiter.sleeper.fiber) catch |err| switch (err) {
        error.Canceled => unreachable, // 已阻塞
    };
}

fn futexWake(userdata: ?*anyopaque, ptr: *const u32, max_waiters: u32) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    if (max_waiters == 0) return;
    const futex = ev.futexForAddress(@intFromPtr(ptr));
    switch (@atomicRmw(usize, &futex.num_waiters, .Add, 0, .release)) {
        0 => return,
        else => {
            @branchHint(.unlikely);
            var waker: Futex.Waker = .{ .futex = futex, .ptr = ptr, .max_waiters = max_waiters };
            ev.yield(.{ .futex_wake = &waker });
        },
    }
}

fn operate(userdata: ?*anyopaque, operation: Io.Operation) Io.Cancelable!Io.Operation.Result {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    switch (operation) {
        .file_read_streaming => |o| return .{
            .file_read_streaming = ev.fileReadStreaming(o.file, o.data) catch |err| switch (err) {
                error.Canceled => |e| return e,
                else => |e| e,
            },
        },
        .file_write_streaming => |o| return .{
            .file_write_streaming = ev.fileWriteStreaming(
                o.file,
                o.header,
                o.data,
                o.splat,
            ) catch |err| switch (err) {
                error.Canceled => |e| return e,
                else => |e| e,
            },
        },
        .device_io_control => |*o| return .{ .device_io_control = try deviceIoControl(o) },
        .net_receive => @panic("TODO implement net_receive operation"),
        .net_send => @panic("TODO implement net_send operation"),
        .net_read => @panic("TODO implement net_read operation"),
        .net_write => @panic("TODO implement net_write operation"),
    }
}

fn fileReadStreaming(ev: *Evented, file: File, data: []const []u8) File.ReadStreamingError!usize {
    if (file.flags.nonblocking) nonblocking: {
        return fileReadStreamingLimit(file.handle, data, .unlimited) catch |err| switch (err) {
            error.WouldBlock => break :nonblocking,
            else => |e| return e,
        };
    }
    const source = c.dispatch.source_create(
        .READ,
        @bitCast(@as(isize, file.handle)),
        .none,
        ev.queue,
    ) orelse return error.SystemResources;
    source.as_object().set_context(Thread.current().currentFiber());
    source.set_event_handler(&Fiber.@"resume");
    ev.yield(.{ .activate = source.as_object() });
    const limit = source.get_data();
    source.as_object().release();
    while (true) return fileReadStreamingLimit(
        file.handle,
        data,
        .limited(limit),
    ) catch |err| switch (err) {
        error.WouldBlock => {
            ev.yield(.nothing);
            continue;
        },
        else => |e| return e,
    };
}
fn fileReadStreamingLimit(
    handle: File.Handle,
    data: []const []u8,
    limit: Io.Limit,
) File.ReadStreamingError!usize {
    var iovecs: [max_iovecs_len]iovec = undefined;
    var iovlen: iovlen_t = 0;
    // .nothing 可能表示写入端已关闭,
    // 此时仍需排空缓冲区。
    var remaining = if (limit == .nothing) .unlimited else limit;
    for (data) |buf| addBuf(false, &iovecs, &iovlen, &remaining, buf);
    if (iovlen == 0) return 0;
    while (true) {
        const rc = c.readv(handle, &iovecs, iovlen);
        switch (c.errno(rc)) {
            .SUCCESS => return if (rc == 0) error.EndOfStream else @intCast(rc),
            .INTR => continue,
            .INVAL => |err| return errnoBug(err),
            .FAULT => |err| return errnoBug(err),
            .AGAIN => return error.WouldBlock,
            .BADF => |err| return errnoBug(err), // 关闭后仍使用文件描述符
            .IO => return error.InputOutput,
            .ISDIR => return error.IsDir,
            .NOBUFS => return error.SystemResources,
            .NOMEM => return error.SystemResources,
            .NOTCONN => return error.SocketUnconnected,
            .CONNRESET => return error.ConnectionResetByPeer,
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn fileWriteStreaming(
    ev: *Evented,
    file: File,
    header: []const u8,
    data: []const []const u8,
    splat: usize,
) File.Writer.Error!usize {
    if (file.flags.nonblocking) nonblocking: {
        return fileWriteStreamingLimit(
            file.handle,
            header,
            data,
            splat,
            .unlimited,
        ) catch |err| switch (err) {
            error.WouldBlock => break :nonblocking,
            else => |e| return e,
        };
    }
    const source = c.dispatch.source_create(
        .WRITE,
        @bitCast(@as(isize, file.handle)),
        .none,
        ev.queue,
    ) orelse return error.SystemResources;
    source.as_object().set_context(Thread.current().currentFiber());
    source.set_event_handler(&Fiber.@"resume");
    ev.yield(.{ .activate = source.as_object() });
    const limit = source.get_data();
    source.as_object().release();
    while (true) return fileWriteStreamingLimit(
        file.handle,
        header,
        data,
        splat,
        .limited(limit),
    ) catch |err| switch (err) {
        error.WouldBlock => {
            ev.yield(.nothing);
            continue;
        },
        else => |e| return e,
    };
}
fn fileWriteStreamingLimit(
    handle: File.Handle,
    header: []const u8,
    data: []const []const u8,
    splat: usize,
    limit: Io.Limit,
) File.Writer.Error!usize {
    if (limit == .nothing) return 0;
    var iovecs: [max_iovecs_len]iovec_const = undefined;
    var iovlen: iovlen_t = 0;
    var remaining = limit;
    addBuf(true, &iovecs, &iovlen, &remaining, header);
    for (data[0 .. data.len - 1]) |bytes| addBuf(true, &iovecs, &iovlen, &remaining, bytes);
    const pattern = data[data.len - 1];
    var backup_buffer: [splat_buffer_size]u8 = undefined;
    if (iovecs.len - iovlen != 0 and remaining != .nothing) switch (splat) {
        0 => {},
        1 => addBuf(true, &iovecs, &iovlen, &remaining, pattern),
        else => switch (pattern.len) {
            0 => {},
            1 => {
                const splat_buffer = &backup_buffer;
                const memset_len = @min(splat_buffer.len, splat);
                const buf = splat_buffer[0..memset_len];
                @memset(buf, pattern[0]);
                addBuf(true, &iovecs, &iovlen, &remaining, buf);
                var remaining_splat = splat - buf.len;
                while (remaining_splat > splat_buffer.len and iovecs.len - iovlen != 0 and remaining != .nothing) {
                    assert(buf.len == splat_buffer.len);
                    addBuf(true, &iovecs, &iovlen, &remaining, splat_buffer);
                    remaining_splat -= splat_buffer.len;
                }
                addBuf(true, &iovecs, &iovlen, &remaining, splat_buffer[0..@min(remaining_splat, splat_buffer.len)]);
            },
            else => for (0..@min(splat, iovecs.len - iovlen)) |_| {
                if (remaining == .nothing) break;
                addBuf(true, &iovecs, &iovlen, &remaining, pattern);
            },
        },
    };
    if (iovlen == 0) return 0;
    while (true) {
        const rc = c.writev(handle, &iovecs, iovlen);
        switch (c.errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .INTR => continue,
            .INVAL => |err| return errnoBug(err),
            .FAULT => |err| return errnoBug(err),
            .AGAIN => return error.WouldBlock,
            .BADF => return error.NotOpenForWriting, // 可能存在竞态条件。
            .DESTADDRREQ => |err| return errnoBug(err), // 从未调用 `connect`。
            .DQUOT => return error.DiskQuota,
            .FBIG => return error.FileTooBig,
            .IO => return error.InputOutput,
            .NOSPC => return error.NoSpaceLeft,
            .PERM => return error.PermissionDenied,
            .PIPE => return error.BrokenPipe,
            .CONNRESET => |err| return errnoBug(err), // 不是套接字句柄。
            .BUSY => return error.DeviceBusy,
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn deviceIoControl(o: *const Io.Operation.DeviceIoControl) Io.Cancelable!i32 {
    while (true) {
        const rc = c.ioctl(o.file.handle, @bitCast(o.code), @intFromPtr(o.arg));
        switch (c.errno(rc)) {
            .SUCCESS => return rc,
            .INTR => {},
            else => |err| return -@as(i32, @backingInt(err)),
        }
    }
}

const BatchWaiter = struct {
    sleeper: Sleeper,
    queue: c.dispatch.queue_t,
    timer: ?c.dispatch.source_t = null,

    const already_signaled: c.dispatch.source_t = @ptrFromInt(1);

    fn signal(context: ?*anyopaque) callconv(.c) void {
        const waiter: *BatchWaiter = @ptrCast(@alignCast(context));
        if (waiter.timer) |timer| {
            if (timer != already_signaled) timer.cancel();
        } else {
            waiter.timer = already_signaled;
            waiter.queue.async(waiter, &@"suspend");
        }
    }

    fn @"suspend"(context: ?*anyopaque) callconv(.c) void {
        const waiter: *BatchWaiter = @ptrCast(@alignCast(context));
        if (waiter.timer) |timer| if (timer != already_signaled) timer.as_object().release();
        waiter.queue.as_object().@"suspend"();
        waiter.wake();
    }

    fn wake(waiter: *BatchWaiter) void {
        var sleeper = waiter.sleeper;
        waiter.* = undefined;
        Sleeper.wake(&sleeper);
    }
};

fn batchAwaitAsync(userdata: ?*anyopaque, batch: *Io.Batch) Io.Cancelable!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const queue = ev.batchDrainSubmitted(batch, false) catch |err| switch (err) {
        error.ConcurrencyUnavailable => unreachable, // 传入 concurrency=false
        error.Canceled => |e| return e,
    } orelse return;
    if (batch.pending.head == .none) return;
    var waiter: BatchWaiter = .{
        .sleeper = .init(ev.queue, Thread.current().currentFiber()),
        .queue = queue,
    };
    if (batch.completed.head != .none) BatchWaiter.signal(&waiter);
    queue.as_object().set_context(&waiter);
    ev.yield(.{ .@"resume" = queue.as_object() });
}

fn batchAwaitConcurrent(
    userdata: ?*anyopaque,
    batch: *Io.Batch,
    timeout: Io.Timeout,
) Io.Batch.AwaitConcurrentError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const queue = try ev.batchDrainSubmitted(batch, true) orelse return;
    if (batch.pending.head == .none) return;
    var waiter: BatchWaiter = .{
        .sleeper = .init(ev.queue, Thread.current().currentFiber()),
        .queue = queue,
    };
    if (batch.completed.head == .none) switch (timeout) {
        .none => {},
        else => {
            const timer = c.dispatch.source_create(.TIMER, 0, .none, queue) orelse
                return error.ConcurrencyUnavailable;
            assert(timer != BatchWaiter.already_signaled);
            timer.as_object().set_context(&waiter);
            timer.set_event_handler(&BatchWaiter.signal);
            timer.set_cancel_handler(&BatchWaiter.@"suspend");
            timer.set_timer(ev.timeFromTimeout(timeout), c.dispatch.TIME_FOREVER, ev.leeway);
            timer.as_object().activate();
            waiter.timer = timer;
        },
    } else BatchWaiter.signal(&waiter);
    queue.as_object().set_context(&waiter);
    ev.yield(.{ .@"resume" = queue.as_object() });
}

fn batchCancel(userdata: ?*anyopaque, batch: *Io.Batch) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    var index = batch.pending.head;
    while (index != .none) {
        const storage = &batch.storage[index.toIndex()];
        const pending = &storage.pending;
        const operation_userdata: *BatchOperationUserdata = .fromErased(&pending.userdata);
        assert(operation_userdata.batch == batch);
        operation_userdata.source.cancel();
    }
    const queue: c.dispatch.queue_t = @ptrCast(batch.userdata orelse return);
    if (batch.pending.head != .none) {
        var waiter: BatchWaiter = .{
            .sleeper = .init(ev.queue, Thread.current().currentFiber()),
            .queue = queue,
            .timer = BatchWaiter.already_signaled,
        };
        if (batch.pending.head == .none) queue.async(&waiter, &BatchWaiter.signal);
        queue.as_object().set_context(&waiter);
        ev.yield(.{ .@"resume" = queue.as_object() });
    }
    batch.userdata = null;
}

const BatchOperationUserdata = extern struct {
    batch: *Io.Batch,
    source: c.dispatch.source_t,
    operation: extern union {
        file_read_streaming: extern struct {
            data_ptr: [*]const []u8,
            data_len: usize,
        },
        file_write_streaming: extern struct {
            header_ptr: [*]const u8,
            header_len: usize,
            data_ptr: [*]const []const u8,
            data_len: usize,
            splat: usize,

            fn header(operation: *const @This()) []const u8 {
                return operation.header_ptr[0..operation.header_len];
            }

            fn data(operation: *const @This()) []const []const u8 {
                return operation.data_ptr[0..operation.data_len];
            }
        },
    },

    const Erased = Io.Operation.Storage.Pending.Userdata;

    comptime {
        assert(@sizeOf(BatchOperationUserdata) <= @sizeOf(Erased));
    }

    fn toErased(userdata: *BatchOperationUserdata) *Erased {
        return @ptrCast(userdata);
    }

    fn fromErased(erased: *Erased) *BatchOperationUserdata {
        return @ptrCast(erased);
    }
};

/// 若 `concurrency` 为 false,则 `error.ConcurrencyUnavailable` 不可达。
fn batchDrainSubmitted(
    ev: *Evented,
    batch: *Io.Batch,
    concurrency: bool,
) (Io.ConcurrentError || Io.Cancelable)!?c.dispatch.queue_t {
    var index = batch.submitted.head;
    if (index == .none) return @ptrCast(batch.userdata);
    errdefer batch.submitted.head = index;
    const maybe_queue: ?c.dispatch.queue_t = if (batch.userdata) |batch_userdata|
        @ptrCast(batch_userdata)
    else maybe_queue: {
        const queue = c.dispatch.queue_create_with_target(
            "org.ziglang.std.Io.Dispatch.Batch",
            .SERIAL(),
            ev.queue,
        ) orelse if (concurrency) return error.ConcurrencyUnavailable else break :maybe_queue null;
        queue.as_object().@"suspend"();
        batch.userdata = queue;
        break :maybe_queue queue;
    };
    while (index != .none) {
        const storage = &batch.storage[index.toIndex()];
        const next_index = storage.submission.node.next;
        if (@as(?Io.Operation.Result, result: {
            if (maybe_queue) |queue| switch (storage.submission.operation) {
                .file_read_streaming => |operation| {
                    const data = for (operation.data, 0..) |buffer, data_index| {
                        if (buffer.len > 0) break operation.data[data_index..];
                    } else break :result .{ .file_read_streaming = 0 };
                    const source = c.dispatch.source_create(
                        .READ,
                        @bitCast(@as(isize, operation.file.handle)),
                        .none,
                        queue,
                    ) orelse break :result .{ .file_read_streaming = error.SystemResources };
                    storage.* = .{ .pending = .{
                        .node = .{ .prev = batch.pending.tail, .next = .none },
                        .tag = .file_read_streaming,
                        .userdata = undefined,
                    } };
                    const operation_userdata: *BatchOperationUserdata =
                        .fromErased(&storage.pending.userdata);
                    operation_userdata.* = .{
                        .batch = batch,
                        .source = source,
                        .operation = .{ .file_read_streaming = .{
                            .data_ptr = data.ptr,
                            .data_len = data.len,
                        } },
                    };
                    source.as_object().set_context(storage);
                    source.set_event_handler(&batchSourceEvent);
                    source.set_cancel_handler(&batchSourceCancel);
                    source.as_object().activate();
                    break :result null;
                },
                .file_write_streaming => |operation| {
                    const data = for (operation.data, 0..) |buffer, data_index| {
                        if (buffer.len > 0) break operation.data[data_index..];
                    } else if (operation.header.len > 0)
                        operation.data[0..1]
                    else
                        break :result .{ .file_write_streaming = 0 };
                    const source = c.dispatch.source_create(
                        .WRITE,
                        @bitCast(@as(isize, operation.file.handle)),
                        .none,
                        queue,
                    ) orelse break :result .{ .file_write_streaming = error.SystemResources };
                    storage.* = .{ .pending = .{
                        .node = .{ .prev = batch.pending.tail, .next = .none },
                        .tag = .file_write_streaming,
                        .userdata = undefined,
                    } };
                    const operation_userdata: *BatchOperationUserdata =
                        .fromErased(&storage.pending.userdata);
                    operation_userdata.* = .{
                        .batch = batch,
                        .source = source,
                        .operation = .{ .file_write_streaming = .{
                            .header_ptr = operation.header.ptr,
                            .header_len = operation.header.len,
                            .data_ptr = data.ptr,
                            .data_len = data.len,
                            .splat = operation.splat,
                        } },
                    };
                    source.as_object().set_context(storage);
                    source.set_event_handler(&batchSourceEvent);
                    source.set_cancel_handler(&batchSourceCancel);
                    source.as_object().activate();
                    break :result null;
                },
                .device_io_control => {},
                .net_receive => @panic("TODO implement batched net_receive"),
                .net_send => @panic("TODO implement batched net_send"),
                .net_read => @panic("TODO implement batched net_read"),
                .net_write => @panic("TODO implement batched net_write"),
            };
            if (concurrency) return error.ConcurrencyUnavailable;
            break :result try operate(ev, storage.submission.operation);
        })) |result| {
            switch (batch.completed.tail) {
                .none => batch.completed.head = index,
                else => |tail_index| batch.storage[tail_index.toIndex()].completion.node.next = index,
            }
            batch.completed.tail = index;
            storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
        } else {
            switch (batch.pending.tail) {
                .none => batch.pending.head = index,
                else => |tail_index| batch.storage[tail_index.toIndex()].pending.node.next = index,
            }
            batch.pending.tail = index;
        }
        index = next_index;
    }
    batch.submitted = .{ .head = .none, .tail = .none };
    return maybe_queue;
}

fn batchSourceEvent(context: ?*anyopaque) callconv(.c) void {
    const storage: *Io.Operation.Storage = @ptrCast(@alignCast(context));
    const pending = &storage.pending;
    const operation_userdata: *BatchOperationUserdata = .fromErased(&pending.userdata);
    const batch = operation_userdata.batch;
    const source = operation_userdata.source;
    const index: Io.Operation.OptionalIndex = .fromIndex(storage - batch.storage.ptr);
    const result: Io.Operation.Result = result: switch (pending.tag) {
        .file_read_streaming => {
            const operation = &operation_userdata.operation.file_read_streaming;
            break :result .{ .file_read_streaming = fileReadStreamingLimit(
                @intCast(source.get_handle()),
                operation.data_ptr[0..operation.data_len],
                .limited(source.get_data()),
            ) catch |err| switch (err) {
                error.Canceled => return Thread.current().currentFiber().cancel_protection.recancel(),
                error.WouldBlock => return,
                else => |e| e,
            } };
        },
        .file_write_streaming => {
            const operation = &operation_userdata.operation.file_write_streaming;
            break :result .{ .file_write_streaming = fileWriteStreamingLimit(
                @intCast(source.get_handle()),
                operation.header_ptr[0..operation.header_len],
                operation.data_ptr[0..operation.data_len],
                operation.splat,
                .limited(source.get_data()),
            ) catch |err| switch (err) {
                error.Canceled => return Thread.current().currentFiber().cancel_protection.recancel(),
                error.WouldBlock => return,
                else => |e| e,
            } };
        },
        .device_io_control => unreachable,
        .net_receive => @panic("TODO implement batched net_receive"),
        .net_send => @panic("TODO implement batched net_send"),
        .net_read => @panic("TODO implement batched net_read"),
        .net_write => @panic("TODO implement batched net_write"),
    };

    switch (pending.node.prev) {
        .none => batch.pending.head = pending.node.next,
        else => |prev_index| batch.storage[prev_index.toIndex()].pending.node.next = pending.node.next,
    }
    switch (pending.node.next) {
        .none => batch.pending.tail = pending.node.prev,
        else => |next_index| batch.storage[next_index.toIndex()].pending.node.prev = pending.node.prev,
    }

    switch (batch.completed.tail) {
        .none => batch.completed.head = index,
        else => |tail_index| batch.storage[tail_index.toIndex()].completion.node.next = index,
    }
    storage.* = .{ .completion = .{ .node = .{ .next = .none }, .result = result } };
    batch.completed.tail = index;

    source.as_object().release();
    const queue: c.dispatch.queue_t = @ptrCast(batch.userdata);
    const waiter: *BatchWaiter = @ptrCast(@alignCast(queue.as_object().get_context()));
    BatchWaiter.signal(waiter);
}

fn batchSourceCancel(context: ?*anyopaque) callconv(.c) void {
    const storage: *Io.Operation.Storage = @ptrCast(@alignCast(context));
    const pending = &storage.pending;
    const operation_userdata: *BatchOperationUserdata = .fromErased(&pending.userdata);
    const batch = operation_userdata.batch;
    const source = operation_userdata.source;
    const index: Io.Operation.OptionalIndex = .fromIndex(storage - batch.storage.ptr);

    switch (pending.node.prev) {
        .none => batch.pending.head = pending.node.next,
        else => |prev_index| batch.storage[prev_index.toIndex()].pending.node.next = pending.node.next,
    }
    switch (pending.node.next) {
        .none => batch.pending.tail = pending.node.prev,
        else => |next_index| batch.storage[next_index.toIndex()].pending.node.prev = pending.node.prev,
    }

    const tail_index = batch.unused.tail;
    switch (tail_index) {
        .none => batch.unused.head = index,
        else => batch.storage[tail_index.toIndex()].unused.next = index,
    }
    storage.* = .{ .unused = .{ .prev = tail_index, .next = .none } };
    batch.unused.tail = index;

    source.as_object().release();
    if (batch.pending.head != .none) return;
    const queue: c.dispatch.queue_t = @ptrCast(batch.userdata);
    const waiter: *BatchWaiter = @ptrCast(@alignCast(queue.as_object().get_context()));
    queue.as_object().release();
    waiter.wake();
}

fn dirCreateDir(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    permissions: Dir.Permissions,
) Dir.CreateDirError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    while (true) {
        switch (c.errno(c.mkdirat(dir.handle, sub_path_posix, permissions.toMode()))) {
            .SUCCESS => return,
            .INTR => {},
            .ACCES => return error.AccessDenied,
            .PERM => return error.PermissionDenied,
            .DQUOT => return error.DiskQuota,
            .EXIST => return error.PathAlreadyExists,
            .LOOP => return error.SymLinkLoop,
            .MLINK => return error.LinkQuotaExceeded,
            .NAMETOOLONG => return error.NameTooLong,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOSPC => return error.NoSpaceLeft,
            .NOTDIR => return error.NotDir,
            .ROFS => return error.ReadOnlyFileSystem,
            .ILSEQ => return error.BadPathName,
            .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
            .FAULT => |err| return errnoBug(err),
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn dirCreateDirPath(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    permissions: Dir.Permissions,
) Dir.CreateDirPathError!Dir.CreatePathStatus {
    const ev: *Evented = @ptrCast(@alignCast(userdata));

    var it = Dir.path.componentIterator(sub_path);
    var status: Dir.CreatePathStatus = .existed;
    var component = it.last() orelse return error.BadPathName;
    while (true) {
        if (dirCreateDir(ev, dir, component.path, permissions)) |_| {
            status = .created;
        } else |err| switch (err) {
            error.PathAlreadyExists => {
                // 若不是目录,必须返回错误;否则悬空符号链接可能导致无限循环。
                //
                //
                const fstat = try dirStatFile(ev, dir, component.path, .{});
                if (fstat.kind != .directory) return error.NotDir;
            },
            error.FileNotFound => |e| {
                component = it.previous() orelse return e;
                continue;
            },
            else => |e| return e,
        }
        component = it.next() orelse return status;
    }
}

fn dirCreateDirPathOpen(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    permissions: Dir.Permissions,
    options: Dir.OpenOptions,
) Dir.CreateDirPathOpenError!Dir {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return dirOpenDir(ev, dir, sub_path, options) catch |err| switch (err) {
        error.FileNotFound => {
            _ = try dirCreateDirPath(ev, dir, sub_path, permissions);
            return dirOpenDir(ev, dir, sub_path, options);
        },
        else => |e| return e,
    };
}

fn dirOpenDir(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    options: Dir.OpenOptions,
) Dir.OpenError!Dir {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    const flags: c.O = .{
        .ACCMODE = .RDONLY,
        .NOFOLLOW = !options.follow_symlinks,
        .DIRECTORY = true,
        .CLOEXEC = true,
    };

    while (true) {
        const rc = c.openat(dir.handle, sub_path_posix, flags);
        switch (c.errno(rc)) {
            .SUCCESS => return .{ .handle = @intCast(rc) },
            .INTR => {},
            .INVAL => return error.BadPathName,
            .ACCES => return error.AccessDenied,
            .LOOP => return error.SymLinkLoop,
            .MFILE => return error.ProcessFdQuotaExceeded,
            .NAMETOOLONG => return error.NameTooLong,
            .NFILE => return error.SystemFdQuotaExceeded,
            .NODEV => return error.NoDevice,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOTDIR => return error.NotDir,
            .PERM => return error.PermissionDenied,
            .NXIO => return error.NoDevice,
            .ILSEQ => return error.BadPathName,
            .FAULT => |err| return errnoBug(err),
            .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
            .BUSY => |err| return errnoBug(err), // 未传入 O_EXCL
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn dirStat(userdata: ?*anyopaque, dir: Dir) Dir.StatError!Dir.Stat {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return fileStat(ev, .{
        .handle = dir.handle,
        .flags = .{ .nonblocking = false },
    });
}

fn dirStatFile(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    options: Dir.StatFileOptions,
) Dir.StatFileError!File.Stat {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    const flags: u32 = if (options.follow_symlinks) 0 else c.AT.SYMLINK_NOFOLLOW;

    while (true) {
        var stat = std.mem.zeroes(c.Stat);
        switch (c.errno(c.fstatat(dir.handle, sub_path_posix, &stat, flags))) {
            .SUCCESS => return statFromPosix(&stat),
            .INTR => {},
            .INVAL => |err| return errnoBug(err),
            .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
            .NOMEM => return error.SystemResources,
            .ACCES => return error.AccessDenied,
            .PERM => return error.PermissionDenied,
            .FAULT => |err| return errnoBug(err),
            .NAMETOOLONG => return error.NameTooLong,
            .LOOP => return error.SymLinkLoop,
            .NOENT => return error.FileNotFound,
            .NOTDIR => return error.FileNotFound,
            .ILSEQ => return error.BadPathName,
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn dirAccess(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    options: Dir.AccessOptions,
) Dir.AccessError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    const flags: u32 = if (options.follow_symlinks) 0 else c.AT.SYMLINK_NOFOLLOW;

    const mode: u32 =
        @as(u32, if (options.read) c.R_OK else 0) |
        @as(u32, if (options.write) c.W_OK else 0) |
        @as(u32, if (options.execute) c.X_OK else 0);

    while (true) switch (c.errno(c.faccessat(dir.handle, sub_path_posix, mode, flags))) {
        .SUCCESS => return,
        .INTR => {},
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        .LOOP => return error.SymLinkLoop,
        .TXTBSY => return error.FileBusy,
        .NOTDIR => return error.FileNotFound,
        .NOENT => return error.FileNotFound,
        .NAMETOOLONG => return error.NameTooLong,
        .INVAL => |err| return errnoBug(err),
        .FAULT => |err| return errnoBug(err),
        .IO => return error.InputOutput,
        .NOMEM => return error.SystemResources,
        .ILSEQ => return error.BadPathName,
        else => |err| return unexpectedErrno(err),
    };
}

fn dirCreateFile(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    flags: Dir.CreateFileOptions,
) File.OpenError!File {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    const os_flags: c.O = .{
        .ACCMODE = if (flags.read) .RDWR else .WRONLY,
        .NONBLOCK = flags.lock == .none or flags.lock_nonblocking,
        .SHLOCK = flags.lock == .shared,
        .EXLOCK = flags.lock == .exclusive,
        .CREAT = true,
        .TRUNC = flags.truncate,
        .EXCL = flags.exclusive,
        .CLOEXEC = true,
    };

    const fd: c.fd_t = while (true) {
        const rc = c.openat(dir.handle, sub_path_posix, os_flags, flags.permissions.toMode());
        switch (c.errno(rc)) {
            .SUCCESS => break @intCast(rc),
            .INTR => {},
            .FAULT => |err| return errnoBug(err),
            .INVAL => return error.BadPathName,
            .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
            .ACCES => return error.AccessDenied,
            .FBIG => return error.FileTooBig,
            .OVERFLOW => return error.FileTooBig,
            .ISDIR => return error.IsDir,
            .LOOP => return error.SymLinkLoop,
            .MFILE => return error.ProcessFdQuotaExceeded,
            .NAMETOOLONG => return error.NameTooLong,
            .NFILE => return error.SystemFdQuotaExceeded,
            .NODEV => return error.NoDevice,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOSPC => return error.NoSpaceLeft,
            .NOTDIR => return error.NotDir,
            .PERM => return error.PermissionDenied,
            .EXIST => return error.PathAlreadyExists,
            .BUSY => return error.DeviceBusy,
            .OPNOTSUPP => return error.FileLocksUnsupported,
            .AGAIN => return error.WouldBlock,
            .TXTBSY => return error.FileBusy,
            .ROFS => return error.ReadOnlyFileSystem,
            .NXIO => return error.NoDevice,
            .ILSEQ => return error.BadPathName,
            else => |err| return unexpectedErrno(err),
        }
    };
    errdefer closeFd(fd);

    return .{
        .handle = fd,
        .flags = .{ .nonblocking = os_flags.NONBLOCK },
    };
}

fn dirCreateFileAtomic(
    userdata: ?*anyopaque,
    dir: Dir,
    dest_path: []const u8,
    options: Dir.CreateFileAtomicOptions,
) Dir.CreateFileAtomicError!File.Atomic {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    if (Dir.path.dirname(dest_path)) |dirname| {
        const new_dir = if (options.make_path)
            dirCreateDirPathOpen(ev, dir, dirname, .default_dir, .{}) catch |err| switch (err) {
                // 这些值在此上下文中均无意义。
                error.IsDir,
                error.Streaming,
                error.DiskQuota,
                error.PathAlreadyExists,
                error.LinkQuotaExceeded,
                error.PipeBusy,
                error.FileTooBig,
                error.FileLocksUnsupported,
                error.DeviceBusy,
                => return error.Unexpected,

                else => |e| return e,
            }
        else
            try dirOpenDir(ev, dir, dirname, .{});
        return ev.atomicFileInit(Dir.path.basename(dest_path), options.permissions, new_dir, true);
    }
    return ev.atomicFileInit(dest_path, options.permissions, dir, false);
}

fn atomicFileInit(
    ev: *Evented,
    dest_basename: []const u8,
    permissions: File.Permissions,
    dir: Dir,
    close_dir_on_deinit: bool,
) Dir.CreateFileAtomicError!File.Atomic {
    while (true) {
        var random_integer: u64 = undefined;
        random(ev, @ptrCast(&random_integer));
        const tmp_sub_path = std.fmt.hex(random_integer);
        const file = dirCreateFile(ev, dir, &tmp_sub_path, .{
            .permissions = permissions,
            .exclusive = true,
        }) catch |err| switch (err) {
            error.PathAlreadyExists => continue,
            error.DeviceBusy => continue,
            error.FileBusy => continue,

            error.IsDir => return error.Unexpected, // 没有路径分量。
            error.FileTooBig => return error.Unexpected, // 执行创建而非打开。
            error.FileLocksUnsupported => return error.Unexpected, // 不请求锁。
            error.PipeBusy => return error.Unexpected, // 未在打开管道。

            else => |e| return e,
        };
        return .{
            .file = file,
            .file_basename_hex = random_integer,
            .dest_sub_path = dest_basename,
            .file_open = true,
            .file_exists = true,
            .close_dir_on_deinit = close_dir_on_deinit,
            .dir = dir,
        };
    }
}

fn dirOpenFile(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    flags: Dir.OpenFileOptions,
) File.OpenError!File {
    const ev: *Evented = @ptrCast(@alignCast(userdata));

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    const os_flags: c.O = .{
        .ACCMODE = switch (flags.mode) {
            .read_only => .RDONLY,
            .write_only => .WRONLY,
            .read_write => .RDWR,
        },
        .NONBLOCK = flags.lock == .none or flags.lock_nonblocking,
        .SHLOCK = flags.lock == .shared,
        .EXLOCK = flags.lock == .exclusive,
        .NOFOLLOW = !flags.follow_symlinks,
        .NOCTTY = !flags.allow_ctty,
        .CLOEXEC = true,
    };

    const fd: c.fd_t = while (true) {
        const rc = c.openat(dir.handle, sub_path_posix, os_flags);
        switch (c.errno(rc)) {
            .SUCCESS => break @intCast(rc),
            .INTR => {},
            .FAULT => |err| return errnoBug(err),
            .INVAL => return error.BadPathName,
            .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
            .ACCES => return error.AccessDenied,
            .FBIG => return error.FileTooBig,
            .OVERFLOW => return error.FileTooBig,
            .ISDIR => return error.IsDir,
            .LOOP => return error.SymLinkLoop,
            .MFILE => return error.ProcessFdQuotaExceeded,
            .NAMETOOLONG => return error.NameTooLong,
            .NFILE => return error.SystemFdQuotaExceeded,
            .NODEV => return error.NoDevice,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOSPC => return error.NoSpaceLeft,
            .NOTDIR => return error.NotDir,
            .PERM => return error.PermissionDenied,
            .EXIST => return error.PathAlreadyExists,
            .BUSY => return error.DeviceBusy,
            .OPNOTSUPP => return error.FileLocksUnsupported,
            .AGAIN => return error.WouldBlock,
            .TXTBSY => return error.FileBusy,
            .NXIO => return error.NoDevice,
            .ROFS => return error.ReadOnlyFileSystem,
            .ILSEQ => return error.BadPathName,
            else => |err| return unexpectedErrno(err),
        }
    };
    errdefer closeFd(fd);

    if (!flags.allow_directory) {
        const is_dir = is_dir: {
            const stat = fileStat(ev, .{
                .handle = fd,
                .flags = .{ .nonblocking = false },
            }) catch |err| switch (err) {
                // 是否为目录未知,或无法确定。
                error.Streaming => break :is_dir false,
                else => |e| return e,
            };
            break :is_dir stat.kind == .directory;
        };
        if (is_dir) return error.IsDir;
    }

    return .{
        .handle = fd,
        .flags = .{ .nonblocking = os_flags.NONBLOCK },
    };
}

fn dirClose(userdata: ?*anyopaque, dirs: []const Dir) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    for (dirs) |dir| closeFd(dir.handle);
}

fn dirRead(userdata: ?*anyopaque, dr: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const Header = extern struct {
        seek: i64,
    };
    const header: *Header = @ptrCast(dr.buffer.ptr);
    const header_end: usize = @sizeOf(Header);
    if (dr.index < header_end) {
        // 初始化头部。
        dr.index = header_end;
        dr.end = header_end;
        header.* = .{ .seek = 0 };
    }
    var buffer_index: usize = 0;
    while (buffer.len - buffer_index != 0) {
        if (dr.end - dr.index == 0) {
            // 重新填充缓冲区,
            // 除非已创建对缓冲数据的引用。
            if (buffer_index != 0) break;
            if (dr.state == .reset) {
                ev.lseek(dr.dir.handle, 0, c.SEEK.SET) catch |err| switch (err) {
                    error.Unseekable => return error.Unexpected,
                    else => |e| return e,
                };
                dr.state = .reading;
            }
            const dents_buffer = dr.buffer[header_end..];
            const n: usize = while (true) {
                const rc = c.getdirentries(dr.dir.handle, dents_buffer.ptr, dents_buffer.len, &header.seek);
                switch (c.errno(rc)) {
                    .SUCCESS => break @intCast(rc),
                    .INTR => {},
                    .BADF => |err| return errnoBug(err), // Dir 无效,或打开时未启用迭代能力。
                    .FAULT => |err| return errnoBug(err),
                    .NOTDIR => |err| return errnoBug(err),
                    .INVAL => |err| return errnoBug(err),
                    else => |err| return unexpectedErrno(err),
                }
            };
            if (n == 0) {
                dr.state = .finished;
                return 0;
            }
            dr.index = header_end;
            dr.end = header_end + n;
        }
        const darwin_entry = @as(*align(1) c.dirent, @ptrCast(&dr.buffer[dr.index]));
        const next_index = dr.index + darwin_entry.reclen;
        dr.index = next_index;

        const name = @as([*]u8, @ptrCast(&darwin_entry.name))[0..darwin_entry.namlen];
        if (std.mem.eql(u8, name, ".") or std.mem.eql(u8, name, "..") or (darwin_entry.ino == 0))
            continue;

        const entry_kind: File.Kind = switch (darwin_entry.type) {
            c.DT.BLK => .block_device,
            c.DT.CHR => .character_device,
            c.DT.DIR => .directory,
            c.DT.FIFO => .named_pipe,
            c.DT.LNK => .sym_link,
            c.DT.REG => .file,
            c.DT.SOCK => .unix_domain_socket,
            c.DT.WHT => .whiteout,
            else => .unknown,
        };
        buffer[buffer_index] = .{
            .name = name,
            .kind = entry_kind,
            .inode = darwin_entry.ino,
        };
        buffer_index += 1;
    }
    return buffer_index;
}

fn dirRealPath(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return ev.realPath(dir.handle, out_buffer);
}

fn realPath(ev: *Evented, fd: c.fd_t, out_buffer: []u8) File.RealPathError!usize {
    _ = ev;
    var buffer: [c.PATH_MAX]u8 = undefined;
    @memset(&buffer, 0);
    while (true) {
        switch (c.errno(c.fcntl(fd, c.F.GETPATH, &buffer))) {
            .SUCCESS => break,
            .INTR => {},
            .ACCES => return error.AccessDenied,
            .BADF => return error.FileNotFound,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOSPC => return error.NameTooLong,
            .RANGE => return error.NameTooLong,
            else => |err| return unexpectedErrno(err),
        }
    }
    const n = std.mem.findScalar(u8, &buffer, 0) orelse buffer.len;
    if (n > out_buffer.len) return error.NameTooLong;
    @memcpy(out_buffer[0..n], buffer[0..n]);
    return n;
}

fn dirRealPathFile(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    out_buffer: []u8,
) Dir.RealPathFileError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    if (dir.handle == c.AT.FDCWD) {
        if (out_buffer.len < c.PATH_MAX) return error.NameTooLong;
        while (true) {
            if (c.realpath(sub_path_posix, out_buffer.ptr)) |redundant_pointer| {
                assert(redundant_pointer == out_buffer.ptr);
                return std.mem.findScalar(u8, out_buffer, 0) orelse out_buffer.len;
            }
            const err: c.E = @fromBackingInt(@intCast(c._errno().*));
            switch (err) {
                .INTR => {},
                .INVAL => return errnoBug(err),
                .BADF => return errnoBug(err),
                .FAULT => return errnoBug(err),
                .ACCES => return error.AccessDenied,
                .NOENT => return error.FileNotFound,
                .OPNOTSUPP => return error.OperationUnsupported,
                .NOTDIR => return error.NotDir,
                .NAMETOOLONG => return error.NameTooLong,
                .LOOP => return error.SymLinkLoop,
                .IO => return error.InputOutput,
                else => return unexpectedErrno(err),
            }
        }
    }

    const os_flags: c.O = .{
        .NONBLOCK = true,
        .CLOEXEC = true,
    };

    const fd: c.fd_t = while (true) {
        const rc = c.openat(dir.handle, sub_path_posix, os_flags);
        switch (c.errno(rc)) {
            .SUCCESS => break @intCast(rc),
            .INTR => {},
            .FAULT => |err| return errnoBug(err),
            .INVAL => return error.BadPathName,
            .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
            .ACCES => return error.AccessDenied,
            .FBIG => return error.FileTooBig,
            .OVERFLOW => return error.FileTooBig,
            .ISDIR => return error.IsDir,
            .LOOP => return error.SymLinkLoop,
            .MFILE => return error.ProcessFdQuotaExceeded,
            .NAMETOOLONG => return error.NameTooLong,
            .NFILE => return error.SystemFdQuotaExceeded,
            .NODEV => return error.NoDevice,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOSPC => return error.NoSpaceLeft,
            .NOTDIR => return error.NotDir,
            .PERM => return error.PermissionDenied,
            .EXIST => return error.PathAlreadyExists,
            .BUSY => return error.DeviceBusy,
            .NXIO => return error.NoDevice,
            .ILSEQ => return error.BadPathName,
            else => |err| return unexpectedErrno(err),
        }
    };
    defer closeFd(fd);
    return ev.realPath(fd, out_buffer);
}

fn dirDeleteFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    while (true) switch (c.errno(c.unlinkat(dir.handle, sub_path_posix, 0))) {
        .SUCCESS => return,
        .INTR => {},
        // 某些系统在尝试删除目录时返回权限错误,因此需要专门处理该情况并转换错误。
        //
        //
        .PERM => {
            // 不要跟随符号链接,以匹配 unlinkat 的行为(unlinkat 操作符号链接本身而不跟随它们)。
            var st = std.mem.zeroes(c.Stat);
            while (true) switch (c.errno(c.fstatat(
                dir.handle,
                sub_path_posix,
                &st,
                c.AT.SYMLINK_NOFOLLOW,
            ))) {
                .SUCCESS => break,
                .INTR => {},
                else => return error.PermissionDenied,
            };
            if (st.mode & c.S.IFMT == c.S.IFDIR) return error.IsDir else return error.PermissionDenied;
        },
        .ACCES => return error.AccessDenied,
        .BUSY => return error.FileBusy,
        .FAULT => |err| return errnoBug(err),
        .IO => return error.FileSystem,
        .ISDIR => return error.IsDir,
        .LOOP => return error.SymLinkLoop,
        .NAMETOOLONG => return error.NameTooLong,
        .NOENT => return error.FileNotFound,
        .NOTDIR => return error.NotDir,
        .NOMEM => return error.SystemResources,
        .ROFS => return error.ReadOnlyFileSystem,
        .EXIST => |err| return errnoBug(err),
        .NOTEMPTY => |err| return errnoBug(err), // 未传入 AT.REMOVEDIR
        .ILSEQ => return error.BadPathName,
        .INVAL => |err| return errnoBug(err), // 标志无效,或路径名的最后一个分量为 .
        .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
        else => |err| return unexpectedErrno(err),
    };
}

fn dirDeleteDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    while (true) switch (c.errno(c.unlinkat(dir.handle, sub_path_posix, c.AT.REMOVEDIR))) {
        .SUCCESS => return,
        .INTR => {},
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .BUSY => return error.FileBusy,
        .FAULT => |err| return errnoBug(err),
        .IO => return error.FileSystem,
        .ISDIR => |err| return errnoBug(err),
        .LOOP => return error.SymLinkLoop,
        .NAMETOOLONG => return error.NameTooLong,
        .NOENT => return error.FileNotFound,
        .NOTDIR => return error.NotDir,
        .NOMEM => return error.SystemResources,
        .ROFS => return error.ReadOnlyFileSystem,
        .EXIST => |err| return errnoBug(err),
        .NOTEMPTY => return error.DirNotEmpty,
        .ILSEQ => return error.BadPathName,
        .INVAL => |err| return errnoBug(err), // 标志无效,或路径名的最后一个分量为 .
        .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
        else => |err| return unexpectedErrno(err),
    };
}

fn dirRename(
    userdata: ?*anyopaque,
    old_dir: Dir,
    old_sub_path: []const u8,
    new_dir: Dir,
    new_sub_path: []const u8,
) Dir.RenameError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var old_path_buffer: [c.PATH_MAX]u8 = undefined;
    var new_path_buffer: [c.PATH_MAX]u8 = undefined;

    const old_sub_path_posix = try pathToPosix(old_sub_path, &old_path_buffer);
    const new_sub_path_posix = try pathToPosix(new_sub_path, &new_path_buffer);

    while (true) switch (c.errno(c.renameat(old_dir.handle, old_sub_path_posix, new_dir.handle, new_sub_path_posix))) {
        .SUCCESS => return,
        .INTR => {},
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .BUSY => return error.FileBusy,
        .DQUOT => return error.DiskQuota,
        .ISDIR => return error.IsDir,
        .IO => return error.HardwareFailure,
        .LOOP => return error.SymLinkLoop,
        .MLINK => return error.LinkQuotaExceeded,
        .NAMETOOLONG => return error.NameTooLong,
        .NOENT => return error.FileNotFound,
        .NOTDIR => return error.NotDir,
        .NOMEM => return error.SystemResources,
        .NOSPC => return error.NoSpaceLeft,
        .EXIST => return error.DirNotEmpty,
        .NOTEMPTY => return error.DirNotEmpty,
        .ROFS => return error.ReadOnlyFileSystem,
        .XDEV => return error.CrossDevice,
        .ILSEQ => return error.BadPathName,
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        else => |err| return unexpectedErrno(err),
    };
}

fn dirRenamePreserve(
    userdata: ?*anyopaque,
    old_dir: Dir,
    old_sub_path: []const u8,
    new_dir: Dir,
    new_sub_path: []const u8,
) Dir.RenamePreserveError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    // 创建硬链接,然后删除原文件。
    try dirHardLink(ev, old_dir, old_sub_path, new_dir, new_sub_path, .{ .follow_symlinks = false });
    const prev = swapCancelProtection(ev, .blocked);
    defer _ = swapCancelProtection(ev, prev);
    dirDeleteFile(ev, old_dir, old_sub_path) catch {};
}

fn dirSymLink(
    userdata: ?*anyopaque,
    dir: Dir,
    target_path: []const u8,
    sym_link_path: []const u8,
    flags: Dir.SymLinkFlags,
) Dir.SymLinkError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = flags;

    var target_path_buffer: [c.PATH_MAX]u8 = undefined;
    var sym_link_path_buffer: [c.PATH_MAX]u8 = undefined;

    const target_path_posix = try pathToPosix(target_path, &target_path_buffer);
    const sym_link_path_posix = try pathToPosix(sym_link_path, &sym_link_path_buffer);

    while (true) switch (c.errno(c.symlinkat(target_path_posix, dir.handle, sym_link_path_posix))) {
        .SUCCESS => return,
        .INTR => {},
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .DQUOT => return error.DiskQuota,
        .EXIST => return error.PathAlreadyExists,
        .IO => return error.FileSystem,
        .LOOP => return error.SymLinkLoop,
        .NAMETOOLONG => return error.NameTooLong,
        .NOENT => return error.FileNotFound,
        .NOTDIR => return error.NotDir,
        .NOMEM => return error.SystemResources,
        .NOSPC => return error.NoSpaceLeft,
        .ROFS => return error.ReadOnlyFileSystem,
        .ILSEQ => return error.BadPathName,
        else => |err| return unexpectedErrno(err),
    };
}

fn dirReadLink(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    buffer: []u8,
) Dir.ReadLinkError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    var sub_path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &sub_path_buffer);
    while (true) {
        const rc = c.readlinkat(dir.handle, sub_path_posix, buffer.ptr, buffer.len);
        switch (c.errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .INTR => {},
            .ACCES => return error.AccessDenied,
            .FAULT => |err| return errnoBug(err),
            .INVAL => return error.NotLink,
            .IO => return error.FileSystem,
            .LOOP => return error.SymLinkLoop,
            .NAMETOOLONG => return error.NameTooLong,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOTDIR => return error.NotDir,
            .ILSEQ => return error.BadPathName,
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn dirSetOwner(
    userdata: ?*anyopaque,
    dir: Dir,
    owner: ?File.Uid,
    group: ?File.Gid,
) Dir.SetOwnerError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    return fchown(dir.handle, owner, group);
}

fn fchown(fd: c.fd_t, owner: ?File.Uid, group: ?File.Gid) File.SetOwnerError!void {
    const uid = owner orelse std.math.maxInt(c.uid_t);
    const gid = group orelse std.math.maxInt(c.gid_t);
    while (true) switch (c.errno(c.fchown(fd, uid, gid))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err), // fd 很可能指向未设置 `Dir.OpenOptions.iterate` 打开的目录
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ACCES => return error.AccessDenied,
        .IO => return error.InputOutput,
        .LOOP => return error.SymLinkLoop,
        .NOENT => return error.FileNotFound,
        .NOMEM => return error.SystemResources,
        .NOTDIR => return error.FileNotFound,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        else => |err| return unexpectedErrno(err),
    };
}

fn dirSetFileOwner(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    owner: ?File.Uid,
    group: ?File.Gid,
    options: Dir.SetFileOwnerOptions,
) Dir.SetFileOwnerError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);
    _ = ev;
    while (true) switch (c.errno(c.fchownat(
        dir.handle,
        sub_path_posix,
        owner orelse std.math.maxInt(c.uid_t),
        group orelse std.math.maxInt(c.gid_t),
        if (options.follow_symlinks) 0 else c.AT.SYMLINK_NOFOLLOW,
    ))) {
        .SUCCESS => return,
        .INTR => continue,
        .BADF => |err| return errnoBug(err), // fd 很可能指向未设置 `Dir.OpenOptions.iterate` 打开的目录
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ACCES => return error.AccessDenied,
        .IO => return error.InputOutput,
        .LOOP => return error.SymLinkLoop,
        .NOENT => return error.FileNotFound,
        .NOMEM => return error.SystemResources,
        .NOTDIR => return error.FileNotFound,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        else => |err| return unexpectedErrno(err),
    };
}

fn dirSetPermissions(
    userdata: ?*anyopaque,
    dir: Dir,
    permissions: Dir.Permissions,
) Dir.SetPermissionsError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return ev.fchmod(dir.handle, permissions.toMode());
}

fn dirSetFilePermissions(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    permissions: Dir.Permissions,
    options: Dir.SetFilePermissionsOptions,
) Dir.SetFilePermissionsError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    const mode = permissions.toMode();
    const flags: u32 = if (options.follow_symlinks) 0 else c.AT.SYMLINK_NOFOLLOW;

    while (true) switch (c.errno(c.fchmodat(dir.handle, sub_path_posix, mode, flags))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err),
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ACCES => return error.AccessDenied,
        .IO => return error.InputOutput,
        .LOOP => return error.SymLinkLoop,
        .MFILE => return error.ProcessFdQuotaExceeded,
        .NAMETOOLONG => return error.NameTooLong,
        .NFILE => return error.SystemFdQuotaExceeded,
        .NOENT => return error.FileNotFound,
        .NOTDIR => return error.FileNotFound,
        .NOMEM => return error.SystemResources,
        .OPNOTSUPP => return error.OperationUnsupported,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        else => |err| return unexpectedErrno(err),
    };
}

fn dirSetTimestamps(
    userdata: ?*anyopaque,
    dir: Dir,
    sub_path: []const u8,
    options: Dir.SetTimestampsOptions,
) Dir.SetTimestampsError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var times_buffer: [2]c.timespec = undefined;
    const times = if (options.modify_timestamp == .now and options.access_timestamp == .now) null else p: {
        times_buffer = .{
            setTimestampToPosix(options.access_timestamp),
            setTimestampToPosix(options.modify_timestamp),
        };
        break :p &times_buffer;
    };

    const flags: u32 = if (options.follow_symlinks) 0 else c.AT.SYMLINK_NOFOLLOW;

    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const sub_path_posix = try pathToPosix(sub_path, &path_buffer);

    while (true) switch (c.errno(c.utimensat(dir.handle, sub_path_posix, times, flags))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err), // 始终存在竞态条件
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        else => |err| return unexpectedErrno(err),
    };
}

fn dirHardLink(
    userdata: ?*anyopaque,
    old_dir: Dir,
    old_sub_path: []const u8,
    new_dir: Dir,
    new_sub_path: []const u8,
    options: Dir.HardLinkOptions,
) Dir.HardLinkError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var old_path_buffer: [c.PATH_MAX]u8 = undefined;
    var new_path_buffer: [c.PATH_MAX]u8 = undefined;

    const old_sub_path_posix = try pathToPosix(old_sub_path, &old_path_buffer);
    const new_sub_path_posix = try pathToPosix(new_sub_path, &new_path_buffer);

    const flags: u32 = if (options.follow_symlinks) c.AT.SYMLINK_FOLLOW else 0;
    return linkat(old_dir.handle, old_sub_path_posix, new_dir.handle, new_sub_path_posix, flags);
}

fn fileStat(userdata: ?*anyopaque, file: File) File.StatError!File.Stat {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    while (true) {
        var stat = std.mem.zeroes(c.Stat);
        switch (c.errno(c.fstat(file.handle, &stat))) {
            .SUCCESS => return statFromPosix(&stat),
            .INTR => {},
            .INVAL => |err| return errnoBug(err),
            .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
            .NOMEM => return error.SystemResources,
            .ACCES => return error.AccessDenied,
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn fileLength(userdata: ?*anyopaque, file: File) File.LengthError!u64 {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const stat = try fileStat(ev, file);
    return stat.size;
}

fn fileClose(userdata: ?*anyopaque, files: []const File) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    for (files) |file| closeFd(file.handle);
}

fn fileWritePositional(
    userdata: ?*anyopaque,
    file: File,
    header: []const u8,
    data: []const []const u8,
    splat: usize,
    offset: u64,
) File.WritePositionalError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    var iovecs: [max_iovecs_len]iovec_const = undefined;
    var iovlen: iovlen_t = 0;
    var remaining: Io.Limit = .unlimited;
    addBuf(true, &iovecs, &iovlen, &remaining, header);
    for (data[0 .. data.len - 1]) |bytes| addBuf(true, &iovecs, &iovlen, &remaining, bytes);
    const pattern = data[data.len - 1];
    var backup_buffer: [splat_buffer_size]u8 = undefined;
    if (iovecs.len - iovlen != 0 and remaining != .nothing) switch (splat) {
        0 => {},
        1 => addBuf(true, &iovecs, &iovlen, &remaining, pattern),
        else => switch (pattern.len) {
            0 => {},
            1 => {
                const splat_buffer = &backup_buffer;
                const memset_len = @min(splat_buffer.len, splat);
                const buf = splat_buffer[0..memset_len];
                @memset(buf, pattern[0]);
                addBuf(true, &iovecs, &iovlen, &remaining, buf);
                var remaining_splat = splat - buf.len;
                while (remaining_splat > splat_buffer.len and iovecs.len - iovlen != 0 and remaining != .nothing) {
                    assert(buf.len == splat_buffer.len);
                    addBuf(true, &iovecs, &iovlen, &remaining, splat_buffer);
                    remaining_splat -= splat_buffer.len;
                }
                addBuf(true, &iovecs, &iovlen, &remaining, splat_buffer[0..@min(remaining_splat, splat_buffer.len)]);
            },
            else => for (0..@min(splat, iovecs.len - iovlen)) |_| {
                if (remaining == .nothing) break;
                addBuf(true, &iovecs, &iovlen, &remaining, pattern);
            },
        },
    };
    if (iovlen == 0) return 0;
    while (true) {
        const rc = c.pwritev(file.handle, &iovecs, iovlen, @bitCast(offset));
        switch (c.errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .INTR => {},
            .INVAL => |err| return errnoBug(err),
            .FAULT => |err| return errnoBug(err),
            .DESTADDRREQ => |err| return errnoBug(err), // 从未调用 `connect`。
            .CONNRESET => |err| return errnoBug(err), // 不是套接字句柄。
            .BADF => return error.NotOpenForWriting,
            .AGAIN => return error.WouldBlock,
            .DQUOT => return error.DiskQuota,
            .FBIG => return error.FileTooBig,
            .IO => return error.InputOutput,
            .NOSPC => return error.NoSpaceLeft,
            .PERM => return error.PermissionDenied,
            .PIPE => return error.BrokenPipe,
            .BUSY => return error.DeviceBusy,
            .TXTBSY => return error.FileBusy,
            .NXIO => return error.Unseekable,
            .SPIPE => return error.Unseekable,
            .OVERFLOW => return error.Unseekable,
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn fileWriteFileStreaming(
    userdata: ?*anyopaque,
    file: File,
    header: []const u8,
    file_reader: *File.Reader,
    limit: Io.Limit,
) File.Writer.WriteFileError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const reader_buffered = file_reader.interface.buffered();
    if (reader_buffered.len >= @backingInt(limit)) {
        const n = try fileWriteStreaming(ev, file, header, &.{limit.slice(reader_buffered)}, 1);
        file_reader.interface.toss(n -| header.len);
        return n;
    }
    const file_limit = @backingInt(limit) - reader_buffered.len;
    const out_fd = file.handle;
    const in_fd = file_reader.file.handle;

    if (file_reader.size) |size| {
        if (size - file_reader.pos == 0) {
            if (reader_buffered.len != 0) {
                const n = try fileWriteStreaming(ev, file, header, &.{limit.slice(reader_buffered)}, 1);
                file_reader.interface.toss(n -| header.len);
                return n;
            } else {
                return error.EndOfStream;
            }
        }
    }

    if (@atomicLoad(UseSendfile, &ev.use_sendfile, .monotonic) == .disabled) return error.Unimplemented;
    const offset = std.math.cast(c.off_t, file_reader.pos) orelse return error.Unimplemented;
    var hdtr_data: c.sf_hdtr = undefined;
    var headers: [2]iovec_const = undefined;
    var headers_i: u8 = 0;
    if (header.len != 0) {
        headers[headers_i] = .{ .base = header.ptr, .len = header.len };
        headers_i += 1;
    }
    if (reader_buffered.len != 0) {
        headers[headers_i] = .{ .base = reader_buffered.ptr, .len = reader_buffered.len };
        headers_i += 1;
    }
    const hdtr: ?*c.sf_hdtr = if (headers_i == 0) null else b: {
        hdtr_data = .{
            .headers = &headers,
            .hdr_cnt = headers_i,
            .trailers = null,
            .trl_cnt = 0,
        };
        break :b &hdtr_data;
    };
    const max_count = std.math.maxInt(i32); // 避免 EINVAL。
    var len: c.off_t = @min(file_limit, max_count);
    const flags = 0;
    while (true) switch (c.errno(c.sendfile(in_fd, out_fd, offset, &len, hdtr, flags))) {
        .SUCCESS => break,
        .OPNOTSUPP, .NOTSOCK, .NOSYS => {
            // 在尝试其他操作之前,
            // 给予调用代码观察状态的机会。
            @atomicStore(UseSendfile, &ev.use_sendfile, .disabled, .monotonic);
            return 0;
        },
        .INTR => if (len > 0) break,
        .AGAIN => {
            if (len == 0) return error.WouldBlock;
            break;
        },
        else => |e| {
            assert(error.Unexpected == switch (e) {
                .NOTCONN => return error.BrokenPipe,
                .IO => return error.InputOutput,
                .PIPE => return error.BrokenPipe,
                .BADF => |err| errnoBug(err),
                .FAULT => |err| errnoBug(err),
                .INVAL => |err| errnoBug(err),
                else => |err| unexpectedErrno(err),
            });
            // 让调用代码有机会先观察错误,
            // 再尝试其他方式。
            @atomicStore(UseSendfile, &ev.use_sendfile, .disabled, .monotonic);
            return 0;
        },
    };
    if (len == 0) {
        file_reader.size = file_reader.pos;
        return error.EndOfStream;
    }
    const u_len: usize = @bitCast(len);
    file_reader.interface.toss(u_len -| header.len);
    return u_len;
}

fn fileWriteFilePositional(
    userdata: ?*anyopaque,
    file: File,
    header: []const u8,
    file_reader: *File.Reader,
    limit: Io.Limit,
    offset: u64,
) File.WriteFilePositionalError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const reader_buffered = file_reader.interface.buffered();
    if (reader_buffered.len >= @backingInt(limit)) {
        const n = try fileWritePositional(
            ev,
            file,
            header,
            &.{limit.slice(reader_buffered)},
            1,
            offset,
        );
        file_reader.interface.toss(n -| header.len);
        return n;
    }
    const out_fd = file.handle;
    const in_fd = file_reader.file.handle;

    if (file_reader.size) |size| {
        if (size - file_reader.pos == 0) {
            if (reader_buffered.len != 0) {
                const n = try fileWritePositional(
                    ev,
                    file,
                    header,
                    &.{limit.slice(reader_buffered)},
                    1,
                    offset,
                );
                file_reader.interface.toss(n -| header.len);
                return n;
            } else {
                return error.EndOfStream;
            }
        }
    }

    if (@atomicLoad(UseFcopyfile, &ev.use_fcopyfile, .monotonic) == .disabled)
        return error.Unimplemented;
    if (file_reader.pos != 0) return error.Unimplemented;
    if (offset != 0) return error.Unimplemented;
    if (limit != .unlimited) return error.Unimplemented;
    const size = file_reader.getSize() catch return error.Unimplemented;
    if (header.len != 0 or reader_buffered.len != 0) {
        const n = try fileWritePositional(
            ev,
            file,
            header,
            &.{limit.slice(reader_buffered)},
            1,
            offset,
        );
        file_reader.interface.toss(n -| header.len);
        return n;
    }
    while (true) {
        const rc = c.fcopyfile(in_fd, out_fd, null, .{ .DATA = true });
        switch (c.errno(rc)) {
            .SUCCESS => break,
            .INTR => {},
            .OPNOTSUPP => {
                // 在尝试其他操作之前,
                // 给予调用代码观察状态的机会。
                @atomicStore(UseFcopyfile, &ev.use_fcopyfile, .disabled, .monotonic);
                return 0;
            },
            else => |e| {
                assert(error.Unexpected == switch (e) {
                    .NOMEM => return error.SystemResources,
                    .INVAL => |err| errnoBug(err),
                    else => |err| unexpectedErrno(err),
                });
                return 0;
            },
        }
    }
    file_reader.pos = size;
    return size;
}

fn fileReadPositional(
    userdata: ?*anyopaque,
    file: File,
    data: []const []u8,
    offset: u64,
) File.ReadPositionalError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    var iovecs: [max_iovecs_len]iovec = undefined;
    var iovlen: iovlen_t = 0;
    var remaining: Io.Limit = .unlimited;
    for (data) |buf| addBuf(false, &iovecs, &iovlen, &remaining, buf);
    if (iovlen == 0) return 0;
    while (true) {
        const rc = c.preadv(file.handle, &iovecs, iovlen, @bitCast(offset));
        switch (c.errno(rc)) {
            .SUCCESS => return @intCast(rc),
            .INTR => {},
            .NXIO => return error.Unseekable,
            .SPIPE => return error.Unseekable,
            .OVERFLOW => return error.Unseekable,
            .NOBUFS => return error.SystemResources,
            .NOMEM => return error.SystemResources,
            .AGAIN => return error.WouldBlock,
            .IO => return error.InputOutput,
            .ISDIR => return error.IsDir,
            .NOTCONN => |err| return errnoBug(err), // 不是套接字
            .CONNRESET => |err| return errnoBug(err), // 不是套接字
            .INVAL => |err| return errnoBug(err),
            .FAULT => |err| return errnoBug(err),
            .BADF => return error.NotOpenForReading,
            else => |err| return unexpectedErrno(err),
        }
    }
}

fn fileSeekBy(userdata: ?*anyopaque, file: File, offset: i64) File.SeekError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return ev.lseek(file.handle, @bitCast(offset), c.SEEK.CUR);
}

fn fileSeekTo(userdata: ?*anyopaque, file: File, offset: u64) File.SeekError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return ev.lseek(file.handle, offset, c.SEEK.SET);
}

fn lseek(ev: *Evented, fd: c.fd_t, offset: u64, whence: i32) File.SeekError!void {
    _ = ev;
    while (true) switch (c.errno(c.lseek(fd, @bitCast(offset), whence))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err), // 文件描述符在关闭后被使用。
        .INVAL => return error.Unseekable,
        .OVERFLOW => return error.Unseekable,
        .SPIPE => return error.Unseekable,
        .NXIO => return error.Unseekable,
        else => |err| return unexpectedErrno(err),
    };
}

fn fileSync(userdata: ?*anyopaque, file: File) File.SyncError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    while (true) switch (c.errno(c.fsync(file.handle))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ROFS => |err| return errnoBug(err),
        .IO => return error.InputOutput,
        .NOSPC => return error.NoSpaceLeft,
        .DQUOT => return error.DiskQuota,
        else => |err| return unexpectedErrno(err),
    };
}

fn fileIsTty(userdata: ?*anyopaque, file: File) Io.Cancelable!bool {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    while (true) {
        const rc = c.isatty(file.handle);
        switch (c.errno(rc - 1)) {
            .SUCCESS => return true,
            .INTR => {},
            else => return false,
        }
    }
}

fn fileEnableAnsiEscapeCodes(userdata: ?*anyopaque, file: File) File.EnableAnsiEscapeCodesError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    if (!try fileIsTty(ev, file)) return error.NotTerminalDevice;
}

fn fileSetLength(userdata: ?*anyopaque, file: File, length: u64) File.SetLengthError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    const signed_len: i64 = @bitCast(length);
    if (signed_len < 0) return error.FileTooBig; // 避免含义不明确的 EINVAL 错误。

    while (true) switch (c.errno(c.ftruncate(file.handle, signed_len))) {
        .SUCCESS => return,
        .INTR => {},
        .FBIG => return error.FileTooBig,
        .IO => return error.InputOutput,
        .PERM => return error.PermissionDenied,
        .TXTBSY => return error.FileBusy,
        .BADF => |err| return errnoBug(err), // 句柄未以写入方式打开。
        .INVAL => return error.NonResizable, // 例如,/dev/null 会返回此值。
        else => |err| return unexpectedErrno(err),
    };
}

fn fileSetOwner(
    userdata: ?*anyopaque,
    file: File,
    owner: ?File.Uid,
    group: ?File.Gid,
) File.SetOwnerError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    return fchown(file.handle, owner, group);
}

fn fileSetPermissions(
    userdata: ?*anyopaque,
    file: File,
    permissions: File.Permissions,
) File.SetPermissionsError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    return ev.fchmod(file.handle, permissions.toMode());
}

fn fchmod(ev: *Evented, fd: c.fd_t, mode: c.mode_t) File.SetPermissionsError!void {
    _ = ev;
    while (true) switch (c.errno(c.fchmod(fd, mode))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err),
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ACCES => return error.AccessDenied,
        .IO => return error.InputOutput,
        .LOOP => return error.SymLinkLoop,
        .NOENT => return error.FileNotFound,
        .NOMEM => return error.SystemResources,
        .NOTDIR => return error.FileNotFound,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        else => |err| return unexpectedErrno(err),
    };
}

fn fileSetTimestamps(
    userdata: ?*anyopaque,
    file: File,
    options: File.SetTimestampsOptions,
) File.SetTimestampsError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    var times_buffer: [2]c.timespec = undefined;
    const times = if (options.modify_timestamp == .now and options.access_timestamp == .now) null else p: {
        times_buffer = .{
            setTimestampToPosix(options.access_timestamp),
            setTimestampToPosix(options.modify_timestamp),
        };
        break :p &times_buffer;
    };

    while (true) switch (c.errno(c.futimens(file.handle, times))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err), // 始终存在竞态条件
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        else => |err| return unexpectedErrno(err),
    };
}

fn fileLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const operation: i32 = switch (lock) {
        .none => c.LOCK.UN,
        .shared => c.LOCK.SH,
        .exclusive => c.LOCK.EX,
    };
    while (true) switch (c.errno(c.flock(file.handle, operation))) {
        .SUCCESS => return,
        .INTR => {},
        .BADF => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err), // 无效参数
        .NOLCK => return error.SystemResources,
        .AGAIN => |err| return errnoBug(err),
        .OPNOTSUPP => return error.FileLocksUnsupported,
        else => |err| return unexpectedErrno(err),
    };
}

fn fileTryLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!bool {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const operation: i32 = switch (lock) {
        .none => c.LOCK.UN,
        .shared => c.LOCK.SH | c.LOCK.NB,
        .exclusive => c.LOCK.EX | c.LOCK.NB,
    };
    while (true) switch (c.errno(c.flock(file.handle, operation))) {
        .SUCCESS => return true,
        .INTR => {},
        .AGAIN => return false,
        .BADF => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err), // 无效参数
        .NOLCK => return error.SystemResources,
        .OPNOTSUPP => return error.FileLocksUnsupported,
        else => |err| return unexpectedErrno(err),
    };
}

fn fileUnlock(userdata: ?*anyopaque, file: File) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    while (true) switch (c.errno(c.flock(file.handle, c.LOCK.UN))) {
        .SUCCESS => return,
        .INTR => {},
        .AGAIN => return recoverableOsBugDetected(), // 解锁不能阻塞
        .BADF => return recoverableOsBugDetected(), // 文件描述符在关闭后被使用。
        .INVAL => return recoverableOsBugDetected(), // 无效参数
        .NOLCK => return recoverableOsBugDetected(), // 资源释放。
        .OPNOTSUPP => return recoverableOsBugDetected(), // 我们已经获得锁。
        else => return recoverableOsBugDetected(), // 资源释放必须成功。
    };
}

fn fileDowngradeLock(userdata: ?*anyopaque, file: File) File.DowngradeLockError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const operation = c.LOCK.SH | c.LOCK.NB;
    while (true) switch (c.errno(c.flock(file.handle, operation))) {
        .SUCCESS => return,
        .INTR => {},
        .AGAIN => |err| return errnoBug(err), // 文件未以排他模式加锁。
        .BADF => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err), // 无效参数
        .NOLCK => |err| return errnoBug(err), // 已获取锁。
        .OPNOTSUPP => |err| return errnoBug(err), // 已获取锁。
        else => |err| return unexpectedErrno(err),
    };
}

fn fileRealPath(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    var buffer: [c.PATH_MAX]u8 = undefined;
    @memset(&buffer, 0);
    while (true) {
        switch (c.errno(c.fcntl(file.handle, c.F.GETPATH, &buffer))) {
            .SUCCESS => break,
            .INTR => {},
            .ACCES => return error.AccessDenied,
            .BADF => return error.FileNotFound,
            .NOENT => return error.FileNotFound,
            .NOMEM => return error.SystemResources,
            .NOSPC => return error.NameTooLong,
            .RANGE => return error.NameTooLong,
            else => |err| return unexpectedErrno(err),
        }
    }
    const n = std.mem.findScalar(u8, &buffer, 0) orelse buffer.len;
    if (n > out_buffer.len) return error.NameTooLong;
    @memcpy(out_buffer[0..n], buffer[0..n]);
    return n;
}

fn fileHardLink(
    userdata: ?*anyopaque,
    file: File,
    new_dir: Dir,
    new_sub_path: []const u8,
    options: File.HardLinkOptions,
) File.HardLinkError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = file;
    _ = new_dir;
    _ = new_sub_path;
    _ = options;
    return error.OperationUnsupported;
}

fn linkat(
    old_dir: c.fd_t,
    old_path: [*:0]const u8,
    new_dir: c.fd_t,
    new_path: [*:0]const u8,
    flags: u32,
) File.HardLinkError!void {
    while (true) switch (c.errno(c.linkat(old_dir, old_path, new_dir, new_path, flags))) {
        .SUCCESS => return,
        .INTR => {},
        .ACCES => return error.AccessDenied,
        .DQUOT => return error.DiskQuota,
        .EXIST => return error.PathAlreadyExists,
        .IO => return error.HardwareFailure,
        .LOOP => return error.SymLinkLoop,
        .MLINK => return error.LinkQuotaExceeded,
        .NAMETOOLONG => return error.NameTooLong,
        .NOENT => return error.FileNotFound,
        .NOMEM => return error.SystemResources,
        .NOSPC => return error.NoSpaceLeft,
        .NOTDIR => return error.NotDir,
        .PERM => return error.PermissionDenied,
        .ROFS => return error.ReadOnlyFileSystem,
        .XDEV => return error.CrossDevice,
        .ILSEQ => return error.BadPathName,
        .FAULT => |err| return errnoBug(err),
        .INVAL => |err| return errnoBug(err),
        else => |err| return unexpectedErrno(err),
    };
}

fn fileMemoryMapCreate(
    userdata: ?*anyopaque,
    file: File,
    options: File.MemoryMap.CreateOptions,
) File.MemoryMap.CreateError!File.MemoryMap {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    const prot: c.PROT = .{
        .READ = options.protection.read,
        .WRITE = options.protection.write,
        .EXEC = options.protection.execute,
    };
    const flags: c.MAP = .{
        .TYPE = .SHARED,
    };

    const page_align = std.heap.page_size_min;

    const contents = while (true) {
        const casted_offset = std.math.cast(i64, options.offset) orelse return error.Unseekable;
        const rc = c.mmap(null, options.len, prot, flags, file.handle, casted_offset);
        const err: c.E = if (rc != c.MAP_FAILED) .SUCCESS else @fromBackingInt(@intCast(c._errno().*));
        switch (err) {
            .SUCCESS => break @as([*]align(page_align) u8, @ptrCast(@alignCast(rc)))[0..options.len],
            .INTR => {},
            .ACCES => return error.AccessDenied,
            .AGAIN => return error.LockedMemoryLimitExceeded,
            .MFILE => return error.ProcessFdQuotaExceeded,
            .NFILE => return error.SystemFdQuotaExceeded,
            .NOMEM => return error.OutOfMemory,
            .PERM => return error.PermissionDenied,
            .OVERFLOW => return error.Unseekable,
            .BADF => return errnoBug(err), // 始终存在竞态条件。
            .INVAL => return errnoBug(err), // mmap() 的参数无效
            else => return unexpectedErrno(err),
        }
    };
    return .{
        .file = file,
        .offset = options.offset,
        .memory = contents,
        .section = {},
    };
}

fn fileMemoryMapDestroy(userdata: ?*anyopaque, mm: *File.MemoryMap) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const memory = mm.memory;
    if (memory.len == 0) return;
    switch (c.errno(c.munmap(memory.ptr, memory.len))) {
        .SUCCESS => {},
        else => |err| if (builtin.mode == .debug)
            std.log.err("failed to unmap {d} bytes at {*}: {t}", .{ memory.len, memory.ptr, err }),
    }
    mm.* = undefined;
}

fn fileMemoryMapSetLength(
    userdata: ?*anyopaque,
    mm: *File.MemoryMap,
    new_len: usize,
) File.MemoryMap.SetLengthError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;

    const page_size = std.heap.pageSize();
    const alignment: Alignment = .fromByteUnits(page_size);
    const old_memory = mm.memory;

    if (alignment.forward(new_len) == alignment.forward(old_memory.len)) {
        mm.memory.len = new_len;
        return;
    }
    return error.OperationUnsupported;
}

fn fileMemoryMapRead(userdata: ?*anyopaque, mm: *File.MemoryMap) File.ReadPositionalError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = mm;
}

fn fileMemoryMapWrite(userdata: ?*anyopaque, mm: *File.MemoryMap) File.WritePositionalError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = mm;
}

fn processExecutableOpen(
    userdata: ?*anyopaque,
    flags: Dir.OpenFileOptions,
) process.OpenExecutableError!File {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    // _NSGetExecutablePath() 返回的路径可能是指向
    // 可执行文件的符号链接。此处会打开它,因此没有影响。
    var symlink_path_buf: [c.PATH_MAX + 1]u8 = undefined;
    var n: u32 = symlink_path_buf.len;
    const rc = c._NSGetExecutablePath(&symlink_path_buf, &n);
    if (rc != 0) return error.NameTooLong;
    const symlink_path = std.mem.sliceTo(&symlink_path_buf, 0);
    return dirOpenFile(ev, .cwd(), symlink_path, flags);
}

fn processExecutablePath(userdata: ?*anyopaque, out_buffer: []u8) process.ExecutablePathError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    // _NSGetExecutablePath() 返回的路径可能是指向可执行文件的符号链接。
    //
    var symlink_path_buf: [c.PATH_MAX + 1]u8 = undefined;
    var n: u32 = symlink_path_buf.len;
    const rc = c._NSGetExecutablePath(&symlink_path_buf, &n);
    if (rc != 0) return error.NameTooLong;
    const symlink_path = std.mem.sliceTo(&symlink_path_buf, 0);
    assert(Dir.path.isAbsolute(symlink_path));
    return dirRealPathFile(ev, .cwd(), symlink_path, out_buffer) catch |err| switch (err) {
        error.NetworkNotFound => unreachable, // 仅限 Windows
        error.FileBusy => unreachable, // 仅限 Windows
        else => |e| return e,
    };
}

fn lockStderr(userdata: ?*anyopaque, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    try ev.stderr_mutex.lock(ev);
    errdefer ev.stderr_mutex.unlock();
    return ev.initLockedStderr(terminal_mode);
}

fn tryLockStderr(
    userdata: ?*anyopaque,
    terminal_mode: ?Io.Terminal.Mode,
) Io.Cancelable!?Io.LockedStderr {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    if (!ev.stderr_mutex.tryLock()) return null;
    errdefer ev.stderr_mutex.unlock();
    return try ev.initLockedStderr(terminal_mode);
}

fn initLockedStderr(ev: *Evented, terminal_mode: ?Io.Terminal.Mode) Io.Cancelable!Io.LockedStderr {
    ev.init_stderr_writer.once(ev, &initStderrWriter);
    return .{
        .file_writer = &ev.stderr_writer,
        .terminal_mode = terminal_mode orelse ev.stderr_mode,
    };
}

fn initStderrWriter(context: ?*anyopaque) callconv(.c) void {
    const ev: *Evented = @ptrCast(@alignCast(context));
    const cancel_protection = swapCancelProtection(ev, .blocked);
    defer assert(swapCancelProtection(ev, cancel_protection) == .blocked);
    ev.scan_environ.once(ev, &scanEnviron);
    const NO_COLOR = ev.environ.exist.NO_COLOR;
    const CLICOLOR_FORCE = ev.environ.exist.CLICOLOR_FORCE;
    ev.stderr_mode = Io.Terminal.Mode.detect(
        ev.io(),
        ev.stderr_writer.file,
        NO_COLOR,
        CLICOLOR_FORCE,
    ) catch |err| switch (err) {
        error.Canceled => unreachable, // 已阻塞
    };
}

fn unlockStderr(userdata: ?*anyopaque) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    if (ev.stderr_writer.err == null) ev.stderr_writer.interface.flush() catch {};
    if (ev.stderr_writer.err) |err| {
        switch (err) {
            error.Canceled => Thread.current().currentFiber().cancel_protection.recancel(),
            else => {},
        }
        ev.stderr_writer.err = null;
    }
    ev.stderr_writer.interface.end = 0;
    ev.stderr_writer.interface.buffer.len = 0;
    ev.stderr_mutex.unlock();
}

fn processCurrentPath(userdata: ?*anyopaque, buffer: []u8) process.CurrentPathError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const err: c.E = if (c.getcwd(buffer.ptr, buffer.len)) |_| .SUCCESS else @fromBackingInt(@intCast(c._errno().*));
    switch (err) {
        .SUCCESS => return std.mem.findScalar(u8, buffer, 0).?,
        .NOENT => return error.CurrentDirUnlinked,
        .RANGE => return error.NameTooLong,
        .FAULT => |e| return errnoBug(e),
        .INVAL => |e| return errnoBug(e),
        else => return unexpectedErrno(err),
    }
}

fn processSetCurrentDir(userdata: ?*anyopaque, dir: Dir) process.SetCurrentDirError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    if (dir.handle == c.AT.FDCWD) return;
    while (true) switch (c.errno(c.fchdir(dir.handle))) {
        .SUCCESS => return,
        .INTR => {},
        .ACCES => return error.AccessDenied,
        .NOTDIR => return error.NotDir,
        .IO => return error.FileSystem,
        .BADF => |err| return errnoBug(err),
        else => |err| return unexpectedErrno(err),
    };
}

fn processSetCurrentPath(userdata: ?*anyopaque, dir_path: []const u8) process.SetCurrentPathError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    var path_buffer: [c.PATH_MAX]u8 = undefined;
    const dir_path_posix = try pathToPosix(dir_path, &path_buffer);
    while (true) switch (c.errno(c.chdir(dir_path_posix))) {
        .SUCCESS => return,
        .INTR => {},
        .ACCES => return error.AccessDenied,
        .IO => return error.FileSystem,
        .LOOP => return error.SymLinkLoop,
        .NAMETOOLONG => return error.NameTooLong,
        .NOENT => return error.FileNotFound,
        .NOMEM => return error.SystemResources,
        .NOTDIR => return error.NotDir,
        .ILSEQ => return error.BadPathName,
        .FAULT => |err| return errnoBug(err),
        else => |err| return unexpectedErrno(err),
    };
}

fn processReplace(userdata: ?*anyopaque, options: process.ReplaceOptions) process.ReplaceError {
    const ev: *Evented = @ptrCast(@alignCast(userdata));

    if (!process.can_replace) return error.OperationUnsupported;

    ev.scan_environ.once(ev, &scanEnviron); // 用于 PATH
    const PATH = ev.environ.string.PATH orelse default_PATH;

    var arena_allocator = std.heap.ArenaAllocator.init(ev.allocator());
    defer arena_allocator.deinit();
    const arena = arena_allocator.allocator();

    const argv_buf = try arena.allocSentinel(?[*:0]const u8, options.argv.len, null);
    for (options.argv, 0..) |arg, i| argv_buf[i] = (try arena.dupeSentinel(u8, arg, 0)).ptr;

    const env_block = env_block: {
        const prog_fd: i32 = -1;
        if (options.environ_map) |environ_map| break :env_block try environ_map.createPosixBlock(arena, .{
            .zig_progress_fd = prog_fd,
        });
        break :env_block try ev.environ.process_environ.createPosixBlock(arena, .{
            .zig_progress_fd = prog_fd,
        });
    };

    return ev.execv(options.expand_arg0, argv_buf.ptr[0].?, argv_buf.ptr, env_block, PATH);
}

fn processReplacePath(
    userdata: ?*anyopaque,
    dir: Dir,
    options: process.ReplaceOptions,
) process.ReplaceError {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = dir;
    _ = options;
    @panic("TODO processReplacePath");
}

fn processSpawn(userdata: ?*anyopaque, options: process.SpawnOptions) process.SpawnError!process.Child {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const spawned = try ev.spawn(options);
    defer fileClose(ev, &.{spawned.err_pipe});

    // 等待子进程报告 `execvpe` 内部或之前发生的任何错误。
    var child_err: ForkBailError = undefined;
    ev.readAll(spawned.err_pipe, @ptrCast(&child_err)) catch |read_err| {
        switch (read_err) {
            error.Canceled => unreachable, // 已阻塞
            error.EndOfStream => {
                // 调用 `execvpe` 时,写入端由 CLOEXEC 关闭,
                // 表示成功。
            },
            else => {
                // 从错误报告管道读取错误时出现问题。
                // 无法确定子进程仍存活还是已退出。最好假定它仍
                // 存活,以免资源泄漏。
            },
        }
        return .{
            .id = spawned.pid,
            .thread_handle = {},
            .stdin = spawned.stdin,
            .stdout = spawned.stdout,
            .stderr = spawned.stderr,
            .request_resource_usage_statistics = options.request_resource_usage_statistics,
        };
    };
    return child_err;
}

fn processSpawnPath(
    userdata: ?*anyopaque,
    dir: Dir,
    options: process.SpawnOptions,
) process.SpawnError!process.Child {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = dir;
    _ = options;
    @panic("TODO processSpawnPath");
}

const prog_fileno = @max(c.STDIN_FILENO, c.STDOUT_FILENO, c.STDERR_FILENO) + 1;

const Spawned = struct {
    pid: c.pid_t,
    err_pipe: File,
    stdin: ?File,
    stdout: ?File,
    stderr: ?File,
};
fn spawn(ev: *Evented, options: process.SpawnOptions) process.SpawnError!Spawned {
    // 子进程确实需要访问这些管道的一端,但最初必须设置 CLOEXEC,以避免竞态条件。若另一个线程正在并发创建其他子进程,绝不能让后者继承这些文件描述符。例如,其他子进程可能保留管道写端引用,导致父进程调用 `poll` 时,无法在预期时机检测到目标子进程的标准输出关闭。
    // 因此,创建管道时先设置 CLOEXEC。fork 后,必须在新子进程中确保保留所需引用。可以使用 `fcntl` 移除描述符上的 CLOEXEC,但实际上所有描述符都会经过 `dup2`,因此无需额外操作。
    //
    //
    //
    //
    //
    //
    //
    //
    const pipe_flags: c.O = .{ .CLOEXEC = true };

    const stdin_pipe = if (options.stdin == .pipe) try pipe2(pipe_flags) else undefined;
    errdefer if (options.stdin == .pipe) {
        destroyPipe(stdin_pipe);
    };

    const stdout_pipe = if (options.stdout == .pipe) try pipe2(pipe_flags) else undefined;
    errdefer if (options.stdout == .pipe) {
        destroyPipe(stdout_pipe);
    };

    const stderr_pipe = if (options.stderr == .pipe) try pipe2(pipe_flags) else undefined;
    errdefer if (options.stderr == .pipe) {
        destroyPipe(stderr_pipe);
    };

    const any_ignore =
        options.stdin == .ignore or options.stdout == .ignore or options.stderr == .ignore;
    const dev_null_file = if (any_ignore) dev_null_file: {
        ev.open_dev_null.once(ev, &openDevNullFile);
        break :dev_null_file try ev.dev_null_file;
    } else undefined;

    const prog_pipe: [2]c.fd_t = if (options.progress_node.index != .none)
        // 与 `pipe_flags` 中相同的原因,使用 CLOEXEC。
        try pipe2(.{ .NONBLOCK = true, .CLOEXEC = true })
    else
        .{ -1, -1 };
    errdefer destroyPipe(prog_pipe);

    var arena_allocator = std.heap.ArenaAllocator.init(ev.allocator());
    defer arena_allocator.deinit();
    const arena = arena_allocator.allocator();

    // POSIX 标准不允许在 fork() 与 execve() 之间调用 malloc(),
    // 而此分配器可能是 libc 分配器。
    // 我曾在 musl v1.1.24 中亲眼观察到:
    // 由于 fork() 与 execve() 之间发生堆分配,
    // 子进程尝试调用 malloc() 时发生死锁。
    // 此外,我们希望减少 fork() 与 execve() 之间
    // 可能发生失败的方式。
    // 因此,execve() 所需的所有分配都在 fork() 之前完成。
    // 这意味着必须在此处为 argv 和环境变量添加空字符终止符。
    const argv_buf = try arena.allocSentinel(?[*:0]const u8, options.argv.len, null);
    for (options.argv, 0..) |arg, i| argv_buf[i] = (try arena.dupeSentinel(u8, arg, 0)).ptr;

    const env_block = env_block: {
        const prog_fd: i32 = if (prog_pipe[1] == -1) -1 else prog_fileno;
        if (options.environ_map) |environ_map| break :env_block try environ_map.createPosixBlock(arena, .{
            .zig_progress_fd = prog_fd,
        });
        break :env_block try ev.environ.process_environ.createPosixBlock(arena, .{
            .zig_progress_fd = prog_fd,
        });
    };

    // 此管道在 `fork` 与 `execvpe` 之间向父进程传递子进程错误。
    // 若 `execvpe` 成功,子进程会通过 CLOEXEC 关闭管道而不写入。
    const err_pipe: [2]File = err_pipe: {
        const err_pipe = try pipe2(.{ .CLOEXEC = true });
        break :err_pipe .{
            .{ .handle = err_pipe[0], .flags = .{ .nonblocking = false } },
            .{ .handle = err_pipe[1], .flags = .{ .nonblocking = false } },
        };
    };
    errdefer fileClose(ev, &err_pipe);

    ev.scan_environ.once(ev, &scanEnviron); // 用于 PATH
    const PATH = ev.environ.string.PATH orelse default_PATH;

    const pid_result: c.pid_t = fork: {
        const rc = c.fork();
        switch (c.errno(rc)) {
            .SUCCESS => break :fork @intCast(rc),
            .AGAIN => return error.SystemResources,
            .NOMEM => return error.SystemResources,
            .NOSYS => return error.OperationUnsupported,
            else => |err| return unexpectedErrno(err),
        }
    };

    if (pid_result == 0) {
        defer comptime unreachable; // 当前为子进程。
        const err = ev.setUpChild(.{
            .stdin_pipe = stdin_pipe[0],
            .stdout_pipe = stdout_pipe[1],
            .stderr_pipe = stderr_pipe[1],
            .dev_null_fd = dev_null_file.handle,
            .prog_pipe = prog_pipe[1],
            .argv_buf = argv_buf,
            .env_block = env_block,
            .PATH = PATH,
            .spawn = options,
        });
        ev.writeAll(err_pipe[1], @ptrCast(&err)) catch {};
        c.exit(1);
    }

    const pid: c.pid_t = @intCast(pid_result); // 当前为父进程。
    errdefer comptime unreachable; // 子进程已 fork;此后绝不能返回错误

    fileClose(ev, err_pipe[1..2]); // 确保只有子进程保持写入端打开

    if (options.stdin == .pipe) closeFd(stdin_pipe[0]);
    if (options.stdout == .pipe) closeFd(stdout_pipe[1]);
    if (options.stderr == .pipe) closeFd(stderr_pipe[1]);

    if (prog_pipe[1] != -1) closeFd(prog_pipe[1]);

    options.progress_node.setIpcFile(ev, .{ .handle = prog_pipe[0], .flags = .{ .nonblocking = true } });

    return .{
        .pid = pid,
        .err_pipe = err_pipe[0],
        .stdin = switch (options.stdin) {
            .pipe => .{ .handle = stdin_pipe[1], .flags = .{ .nonblocking = false } },
            else => null,
        },
        .stdout = switch (options.stdout) {
            .pipe => .{ .handle = stdout_pipe[0], .flags = .{ .nonblocking = false } },
            else => null,
        },
        .stderr = switch (options.stderr) {
            .pipe => .{ .handle = stderr_pipe[0], .flags = .{ .nonblocking = false } },
            else => null,
        },
    };
}

fn openDevNullFile(context: ?*anyopaque) callconv(.c) void {
    const ev: *Evented = @ptrCast(@alignCast(context));
    ev.dev_null_file = dirOpenFile(ev, .cwd(), "/dev/null", .{ .mode = .read_write });
}

/// fork() 与 execv() 之间可能发生的错误。
const ForkBailError = process.SetCurrentDirError || ChdirError ||
    process.SpawnError || process.ReplaceError;
fn setUpChild(ev: *Evented, options: struct {
    stdin_pipe: c.fd_t,
    stdout_pipe: c.fd_t,
    stderr_pipe: c.fd_t,
    dev_null_fd: c.fd_t,
    prog_pipe: c.fd_t,
    argv_buf: [:null]?[*:0]const u8,
    env_block: process.Environ.Block,
    PATH: []const u8,
    spawn: process.SpawnOptions,
}) ForkBailError {
    try ev.setUpChildIo(
        options.spawn.stdin,
        options.stdin_pipe,
        c.STDIN_FILENO,
        options.dev_null_fd,
    );
    try ev.setUpChildIo(
        options.spawn.stdout,
        options.stdout_pipe,
        c.STDOUT_FILENO,
        options.dev_null_fd,
    );
    try ev.setUpChildIo(
        options.spawn.stderr,
        options.stderr_pipe,
        c.STDERR_FILENO,
        options.dev_null_fd,
    );

    switch (options.spawn.cwd) {
        .inherit => {},
        .dir => |cwd_dir| try processSetCurrentDir(ev, cwd_dir),
        .path => |cwd_path| try processSetCurrentPath(ev, cwd_path),
    }

    // 必须在上方 fchdir 之后执行,因为 cwd 文件描述符
    // 可能等于 prog_fileno,并被此 dup2 调用覆盖。
    if (options.prog_pipe != -1) try ev.dup2(options.prog_pipe, prog_fileno);

    if (options.spawn.gid) |gid| while (true) switch (c.errno(c.setregid(gid, gid))) {
        .SUCCESS => break,
        .INTR => {},
        .AGAIN => return error.ResourceLimitReached,
        .INVAL => return error.InvalidUserId,
        .PERM => return error.PermissionDenied,
        else => return error.Unexpected,
    };

    if (options.spawn.uid) |uid| while (true) switch (c.errno(c.setreuid(uid, uid))) {
        .SUCCESS => break,
        .INTR => {},
        .AGAIN => return error.ResourceLimitReached,
        .INVAL => return error.InvalidUserId,
        .PERM => return error.PermissionDenied,
        else => return error.Unexpected,
    };

    if (options.spawn.pgid) |pid| while (true) switch (c.errno(c.setpgid(0, pid))) {
        .SUCCESS => break,
        .INTR => {},
        .ACCES => return error.ProcessAlreadyExec,
        .INVAL => return error.InvalidProcessGroupId,
        .PERM => return error.PermissionDenied,
        else => return error.Unexpected,
    };

    if (options.spawn.start_suspended) while (true) switch (c.errno(c.kill(0, .STOP))) {
        .SUCCESS => break,
        .INTR => {},
        .PERM => return error.PermissionDenied,
        else => return error.Unexpected,
    };

    return ev.execv(
        options.spawn.expand_arg0,
        options.argv_buf.ptr[0].?,
        options.argv_buf.ptr,
        options.env_block,
        options.PATH,
    );
}

fn setUpChildIo(
    ev: *Evented,
    stdio: process.SpawnOptions.StdIo,
    pipe_fd: c.fd_t,
    std_fileno: i32,
    dev_null_fd: c.fd_t,
) !void {
    switch (stdio) {
        .pipe => try ev.dup2(pipe_fd, std_fileno),
        .close => closeFd(std_fileno),
        .inherit => {},
        .ignore => try ev.dup2(dev_null_fd, std_fileno),
        .file => |file| try ev.dup2(file.handle, std_fileno),
    }
}

const PipeError = error{
    SystemFdQuotaExceeded,
    ProcessFdQuotaExceeded,
} || Io.UnexpectedError;

fn pipe2(flags: c.O) PipeError![2]c.fd_t {
    var fds: [2]c.fd_t = undefined;

    while (true) switch (c.errno(c.pipe(&fds))) {
        .SUCCESS => break,
        .INTR => {},
        .NFILE => return error.SystemFdQuotaExceeded,
        .MFILE => return error.ProcessFdQuotaExceeded,
        else => |err| return unexpectedErrno(err),
    };
    errdefer {
        closeFd(fds[0]);
        closeFd(fds[1]);
    }

    // https://github.com/ziglang/zig/issues/18882
    if (@as(u32, @bitCast(flags)) == 0) return fds;

    // CLOEXEC 特殊:它是文件描述符标志,必须使用 F.SETFD 设置。
    //
    if (flags.CLOEXEC) for (fds) |fd| while (true) switch (c.errno(c.fcntl(fd, c.F.SETFD, @as(u32, c.FD_CLOEXEC)))) {
        .SUCCESS => break,
        .INTR => {},
        else => |err| return unexpectedErrno(err),
    };

    const new_flags: u32 = f: {
        var new_flags = flags;
        new_flags.CLOEXEC = false;
        break :f @bitCast(new_flags);
    };

    // 使用 F.SETFL 设置其他影响文件状态的所有标志。
    if (new_flags != 0) for (fds) |fd| while (true) switch (c.errno(c.fcntl(fd, c.F.SETFL, new_flags))) {
        .SUCCESS => break,
        .INTR => {},
        .INVAL => |err| return errnoBug(err),
        else => |err| return unexpectedErrno(err),
    };

    return fds;
}

fn destroyPipe(pipe: [2]c.fd_t) void {
    if (pipe[0] != -1) closeFd(pipe[0]);
    if (pipe[0] != pipe[1]) closeFd(pipe[1]);
}

const DupError = error{
    ProcessFdQuotaExceeded,
    SystemResources,
} || Io.UnexpectedError || Io.Cancelable;
fn dup2(ev: *Evented, old_fd: c.fd_t, new_fd: c.fd_t) DupError!void {
    _ = ev;
    while (true) switch (c.errno(c.dup2(old_fd, new_fd))) {
        .SUCCESS => return,
        .BUSY, .INTR => {},
        .INVAL => |err| return errnoBug(err), // 无效参数
        .BADF => |err| return errnoBug(err), // 释放后使用
        .MFILE => return error.ProcessFdQuotaExceeded,
        .NOMEM => return error.SystemResources,
        else => |err| return unexpectedErrno(err),
    };
}

fn execv(
    ev: *Evented,
    arg0_expand: process.ArgExpansion,
    file: [*:0]const u8,
    child_argv: [*:null]?[*:0]const u8,
    env_block: process.Environ.PosixBlock,
    PATH: []const u8,
) process.ReplaceError {
    const file_slice = std.mem.sliceTo(file, 0);
    if (std.mem.findScalar(u8, file_slice, '/') != null) return ev.execvPath(file, child_argv, env_block);

    // 此处使用 PATH_MAX 合理,因为 path_buf 会在
    // posixExecvPath 中直接传给操作系统。
    var path_buf: [c.PATH_MAX]u8 = undefined;
    var it = std.mem.tokenizeScalar(u8, PATH, ':');
    var seen_eacces = false;
    var err: process.ReplaceError = error.FileNotFound;

    // 若扩展了 arg0,则因错误返回时必须将其恢复。
    const prev_arg0 = child_argv[0];
    defer switch (arg0_expand) {
        .expand => child_argv[0] = prev_arg0,
        .no_expand => {},
    };

    while (it.next()) |search_path| {
        const path_len = search_path.len + file_slice.len + 1;
        if (path_buf.len < path_len + 1) return error.NameTooLong;
        @memcpy(path_buf[0..search_path.len], search_path);
        path_buf[search_path.len] = '/';
        @memcpy(path_buf[search_path.len + 1 ..][0..file_slice.len], file_slice);
        path_buf[path_len] = 0;
        const full_path = path_buf[0..path_len :0].ptr;
        switch (arg0_expand) {
            .expand => child_argv[0] = full_path,
            .no_expand => {},
        }
        err = ev.execvPath(full_path, child_argv, env_block);
        switch (err) {
            error.AccessDenied => seen_eacces = true,
            error.FileNotFound, error.NotDir => {},
            else => |e| return e,
        }
    }
    if (seen_eacces) return error.AccessDenied;
    return err;
}
/// 此函数忽略 PATH 环境变量。
fn execvPath(
    ev: *Evented,
    path: [*:0]const u8,
    child_argv: [*:null]const ?[*:0]const u8,
    env_block: process.Environ.PosixBlock,
) process.ReplaceError {
    _ = ev;
    switch (c.errno(c.execve(path, child_argv, env_block.slice.ptr))) {
        .FAULT => |err| return errnoBug(err), // 错误的指针参数。
        .@"2BIG" => return error.SystemResources,
        .MFILE => return error.ProcessFdQuotaExceeded,
        .NAMETOOLONG => return error.NameTooLong,
        .NFILE => return error.SystemFdQuotaExceeded,
        .NOMEM => return error.SystemResources,
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .INVAL => return error.InvalidExe,
        .NOEXEC => return error.InvalidExe,
        .IO => return error.FileSystem,
        .LOOP => return error.FileSystem,
        .ISDIR => return error.IsDir,
        .NOENT => return error.FileNotFound,
        .NOTDIR => return error.NotDir,
        .TXTBSY => return error.FileBusy,
        .BADEXEC => return error.InvalidExe,
        .BADARCH => return error.InvalidExe,
        else => |err| return unexpectedErrno(err),
    }
}

fn childWait(userdata: ?*anyopaque, child: *process.Child) process.Child.WaitError!process.Child.Term {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    defer ev.childCleanup(child);
    const pid = child.id.?;
    const source = c.dispatch.source_create(
        .PROC,
        @bitCast(@as(isize, pid)),
        .{ .PROC = .{ .EXIT = true } },
        ev.queue,
    ) orelse return error.Unexpected;
    source.as_object().set_context(Thread.current().currentFiber());
    source.set_event_handler(&Fiber.@"resume");
    ev.yield(.{ .activate = source.as_object() });
    source.as_object().release();
    var status: c_int = undefined;
    var ru: c.rusage = undefined;
    const ru_ptr = if (child.request_resource_usage_statistics) &ru else null;
    while (true) switch (c.errno(c.wait4(pid, &status, 0, ru_ptr))) {
        .SUCCESS => {
            if (ru_ptr) |p| child.resource_usage_statistics.rusage = p.*;
            return statusToTerm(@bitCast(status));
        },
        .INTR => {},
        .CHILD => |err| return errnoBug(err), // 重复释放。
        else => |err| return unexpectedErrno(err),
    };
}

fn childKill(userdata: ?*anyopaque, child: *process.Child) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    defer ev.childCleanup(child);
    const pid = child.id.?;
    while (true) switch (c.errno(c.kill(pid, .TERM))) {
        .SUCCESS => break,
        .INTR => {},
        .PERM => return,
        .INVAL => |err| errnoBug(err) catch return,
        .SRCH => |err| errnoBug(err) catch return,
        else => |err| unexpectedErrno(err) catch return,
    };
    var status: c_int = undefined;
    while (true) switch (c.errno(c.wait4(pid, &status, 0, null))) {
        .SUCCESS => return,
        .INTR => {},
        .CHILD => |err| errnoBug(err) catch return, // 重复释放。
        else => |err| unexpectedErrno(err) catch return,
    };
}

fn childCleanup(ev: *Evented, child: *process.Child) void {
    if (child.stdin) |stdin| {
        fileClose(ev, &.{stdin});
        child.stdin = null;
    }
    if (child.stdout) |stdout| {
        fileClose(ev, &.{stdout});
        child.stdout = null;
    }
    if (child.stderr) |stderr| {
        fileClose(ev, &.{stderr});
        child.stderr = null;
    }
    child.id = null;
}

fn progressParentFile(userdata: ?*anyopaque) std.Progress.ParentFileError!File {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    ev.scan_environ.once(ev, &scanEnviron);
    return ev.environ.zig_progress_file;
}

fn scanEnviron(context: ?*anyopaque) callconv(.c) void {
    const ev: *Evented = @ptrCast(@alignCast(context));
    ev.environ.scan(ev.allocator());
}

fn now(userdata: ?*anyopaque, clock: Io.Clock) Io.Timestamp {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const clock_id: c.clockid_t = clockToPosix(clock);
    var timespec: c.timespec = undefined;
    switch (c.errno(c.clock_gettime(clock_id, &timespec))) {
        .SUCCESS => return timestampFromPosix(&timespec),
        else => return .zero,
    }
}

fn clockResolution(userdata: ?*anyopaque, clock: Io.Clock) Io.Clock.ResolutionError!Io.Duration {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    const clock_id: c.clockid_t = clockToPosix(clock);
    var timespec: c.timespec = undefined;
    return switch (c.errno(c.clock_getres(clock_id, &timespec))) {
        .SUCCESS => .fromNanoseconds(nanosecondsFromPosix(&timespec)),
        .INVAL => return error.ClockUnavailable,
        else => |err| return unexpectedErrno(err),
    };
}

const SleepWaiter = struct {
    sleeper: Sleeper = undefined,
    cancelable: Cancelable,
    timer: c.dispatch.source_t,
    started: bool = false,

    fn start(context: ?*anyopaque) callconv(.c) void {
        const waiter: *SleepWaiter = @ptrCast(@alignCast(context));
        waiter.cancelable.enter(waiter.sleeper.fiber) catch |err| switch (err) {
            error.CancelRequested => waiter.timer.cancel(),
        };
        waiter.timer.as_object().activate();
    }

    fn timedOut(context: ?*anyopaque) callconv(.c) void {
        const waiter: *SleepWaiter = @ptrCast(@alignCast(context));
        waiter.cancelable.leave(waiter.sleeper.fiber) catch |err| switch (err) {
            error.CancelRequested => return,
        };
        waiter.timer.cancel();
    }

    fn canceled(context: ?*anyopaque) callconv(.c) void {
        const cancelable: *Cancelable = @ptrCast(@alignCast(context));
        const waiter: *SleepWaiter = @fieldParentPtr("cancelable", cancelable);
        cancelable.requested(waiter.sleeper.fiber);
        waiter.timer.cancel();
    }

    fn wake(context: ?*anyopaque) callconv(.c) void {
        const waiter: *SleepWaiter = @ptrCast(@alignCast(context));
        var sleeper = waiter.sleeper;
        waiter.* = undefined;
        Sleeper.wake(&sleeper);
    }
};

fn sleep(userdata: ?*anyopaque, timeout: Io.Timeout) Io.Cancelable!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    const queue = c.dispatch.queue_create_with_target(
        "org.ziglang.std.Io.Dispatch.sleep",
        .SERIAL(),
        ev.queue,
    ) orelse {
        log.warn("failed to create serial queue for sleep", .{});
        return ev.yield(.{ .after = ev.timeFromTimeout(timeout) });
    };
    defer queue.as_object().release();
    const timer = c.dispatch.source_create(.TIMER, 0, .none, queue) orelse {
        log.warn("failed to create timer for sleep", .{});
        return ev.yield(.{ .after = ev.timeFromTimeout(timeout) });
    };
    var waiter: SleepWaiter = .{
        .cancelable = .{ .queue = queue, .cancel = &SleepWaiter.canceled },
        .timer = timer,
    };
    timer.as_object().set_context(&waiter);
    timer.set_event_handler(&SleepWaiter.timedOut);
    timer.set_cancel_handler(&SleepWaiter.wake);
    timer.set_timer(ev.timeFromTimeout(timeout), c.dispatch.TIME_FOREVER, ev.leeway);
    ev.yield(.{ .sleep_wait = &waiter });
    timer.as_object().release();
    try waiter.cancelable.acknowledge(waiter.sleeper.fiber);
}

fn timeFromTimeout(ev: *Evented, timeout: Io.Timeout) c.dispatch.time_t {
    return timeout: switch (timeout) {
        .none => .FOREVER,
        .duration => |duration| .time(switch (duration.clock) {
            .real => .WALL_NOW,
            else => .NOW,
        }, std.math.lossyCast(i64, duration.raw.toNanoseconds())),
        .deadline => |deadline| switch (deadline.clock) {
            .real => .walltime(&.{
                .sec = @intCast(@divFloor(deadline.raw.toNanoseconds(), std.time.ns_per_s)),
                .nsec = @intCast(@mod(deadline.raw.toNanoseconds(), std.time.ns_per_s)),
            }, 0),
            else => continue :timeout .{ .duration = deadline.durationFromNow(ev.io()) },
        },
    };
}

const Random = struct {
    evented: *Evented,
    thread: *Thread,
    buffer: []u8,

    fn seed(context: ?*anyopaque) callconv(.c) void {
        const rand: *Random = @ptrCast(@alignCast(context));
        const ev = rand.evented;
        ev.csprng_mutex.lockUncancelable(ev);
        defer ev.csprng_mutex.unlock();
        var buffer: [Csprng.seed_len]u8 = undefined;
        if (!ev.csprng.isInitialized()) {
            @branchHint(.unlikely);
            const cancel_protection = swapCancelProtection(ev, .blocked);
            defer assert(swapCancelProtection(ev, cancel_protection) == .blocked);
            randomSecure(ev, &buffer) catch |err| switch (err) {
                error.Canceled => unreachable, // 已阻塞
                error.EntropyUnavailable => fallbackSeed(ev, &buffer),
            };
            ev.csprng.rng = .init(buffer);
        }
        ev.csprng.rng.fill(&buffer);
        rand.thread.csprng.rng = .init(buffer);
        rand.thread.csprng.rng.fill(rand.buffer);
        rand.buffer.len = 0;
    }
};

fn random(userdata: ?*anyopaque, buffer: []u8) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    if (buffer.len == 0) return;
    const thread: *Thread = .current();
    var rand: Random = .{ .evented = ev, .thread = thread, .buffer = buffer };
    thread.seed_csprng.once(&rand, &Random.seed);
    if (rand.buffer.len > 0) thread.csprng.rng.fill(buffer);
}

fn randomSecure(userdata: ?*anyopaque, buffer: []u8) Io.RandomSecureError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    if (buffer.len > 0) c.arc4random_buf(buffer.ptr, buffer.len);
}

fn netListenIpUnavailable(
    userdata: ?*anyopaque,
    address: *const net.IpAddress,
    options: net.IpAddress.ListenOptions,
) net.IpAddress.ListenError!net.Socket {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = address;
    _ = options;
    return error.NetworkDown;
}

fn netAcceptUnavailable(
    userdata: ?*anyopaque,
    listen_handle: net.Socket.Handle,
    options: net.Server.AcceptOptions,
) net.Server.AcceptError!net.Socket {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = listen_handle;
    _ = options;
    return error.NetworkDown;
}

fn netBindIpUnavailable(
    userdata: ?*anyopaque,
    address: *const net.IpAddress,
    options: net.IpAddress.BindOptions,
) net.IpAddress.BindError!net.Socket {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = address;
    _ = options;
    return error.NetworkDown;
}

fn netConnectIpUnavailable(
    userdata: ?*anyopaque,
    address: *const net.IpAddress,
    options: net.IpAddress.ConnectOptions,
) net.IpAddress.ConnectError!net.Socket {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = address;
    _ = options;
    return error.NetworkDown;
}

fn netListenUnixUnavailable(
    userdata: ?*anyopaque,
    address: *const net.UnixAddress,
    options: net.UnixAddress.ListenOptions,
) net.UnixAddress.ListenError!net.Socket.Handle {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = address;
    _ = options;
    return error.AddressFamilyUnsupported;
}

fn netConnectUnixUnavailable(
    userdata: ?*anyopaque,
    address: *const net.UnixAddress,
) net.UnixAddress.ConnectError!net.Socket.Handle {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = address;
    return error.AddressFamilyUnsupported;
}

fn netSocketCreatePairUnavailable(
    userdata: ?*anyopaque,
    options: net.Socket.CreatePairOptions,
) net.Socket.CreatePairError![2]net.Socket {
    _ = userdata;
    _ = options;
    return error.OperationUnsupported;
}

fn netWriteFileUnavailable(
    userdata: ?*anyopaque,
    socket_handle: net.Socket.Handle,
    header: []const u8,
    file_reader: *File.Reader,
    limit: Io.Limit,
) net.Stream.Writer.WriteFileError!usize {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = socket_handle;
    _ = header;
    _ = file_reader;
    _ = limit;
    return error.Unimplemented;
}

fn netClose(userdata: ?*anyopaque, sockets: []const net.Socket) void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    for (sockets) |socket| closeFd(socket.handle);
}

fn netShutdownUnavailable(
    userdata: ?*anyopaque,
    handle: net.Socket.Handle,
    how: net.ShutdownHow,
) net.ShutdownError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = handle;
    _ = how;
    unreachable; // 无法打开的对象,又如何将其关闭?
}

fn netInterfaceNameResolveUnavailable(
    userdata: ?*anyopaque,
    name: *const net.Interface.Name,
) net.Interface.Name.ResolveError!net.Interface {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = name;
    return error.InterfaceNotFound;
}

fn netInterfaceNameUnavailable(
    userdata: ?*anyopaque,
    interface: net.Interface,
) net.Interface.NameError!net.Interface.Name {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = ev;
    _ = interface;
    return error.Unexpected;
}

fn netLookupUnavailable(
    userdata: ?*anyopaque,
    host_name: net.HostName,
    resolved: *Io.Queue(net.HostName.LookupResult),
    options: net.HostName.LookupOptions,
) net.HostName.LookupError!void {
    const ev: *Evented = @ptrCast(@alignCast(userdata));
    _ = host_name;
    _ = options;
    resolved.close(ev.io());
    return error.NetworkDown;
}

fn readAll(ev: *Evented, file: File, buffer: []u8) File.ReadStreamingError!void {
    var index: usize = 0;
    while (buffer.len - index != 0) {
        const len = try ev.fileReadStreaming(file, &.{buffer[index..]});
        if (len == 0) return error.EndOfStream;
        index += len;
    }
}

fn writeAll(ev: *Evented, file: File, buffer: []const u8) (File.Writer.Error || error{EndOfStream})!void {
    var index: usize = 0;
    while (buffer.len - index != 0) {
        const len = try ev.fileWriteStreaming(file, &.{}, &.{buffer[index..]}, 1);
        if (len == 0) return error.EndOfStream;
        index += len;
    }
}

/// 此处为 usize 或 u32,二者均可。因此对写入文件
/// 和发送网络消息均使用同一个 `addBuf` 函数。
const iovlen_t = @FieldType(c.msghdr_const, "iovlen");

fn addConstBuf(v: []iovec_const, i: *iovlen_t, remaining: ?*usize, bytes: []const u8) void {
    if (v.len - i.* == 0) return;
    const len = @min(remaining.*, bytes.len);
    if (len == 0) return;
    v[i.*] = .{ .base = bytes.ptr, .len = len };
    i.* += 1;
    remaining.* -= len;
}
fn addBuf(
    comptime is_const: bool,
    vec: []if (is_const) iovec_const else iovec,
    vec_len: *iovlen_t,
    remaining: *Io.Limit,
    bytes: if (is_const) []const u8 else []u8,
) void {
    if (vec.len - vec_len.* == 0) return;
    const len = remaining.minInt(bytes.len);
    if (len == 0) return;
    vec[vec_len.*] = .{ .base = bytes.ptr, .len = len };
    vec_len.* += 1;
    remaining.* = remaining.subtract(len).?;
}

test {
    _ = Fiber.CancelProtection;
}