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

第 1 行

std.Io.net.assert

别名

第 5 行

别名目标 std.debug.assert

std.Io.net.builtin

常量

第 1 行

std.Io.net.cmsg

命名空间

第 1523 行

用于处理 POSIX 套接字控制消息的工具函数。 另见 https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_socket.h.html

std.Io.net.cmsg_align

常量

第 1520 行

std.Io.net.cmsg.cmsghdr

别名

第 1524 行

别名目标 std.posix.cmsghdr

std.Io.net.cmsg.data

函数

第 1538 行

等价于 C 中的 CMSG_DATA。

pub fn data(header: *align(cmsg_align) cmsghdr) []align(cmsg_align) u8

参数

header: *align(cmsg_align) cmsghdr

std.Io.net.cmsg.Iterator

容器

第 1544 行

等同于 C 中的 CMSG_FIRSTHDR 和 CMSG_NXTHDR。

字段

control: []align(cmsg_align) u8

std.Io.net.cmsg.Iterator.Message

容器

第 1547 行

字段

header: *align(cmsg_align) cmsghdr
data: []align(cmsg_align) u8

std.Io.net.cmsg.Iterator.next

函数

第 1552 行

pub fn next(it: *Iterator) ?Message

参数

it: *Iterator

std.Io.net.cmsg.len

函数

第 1533 行

等价于 C 中的 CMSG_LEN。

pub fn len(data_len: @FieldType(cmsghdr, "len")) @TypeOf(data_len)

参数

data_len: @FieldType(cmsghdr, "len")

std.Io.net.cmsg.space

函数

第 1527 行

等价于 C 中的 CMSG_SPACE。

pub fn space(data_len: usize) usize

参数

data_len: usize

std.Io.net.default_kernel_backlog

常量

第 55 行

std.Io.net.has_unix_sockets

常量

第 49 行

Windows 10 从内部版本 17063 起增加 Unix 套接字支持,redstone 4 是 首个支持它们的正式版本。

std.Io.net.HostName

别名

第 7 行

别名目标 std.Io.net.HostName

std.Io.net.IncomingMessage

容器

第 944 行

字段

from: IpAddress

由接收函数填充。

data: []u8

由接收函数填充,指向调用方提供的缓冲区。

control: []u8

由调用方在调用接收函数之前提供; 由接收函数修改。

flags: Flags

由接收函数填充。

std.Io.net.IncomingMessage.Flags

容器

第 963 行

字段

eor: bool

表示记录结束;返回的数据补全了一条记录 (通常用于 SOCK_SEQPACKET 类型的套接字)。

trunc: bool

表示数据报大于提供的缓冲区,因此丢弃了数据报尾部。

ctrunc: bool

表示由于辅助数据缓冲区 空间不足,部分控制数据被丢弃。

oob: bool

表示收到了加急或带外数据。

errqueue: bool

表示未收到数据,但从套接字错误队列中 收到了扩展错误。

_: u3 = 0

std.Io.net.IncomingMessage.init

常量

第 956 行

适合在调用 receiveManyTimeout 之前初始化。

IncomingMessage

std.Io.net.Interface

容器

第 1010 行

字段

index: u32

值 0 表示 none。

std.Io.net.Interface.isNone

函数

第 1066 行

pub fn isNone(i: Interface) bool

参数

std.Io.net.Interface.name

函数

第 1061 行

断言不为 none。

对应 libc 中的 "if_indextoname"。

pub fn name(i: Interface, io: Io) NameError!Name

参数

i: Interface
io: Io

错误

Canceled Cancelable

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

InterfaceNotFound

index 超出范围。

NameTooLong

接口名称长于 Name.max_len。

Unexpected UnexpectedError

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

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

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

std.Io.net.Interface.Name

容器

第 1016 行

字段

bytes: [max_len:0]u8

std.Io.net.Interface.Name.fromSlice

函数

第 1025 行

pub fn fromSlice(bytes: []const u8) error{NameTooLong}!Name

参数

bytes: []const u8

错误

NameTooLong

std.Io.net.Interface.Name.fromSliceUnchecked

函数

第 1031 行

断言 bytes.len 不超过 max_len。

pub fn fromSliceUnchecked(bytes: []const u8) Name

参数

bytes: []const u8

std.Io.net.Interface.Name.max_len

常量

第 1019 行

std.Io.net.Interface.Name.resolve

函数

第 1046 行

对应 libc 中的 "if_nametoindex"。

pub fn resolve(n: *const Name, io: Io) ResolveError!Interface

参数

n: *const Name
io: Io

错误

AccessDenied
Canceled Cancelable

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

InterfaceNotFound
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.net.Interface.Name.ResolveError

错误集合

第 1039 行

错误

AccessDenied
Canceled Cancelable

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

InterfaceNotFound
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.net.Interface.Name.toSlice

函数

第 1021 行

pub fn toSlice(n: *const Name) []const u8

参数

n: *const Name

std.Io.net.Interface.NameError

错误集合

第 1051 行

错误

Canceled Cancelable

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

InterfaceNotFound

index 超出范围。

NameTooLong

接口名称长于 Name.max_len。

Unexpected UnexpectedError

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

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

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

std.Io.net.Interface.none

常量

第 1014 行

Interface

std.Io.net.Io

别名

第 4 行

别名目标 std.Io

std.Io.net.Ip4Address

容器

第 351 行

二进制内存布局的 IPv4 地址。

字段

bytes: [4]u8
port: u16

std.Io.net.Ip4Address.eql

函数

第 431 行

pub fn eql(a: Ip4Address, b: Ip4Address) bool

参数

std.Io.net.Ip4Address.format

函数

第 426 行

pub fn format(a: Ip4Address, w: *Io.Writer) Io.Writer.Error!void

参数

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.net.Ip4Address.fromAny

函数

第 379 行

给定 IpAddress,将其直接转换为 Ip4Address,或从 IPv4 映射的 IPv6 地址转换;无法转换则返回 null。

pub fn fromAny(addr: IpAddress) ?Ip4Address

参数

addr: IpAddress

std.Io.net.Ip4Address.fromIp6

函数

第 370 行

从 IPv4 映射的 IPv6 地址转换,或返回 null。

pub fn fromIp6(ip6: Ip6Address) ?Ip4Address

参数

ip6: Ip6Address

std.Io.net.Ip4Address.loopback

函数

第 355 行

pub fn loopback(port: u16) Ip4Address

参数

port: u16

std.Io.net.Ip4Address.parse

函数

第 394 行

pub fn parse(buffer: []const u8, port: u16) ParseError!Ip4Address

参数

buffer: []const u8
port: u16

错误

Incomplete
InvalidCharacter
InvalidEnd
NonCanonical
Overflow

std.Io.net.Ip4Address.ParseError

错误集合

第 386 行

错误

Incomplete
InvalidCharacter
InvalidEnd
NonCanonical
Overflow

std.Io.net.Ip4Address.unspecified

函数

第 362 行

pub fn unspecified(port: u16) Ip4Address

参数

port: u16

std.Io.net.Ip6Address

容器

第 439 行

使用二进制内存布局的 IPv6 地址。

字段

port: u16

本机字节序

bytes: [16]u8

大端序

flow: u32 = 0
interface: Interface = .none

std.Io.net.Ip6Address.defined_policies

常量

第 804 行

std.Io.net.Ip6Address.eql

函数

第 760 行

pub fn eql(a: Ip6Address, b: Ip6Address) bool

参数

std.Io.net.Ip6Address.format

函数

第 755 行

另见 formatResolved:它还会在地址末尾打印可选作用域,并且需要 Io 参数。

pub fn format(a: *const Ip6Address, w: *Io.Writer) Io.Writer.Error!void

参数

a: *const Ip6Address
w: *Io.Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.net.Ip6Address.FormatError

错误集合

第 738 行

错误

Canceled Cancelable

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

InterfaceNotFound NameError

index 超出范围。

NameTooLong NameError

接口名称长于 Name.max_len。

Unexpected UnexpectedError

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

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

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

WriteFailed Error

详细诊断信息见 Writer 实现。

std.Io.net.Ip6Address.formatResolved

函数

第 744 行

包含可选的作用域(末尾的 "%foo")。

另见 format,它省略作用域,且 不需要 Io 参数。

pub fn formatResolved(a: *const Ip6Address, io: Io, w: *Io.Writer) FormatError!void

参数

a: *const Ip6Address
io: Io
w: *Io.Writer

错误

Canceled Cancelable

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

InterfaceNotFound NameError

index 超出范围。

NameTooLong NameError

接口名称长于 Name.max_len。

Unexpected UnexpectedError

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

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

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

WriteFailed Error

详细诊断信息见 Writer 实现。

std.Io.net.Ip6Address.fromAny

函数

第 479 行

给定 IpAddress,将其直接转换为 Ip6Address,或通过 构造 IPv4 映射的 IPv6 地址来完成转换。

pub fn fromAny(addr: IpAddress) Ip6Address

参数

addr: IpAddress

std.Io.net.Ip6Address.fromIp4

函数

第 470 行

构造 IPv4 映射的 IPv6 地址。

pub fn fromIp4(ip4: Ip4Address) Ip6Address

参数

ip4: Ip4Address

std.Io.net.Ip6Address.isLinkLocal

函数

第 768 行

pub fn isLinkLocal(a: Ip6Address) bool

参数

std.Io.net.Ip6Address.isLoopBack

函数

第 773 行

pub fn isLoopBack(a: Ip6Address) bool

参数

std.Io.net.Ip6Address.isMultiCast

函数

第 764 行

pub fn isMultiCast(a: Ip6Address) bool

参数

std.Io.net.Ip6Address.isSiteLocal

函数

第 781 行

pub fn isSiteLocal(a: Ip6Address) bool

参数

std.Io.net.Ip6Address.loopback

函数

第 455 行

pub fn loopback(port: u16) Ip6Address

参数

port: u16

std.Io.net.Ip6Address.parse

函数

第 699 行

这是纯函数,但无法处理带作用域 ID(末尾的“%foo”)的 IPv6 地址。要处理这些地址,应改为调用 resolve, 也可使用较底层的 Unresolved 接口。

pub fn parse(buffer: []const u8, port: u16) ParseError!Ip6Address

参数

buffer: []const u8
port: u16

错误

ParseFailed

返回此错误时,可通过调用 Ip6Address.Parsed.init 获得更详细的诊断信息。

UnresolvedScope

返回此错误表示 IPv6 地址带有作用域标识, 即末尾的“%foo”,需要调用 resolve。

std.Io.net.Ip6Address.ParseError

错误集合

第 687 行

错误

ParseFailed

返回此错误时,可通过调用 Ip6Address.Parsed.init 获得更详细的诊断信息。

UnresolvedScope

返回此错误表示 IPv6 地址带有作用域标识, 即末尾的“%foo”,需要调用 resolve。

std.Io.net.Ip6Address.policy

函数

第 786 行

pub fn policy(a: Ip6Address) *const Policy

参数

std.Io.net.Ip6Address.Policy

容器

第 447 行

字段

addr: [16]u8
len: u8
mask: u8
prec: u8
label: u8

std.Io.net.Ip6Address.resolve

函数

第 723 行

此函数需要 Io 参数,因为它必须查询操作系统, 将接口名转换为索引。例如,在 “fe80::e0e:76ff:fed4:cf22%eno1”中,必须创建套接字, 再使用 ioctl 系统调用将“eno1”解析为索引。

pub fn resolve(io: Io, buffer: []const u8, port: u16) ResolveError!Ip6Address

参数

io: Io
buffer: []const u8
port: u16

错误

AccessDenied ResolveError
Canceled Cancelable

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

InterfaceNotFound ResolveError
NameTooLong

接口名称长度超过宿主操作系统支持的范围。

ParseFailed

如果返回此错误,可调用 Parsed.init 函数 获取更详细的诊断信息。

SystemResources ResolveError
Unexpected UnexpectedError

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

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

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

std.Io.net.Ip6Address.ResolveError

错误集合

第 711 行

错误

AccessDenied ResolveError
Canceled Cancelable

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

InterfaceNotFound ResolveError
NameTooLong

接口名称长度超过宿主操作系统支持的范围。

ParseFailed

如果返回此错误,可调用 Parsed.init 函数 获取更详细的诊断信息。

SystemResources ResolveError
Unexpected UnexpectedError

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

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

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

std.Io.net.Ip6Address.scope

函数

第 796 行

pub fn scope(a: Ip6Address) u8

参数

std.Io.net.Ip6Address.Unresolved

容器

第 487 行

IPv6 地址,但 Interface 使用名称而非索引。

字段

bytes: [16]u8

大端序

interface_name: ?[]const u8

尚未检查它是否为有效的原生接口名称。 内存由外部管理。

std.Io.net.Ip6Address.Unresolved.format

函数

第 625 行

pub fn format(u: *const Unresolved, w: *Io.Writer) Io.Writer.Error!void

参数

u: *const Unresolved
w: *Io.Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.net.Ip6Address.Unresolved.parse

函数

第 504 行

pub fn parse(text_in: []const u8) Parsed

参数

text_in: []const u8

std.Io.net.Ip6Address.Unresolved.Parsed

容器

第 494 行

字段

success: Unresolved
invalid_byte: usize
incomplete
junk_after_end: usize
interface_name_oversized: usize
invalid_ip4_mapping: usize
overflow: usize

std.Io.net.Ip6Address.unspecified

函数

第 462 行

pub fn unspecified(port: u16) Ip6Address

参数

port: u16

std.Io.net.IpAddress

容器

第 57 行

字段

std.Io.net.IpAddress.bind

函数

第 305 行

将地址与 Socket 关联,用于接收 UDP 数据包 及其他非流式消息。流式替代方案参见 listen。

一个已绑定的 Socket 可以接收来自多个 不同地址的消息。

pub fn bind(address: *const IpAddress, io: Io, options: BindOptions) BindError!Socket

参数

address: *const IpAddress
io: Io
options: BindOptions

错误

AccessDenied

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

AddressFamilyUnsupported

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

AddressInUse

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

AddressUnavailable

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

Canceled Cancelable

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

NetworkDown

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

OptionUnsupported

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded

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

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

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

SystemResources

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

Unexpected UnexpectedError

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

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

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

std.Io.net.IpAddress.BindError

错误集合

第 258 行

错误

AccessDenied

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

AddressFamilyUnsupported

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

AddressInUse

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

AddressUnavailable

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

Canceled Cancelable

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

NetworkDown

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

OptionUnsupported

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded

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

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

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

SystemResources

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

Unexpected UnexpectedError

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

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

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

std.Io.net.IpAddress.BindOptions

容器

第 284 行

字段

ip6_only: ?bool = null

套接字仅限发送和接收 IPv6 数据包。 此时 IPv4 应用和 IPv6 应用可以 同时绑定同一端口。

默认值由系统配置决定。

allow_broadcast: bool = false

允许套接字向广播地址发送数据报。 未启用时,任何向广播地址发送数据报的尝试 都会以 error.AccessDenied 失败。

mode: Socket.Mode
protocol: ?Protocol = null

std.Io.net.IpAddress.connect

函数

第 345 行

发起面向连接的网络流。

pub fn connect(address: *const IpAddress, io: Io, options: ConnectOptions) ConnectError!Stream

参数

address: *const IpAddress
io: Io
options: 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.net.IpAddress.ConnectError

错误集合

第 309 行

错误

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.net.IpAddress.ConnectOptions

容器

第 338 行

字段

mode: Socket.Mode
protocol: ?Protocol = null
timeout: Io.Timeout = .none

std.Io.net.IpAddress.eql

函数

第 187 行

pub fn eql(a: *const IpAddress, b: *const IpAddress) bool

参数

a: *const IpAddress
b: *const IpAddress

std.Io.net.IpAddress.Family

常量

第 61 行

std.Io.net.IpAddress.format

函数

第 181 行

另一种形式参见 formatResolved;它还会打印 IPv6 地址末尾的可选作用域, 并且需要 Io 参数。

pub fn format(a: IpAddress, w: *Io.Writer) Io.Writer.Error!void

参数

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.net.IpAddress.formatResolved

函数

第 172 行

包含 IPv6 地址中的可选作用域,即末尾的“%foo”。

不包含作用域且无需 Io 参数的替代形式,参见 format。

pub fn formatResolved(a: IpAddress, io: Io, w: *Io.Writer) Ip6Address.FormatError!void

参数

a: IpAddress
io: Io
w: *Io.Writer

错误

Canceled Cancelable

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

InterfaceNotFound NameError

index 超出范围。

NameTooLong NameError

接口名称长于 Name.max_len。

Unexpected UnexpectedError

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

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

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

WriteFailed Error

详细诊断信息见 Writer 实现。

std.Io.net.IpAddress.fromIp6

函数

第 164 行

转换 IPv4 映射的 IPv6 地址,或直接返回 IPv6 地址。

pub fn fromIp6(ip6: Ip6Address) IpAddress

参数

ip6: Ip6Address

std.Io.net.IpAddress.getPort

函数

第 149 行

以本机字节序返回端口。

pub fn getPort(a: IpAddress) u16

参数

std.Io.net.IpAddress.listen

函数

第 248 行

等待 TCP 连接。使用此 API 时无需调用 bind。返回的 Server 具有打开的 stream。

pub fn listen(address: *const IpAddress, io: Io, options: ListenOptions) ListenError!Server

参数

address: *const IpAddress
io: Io
options: 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.net.IpAddress.ListenError

错误集合

第 200 行

错误

AccessDenied

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

AddressFamilyUnsupported

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

AddressInUse

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

AddressUnavailable

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

Canceled Cancelable

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

NetworkDown

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

OptionUnsupported

Io 实现不支持某个 ListenOptions。

ProcessFdQuotaExceeded

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

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

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

SystemResources

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

Unexpected UnexpectedError

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

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

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

std.Io.net.IpAddress.ListenOptions

容器

第 226 行

字段

kernel_backlog: u31 = default_kernel_backlog

内核代表应用程序接受的连接数量。 若内核中积压的连接超过此数量,客户端将开始 收到“Connection refused”。

reuse_address: bool = false

在 POSIX 上设置 SO_REUSEADDR 和 SO_REUSEPORT。 在 Windows 上设置大致等价的 SO_REUSEADDR。

mode: Socket.Mode = .stream

此处只能使用面向连接的模式,包括:

  • Socket.Mode.stream
  • Socket.Mode.seqpacket
protocol: Protocol = .tcp

此处仅可使用面向连接的协议,包括:

  • Protocol.tcp
  • Protocol.tp
  • Protocol.dccp
  • Protocol.sctp

std.Io.net.IpAddress.parse

函数

第 101 行

将给定 IP 地址字符串解析为 IpAddress 值。

这是纯函数,但无法处理带作用域 ID(末尾的“%foo”)的 IPv6 地址。要处理此类地址, 应改为调用 resolve。

pub fn parse(text: []const u8, port: u16) !IpAddress

参数

text: []const u8
port: u16

std.Io.net.IpAddress.parseIp4

函数

第 114 行

pub fn parseIp4(text: []const u8, port: u16) Ip4Address.ParseError!IpAddress

参数

text: []const u8
port: u16

错误

Incomplete
InvalidCharacter
InvalidEnd
NonCanonical
Overflow

std.Io.net.IpAddress.parseIp6

函数

第 121 行

这是纯函数,但无法处理带作用域 ID(末尾的“%foo”)的 IPv6 地址。要处理这类地址, 应改为调用 resolveIp6。

pub fn parseIp6(text: []const u8, port: u16) Ip6Address.ParseError!IpAddress

参数

text: []const u8
port: u16

错误

ParseFailed

返回此错误时,可通过调用 Ip6Address.Parsed.init 获得更详细的诊断信息。

UnresolvedScope

返回此错误表示 IPv6 地址带有作用域标识, 即末尾的“%foo”,需要调用 resolve。

std.Io.net.IpAddress.parseLiteral

函数

第 73 行

解析可能包含端口的 IP 地址。

IPv4 的写法为 address:port。

对于 IPv6,RFC 3986 将其定义为“IP 字面量”,通过用方括号包围地址部分来区分地址与端口,即“[addr]:port”。即使未给出端口,也必须保留方括号。

pub fn parseLiteral(text: []const u8) ParseLiteralError!IpAddress

参数

text: []const u8

错误

InvalidAddress
InvalidPort

std.Io.net.IpAddress.ParseLiteralError

错误集合

第 63 行

错误

InvalidAddress
InvalidPort

std.Io.net.IpAddress.resolve

函数

第 131 行

此函数需要 Io 参数,因为必须查询操作 系统,将接口名称转换为索引。例如, 在 "fe80::e0e:76ff:fed4:cf22%eno1" 中,需要通过 创建套接字再调用 ioctl,将 "eno1" 解析为索引。

不处理作用域的纯函数,参见 parse。

pub fn resolve(io: Io, text: []const u8, port: u16) !IpAddress

参数

io: Io
text: []const u8
port: u16

std.Io.net.IpAddress.resolveIp6

函数

第 144 行

pub fn resolveIp6(io: Io, text: []const u8, port: u16) Ip6Address.ResolveError!IpAddress

参数

io: Io
text: []const u8
port: u16

错误

AccessDenied ResolveError
Canceled Cancelable

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

InterfaceNotFound ResolveError
NameTooLong

接口名称长度超过宿主操作系统支持的范围。

ParseFailed

如果返回此错误,可调用 Parsed.init 函数 获取更详细的诊断信息。

SystemResources ResolveError
Unexpected UnexpectedError

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

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

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

std.Io.net.IpAddress.setPort

函数

第 156 行

port 使用本机字节序。

pub fn setPort(a: *IpAddress, port: u16) void

参数

a: *IpAddress
port: u16

std.Io.net.native_os

常量

第 2 行

std.Io.net.OutgoingMessage

容器

第 982 行

字段

address: *const IpAddress
data_ptr: [*]const u8
data_len: usize

初始化为要从 data_ptr 发送的字节数。发送成功后, 替换为实际发送的字节数。

control: []const u8 = &.{}

std.Io.net.Protocol

容器

第 10 行

权威来源:互联网号码分配局(IANA)

字段

hopopts = 0
icmp = 1
igmp = 2
ipip = 4
tcp = 6
egp = 8
pup = 12
udp = 17
idp = 22
tp = 29
dccp = 33
ipv6 = 41
routing = 43
fragment = 44
rsvp = 46
gre = 47
esp = 50
ah = 51
icmpv6 = 58
none = 59
dstopts = 60
mtp = 92
beetph = 94
encap = 98
pim = 103
comp = 108
sctp = 132
mh = 135
udplite = 136
mpls = 137
ethernet = 143
raw = 255
mptcp = 262
_

std.Io.net.ReceiveFlags

容器

第 937 行

字段

oob: bool = false
peek: bool = false
trunc: bool = false
_: u5 = 0

std.Io.net.SendFlags

容器

第 991 行

字段

confirm: bool = false
dont_route: bool = false
eor: bool = false
oob: bool = false
fastopen: bool = false
_: u3 = 0

std.Io.net.Server

容器

第 1567 行

字段

socket: Socket
options: AcceptOptions

std.Io.net.Server.accept

函数

第 1607 行

阻塞直到客户端连接服务器。

pub fn accept(s: *Server, io: Io) AcceptError!Stream

参数

s: *Server
io: Io

错误

BlockedByFirewall

防火墙规则禁止连接。

Canceled Cancelable

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

ConnectionAborted

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

NetworkDown

网络子系统已失败。

ProcessFdQuotaExceeded

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

ProtocolFailure
SocketNotListening

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

SystemFdQuotaExceeded

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

SystemResources

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

Unexpected UnexpectedError

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

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

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

WouldBlock

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

std.Io.net.Server.AcceptError

错误集合

第 1576 行

错误

BlockedByFirewall

防火墙规则禁止连接。

Canceled Cancelable

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

ConnectionAborted

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

NetworkDown

网络子系统已失败。

ProcessFdQuotaExceeded

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

ProtocolFailure
SocketNotListening

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

SystemFdQuotaExceeded

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

SystemResources

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

Unexpected UnexpectedError

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

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

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

WouldBlock

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

std.Io.net.Server.AcceptOptions

类型

第 1601 行

std.Io.net.Server.deinit

函数

第 1571 行

pub fn deinit(s: *Server, io: Io) void

参数

s: *Server
io: Io

std.Io.net.ShutdownError

错误集合

第 1002 行

错误

Canceled Cancelable

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

ConnectionAborted
ConnectionResetByPeer
NetworkDown
SocketUnconnected
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.net.ShutdownHow

容器

第 1000 行

字段

recv
send
both

std.Io.net.Socket

容器

第 1072 行

未指定协议的开放端口。

字段

handle: Handle
address: IpAddress

若请求此信息,则包含解析得到的临时端口号。

std.Io.net.Socket.close

函数

第 1100 行

使 address 保持有效状态。

pub fn close(s: *const Socket, io: Io) void

参数

s: *const Socket
io: Io

std.Io.net.Socket.closeMany

函数

第 1104 行

pub fn closeMany(io: Io, sockets: []const Socket) void

参数

io: Io
sockets: []const Socket

std.Io.net.Socket.createPair

函数

第 1276 行

创建一对彼此连接的套接字。

也称为 "socketpair"。

pub fn createPair(io: Io, options: CreatePairOptions) CreatePairError![2]Socket

参数

io: Io
options: CreatePairOptions

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

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

OperationUnsupported
ProcessFdQuotaExceeded

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

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

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

SystemResources

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.CreatePairError

错误集合

第 1251 行

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

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

OperationUnsupported
ProcessFdQuotaExceeded

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

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

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

SystemResources

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.CreatePairOptions

容器

第 1267 行

字段

family: IpAddress.Family = .ip4
mode: Mode = .stream
protocol: ?Protocol = null

std.Io.net.Socket.Handle

别名

第 1097 行

由底层平台定义的类型,可能可以,也可能不可以 与文件系统文件描述符互换。

别名目标 std.posix.fd_t

std.Io.net.Socket.Mode

容器

第 1077 行

字段

stream

提供有序、可靠、双向、基于连接的字节流。 可能支持带外数据传输机制。

dgram

支持数据报(无连接、不可靠, 且最大长度固定的消息)。

seqpacket

为具有固定最大长度的数据报提供有序、可靠、 双向、面向连接的数据传输通道;要求消费者 每次输入系统调用都读取一个完整数据包。

raw

提供对原始网络协议的访问。

rdm

提供不保证顺序的可靠数据报层。

std.Io.net.Socket.receive

函数

第 1183 行

等待数据。无连接。

另请参见:

  • receiveTimeout
pub fn receive(s: *const Socket, io: Io, buffer: []u8) ReceiveError!IncomingMessage

参数

s: *const Socket
io: Io
buffer: []u8

错误

Canceled Cancelable

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

ConnectionResetByPeer Error

发送方意外关闭了网络连接。

ConnectionTimedOut Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

PortUnreachable Error

此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。

ProcessFdQuotaExceeded Error

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

SocketUnconnected Error

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

SystemFdQuotaExceeded Error

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

SystemResources Error

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.ReceiveError

错误集合

第 1177 行

错误

Canceled Cancelable

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

ConnectionResetByPeer Error

发送方意外关闭了网络连接。

ConnectionTimedOut Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

PortUnreachable Error

此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。

ProcessFdQuotaExceeded Error

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

SocketUnconnected Error

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

SystemFdQuotaExceeded Error

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

SystemResources Error

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.receiveManyTimeout

类型函数

第 1232 行

等待至少一条消息到达,也可能返回 多条消息。无需连接。

返回收到的消息数;若消息未及时到达, 则返回 error.Timeout。

另见:

  • receive
  • receiveTimeout
pub fn receiveManyTimeout( s: *const Socket, io: Io, message_buffer: []IncomingMessage, data_buffer: []u8, flags: ReceiveFlags, timeout: Io.Timeout, ) struct { ?ReceiveTimeoutError, usize }

参数

s: *const Socket
io: Io
message_buffer: []IncomingMessage

此函数假定每个元素的 control 字段已初始化。 使用 IncomingMessage.init 初始化可能有帮助。

data_buffer: []u8
flags: ReceiveFlags
timeout: Io.Timeout

std.Io.net.Socket.receiveTimeout

函数

第 1205 行

等待数据。无连接。

若没有消息及时到达,则返回 error.Timeout。

另见:

  • receive
  • receiveManyTimeout
pub fn receiveTimeout( s: *const Socket, io: Io, buffer: []u8, timeout: Io.Timeout, ) ReceiveTimeoutError!IncomingMessage

参数

s: *const Socket
io: Io
buffer: []u8
timeout: Io.Timeout

错误

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

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

ConnectionResetByPeer Error

发送方意外关闭了网络连接。

ConnectionTimedOut Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

PortUnreachable Error

此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。

ProcessFdQuotaExceeded Error

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

SocketUnconnected Error

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

SystemFdQuotaExceeded Error

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

SystemResources Error

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

Timeout Error
Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.ReceiveTimeoutError

错误集合

第 1196 行

错误

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

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

ConnectionResetByPeer Error

发送方意外关闭了网络连接。

ConnectionTimedOut Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

PortUnreachable Error

此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。

ProcessFdQuotaExceeded Error

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

SocketUnconnected Error

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

SystemFdQuotaExceeded Error

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

SystemResources Error

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

Timeout Error
Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.send

函数

第 1111 行

以无连接方式,在单个数据包中将 data 传给 dest。

pub fn send(s: *const Socket, io: Io, dest: *const IpAddress, data: []const u8) SendError!void

参数

s: *const Socket
io: Io
dest: *const IpAddress
data: []const u8

错误

AccessDenied Error

尝试向网络/广播地址发送数据, 却将其当作单播地址。

AddressFamilyUnsupported Error

操作系统或协议不支持该地址族。

Canceled Cancelable

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

ConnectionRefused Error

目标地址未在侦听;对于无连接消息也可能发生此情况。

ConnectionResetByPeer Error

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

ConnectionTimedOut Error

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

FastOpenAlreadyInProgress Error

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

HostUnreachable Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

NetworkUnreachable Error

没有到网络的路由。

SocketUnconnected Error

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

SystemResources Error

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

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.SendError

错误集合

第 1108 行

错误

AccessDenied Error

尝试向网络/广播地址发送数据, 却将其当作单播地址。

AddressFamilyUnsupported Error

操作系统或协议不支持该地址族。

Canceled Cancelable

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

ConnectionRefused Error

目标地址未在侦听;对于无连接消息也可能发生此情况。

ConnectionResetByPeer Error

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

ConnectionTimedOut Error

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

FastOpenAlreadyInProgress Error

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

HostUnreachable Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

NetworkUnreachable Error

没有到网络的路由。

SocketUnconnected Error

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

SystemResources Error

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

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.sendMany

函数

第 1152 行

已弃用;请使用超时为 .none 的 sendManyTimeout。

若此函数返回错误,messages 中的部分消息 仍可能已经发送,但不会全部发送。此函数不报告该情况, 而 sendManyTimeout 会报告。

pub fn sendMany(s: *const Socket, io: Io, messages: []OutgoingMessage, flags: SendFlags) SendError!void

参数

s: *const Socket
io: Io
messages: []OutgoingMessage
flags: SendFlags

错误

AccessDenied Error

尝试向网络/广播地址发送数据, 却将其当作单播地址。

AddressFamilyUnsupported Error

操作系统或协议不支持该地址族。

Canceled Cancelable

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

ConnectionRefused Error

目标地址未在侦听;对于无连接消息也可能发生此情况。

ConnectionResetByPeer Error

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

ConnectionTimedOut Error

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

FastOpenAlreadyInProgress Error

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

HostUnreachable Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

NetworkUnreachable Error

没有到网络的路由。

SocketUnconnected Error

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

SystemResources Error

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

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.sendManyTimeout

类型函数

第 1162 行

pub fn sendManyTimeout( s: *const Socket, io: Io, messages: []OutgoingMessage, flags: SendFlags, timeout: Io.Timeout, ) struct { ?SendTimeoutError, usize }

参数

s: *const Socket
io: Io
messages: []OutgoingMessage
flags: SendFlags
timeout: Io.Timeout

std.Io.net.Socket.sendTimeout

函数

第 1129 行

pub fn sendTimeout( s: *const Socket, io: Io, dest: *const IpAddress, data: []const u8, timeout: Io.Timeout, ) SendTimeoutError!void

参数

s: *const Socket
io: Io
dest: *const IpAddress
data: []const u8
timeout: Io.Timeout

错误

AccessDenied Error

尝试向网络/广播地址发送数据, 却将其当作单播地址。

AddressFamilyUnsupported Error

操作系统或协议不支持该地址族。

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

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

ConnectionRefused Error

目标地址未在侦听;对于无连接消息也可能发生此情况。

ConnectionResetByPeer Error

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

ConnectionTimedOut Error

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

FastOpenAlreadyInProgress Error

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

HostUnreachable Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

NetworkUnreachable Error

没有到网络的路由。

SocketUnconnected Error

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

SystemResources Error

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

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

Timeout Error
Unexpected UnexpectedError

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

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

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

std.Io.net.Socket.SendTimeoutError

错误集合

第 1127 行

错误

AccessDenied Error

尝试向网络/广播地址发送数据, 却将其当作单播地址。

AddressFamilyUnsupported Error

操作系统或协议不支持该地址族。

Canceled Cancelable

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

ConcurrencyUnavailable ConcurrentError

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

ConnectionRefused Error

目标地址未在侦听;对于无连接消息也可能发生此情况。

ConnectionResetByPeer Error

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

ConnectionTimedOut Error

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

FastOpenAlreadyInProgress Error

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

HostUnreachable Error

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

MessageOversize Error

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown Error

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

NetworkUnreachable Error

没有到网络的路由。

SocketUnconnected Error

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

SystemResources Error

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

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

Timeout Error
Unexpected UnexpectedError

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

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

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

std.Io.net.std

别名

第 3 行

别名目标 std

std.Io.net.Stream

容器

第 1284 行

已打开的套接字连接,其网络协议保证 顺序、交付并防止重复。通常为 TCP 或 UNIX 域 套接字。

字段

socket: Socket

std.Io.net.Stream.close

函数

第 1321 行

pub fn close(s: *const Stream, io: Io) void

参数

s: *const Stream
io: Io

std.Io.net.Stream.max_iovecs_len

常量

第 1287 行

std.Io.net.Stream.read

函数

第 1302 行

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

pub fn read(s: *const Stream, io: Io, data: [][]u8) Reader.Error!usize

参数

s: *const Stream
io: Io
data: [][]u8

错误

AccessDenied Error

文件描述符不具有读取所需权限。

Canceled Cancelable

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

ConnectionResetByPeer Error
ConnectionTimedOut Error

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

NetworkDown Error
SocketUnconnected Error
SystemResources Error
Unexpected UnexpectedError

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

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

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

std.Io.net.Stream.reader

函数

第 1501 行

pub fn reader(stream: Stream, io: Io, buffer: []u8) Reader

参数

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Reader

容器

第 1329 行

字段

io: Io
interface: Io.Reader
control_buffer: []align(cmsg_align) u8
control_len: usize
control_truncated: bool
stream: Stream
err: ?Error

std.Io.net.Stream.Reader.clearControl

函数

第 1412 行

清除缓冲的控制数据。

pub fn clearControl(r: *Reader) void

参数

r: *Reader

std.Io.net.Stream.Reader.controlIterator

函数

第 1407 行

遍历已缓冲的控制消息。

pub fn controlIterator(r: *const Reader) cmsg.Iterator

参数

r: *const Reader

std.Io.net.Stream.Reader.controlSlice

函数

第 1402 行

访问原始的缓冲控制数据。

pub fn controlSlice(r: *const Reader) []align(cmsg_align) u8

参数

r: *const Reader

std.Io.net.Stream.Reader.Error

错误集合

第 1338 行

错误

AccessDenied Error

文件描述符不具有读取所需权限。

Canceled Cancelable

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

ConnectionResetByPeer Error
ConnectionTimedOut Error

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

NetworkDown Error
SocketUnconnected Error
SystemResources Error
Unexpected UnexpectedError

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

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

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

std.Io.net.Stream.Reader.init

函数

第 1340 行

pub fn init(stream: Stream, io: Io, buffer: []u8) Reader

参数

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Reader.initWithControl

函数

第 1345 行

与 init 相同,但还提供用于存储控制数据的缓冲区。

pub fn initWithControl( stream: Stream, io: Io, buffer: []u8, control_buffer: []align(cmsg_align) u8, ) Reader

参数

stream: Stream
io: Io
buffer: []u8
control_buffer: []align(cmsg_align) u8

std.Io.net.Stream.Reader.readVec

函数

第 1378 行

fn readVec(io_r: *Io.Reader, data: [][]u8) Io.Reader.Error!usize

参数

io_r: *Io.Reader
data: [][]u8

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.Io.net.Stream.Reader.streamImpl

函数

第 1370 行

fn streamImpl(io_r: *Io.Reader, io_w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize

参数

io_r: *Io.Reader
io_w: *Io.Writer
limit: Io.Limit

错误

EndOfStream

Reader 指示流结束。此错误不会从 Writer 产生。

ReadFailed

详细诊断参见 Reader 的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.net.Stream.readerWithControl

函数

第 1506 行

与 reader 相同,但还提供用于存储控制数据的缓冲区。

pub fn readerWithControl( stream: Stream, io: Io, buffer: []u8, control_buffer: []align(cmsg_align) u8, ) Reader

参数

stream: Stream
io: Io
buffer: []u8
control_buffer: []align(cmsg_align) u8

std.Io.net.Stream.ReadResult

容器

第 1289 行

字段

data_len: usize
control_len: usize = 0
control_truncated: bool = false

是否仅收到部分控制数据。

控制数据被截断时,额外数据实际上 会直接丢失。这表明存在设计问题, 例如控制缓冲区过小。

std.Io.net.Stream.readWithControl

函数

第 1313 行

连同控制数据一起读取。

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

pub fn readWithControl(s: *const Stream, io: Io, data: [][]u8, control: []u8) Reader.Error!ReadResult

参数

s: *const Stream
io: Io
data: [][]u8
control: []u8

错误

AccessDenied Error

文件描述符不具有读取所需权限。

Canceled Cancelable

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

ConnectionResetByPeer Error
ConnectionTimedOut Error

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

NetworkDown Error
SocketUnconnected Error
SystemResources Error
Unexpected UnexpectedError

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

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

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

std.Io.net.Stream.shutdown

函数

第 1325 行

pub fn shutdown(s: *const Stream, io: Io, how: ShutdownHow) ShutdownError!void

参数

s: *const Stream
io: Io
how: ShutdownHow

错误

Canceled Cancelable

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

ConnectionAborted
ConnectionResetByPeer
NetworkDown
SocketUnconnected
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.net.Stream.writer

函数

第 1515 行

pub fn writer(stream: Stream, io: Io, buffer: []u8) Writer

参数

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Writer

容器

第 1418 行

字段

io: Io
interface: Io.Writer
control: []const u8 = &.{}

将在下次排空时发送,然后重新设为空切片。

stream: Stream
err: ?Error = null
write_file_err: ?WriteFileError = null

std.Io.net.Stream.Writer.drain

函数

第 1455 行

fn drain(io_w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize

参数

io_w: *Io.Writer
data: []const []const u8
splat: usize

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.net.Stream.Writer.Error

错误集合

第 1427 行

错误

AddressFamilyUnsupported Error

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

Canceled Cancelable

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

ConnectionRefused Error

目标地址未在监听。

ConnectionResetByPeer Error

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

ConnectionTimedOut Error

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

FastOpenAlreadyInProgress Error

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

HostUnreachable Error

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

NetworkDown Error

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

NetworkUnreachable Error

没有到网络的路由。

SocketNotBound Error
SocketUnconnected Error

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

SystemResources Error

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

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

Unexpected UnexpectedError

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

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

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

std.Io.net.Stream.Writer.init

函数

第 1441 行

pub fn init(stream: Stream, io: Io, buffer: []u8) Writer

参数

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Writer.sendFile

函数

第 1478 行

fn sendFile(io_w: *Io.Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize

参数

io_w: *Io.Writer
file_reader: *Io.File.Reader
limit: Io.Limit

错误

EndOfStream

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

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.net.Stream.Writer.WriteFileError

错误集合

第 1429 行

错误

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.net.testIp6Parse

函数

第 1636 行

fn testIp6Parse(input: []const u8) !void

参数

input: []const u8

std.Io.net.testIp6ParseTransform

函数

第 1640 行

fn testIp6ParseTransform(expected: []const u8, input: []const u8) !void

参数

expected: []const u8
input: []const u8

std.Io.net.UnixAddress

容器

第 857 行

字段

path: []const u8

std.Io.net.UnixAddress.connect

函数

第 928 行

pub fn connect(ua: *const UnixAddress, io: Io) ConnectError!Stream

参数

ua: *const UnixAddress
io: Io

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

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

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

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

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

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

WouldBlock

std.Io.net.UnixAddress.ConnectError

错误集合

第 910 行

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

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

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

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

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

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

WouldBlock

std.Io.net.UnixAddress.init

函数

第 867 行

pub fn init(p: []const u8) InitError!UnixAddress

参数

p: []const u8

错误

NameTooLong

std.Io.net.UnixAddress.InitError

错误集合

第 865 行

错误

NameTooLong

std.Io.net.UnixAddress.isAbstract

函数

第 872 行

pub fn isAbstract(ua: *const UnixAddress) bool

参数

ua: *const UnixAddress

std.Io.net.UnixAddress.listen

函数

第 899 行

pub fn listen(ua: *const UnixAddress, io: Io, options: ListenOptions) ListenError!Server

参数

ua: *const UnixAddress
io: Io
options: ListenOptions

错误

AccessDenied
AddressFamilyUnsupported
AddressInUse
AddressUnavailable
Canceled Cancelable

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

FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.net.UnixAddress.ListenError

错误集合

第 876 行

错误

AccessDenied
AddressFamilyUnsupported
AddressInUse
AddressUnavailable
Canceled Cancelable

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

FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

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

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

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

std.Io.net.UnixAddress.ListenOptions

容器

第 892 行

字段

kernel_backlog: u31 = default_kernel_backlog

内核代表应用程序接受的连接数量。 若内核中积压的连接超过此数量,客户端将开始 收到“Connection refused”。

std.Io.net.UnixAddress.max_len

常量

第 860 行

源码

std/Io/net.zig

const builtin = @import("builtin");
const native_os = builtin.os.tag;
const std = @import("../std.zig");
const Io = std.Io;
const assert = std.debug.assert;

pub const HostName = @import("net/HostName.zig");

/// 权威来源:互联网号码分配局(IANA)
pub const Protocol = enum(u32) {
    hopopts = 0,
    icmp = 1,
    igmp = 2,
    ipip = 4,
    tcp = 6,
    egp = 8,
    pup = 12,
    udp = 17,
    idp = 22,
    tp = 29,
    dccp = 33,
    ipv6 = 41,
    routing = 43,
    fragment = 44,
    rsvp = 46,
    gre = 47,
    esp = 50,
    ah = 51,
    icmpv6 = 58,
    none = 59,
    dstopts = 60,
    mtp = 92,
    beetph = 94,
    encap = 98,
    pim = 103,
    comp = 108,
    sctp = 132,
    mh = 135,
    udplite = 136,
    mpls = 137,
    ethernet = 143,
    raw = 255,
    mptcp = 262,
    _,
};

/// Windows 10 从内部版本 17063 起增加 Unix 套接字支持,redstone 4 是
/// 首个支持它们的正式版本。
pub const has_unix_sockets = switch (native_os) {
    .windows => builtin.os.version_range.windows.isAtLeast(.win10_rs4) orelse false,
    .wasi => false,
    else => true,
};

pub const default_kernel_backlog = 128;

pub const IpAddress = union(enum) {
    ip4: Ip4Address,
    ip6: Ip6Address,

    pub const Family = @typeInfo(IpAddress).@"union".tag_type.?;

    pub const ParseLiteralError = error{ InvalidAddress, InvalidPort };

    /// 解析可能包含端口的 IP 地址。
    ///
    /// IPv4 的写法为 `address:port`。
    ///
    /// 对于 IPv6,RFC 3986 将其定义为“IP 字面量”,通过用方括号包围地址部分来区分地址与端口,即“[addr]:port”。即使未给出端口,也必须保留方括号。
    ///
    ///
    ///
    pub fn parseLiteral(text: []const u8) ParseLiteralError!IpAddress {
        if (text.len == 0) return error.InvalidAddress;
        if (text[0] == '[') {
            const addr_end = std.mem.findScalar(u8, text, ']') orelse
                return error.InvalidAddress;
            const addr_text = text[1..addr_end];
            const port: u16 = p: {
                if (addr_end == text.len - 1) break :p 0;
                if (text[addr_end + 1] != ':') return error.InvalidAddress;
                break :p std.fmt.parseInt(u16, text[addr_end + 2 ..], 10) catch return error.InvalidPort;
            };
            return parseIp6(addr_text, port) catch error.InvalidAddress;
        }
        if (std.mem.findScalar(u8, text, ':')) |i| {
            const addr = Ip4Address.parse(text[0..i], 0) catch return error.InvalidAddress;
            return .{ .ip4 = .{
                .bytes = addr.bytes,
                .port = std.fmt.parseInt(u16, text[i + 1 ..], 10) catch return error.InvalidPort,
            } };
        }
        return parseIp4(text, 0) catch error.InvalidAddress;
    }

    /// 将给定 IP 地址字符串解析为 `IpAddress` 值。
    ///
    /// 这是纯函数,但无法处理带作用域 ID(末尾的“%foo”)的 IPv6 地址。要处理此类地址,
    /// 应改为调用 `resolve`。
    ///
    pub fn parse(text: []const u8, port: u16) !IpAddress {
        if (parseIp4(text, port)) |ip4| return ip4 else |err| switch (err) {
            error.Overflow,
            error.InvalidEnd,
            error.InvalidCharacter,
            error.Incomplete,
            error.NonCanonical,
            => {},
        }

        return parseIp6(text, port);
    }

    pub fn parseIp4(text: []const u8, port: u16) Ip4Address.ParseError!IpAddress {
        return .{ .ip4 = try Ip4Address.parse(text, port) };
    }

    /// 这是纯函数,但无法处理带作用域 ID(末尾的“%foo”)的
    /// IPv6 地址。要处理这类地址,
    /// 应改为调用 `resolveIp6`。
    pub fn parseIp6(text: []const u8, port: u16) Ip6Address.ParseError!IpAddress {
        return .{ .ip6 = try Ip6Address.parse(text, port) };
    }

    /// 此函数需要 `Io` 参数,因为必须查询操作
    /// 系统,将接口名称转换为索引。例如,
    /// 在 "fe80::e0e:76ff:fed4:cf22%eno1" 中,需要通过
    /// 创建套接字再调用 `ioctl`,将 "eno1" 解析为索引。
    ///
    /// 不处理作用域的纯函数,参见 `parse`。
    pub fn resolve(io: Io, text: []const u8, port: u16) !IpAddress {
        if (parseIp4(text, port)) |ip4| return ip4 else |err| switch (err) {
            error.Overflow,
            error.InvalidEnd,
            error.InvalidCharacter,
            error.Incomplete,
            error.NonCanonical,
            => {},
        }

        return resolveIp6(io, text, port);
    }

    pub fn resolveIp6(io: Io, text: []const u8, port: u16) Ip6Address.ResolveError!IpAddress {
        return .{ .ip6 = try Ip6Address.resolve(io, text, port) };
    }

    /// 以本机字节序返回端口。
    pub fn getPort(a: IpAddress) u16 {
        return switch (a) {
            inline .ip4, .ip6 => |x| x.port,
        };
    }

    /// `port` 使用本机字节序。
    pub fn setPort(a: *IpAddress, port: u16) void {
        switch (a.*) {
            .ip4 => a.ip4.port = port,
            .ip6 => a.ip6.port = port,
        }
    }

    /// 转换 IPv4 映射的 IPv6 地址,或直接返回 IPv6 地址。
    pub fn fromIp6(ip6: Ip6Address) IpAddress {
        return if (Ip4Address.fromIp6(ip6)) |ip4| .{ .ip4 = ip4 } else .{ .ip6 = ip6 };
    }

    /// 包含 IPv6 地址中的可选作用域,即末尾的“%foo”。
    ///
    /// 不包含作用域且无需 `Io` 参数的替代形式,参见 `format`。
    ///
    pub fn formatResolved(a: IpAddress, io: Io, w: *Io.Writer) Ip6Address.FormatError!void {
        switch (a) {
            .ip4 => |x| return x.format(w),
            .ip6 => |x| return x.formatResolved(io, w),
        }
    }

    /// 另一种形式参见 `formatResolved`;它还会打印 IPv6 地址末尾的可选作用域,
    /// 并且需要 `Io` 参数。
    pub fn format(a: IpAddress, w: *Io.Writer) Io.Writer.Error!void {
        switch (a) {
            inline .ip4, .ip6 => |x| return x.format(w),
        }
    }

    pub fn eql(a: *const IpAddress, b: *const IpAddress) bool {
        return switch (a.*) {
            .ip4 => |a_ip4| switch (b.*) {
                .ip4 => |b_ip4| a_ip4.eql(b_ip4),
                else => false,
            },
            .ip6 => |a_ip6| switch (b.*) {
                .ip6 => |b_ip6| a_ip6.eql(b_ip6),
                else => false,
            },
        };
    }

    pub const ListenError = error{
        /// 该地址受到保护,当前用户没有绑定它的权限。
        AccessDenied,
        /// 地址已被占用。当绑定端口为 0,
        /// 但所有临时端口均已使用时,可能发生此情况。
        AddressInUse,
        /// 请求了不存在的接口,或请求的地址不是本地地址。
        AddressUnavailable,
        /// 用于到达目标的本地网络接口已离线。
        NetworkDown,
        /// 操作系统内部内存或其他资源不足。
        SystemResources,
        /// 已达到每进程可打开文件描述符数量上限。
        ProcessFdQuotaExceeded,
        /// 已达到系统范围内已打开文件的总数上限。
        SystemFdQuotaExceeded,
        /// 操作系统不支持请求的地址族(IPv4 或 IPv6)。
        AddressFamilyUnsupported,
        ProtocolUnsupportedBySystem,
        ProtocolUnsupportedByAddressFamily,
        SocketModeUnsupported,
        /// Io 实现不支持某个 `ListenOptions`。
        ///
        OptionUnsupported,
    } || Io.UnexpectedError || Io.Cancelable;

    pub const ListenOptions = struct {
        /// 内核代表应用程序接受的连接数量。
        /// 若内核中积压的连接超过此数量,客户端将开始
        /// 收到“Connection refused”。
        kernel_backlog: u31 = default_kernel_backlog,
        /// 在 POSIX 上设置 SO_REUSEADDR 和 SO_REUSEPORT。
        /// 在 Windows 上设置大致等价的 SO_REUSEADDR。
        reuse_address: bool = false,
        /// 此处只能使用面向连接的模式,包括:
        /// * `Socket.Mode.stream`
        /// * `Socket.Mode.seqpacket`
        mode: Socket.Mode = .stream,
        /// 此处仅可使用面向连接的协议,包括:
        /// * `Protocol.tcp`
        /// * `Protocol.tp`
        /// * `Protocol.dccp`
        /// * `Protocol.sctp`
        protocol: Protocol = .tcp,
    };

    /// 等待 TCP 连接。使用此 API 时无需调用 `bind`。返回的 `Server` 具有打开的 `stream`。
    ///
    pub fn listen(address: *const IpAddress, io: Io, options: ListenOptions) ListenError!Server {
        return .{
            .socket = try io.vtable.netListenIp(io.userdata, address, options),
            .options = if (Server.AcceptOptions != void) .{
                .mode = options.mode,
                .protocol = options.protocol,
            },
        };
    }

    pub const BindError = error{
        /// 该地址受到保护,当前用户没有绑定它的权限。
        AccessDenied,
        /// 地址已被占用。当绑定端口为 0,
        /// 但所有临时端口均已使用时,可能发生此情况。
        AddressInUse,
        /// 请求了不存在的接口,或请求的地址不是本地地址。
        AddressUnavailable,
        /// 该地址对于套接字的地址族无效。
        AddressFamilyUnsupported,
        /// 操作系统内部内存或其他资源不足。
        SystemResources,
        /// 用于到达目标的本地网络接口已离线。
        NetworkDown,
        ProtocolUnsupportedBySystem,
        ProtocolUnsupportedByAddressFamily,
        /// 已达到每进程可打开文件描述符数量上限。
        ProcessFdQuotaExceeded,
        /// 已达到系统范围内已打开文件的总数上限。
        SystemFdQuotaExceeded,
        SocketModeUnsupported,
        /// Io 实现不支持某个 `BindOptions`。
        ///
        OptionUnsupported,
    } || Io.UnexpectedError || Io.Cancelable;

    pub const BindOptions = struct {
        /// 套接字仅限发送和接收 IPv6 数据包。
        /// 此时 IPv4 应用和 IPv6 应用可以
        /// 同时绑定同一端口。
        ///
        /// 默认值由系统配置决定。
        ip6_only: ?bool = null,
        /// 允许套接字向广播地址发送数据报。
        /// 未启用时,任何向广播地址发送数据报的尝试
        /// 都会以 `error.AccessDenied` 失败。
        allow_broadcast: bool = false,
        mode: Socket.Mode,
        protocol: ?Protocol = null,
    };

    /// 将地址与 `Socket` 关联,用于接收 UDP 数据包
    /// 及其他非流式消息。流式替代方案参见 `listen`。
    ///
    ///
    /// 一个已绑定的 `Socket` 可以接收来自多个
    /// 不同地址的消息。
    pub fn bind(address: *const IpAddress, io: Io, options: BindOptions) BindError!Socket {
        return io.vtable.netBindIp(io.userdata, address, options);
    }

    pub const ConnectError = error{
        AddressUnavailable,
        AddressFamilyUnsupported,
        /// 操作系统内部内存或其他资源不足。
        SystemResources,
        ConnectionPending,
        ConnectionRefused,
        ConnectionResetByPeer,
        HostUnreachable,
        NetworkUnreachable,
        Timeout,
        /// Io 实现不支持某个
        /// `ConnectOptions` 选项。
        OptionUnsupported,
        /// 已达到每进程可打开文件描述符数量上限。
        ProcessFdQuotaExceeded,
        /// 已达到系统范围内已打开文件的总数上限。
        SystemFdQuotaExceeded,
        ProtocolUnsupportedBySystem,
        ProtocolUnsupportedByAddressFamily,
        SocketModeUnsupported,
        /// 用户尝试连接广播地址,但未启用套接字广播标志;或
        /// 连接请求因本地防火墙规则而失败。
        AccessDenied,
        /// 已请求非阻塞模式,但该操作无法立即返回。
        WouldBlock,
        NetworkDown,
    } || Io.Timeout.Error || Io.UnexpectedError || Io.Cancelable;

    pub const ConnectOptions = struct {
        mode: Socket.Mode,
        protocol: ?Protocol = null,
        timeout: Io.Timeout = .none,
    };

    /// 发起面向连接的网络流。
    pub fn connect(address: *const IpAddress, io: Io, options: ConnectOptions) ConnectError!Stream {
        return .{ .socket = try io.vtable.netConnectIp(io.userdata, address, options) };
    }
};

/// 二进制内存布局的 IPv4 地址。
pub const Ip4Address = struct {
    bytes: [4]u8,
    port: u16,

    pub fn loopback(port: u16) Ip4Address {
        return .{
            .bytes = .{ 127, 0, 0, 1 },
            .port = port,
        };
    }

    pub fn unspecified(port: u16) Ip4Address {
        return .{
            .bytes = .{ 0, 0, 0, 0 },
            .port = port,
        };
    }

    /// 从 IPv4 映射的 IPv6 地址转换,或返回 `null`。
    pub fn fromIp6(ip6: Ip6Address) ?Ip4Address {
        return if (std.mem.eql(u8, ip6.bytes[0..12], &.{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff })) .{
            .bytes = ip6.bytes[12..].*,
            .port = ip6.port,
        } else null;
    }

    /// 给定 `IpAddress`,将其直接转换为 `Ip4Address`,或从
    /// IPv4 映射的 IPv6 地址转换;无法转换则返回 `null`。
    pub fn fromAny(addr: IpAddress) ?Ip4Address {
        return switch (addr) {
            .ip4 => |ip4| ip4,
            .ip6 => |ip6| fromIp6(ip6),
        };
    }

    pub const ParseError = error{
        Overflow,
        InvalidEnd,
        InvalidCharacter,
        Incomplete,
        NonCanonical,
    };

    pub fn parse(buffer: []const u8, port: u16) ParseError!Ip4Address {
        var bytes: [4]u8 = @splat(0);
        var index: u8 = 0;
        var saw_any_digits = false;
        var has_zero_prefix = false;
        for (buffer) |c| switch (c) {
            '.' => {
                if (!saw_any_digits) return error.InvalidCharacter;
                if (index == 3) return error.InvalidEnd;
                index += 1;
                saw_any_digits = false;
                has_zero_prefix = false;
            },
            '0'...'9' => {
                if (c == '0' and !saw_any_digits) {
                    has_zero_prefix = true;
                } else if (has_zero_prefix) {
                    return error.NonCanonical;
                }
                saw_any_digits = true;
                bytes[index] = try std.math.mul(u8, bytes[index], 10);
                bytes[index] = try std.math.add(u8, bytes[index], c - '0');
            },
            else => return error.InvalidCharacter,
        };
        if (index == 3 and saw_any_digits) return .{
            .bytes = bytes,
            .port = port,
        };
        return error.Incomplete;
    }

    pub fn format(a: Ip4Address, w: *Io.Writer) Io.Writer.Error!void {
        const bytes = &a.bytes;
        try w.print("{d}.{d}.{d}.{d}:{d}", .{ bytes[0], bytes[1], bytes[2], bytes[3], a.port });
    }

    pub fn eql(a: Ip4Address, b: Ip4Address) bool {
        const a_int: u32 = @bitCast(a.bytes);
        const b_int: u32 = @bitCast(b.bytes);
        return a.port == b.port and a_int == b_int;
    }
};

/// 使用二进制内存布局的 IPv6 地址。
pub const Ip6Address = struct {
    /// 本机字节序
    port: u16,
    /// 大端序
    bytes: [16]u8,
    flow: u32 = 0,
    interface: Interface = .none,

    pub const Policy = struct {
        addr: [16]u8,
        len: u8,
        mask: u8,
        prec: u8,
        label: u8,
    };

    pub fn loopback(port: u16) Ip6Address {
        return .{
            .bytes = .{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1 },
            .port = port,
        };
    }

    pub fn unspecified(port: u16) Ip6Address {
        return .{
            .bytes = .{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
            .port = port,
        };
    }

    /// 构造 IPv4 映射的 IPv6 地址。
    pub fn fromIp4(ip4: Ip4Address) Ip6Address {
        return .{
            .bytes = .{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff } ++ ip4.bytes,
            .port = ip4.port,
        };
    }

    /// 给定 `IpAddress`,将其直接转换为 `Ip6Address`,或通过
    /// 构造 IPv4 映射的 IPv6 地址来完成转换。
    pub fn fromAny(addr: IpAddress) Ip6Address {
        return switch (addr) {
            .ip4 => |ip4| fromIp4(ip4),
            .ip6 => |ip6| ip6,
        };
    }

    /// IPv6 地址,但 `Interface` 使用名称而非索引。
    pub const Unresolved = struct {
        /// 大端序
        bytes: [16]u8,
        /// 尚未检查它是否为有效的原生接口名称。
        /// 内存由外部管理。
        interface_name: ?[]const u8,

        pub const Parsed = union(enum) {
            success: Unresolved,
            invalid_byte: usize,
            incomplete,
            junk_after_end: usize,
            interface_name_oversized: usize,
            invalid_ip4_mapping: usize,
            overflow: usize,
        };

        pub fn parse(text_in: []const u8) Parsed {
            var text: []const u8 = text_in; // 以便在需要时复用 v4_amended
            if (text.len < 2) return .incomplete;

            // 预处理末尾的 :IPv4:如果没有 "%iface",且最后一个冒号之后的部分包含 ".",
            // 则将其按 ipv4 解析,并在 v4_amended 中转换为 IPv6 ASCII 文本,
            // 作为新的 "text"
            var v4_amended: [(8 * 4) + 7]u8 = undefined;
            if (std.mem.findScalar(u8, text, '%') == null) {
                const first_parts, const last_part = std.mem.cutScalarLast(u8, text, ':') orelse
                    return .incomplete;
                if (std.mem.findScalar(u8, last_part, '.')) |_| {
                    if (first_parts.len > (6 * 4) + 5) // hhhh:hhhh:hhhh:hhhh:hhhh:hhhh
                        return .{ .invalid_ip4_mapping = first_parts.len };
                    const parsed = Ip4Address.parse(last_part, 0) catch
                        return .{ .invalid_ip4_mapping = first_parts.len + 1 };
                    @memcpy(v4_amended[0..first_parts.len], first_parts);
                    const v4_part = v4_amended[first_parts.len..][0..10];
                    v4_part[0] = ':';
                    @memcpy(v4_part[1..3], &std.fmt.hex(parsed.bytes[0]));
                    @memcpy(v4_part[3..5], &std.fmt.hex(parsed.bytes[1]));
                    v4_part[5] = ':';
                    @memcpy(v4_part[6..8], &std.fmt.hex(parsed.bytes[2]));
                    @memcpy(v4_part[8..10], &std.fmt.hex(parsed.bytes[3]));
                    text = v4_amended[0 .. first_parts.len + 10];
                }
            }

            // 必须使用 u16 元素,以处理压缩产生的三位十六进制数。
            var parts: [8]u16 = @splat(0);
            var parts_i: u8 = 0;
            var text_i: u8 = 0;
            var digit_i: u8 = 0;
            var compress_start: ?u8 = null;
            var interface_name_text: ?[]const u8 = null;
            const State = union(enum) { digit, end };
            state: switch (State.digit) {
                .digit => c: switch (text[text_i]) {
                    'a'...'f' => |c| {
                        const digit = c - 'a' + 10;
                        parts[parts_i] = (std.math.mul(u16, parts[parts_i], 16) catch return .{
                            .overflow = text_i,
                        }) + digit;
                        if (digit_i == 4) return .{ .invalid_byte = text_i };
                        digit_i += 1;
                        text_i += 1;
                        if (text.len - text_i == 0) {
                            parts_i += 1;
                            continue :state .end;
                        }
                        continue :c text[text_i];
                    },
                    'A'...'F' => |c| continue :c c - 'A' + 'a',
                    '0'...'9' => |c| {
                        const digit = c - '0';
                        parts[parts_i] = (std.math.mul(u16, parts[parts_i], 16) catch return .{
                            .overflow = text_i,
                        }) + digit;
                        if (digit_i == 4) return .{ .invalid_byte = text_i };
                        digit_i += 1;
                        text_i += 1;
                        if (text.len - text_i == 0) {
                            parts_i += 1;
                            continue :state .end;
                        }
                        continue :c text[text_i];
                    },
                    ':' => {
                        if (digit_i == 0) {
                            if (compress_start != null) return .{ .invalid_byte = text_i };
                            if (text_i == 0) {
                                text_i += 1;
                                if (text[text_i] != ':') return .{ .invalid_byte = text_i };
                                assert(parts_i == 0);
                            }
                            compress_start = parts_i;
                            text_i += 1;
                            if (text.len - text_i == 0) continue :state .end;
                            continue :c text[text_i];
                        } else {
                            parts_i += 1;
                            if (parts.len - parts_i == 0) continue :state .end;
                            digit_i = 0;
                            text_i += 1;
                            if (text.len - text_i == 0) return .incomplete;
                            continue :c text[text_i];
                        }
                    },
                    '%' => {
                        if (digit_i == 0) return .{ .invalid_byte = text_i };
                        parts_i += 1;
                        text_i += 1;
                        const name = text[text_i..];
                        if (name.len == 0) return .incomplete;
                        interface_name_text = name;
                        text_i = std.math.cast(u8, text.len) orelse return .{ .overflow = text.len };
                        continue :state .end;
                    },
                    else => return .{ .invalid_byte = text_i },
                },
                .end => {
                    if (text.len - text_i != 0) return .{ .junk_after_end = text_i };
                    const remaining = parts.len - parts_i;
                    if (compress_start) |s| {
                        const src = parts[s..parts_i];
                        @memmove(parts[parts.len - src.len ..], src);
                        @memset(parts[s..][0..remaining], 0);
                    } else {
                        if (remaining != 0) return .incomplete;
                    }

                    for (&parts) |*part| part.* = @byteSwap(part.*);

                    return .{ .success = .{
                        .bytes = @bitCast(parts),
                        .interface_name = interface_name_text,
                    } };
                },
            }
        }

        pub fn format(u: *const Unresolved, w: *Io.Writer) Io.Writer.Error!void {
            const bytes = &u.bytes;
            if (std.mem.eql(u8, bytes[0..12], &[_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff }))
                return w.print("::ffff:{d}.{d}.{d}.{d}", .{ bytes[12], bytes[13], bytes[14], bytes[15] });
            if (std.mem.eql(u8, bytes[0..12], &[_]u8{ 0, 0x64, 0xff, 0x9b, 0, 0, 0, 0, 0, 0, 0, 0 }))
                return w.print("64:ff9b::{d}.{d}.{d}.{d}", .{ bytes[12], bytes[13], bytes[14], bytes[15] });

            const parts: [8]u16 = .{
                std.mem.readInt(u16, bytes[0..2], .big),
                std.mem.readInt(u16, bytes[2..4], .big),
                std.mem.readInt(u16, bytes[4..6], .big),
                std.mem.readInt(u16, bytes[6..8], .big),
                std.mem.readInt(u16, bytes[8..10], .big),
                std.mem.readInt(u16, bytes[10..12], .big),
                std.mem.readInt(u16, bytes[12..14], .big),
                std.mem.readInt(u16, bytes[14..16], .big),
            };

            // 查找最长的连续零序列
            var longest_start: usize = 8;
            var longest_len: usize = 0;
            var current_start: usize = 0;
            var current_len: usize = 0;

            for (parts, 0..) |part, i| {
                if (part == 0) {
                    if (current_len == 0) {
                        current_start = i;
                    }
                    current_len += 1;
                    if (current_len > longest_len) {
                        longest_start = current_start;
                        longest_len = current_len;
                    }
                } else {
                    current_len = 0;
                }
            }

            // 仅当最长连续零段长度至少为 2 时才压缩
            if (longest_len < 2) {
                longest_start = 8;
                longest_len = 0;
            }

            var i: usize = 0;
            while (parts.len - i != 0) : (i += 1) {
                if (i == longest_start) {
                    // 为最长的连续零值输出 "::"
                    try w.writeAll(if (i == 0) "::" else ":");
                    i += longest_len - 1; // 跳过压缩范围
                    continue;
                }
                try w.print("{x}", .{parts[i]});
                if (i != parts.len - 1) {
                    try w.writeAll(":");
                }
            }
            if (u.interface_name) |n| try w.print("%{s}", .{n});
        }
    };

    pub const ParseError = error{
        /// 返回此错误时,可通过调用 `Ip6Address.Parsed.init`
        /// 获得更详细的诊断信息。
        ParseFailed,
        /// 返回此错误表示 IPv6 地址带有作用域标识,
        /// 即末尾的“%foo”,需要调用 `resolve`。
        UnresolvedScope,
    };

    /// 这是纯函数,但无法处理带作用域 ID(末尾的“%foo”)的
    /// IPv6 地址。要处理这些地址,应改为调用 `resolve`,
    /// 也可使用较底层的 `Unresolved` 接口。
    pub fn parse(buffer: []const u8, port: u16) ParseError!Ip6Address {
        switch (Unresolved.parse(buffer)) {
            .success => |p| return .{
                .bytes = p.bytes,
                .port = port,
                .interface = if (p.interface_name != null) return error.UnresolvedScope else .none,
            },
            else => return error.ParseFailed,
        }
        return .{ .ip6 = try Ip6Address.parse(buffer, port) };
    }

    pub const ResolveError = error{
        /// 如果返回此错误,可调用 `Parsed.init` 函数
        /// 获取更详细的诊断信息。
        ParseFailed,
        /// 接口名称长度超过宿主操作系统支持的范围。
        NameTooLong,
    } || Interface.Name.ResolveError;

    /// 此函数需要 `Io` 参数,因为它必须查询操作系统,
    /// 将接口名转换为索引。例如,在
    /// “fe80::e0e:76ff:fed4:cf22%eno1”中,必须创建套接字,
    /// 再使用 `ioctl` 系统调用将“eno1”解析为索引。
    pub fn resolve(io: Io, buffer: []const u8, port: u16) ResolveError!Ip6Address {
        return switch (Unresolved.parse(buffer)) {
            .success => |p| return .{
                .bytes = p.bytes,
                .port = port,
                .interface = i: {
                    const text = p.interface_name orelse break :i .none;
                    const name: Interface.Name = try .fromSlice(text);
                    break :i try name.resolve(io);
                },
            },
            else => return error.ParseFailed,
        };
    }

    pub const FormatError = Io.Writer.Error || Interface.NameError;

    /// 包含可选的作用域(末尾的 "%foo")。
    ///
    /// 另见 `format`,它省略作用域,且
    /// 不需要 `Io` 参数。
    pub fn formatResolved(a: *const Ip6Address, io: Io, w: *Io.Writer) FormatError!void {
        const interface_name = if (a.interface.isNone()) null else try a.interface.name(io);
        const u: Unresolved = .{
            .bytes = a.bytes,
            .interface_name = if (interface_name) |name| name.toSlice() else null,
        };
        try w.print("[{f}]:{d}", .{ u, a.port });
    }

    /// 另见 `formatResolved`:它还会在地址末尾打印可选作用域,并且需要 `Io` 参数。
    ///
    pub fn format(a: *const Ip6Address, w: *Io.Writer) Io.Writer.Error!void {
        const u: Unresolved = .{ .bytes = a.bytes, .interface_name = null };
        try w.print("[{f}]:{d}", .{ u, a.port });
    }

    pub fn eql(a: Ip6Address, b: Ip6Address) bool {
        return a.port == b.port and std.mem.eql(u8, &a.bytes, &b.bytes);
    }

    pub fn isMultiCast(a: Ip6Address) bool {
        return a.bytes[0] == 0xff;
    }

    pub fn isLinkLocal(a: Ip6Address) bool {
        const b = &a.bytes;
        return b[0] == 0xfe and (b[1] & 0xc0) == 0x80;
    }

    pub fn isLoopBack(a: Ip6Address) bool {
        const b = &a.bytes;
        return b[0] == 0 and b[1] == 0 and
            b[2] == 0 and
            b[12] == 0 and b[13] == 0 and
            b[14] == 0 and b[15] == 1;
    }

    pub fn isSiteLocal(a: Ip6Address) bool {
        const b = &a.bytes;
        return b[0] == 0xfe and (b[1] & 0xc0) == 0xc0;
    }

    pub fn policy(a: Ip6Address) *const Policy {
        const b = &a.bytes;
        for (&defined_policies) |*p| {
            if (!std.mem.eql(u8, b[0..p.len], p.addr[0..p.len])) continue;
            if ((b[p.len] & p.mask) != p.addr[p.len]) continue;
            return p;
        }
        unreachable;
    }

    pub fn scope(a: Ip6Address) u8 {
        if (isMultiCast(a)) return a.bytes[1] & 15;
        if (isLinkLocal(a)) return 2;
        if (isLoopBack(a)) return 2;
        if (isSiteLocal(a)) return 5;
        return 14;
    }

    const defined_policies = [_]Policy{
        .{
            .addr = "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01".*,
            .len = 15,
            .mask = 0xff,
            .prec = 50,
            .label = 0,
        },
        .{
            .addr = "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\x00\x00\x00\x00".*,
            .len = 11,
            .mask = 0xff,
            .prec = 35,
            .label = 4,
        },
        .{
            .addr = "\x20\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00".*,
            .len = 1,
            .mask = 0xff,
            .prec = 30,
            .label = 2,
        },
        .{
            .addr = "\x20\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00".*,
            .len = 3,
            .mask = 0xff,
            .prec = 5,
            .label = 5,
        },
        .{
            .addr = "\xfc\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00".*,
            .len = 0,
            .mask = 0xfe,
            .prec = 3,
            .label = 13,
        },
        //  这些地址已弃用和/或归还地址池,
        //  因而尽管 RFC 如此规定,将它们视为特殊地址
        //  可能并不正确。
        // { "", 11, 0xff, 1, 3 },
        // { "\xfe\xc0", 1, 0xc0, 1, 11 },
        // { "\x3f\xfe", 1, 0xff, 1, 12 },
        // 最后一条规则必须匹配所有地址,才能终止循环。
        .{
            .addr = "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00".*,
            .len = 0,
            .mask = 0,
            .prec = 40,
            .label = 1,
        },
    };
};

pub const UnixAddress = struct {
    path: []const u8,

    pub const max_len = switch (native_os) {
        .windows => std.os.windows.PATH_MAX_WIDE,
        else => 108,
    };

    pub const InitError = error{NameTooLong};

    pub fn init(p: []const u8) InitError!UnixAddress {
        if (p.len > max_len) return error.NameTooLong;
        return .{ .path = p };
    }

    pub fn isAbstract(ua: *const UnixAddress) bool {
        return ua.path.len == 0 or ua.path[0] == 0;
    }

    pub const ListenError = error{
        AddressFamilyUnsupported,
        AddressInUse,
        NetworkDown,
        SystemResources,
        SymLinkLoop,
        FileNotFound,
        NotDir,
        ReadOnlyFileSystem,
        ProcessFdQuotaExceeded,
        SystemFdQuotaExceeded,
        AccessDenied,
        PermissionDenied,
        AddressUnavailable,
    } || Io.Cancelable || Io.UnexpectedError;

    pub const ListenOptions = struct {
        /// 内核代表应用程序接受的连接数量。
        /// 若内核中积压的连接超过此数量,客户端将开始
        /// 收到“Connection refused”。
        kernel_backlog: u31 = default_kernel_backlog,
    };

    pub fn listen(ua: *const UnixAddress, io: Io, options: ListenOptions) ListenError!Server {
        assert(ua.path.len <= max_len);
        return .{
            .socket = .{
                .handle = try io.vtable.netListenUnix(io.userdata, ua, options),
                .address = .{ .ip4 = .loopback(0) },
            },
            .options = if (Server.AcceptOptions != void) .{ .mode = .stream, .protocol = null },
        };
    }

    pub const ConnectError = error{
        SystemResources,
        ProcessFdQuotaExceeded,
        SystemFdQuotaExceeded,
        AddressFamilyUnsupported,
        ProtocolUnsupportedBySystem,
        SocketModeUnsupported,
        AccessDenied,
        PermissionDenied,
        SymLinkLoop,
        FileNotFound,
        NotDir,
        ReadOnlyFileSystem,
        WouldBlock,
        NetworkDown,
        ConnectionRefused,
    } || Io.Cancelable || Io.UnexpectedError;

    pub fn connect(ua: *const UnixAddress, io: Io) ConnectError!Stream {
        assert(ua.path.len <= max_len);
        return .{ .socket = .{
            .handle = try io.vtable.netConnectUnix(io.userdata, ua),
            .address = .{ .ip4 = .loopback(0) },
        } };
    }
};

pub const ReceiveFlags = packed struct(u8) {
    oob: bool = false,
    peek: bool = false,
    trunc: bool = false,
    _: u5 = 0,
};

pub const IncomingMessage = struct {
    /// 由接收函数填充。
    from: IpAddress,
    /// 由接收函数填充,指向调用方提供的缓冲区。
    data: []u8,
    /// 由调用方在调用接收函数之前提供;
    /// 由接收函数修改。
    control: []u8,
    /// 由接收函数填充。
    flags: Flags,

    /// 适合在调用 `receiveManyTimeout` 之前初始化。
    pub const init: IncomingMessage = .{
        .from = undefined,
        .data = undefined,
        .control = &.{},
        .flags = undefined,
    };

    pub const Flags = packed struct(u8) {
        /// 表示记录结束;返回的数据补全了一条记录
        /// (通常用于 SOCK_SEQPACKET 类型的套接字)。
        eor: bool,
        /// 表示数据报大于提供的缓冲区,因此丢弃了数据报尾部。
        ///
        trunc: bool,
        /// 表示由于辅助数据缓冲区
        /// 空间不足,部分控制数据被丢弃。
        ctrunc: bool,
        /// 表示收到了加急或带外数据。
        oob: bool,
        /// 表示未收到数据,但从套接字错误队列中
        /// 收到了扩展错误。
        errqueue: bool,
        _: u3 = 0,
    };
};

pub const OutgoingMessage = struct {
    address: *const IpAddress,
    data_ptr: [*]const u8,
    /// 初始化为要从 `data_ptr` 发送的字节数。发送成功后,
    /// 替换为实际发送的字节数。
    data_len: usize,
    control: []const u8 = &.{},
};

pub const SendFlags = packed struct(u8) {
    confirm: bool = false,
    dont_route: bool = false,
    eor: bool = false,
    oob: bool = false,
    fastopen: bool = false,
    _: u3 = 0,
};

pub const ShutdownHow = enum { recv, send, both };

pub const ShutdownError = error{
    ConnectionAborted,
    ConnectionResetByPeer,
    NetworkDown,
    SocketUnconnected,
    SystemResources,
} || Io.UnexpectedError || Io.Cancelable;

pub const Interface = struct {
    /// 值 0 表示 `none`。
    index: u32,

    pub const none: Interface = .{ .index = 0 };

    pub const Name = struct {
        bytes: [max_len:0]u8,

        pub const max_len = if (@TypeOf(std.posix.IFNAMESIZE) == void) 0 else std.posix.IFNAMESIZE - 1;

        pub fn toSlice(n: *const Name) []const u8 {
            return std.mem.sliceTo(&n.bytes, 0);
        }

        pub fn fromSlice(bytes: []const u8) error{NameTooLong}!Name {
            if (bytes.len > max_len) return error.NameTooLong;
            return .fromSliceUnchecked(bytes);
        }

        /// 断言 bytes.len 不超过 `max_len`。
        pub fn fromSliceUnchecked(bytes: []const u8) Name {
            assert(bytes.len <= max_len);
            var result: Name = undefined;
            @memcpy(result.bytes[0..bytes.len], bytes);
            result.bytes[bytes.len] = 0;
            return result;
        }

        pub const ResolveError = error{
            InterfaceNotFound,
            AccessDenied,
            SystemResources,
        } || Io.UnexpectedError || Io.Cancelable;

        /// 对应 libc 中的 "if_nametoindex"。
        pub fn resolve(n: *const Name, io: Io) ResolveError!Interface {
            return io.vtable.netInterfaceNameResolve(io.userdata, n);
        }
    };

    pub const NameError = error{
        /// `index` 超出范围。
        InterfaceNotFound,
        /// 接口名称长于 `Name.max_len`。
        NameTooLong,
    } || Io.UnexpectedError || Io.Cancelable;

    /// 断言不为 `none`。
    ///
    /// 对应 libc 中的 "if_indextoname"。
    pub fn name(i: Interface, io: Io) NameError!Name {
        assert(i.index != 0);
        return io.vtable.netInterfaceName(io.userdata, i);
    }

    pub fn isNone(i: Interface) bool {
        return i.index == 0;
    }
};

/// 未指定协议的开放端口。
pub const Socket = struct {
    handle: Handle,
    /// 若请求此信息,则包含解析得到的临时端口号。
    address: IpAddress,

    pub const Mode = enum {
        /// 提供有序、可靠、双向、基于连接的字节流。
        /// 可能支持带外数据传输机制。
        ///
        stream,
        /// 支持数据报(无连接、不可靠,
        /// 且最大长度固定的消息)。
        dgram,
        /// 为具有固定最大长度的数据报提供有序、可靠、
        /// 双向、面向连接的数据传输通道;要求消费者
        /// 每次输入系统调用都读取一个完整数据包。
        seqpacket,
        /// 提供对原始网络协议的访问。
        raw,
        /// 提供不保证顺序的可靠数据报层。
        rdm,
    };

    /// 由底层平台定义的类型,可能可以,也可能不可以
    /// 与文件系统文件描述符互换。
    pub const Handle = std.posix.fd_t;

    /// 使 `address` 保持有效状态。
    pub fn close(s: *const Socket, io: Io) void {
        io.vtable.netClose(io.userdata, s[0..1]);
    }

    pub fn closeMany(io: Io, sockets: []const Socket) void {
        io.vtable.netClose(io.userdata, sockets);
    }

    pub const SendError = Io.Operation.NetSend.Error || Io.Cancelable;

    /// 以无连接方式,在单个数据包中将 `data` 传给 `dest`。
    pub fn send(s: *const Socket, io: Io, dest: *const IpAddress, data: []const u8) SendError!void {
        var message: OutgoingMessage = .{ .address = dest, .data_ptr = data.ptr, .data_len = data.len };
        const maybe_err, const count = (try io.operate(.{ .net_send = .{
            .socket_handle = s.handle,
            .messages = (&message)[0..1],
            .flags = .{},
        } })).net_send;
        if (maybe_err) |err| {
            assert(count == 0);
            return err;
        } else {
            assert(count == 1);
        }
        if (message.data_len != data.len) return error.MessageOversize;
    }

    pub const SendTimeoutError = SendError || Io.Timeout.Error || Io.ConcurrentError;

    pub fn sendTimeout(
        s: *const Socket,
        io: Io,
        dest: *const IpAddress,
        data: []const u8,
        timeout: Io.Timeout,
    ) SendTimeoutError!void {
        var message: OutgoingMessage = .{ .address = dest, .data_ptr = data.ptr, .data_len = data.len };
        const maybe_err, const count = (try io.operateTimeout(.{ .net_send = .{
            .socket_handle = s.handle,
            .messages = (&message)[0..1],
            .flags = .{},
        } }, timeout)).net_send;
        if (maybe_err) |err| return err;
        assert(1 == count);
        if (message.data_len != data.len) return error.MessageOversize;
    }

    /// 已弃用;请使用超时为 `.none` 的 `sendManyTimeout`。
    ///
    /// 若此函数返回错误,`messages` 中的部分消息
    /// 仍可能已经发送,但不会全部发送。此函数不报告该情况,
    /// 而 `sendManyTimeout` 会报告。
    pub fn sendMany(s: *const Socket, io: Io, messages: []OutgoingMessage, flags: SendFlags) SendError!void {
        const result = try io.operate(.{ .net_send = .{
            .socket_handle = s.handle,
            .messages = messages,
            .flags = flags,
        } });
        const maybe_send_err, _ = result.net_send;
        return maybe_send_err orelse {};
    }

    pub fn sendManyTimeout(
        s: *const Socket,
        io: Io,
        messages: []OutgoingMessage,
        flags: SendFlags,
        timeout: Io.Timeout,
    ) struct { ?SendTimeoutError, usize } {
        const result = io.operateTimeout(.{ .net_send = .{
            .socket_handle = s.handle,
            .messages = messages,
            .flags = flags,
        } }, timeout) catch |err| return .{ err, 0 };
        return result.net_send;
    }

    pub const ReceiveError = Io.Operation.NetReceive.Error || Io.Cancelable;

    /// 等待数据。无连接。
    ///
    /// 另请参见:
    /// * `receiveTimeout`
    pub fn receive(s: *const Socket, io: Io, buffer: []u8) ReceiveError!IncomingMessage {
        var message: IncomingMessage = .init;
        const maybe_err, const count = (try io.operate(.{ .net_receive = .{
            .socket_handle = s.handle,
            .message_buffer = (&message)[0..1],
            .data_buffer = buffer,
            .flags = .{},
        } })).net_receive;
        if (maybe_err) |err| return err;
        assert(1 == count);
        return message;
    }

    pub const ReceiveTimeoutError = ReceiveError || Io.Timeout.Error || Io.ConcurrentError;

    /// 等待数据。无连接。
    ///
    /// 若没有消息及时到达,则返回 `error.Timeout`。
    ///
    /// 另见:
    /// * `receive`
    /// * `receiveManyTimeout`
    pub fn receiveTimeout(
        s: *const Socket,
        io: Io,
        buffer: []u8,
        timeout: Io.Timeout,
    ) ReceiveTimeoutError!IncomingMessage {
        var message: IncomingMessage = .init;
        const maybe_err, const count = (try io.operateTimeout(.{ .net_receive = .{
            .socket_handle = s.handle,
            .message_buffer = (&message)[0..1],
            .data_buffer = buffer,
            .flags = .{},
        } }, timeout)).net_receive;
        if (maybe_err) |err| return err;
        assert(1 == count);
        return message;
    }

    /// 等待至少一条消息到达,也可能返回
    /// 多条消息。无需连接。
    ///
    /// 返回收到的消息数;若消息未及时到达,
    /// 则返回 `error.Timeout`。
    ///
    /// 另见:
    /// * `receive`
    /// * `receiveTimeout`
    pub fn receiveManyTimeout(
        s: *const Socket,
        io: Io,
        /// 此函数假定每个元素的 `control` 字段已初始化。
        /// 使用 `IncomingMessage.init` 初始化可能有帮助。
        message_buffer: []IncomingMessage,
        data_buffer: []u8,
        flags: ReceiveFlags,
        timeout: Io.Timeout,
    ) struct { ?ReceiveTimeoutError, usize } {
        const result = io.operateTimeout(.{ .net_receive = .{
            .socket_handle = s.handle,
            .message_buffer = message_buffer,
            .data_buffer = data_buffer,
            .flags = flags,
        } }, timeout) catch |err| return .{ err, 0 };
        return result.net_receive;
    }

    pub const CreatePairError = error{
        OperationUnsupported,
        AccessDenied,
        AddressFamilyUnsupported,
        ProtocolUnsupportedBySystem,
        /// 已达到每个进程可打开的文件描述符数量限制。
        ProcessFdQuotaExceeded,
        /// 已达到系统范围内打开文件总数的上限。
        SystemFdQuotaExceeded,
        /// 可用内存不足。在释放足够资源前,
        /// 无法创建套接字。
        SystemResources,
        ProtocolUnsupportedByAddressFamily,
        SocketModeUnsupported,
    } || Io.UnexpectedError || Io.Cancelable;

    pub const CreatePairOptions = struct {
        family: IpAddress.Family = .ip4,
        mode: Mode = .stream,
        protocol: ?Protocol = null,
    };

    /// 创建一对彼此连接的套接字。
    ///
    /// 也称为 "socketpair"。
    pub fn createPair(io: Io, options: CreatePairOptions) CreatePairError![2]Socket {
        return io.vtable.netSocketCreatePair(io.userdata, options);
    }
};

/// 已打开的套接字连接,其网络协议保证
/// 顺序、交付并防止重复。通常为 TCP 或 UNIX 域
/// 套接字。
pub const Stream = struct {
    socket: Socket,

    const max_iovecs_len = 8;

    pub const ReadResult = struct {
        data_len: usize,
        control_len: usize = 0,
        /// 是否仅收到部分控制数据。
        ///
        /// 控制数据被截断时,额外数据实际上
        /// 会直接丢失。这表明存在设计问题,
        /// 例如控制缓冲区过小。
        control_truncated: bool = false,
    };

    /// 这是直接调用 `Io` 接口函数的底层 API。
    /// 更高层 API 参见 `reader`。
    pub fn read(s: *const Stream, io: Io, data: [][]u8) Reader.Error!usize {
        return (try (try io.operate(.{ .net_read = .{
            .socket_handle = s.socket.handle,
            .data = data,
        } })).net_read).data_len;
    }

    /// 连同控制数据一起读取。
    ///
    /// 这是直接调用 `Io` 接口函数的底层 API。
    /// 更高层 API 参见 `reader`。
    pub fn readWithControl(s: *const Stream, io: Io, data: [][]u8, control: []u8) Reader.Error!ReadResult {
        return try (try io.operate(.{ .net_read = .{
            .socket_handle = s.socket.handle,
            .data = data,
            .control = control,
        } })).net_read;
    }

    pub fn close(s: *const Stream, io: Io) void {
        io.vtable.netClose(io.userdata, (&s.socket)[0..1]);
    }

    pub fn shutdown(s: *const Stream, io: Io, how: ShutdownHow) ShutdownError!void {
        return io.vtable.netShutdown(io.userdata, s.socket.handle, how);
    }

    pub const Reader = struct {
        io: Io,
        interface: Io.Reader,
        control_buffer: []align(cmsg_align) u8,
        control_len: usize,
        control_truncated: bool,
        stream: Stream,
        err: ?Error,

        pub const Error = Io.Operation.NetRead.Error || Io.Cancelable;

        pub fn init(stream: Stream, io: Io, buffer: []u8) Reader {
            return initWithControl(stream, io, buffer, &.{});
        }

        /// 与 `init` 相同,但还提供用于存储控制数据的缓冲区。
        pub fn initWithControl(
            stream: Stream,
            io: Io,
            buffer: []u8,
            control_buffer: []align(cmsg_align) u8,
        ) Reader {
            return .{
                .io = io,
                .interface = .{
                    .vtable = &.{
                        .stream = streamImpl,
                        .readVec = readVec,
                    },
                    .buffer = buffer,
                    .seek = 0,
                    .end = 0,
                },
                .control_buffer = control_buffer,
                .control_len = 0,
                .control_truncated = false,
                .stream = stream,
                .err = null,
            };
        }

        fn streamImpl(io_r: *Io.Reader, io_w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize {
            const dest = limit.slice(try io_w.writableSliceGreedy(1));
            var data: [1][]u8 = .{dest};
            const n = try readVec(io_r, &data);
            io_w.advance(n);
            return n;
        }

        fn readVec(io_r: *Io.Reader, data: [][]u8) Io.Reader.Error!usize {
            const r: *Reader = @alignCast(@fieldParentPtr("interface", io_r));
            const io = r.io;
            var iovecs_buffer: [max_iovecs_len][]u8 = undefined;
            const dest_n, const data_size = try io_r.writableVector(&iovecs_buffer, data);
            const dest = iovecs_buffer[0..dest_n];
            assert(dest[0].len > 0);
            const result = r.stream.readWithControl(io, dest, r.control_buffer[r.control_len..]) catch |err| {
                r.err = err;
                return error.ReadFailed;
            };
            r.control_len += result.control_len;
            r.control_truncated = r.control_truncated or result.control_truncated;
            if (result.data_len == 0) {
                return error.EndOfStream;
            }
            if (result.data_len > data_size) {
                r.interface.end += result.data_len - data_size;
                return data_size;
            }
            return result.data_len;
        }

        /// 访问原始的缓冲控制数据。
        pub fn controlSlice(r: *const Reader) []align(cmsg_align) u8 {
            return r.control_buffer[0..r.control_len];
        }

        /// 遍历已缓冲的控制消息。
        pub fn controlIterator(r: *const Reader) cmsg.Iterator {
            return .{ .control = r.controlSlice() };
        }

        /// 清除缓冲的控制数据。
        pub fn clearControl(r: *Reader) void {
            r.control_len = 0;
            r.control_truncated = false;
        }
    };

    pub const Writer = struct {
        io: Io,
        interface: Io.Writer,
        /// 将在下次排空时发送,然后重新设为空切片。
        control: []const u8 = &.{},
        stream: Stream,
        err: ?Error = null,
        write_file_err: ?WriteFileError = null,

        pub const Error = Io.Operation.NetWrite.Error || Io.Cancelable;

        pub const WriteFileError = Error || error{
            /// `Io` 实现无法提供更高效的文件到套接字传输路径;
            /// 调用者应退回基于读取的复制。参见 `Io.Writer.sendFile`。
            ///
            Unimplemented,
            /// 已到达正在读取的文件末尾。
            EndOfStream,
            /// 源 `File.Reader` 失败;
            /// 详细诊断信息见该结构体。
            ReadFailed,
        };

        pub fn init(stream: Stream, io: Io, buffer: []u8) Writer {
            return .{
                .io = io,
                .stream = stream,
                .interface = .{
                    .vtable = &.{
                        .drain = drain,
                        .sendFile = sendFile,
                    },
                    .buffer = buffer,
                },
            };
        }

        fn drain(io_w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize {
            const w: *Writer = @alignCast(@fieldParentPtr("interface", io_w));
            const io = w.io;
            const buffered = io_w.buffered();
            const handle = w.stream.socket.handle;
            const result = io.operate(.{ .net_write = .{
                .socket_handle = handle,
                .header = buffered,
                .data = data,
                .splat = splat,
                .control = w.control,
            } }) catch |err| {
                w.err = err;
                return error.WriteFailed;
            };
            const n = result.net_write catch |err| {
                w.err = err;
                return error.WriteFailed;
            };
            w.control = &.{};
            return io_w.consume(n);
        }

        fn sendFile(io_w: *Io.Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize {
            const w: *Writer = @alignCast(@fieldParentPtr("interface", io_w));
            const io = w.io;
            const header = io_w.buffered();
            const handle = w.stream.socket.handle;
            const n = io.vtable.netWriteFile(io.userdata, handle, header, file_reader, limit) catch |err| switch (err) {
                error.Canceled => {
                    w.err = error.Canceled;
                    return error.WriteFailed;
                },
                error.EndOfStream,
                error.Unimplemented,
                error.ReadFailed,
                => |e| return e,
                else => |e| {
                    w.write_file_err = e;
                    return error.WriteFailed;
                },
            };
            return io_w.consume(n);
        }
    };

    pub fn reader(stream: Stream, io: Io, buffer: []u8) Reader {
        return .init(stream, io, buffer);
    }

    /// 与 `reader` 相同,但还提供用于存储控制数据的缓冲区。
    pub fn readerWithControl(
        stream: Stream,
        io: Io,
        buffer: []u8,
        control_buffer: []align(cmsg_align) u8,
    ) Reader {
        return .initWithControl(stream, io, buffer, control_buffer);
    }

    pub fn writer(stream: Stream, io: Io, buffer: []u8) Writer {
        return .init(stream, io, buffer);
    }
};

pub const cmsg_align = if (@TypeOf(std.posix.cmsg_align) == void) 1 else std.posix.cmsg_align;
/// 用于处理 POSIX 套接字控制消息的工具函数。
/// 另见 https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_socket.h.html
pub const cmsg = struct {
    const cmsghdr = std.posix.cmsghdr;

    /// 等价于 C 中的 `CMSG_SPACE`。
    pub fn space(data_len: usize) usize {
        return std.mem.alignForward(usize, @sizeOf(cmsghdr), cmsg_align) +
            std.mem.alignForward(usize, data_len, cmsg_align);
    }

    /// 等价于 C 中的 `CMSG_LEN`。
    pub fn len(data_len: @FieldType(cmsghdr, "len")) @TypeOf(data_len) {
        return std.mem.alignForward(@TypeOf(data_len), @sizeOf(cmsghdr), cmsg_align) + data_len;
    }

    /// 等价于 C 中的 `CMSG_DATA`。
    pub fn data(header: *align(cmsg_align) cmsghdr) []align(cmsg_align) u8 {
        const bytes: [*]u8 = @ptrCast(header);
        return @alignCast(bytes[0..header.len][std.mem.alignForward(usize, @sizeOf(cmsghdr), cmsg_align)..]);
    }

    /// 等同于 C 中的 `CMSG_FIRSTHDR` 和 `CMSG_NXTHDR`。
    pub const Iterator = struct {
        control: []align(cmsg_align) u8,

        pub const Message = struct {
            header: *align(cmsg_align) cmsghdr,
            data: []align(cmsg_align) u8,
        };

        pub fn next(it: *Iterator) ?Message {
            if (it.control.len < @sizeOf(cmsghdr)) return null;
            const header: *align(cmsg_align) cmsghdr = @ptrCast(it.control.ptr);
            if (it.control.len < header.len) return null;
            const next_header = std.mem.alignForward(usize, header.len, cmsg_align);
            if (it.control.len < next_header) {
                it.control = &.{};
            } else {
                it.control = @alignCast(it.control[next_header..]);
            }
            return .{ .header = header, .data = data(header) };
        }
    };
};

pub const Server = struct {
    socket: Socket,
    options: AcceptOptions,

    pub fn deinit(s: *Server, io: Io) void {
        s.socket.close(io);
        s.* = undefined;
    }

    pub const AcceptError = error{
        /// 已达到每个进程可打开的文件描述符数量限制。
        ProcessFdQuotaExceeded,
        /// 已达到系统范围内打开文件总数的上限。
        SystemFdQuotaExceeded,
        /// 可用内存不足。这通常意味着内存分配受限于
        /// 套接字缓冲区上限,而非系统内存。
        SystemResources,
        /// 从未调用 `listen`,或已调用 `shutdown`,后者可能发生于
        /// 本调用阻塞期间。因此,可将 `shutdown` 用作
        /// 并发取消机制。
        SocketNotListening,
        /// 网络子系统已失败。
        NetworkDown,
        /// 没有已排队且可立即接受的连接,
        /// 而套接字配置为非阻塞模式。
        WouldBlock,
        /// 曾有传入连接,但在接受调用之前,
        /// 远端对等方已将其终止。
        ConnectionAborted,
        /// 防火墙规则禁止连接。
        BlockedByFirewall,
        ProtocolFailure,
    } || Io.UnexpectedError || Io.Cancelable;

    pub const AcceptOptions = switch (native_os) {
        .windows => struct { mode: Socket.Mode, protocol: ?Protocol },
        else => void,
    };

    /// 阻塞直到客户端连接服务器。
    pub fn accept(s: *Server, io: Io) AcceptError!Stream {
        return .{ .socket = try io.vtable.netAccept(io.userdata, s.socket.handle, s.options) };
    }
};

test "parsing IPv6 addresses" {
    try testIp6Parse("fe80::e0e:76ff:fed4:cf22%eno1");
    try testIp6Parse("2001:db8::1");
    try testIp6ParseTransform("2001:db8::1", "2001:0db8:0000:0000:0000:0000:0000:0001");
    try testIp6Parse("::1");
    try testIp6Parse("::");
    try testIp6Parse("fe80::1");
    try testIp6Parse("fe80::abcd:ef12%3");
    try testIp6Parse("ff02::");
    try testIp6Parse("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff");
    try testIp6Parse("::ffff:192.0.2.1"); // 映射到 IPv6 的 IPv4 地址
    try testIp6Parse("64:ff9b::192.0.2.1"); // RFC 6052 定义的知名前缀
    try testIp6Parse("fe80::e0e:76ff:fed4:cf22%iface.123"); // 解析 :ipv4 时的边界情况
    try testIp6ParseTransform("::c000:201", "::192.0.2.1"); // 已弃用的“IPv4 兼容”形式
    try testIp6ParseTransform("::ffff:192.0.2.1", "::ffff:c000:201"); // 映射形式中的非规范表示
    try testIp6ParseTransform("2001:db8::c000:201", "2001:db8::192.0.2.1"); // 任意前缀
    try testIp6ParseTransform("2001:db8::201", "2001:db8::0.0.2.1"); // 压缩表示加 :IPv4 的边界情况
}
test "IpAddress.setPort works" {
    var addr: IpAddress = .{ .ip4 = undefined };
    addr.setPort(0);
    try std.testing.expectEqual(0, addr.getPort());
}

fn testIp6Parse(input: []const u8) !void {
    return testIp6ParseTransform(input, input);
}

fn testIp6ParseTransform(expected: []const u8, input: []const u8) !void {
    const ua = switch (Ip6Address.Unresolved.parse(input)) {
        .success => |p| p,
        else => |x| {
            std.debug.print("failed to parse \"{s}\": {any}\n", .{ input, x });
            return error.TestFailed;
        },
    };
    var buffer: [100]u8 = undefined;
    const result = try std.mem.print(&buffer, "{f}", .{ua});
    try std.testing.expectEqualStrings(expected, result);
}

test {
    _ = HostName;
    _ = @import("net/test.zig");
}