std.Io.net.assert
别名
别名目标 std.debug.assert
std.Io.net.builtin
常量
std.Io.net.cmsg
命名空间
用于处理 POSIX 套接字控制消息的工具函数。 另见 https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_socket.h.html
std.Io.net.cmsg_align
常量
std.Io.net.cmsg.cmsghdr
别名
别名目标 std.posix.cmsghdr
std.Io.net.cmsg.data
函数
等价于 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
容器
等同于 C 中的 CMSG_FIRSTHDR 和 CMSG_NXTHDR。
字段
control: []align(cmsg_align) u8
std.Io.net.cmsg.Iterator.Message
容器
字段
header: *cmsghdr
data: []align(cmsg_align) u8
std.Io.net.cmsg.Iterator.next
函数
pub fn next(it: *Iterator) ?Message
参数
it: *Iterator
std.Io.net.cmsg.len
函数
等价于 C 中的 CMSG_LEN。
pub fn len(data_len: @FieldType(cmsghdr, "len")) @TypeOf(data_len)
参数
data_len: @FieldType(cmsghdr, "len")
std.Io.net.cmsg.space
函数
等价于 C 中的 CMSG_SPACE。
pub fn space(data_len: usize) usize
参数
data_len: usize
std.Io.net.default_kernel_backlog
常量
std.Io.net.has_unix_sockets
常量
Windows 10 从内部版本 17063 起增加 Unix 套接字支持,redstone 4 是 首个支持它们的正式版本。
std.Io.net.HostName
别名
别名目标 std.Io.net.HostName
std.Io.net.IncomingMessage
容器
字段
std.Io.net.IncomingMessage.Flags
容器
字段
eor: bool表示记录结束;返回的数据补全了一条记录 (通常用于 SOCK_SEQPACKET 类型的套接字)。
trunc: bool表示数据报大于提供的缓冲区,因此丢弃了数据报尾部。
ctrunc: bool表示由于辅助数据缓冲区 空间不足,部分控制数据被丢弃。
oob: bool表示收到了加急或带外数据。
errqueue: bool表示未收到数据,但从套接字错误队列中 收到了扩展错误。
_: u3 = 0
std.Io.net.IncomingMessage.init
常量
适合在调用 receiveManyTimeout 之前初始化。
IncomingMessage
std.Io.net.Interface
容器
字段
index: u32值 0 表示 none。
std.Io.net.Interface.isNone
函数
pub fn isNone(i: Interface) bool
参数
i: Interface
std.Io.net.Interface.name
函数
断言不为 none。
对应 libc 中的 "if_indextoname"。
pub fn name(i: Interface, io: Io) NameError!Name
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
index超出范围。- NameTooLong
接口名称长于
Name.max_len。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Interface.Name
容器
字段
bytes: [max_len:0]u8
std.Io.net.Interface.Name.fromSlice
函数
pub fn fromSlice(bytes: []const u8) error{NameTooLong}!Name
参数
bytes: []const u8
错误
- NameTooLong
std.Io.net.Interface.Name.fromSliceUnchecked
函数
断言 bytes.len 不超过 max_len。
pub fn fromSliceUnchecked(bytes: []const u8) Name
参数
bytes: []const u8
std.Io.net.Interface.Name.max_len
常量
std.Io.net.Interface.Name.resolve
函数
对应 libc 中的 "if_nametoindex"。
pub fn resolve(n: *const Name, io: Io) ResolveError!Interface
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Interface.Name.ResolveError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Interface.Name.toSlice
函数
pub fn toSlice(n: *const Name) []const u8
参数
n: *const Name
std.Io.net.Interface.NameError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
index超出范围。- NameTooLong
接口名称长于
Name.max_len。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Interface.none
常量
Interface
std.Io.net.Io
别名
别名目标 std.Io
std.Io.net.Ip4Address
容器
二进制内存布局的 IPv4 地址。
字段
bytes: [4]u8
port: u16
std.Io.net.Ip4Address.eql
函数
pub fn eql(a: Ip4Address, b: Ip4Address) bool
参数
a: Ip4Address
b: Ip4Address
std.Io.net.Ip4Address.format
函数
pub fn format(a: Ip4Address, w: *Io.Writer) Io.Writer.Error!void
参数
a: Ip4Address
w: *Io.Writer
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.net.Ip4Address.fromAny
函数
给定 IpAddress,将其直接转换为 Ip4Address,或从
IPv4 映射的 IPv6 地址转换;无法转换则返回 null。
pub fn fromAny(addr: IpAddress) ?Ip6Address
参数
addr: IpAddress
std.Io.net.Ip4Address.fromIp6
函数
从 IPv4 映射的 IPv6 地址转换,或返回 null。
pub fn fromIp6(ip6: Ip6Address) ?Ip4Address
参数
ip6: Ip6Address
std.Io.net.Ip4Address.loopback
函数
pub fn loopback(port: u16) Ip4Address
参数
port: u16
std.Io.net.Ip4Address.parse
函数
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
错误集合
错误
- Incomplete
- InvalidCharacter
- InvalidEnd
- NonCanonical
- Overflow
std.Io.net.Ip4Address.unspecified
函数
pub fn unspecified(port: u16) Ip4Address
参数
port: u16
std.Io.net.Ip6Address
容器
使用二进制内存布局的 IPv6 地址。
字段
std.Io.net.Ip6Address.defined_policies
常量
std.Io.net.Ip6Address.eql
函数
pub fn eql(a: Ip6Address, b: Ip6Address) bool
参数
a: Ip6Address
b: Ip6Address
std.Io.net.Ip6Address.format
函数
另见 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
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound NameError
index超出范围。- NameTooLong NameError
接口名称长于
Name.max_len。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WriteFailed Error
详细诊断信息见
Writer实现。
std.Io.net.Ip6Address.formatResolved
函数
包含可选的作用域(末尾的 "%foo")。
另见 format,它省略作用域,且
不需要 Io 参数。
pub fn formatResolved(a: *const Ip6Address, io: Io, w: *Io.Writer) FormatError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound NameError
index超出范围。- NameTooLong NameError
接口名称长于
Name.max_len。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WriteFailed Error
详细诊断信息见
Writer实现。
std.Io.net.Ip6Address.fromAny
函数
给定 IpAddress,将其直接转换为 Ip6Address,或通过
构造 IPv4 映射的 IPv6 地址来完成转换。
pub fn fromAny(addr: IpAddress) Ip6Address
参数
addr: IpAddress
std.Io.net.Ip6Address.fromIp4
函数
构造 IPv4 映射的 IPv6 地址。
pub fn fromIp4(ip4: Ip4Address) Ip6Address
参数
ip4: Ip4Address
std.Io.net.Ip6Address.isLinkLocal
函数
pub fn isLinkLocal(a: Ip6Address) bool
参数
a: Ip6Address
std.Io.net.Ip6Address.isLoopBack
函数
pub fn isLoopBack(a: Ip6Address) bool
参数
a: Ip6Address
std.Io.net.Ip6Address.isMultiCast
函数
pub fn isMultiCast(a: Ip6Address) bool
参数
a: Ip6Address
std.Io.net.Ip6Address.isSiteLocal
函数
pub fn isSiteLocal(a: Ip6Address) bool
参数
a: Ip6Address
std.Io.net.Ip6Address.loopback
函数
pub fn loopback(port: u16) Ip6Address
参数
port: u16
std.Io.net.Ip6Address.parse
函数
这是纯函数,但无法处理带作用域 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
错误集合
错误
- ParseFailed
返回此错误时,可通过调用
Ip6Address.Parsed.init获得更详细的诊断信息。- UnresolvedScope
返回此错误表示 IPv6 地址带有作用域标识, 即末尾的“%foo”,需要调用
resolve。
std.Io.net.Ip6Address.policy
函数
pub fn policy(a: Ip6Address) *const Policy
参数
a: Ip6Address
std.Io.net.Ip6Address.Policy
容器
字段
addr: [16]u8
len: u8
mask: u8
prec: u8
label: u8
std.Io.net.Ip6Address.resolve
函数
此函数需要 Io 参数,因为它必须查询操作系统,
将接口名转换为索引。例如,在
“fe80::e0e:76ff:fed4:cf22%eno1”中,必须创建套接字,
再使用 ioctl 系统调用将“eno1”解析为索引。
pub fn resolve(io: Io, buffer: []const u8, port: u16) ResolveError!Ip6Address
参数
错误
- AccessDenied ResolveError
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound ResolveError
- NameTooLong
接口名称长度超过宿主操作系统支持的范围。
- ParseFailed
如果返回此错误,可调用
Parsed.init函数 获取更详细的诊断信息。- SystemResources ResolveError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Ip6Address.ResolveError
错误集合
错误
- AccessDenied ResolveError
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound ResolveError
- NameTooLong
接口名称长度超过宿主操作系统支持的范围。
- ParseFailed
如果返回此错误,可调用
Parsed.init函数 获取更详细的诊断信息。- SystemResources ResolveError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Ip6Address.scope
函数
pub fn scope(a: Ip6Address) u8
参数
a: Ip6Address
std.Io.net.Ip6Address.Unresolved
容器
IPv6 地址,但 Interface 使用名称而非索引。
字段
bytes: [16]u8大端序
interface_name: ?[]const u8尚未检查它是否为有效的原生接口名称。 内存由外部管理。
std.Io.net.Ip6Address.Unresolved.format
函数
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
函数
pub fn parse(text: []const u8) Parsed
参数
text: []const u8
std.Io.net.Ip6Address.Unresolved.Parsed
容器
字段
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
函数
pub fn unspecified(port: u16) Ip6Address
参数
port: u16
std.Io.net.IpAddress
容器
字段
ip4: Ip4Address
ip6: Ip6Address
std.Io.net.IpAddress.bind
函数
将地址与 Socket 关联,用于接收 UDP 数据包
及其他非流式消息。流式替代方案参见 listen。
一个已绑定的 Socket 可以接收来自多个
不同地址的消息。
pub fn bind(address: *const IpAddress, io: Io, options: BindOptions) BindError!Socket
参数
错误
- 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
错误集合
错误
- 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
容器
字段
std.Io.net.IpAddress.connect
函数
发起面向连接的网络流。
pub fn connect(address: *const IpAddress, io: Io, options: ConnectOptions) ConnectError!Stream
参数
错误
- 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
错误集合
错误
- 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
容器
字段
std.Io.net.IpAddress.eql
函数
pub fn eql(a: *const IpAddress, b: *const IpAddress) bool
参数
std.Io.net.IpAddress.Family
常量
std.Io.net.IpAddress.format
函数
另一种形式参见 formatResolved;它还会打印 IPv6 地址末尾的可选作用域,
并且需要 Io 参数。
pub fn format(a: IpAddress, w: *Io.Writer) Io.Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.net.IpAddress.formatResolved
函数
包含 IPv6 地址中的可选作用域,即末尾的“%foo”。
不包含作用域且无需 Io 参数的替代形式,参见 format。
pub fn formatResolved(a: IpAddress, io: Io, w: *Io.Writer) Ip6Address.FormatError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound NameError
index超出范围。- NameTooLong NameError
接口名称长于
Name.max_len。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WriteFailed Error
详细诊断信息见
Writer实现。
std.Io.net.IpAddress.fromIp6
函数
转换 IPv4 映射的 IPv6 地址,或直接返回 IPv6 地址。
pub fn fromIp6(ip6: Ip6Address) IpAddress
参数
ip6: Ip6Address
std.Io.net.IpAddress.getPort
函数
以本机字节序返回端口。
pub fn getPort(a: IpAddress) u16
参数
a: IpAddress
std.Io.net.IpAddress.listen
函数
等待 TCP 连接。使用此 API 时无需调用 bind。返回的 Server 具有打开的 stream。
pub fn listen(address: *const IpAddress, io: Io, options: ListenOptions) ListenError!Server
参数
错误
- 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
错误集合
错误
- 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
容器
字段
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.streamSocket.Mode.seqpacket
protocol: Protocol = .tcp此处仅可使用面向连接的协议,包括:
Protocol.tcpProtocol.tpProtocol.dccpProtocol.sctp
std.Io.net.IpAddress.parse
函数
将给定 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
函数
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
函数
这是纯函数,但无法处理带作用域 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
函数
解析可能包含端口的 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
错误集合
错误
- InvalidAddress
- InvalidPort
std.Io.net.IpAddress.resolve
函数
此函数需要 Io 参数,因为必须查询操作
系统,将接口名称转换为索引。例如,
在 "fe80::e0e:76ff:fed4:cf22%eno1" 中,需要通过
创建套接字再调用 ioctl,将 "eno1" 解析为索引。
不处理作用域的纯函数,参见 parse。
pub fn resolve(io: Io, text: []const u8, port: u16) !IpAddress
参数
std.Io.net.IpAddress.resolveIp6
函数
pub fn resolveIp6(io: Io, text: []const u8, port: u16) Ip6Address.ResolveError!IpAddress
参数
错误
- AccessDenied ResolveError
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound ResolveError
- NameTooLong
接口名称长度超过宿主操作系统支持的范围。
- ParseFailed
如果返回此错误,可调用
Parsed.init函数 获取更详细的诊断信息。- SystemResources ResolveError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.IpAddress.setPort
函数
port 使用本机字节序。
pub fn setPort(a: *IpAddress, port: u16) void
参数
a: *IpAddress
port: u16
std.Io.net.native_os
常量
std.Io.net.OutgoingMessage
容器
字段
address: *const IpAddress
data_ptr: [*]const u8
data_len: usize初始化为要从 data_ptr 发送的字节数。发送成功后,
替换为实际发送的字节数。
control: []const u8 = &.{}
std.Io.net.Protocol
容器
权威来源:互联网号码分配局(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
容器
字段
oob: bool = false
peek: bool = false
trunc: bool = false
_: u5 = 0
std.Io.net.SendFlags
容器
字段
confirm: bool = false
dont_route: bool = false
eor: bool = false
oob: bool = false
fastopen: bool = false
_: u3 = 0
std.Io.net.Server
容器
字段
socket: Socket
options: AcceptOptions
std.Io.net.Server.accept
函数
阻塞直到客户端连接服务器。
pub fn accept(s: *Server, io: Io) AcceptError!Stream
参数
错误
- BlockedByFirewall
防火墙规则禁止连接。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
曾有传入连接,但在接受调用之前, 远端对等方已将其终止。
- NetworkDown
网络子系统已失败。
- ProcessFdQuotaExceeded
已达到每个进程可打开的文件描述符数量限制。
- ProtocolFailure
- SocketNotListening
从未调用
listen,或已调用shutdown,后者可能发生于 本调用阻塞期间。因此,可将shutdown用作 并发取消机制。- SystemFdQuotaExceeded
已达到系统范围内打开文件总数的上限。
- SystemResources
可用内存不足。这通常意味着内存分配受限于 套接字缓冲区上限,而非系统内存。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
没有已排队且可立即接受的连接, 而套接字配置为非阻塞模式。
std.Io.net.Server.AcceptError
错误集合
错误
- BlockedByFirewall
防火墙规则禁止连接。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
曾有传入连接,但在接受调用之前, 远端对等方已将其终止。
- NetworkDown
网络子系统已失败。
- ProcessFdQuotaExceeded
已达到每个进程可打开的文件描述符数量限制。
- ProtocolFailure
- SocketNotListening
从未调用
listen,或已调用shutdown,后者可能发生于 本调用阻塞期间。因此,可将shutdown用作 并发取消机制。- SystemFdQuotaExceeded
已达到系统范围内打开文件总数的上限。
- SystemResources
可用内存不足。这通常意味着内存分配受限于 套接字缓冲区上限,而非系统内存。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
没有已排队且可立即接受的连接, 而套接字配置为非阻塞模式。
std.Io.net.Server.AcceptOptions
类型
std.Io.net.Server.deinit
函数
pub fn deinit(s: *Server, io: Io) void
参数
std.Io.net.ShutdownError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
- ConnectionResetByPeer
- NetworkDown
- SocketUnconnected
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.ShutdownHow
容器
字段
recv
send
both
std.Io.net.Socket
容器
未指定协议的开放端口。
字段
std.Io.net.Socket.close
函数
使 address 保持有效状态。
pub fn close(s: *const Socket, io: Io) void
参数
std.Io.net.Socket.closeMany
函数
pub fn closeMany(io: Io, sockets: []const Socket) void
参数
std.Io.net.Socket.createPair
函数
创建一对彼此连接的套接字。
也称为 "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
错误集合
错误
- AccessDenied
- AddressFamilyUnsupported
- Canceled Cancelable
调用方请求停止异步操作。
- OperationUnsupported
- ProcessFdQuotaExceeded
已达到每个进程可打开的文件描述符数量限制。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内打开文件总数的上限。
- SystemResources
可用内存不足。在释放足够资源前, 无法创建套接字。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Socket.CreatePairOptions
容器
字段
std.Io.net.Socket.Handle
别名
由底层平台定义的类型,可能可以,也可能不可以 与文件系统文件描述符互换。
别名目标 std.posix.fd_t
std.Io.net.Socket.Mode
容器
字段
stream提供有序、可靠、双向、基于连接的字节流。 可能支持带外数据传输机制。
dgram支持数据报(无连接、不可靠, 且最大长度固定的消息)。
seqpacket为具有固定最大长度的数据报提供有序、可靠、 双向、面向连接的数据传输通道;要求消费者 每次输入系统调用都读取一个完整数据包。
raw提供对原始网络协议的访问。
rdm提供不保证顺序的可靠数据报层。
std.Io.net.Socket.receive
函数
等待数据。无连接。
另请参见:
receiveTimeout
pub fn receive(s: *const Socket, io: Io, buffer: []u8) ReceiveError!IncomingMessage
参数
错误
- 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
错误集合
错误
- 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
类型函数
等待至少一条消息到达,也可能返回 多条消息。无需连接。
返回收到的消息数;若消息未及时到达,
则返回 error.Timeout。
另见:
receivereceiveTimeout
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
函数
等待数据。无连接。
若没有消息及时到达,则返回 error.Timeout。
另见:
receivereceiveManyTimeout
pub fn receiveTimeout( s: *const Socket, io: Io, buffer: []u8, timeout: Io.Timeout, ) ReceiveTimeoutError!IncomingMessage
参数
错误
- 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
错误集合
错误
- 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
函数
以无连接方式,在单个数据包中将 data 传给 dest。
pub fn send(s: *const Socket, io: Io, dest: *const IpAddress, data: []const u8) SendError!void
参数
错误
- 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
错误集合
错误
- 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
函数
已弃用;请使用超时为 .none 的 sendManyTimeout。
若此函数返回错误,messages 中的部分消息
仍可能已经发送,但不会全部发送。此函数不报告该情况,
而 sendManyTimeout 会报告。
pub fn sendMany(s: *const Socket, io: Io, messages: []OutgoingMessage, flags: SendFlags) SendError!void
参数
错误
- 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
类型函数
pub fn sendManyTimeout( s: *const Socket, io: Io, messages: []OutgoingMessage, flags: SendFlags, timeout: Io.Timeout, ) struct { ?SendTimeoutError, usize }
参数
std.Io.net.Socket.sendTimeout
函数
pub fn sendTimeout( s: *const Socket, io: Io, dest: *const IpAddress, data: []const u8, timeout: Io.Timeout, ) SendTimeoutError!void
参数
错误
- 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
错误集合
错误
- 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
别名
别名目标 std
std.Io.net.Stream
容器
已打开的套接字连接,其网络协议保证 顺序、交付并防止重复。通常为 TCP 或 UNIX 域 套接字。
字段
socket: Socket
std.Io.net.Stream.close
函数
pub fn close(s: *const Stream, io: Io) void
参数
std.Io.net.Stream.max_iovecs_len
常量
std.Io.net.Stream.read
函数
这是直接调用 Io 接口函数的底层 API。
更高层 API 参见 reader。
pub fn read(s: *const Stream, io: Io, data: [][]u8) Reader.Error!usize
参数
错误
- AccessDenied Error
文件描述符不具有读取所需权限。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer Error
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- NetworkDown Error
- SocketUnconnected Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Stream.reader
函数
pub fn reader(stream: Stream, io: Io, buffer: []u8) Reader
参数
std.Io.net.Stream.Reader
容器
字段
std.Io.net.Stream.Reader.clearControl
函数
清除缓冲的控制数据。
pub fn clearControl(r: *Reader) void
参数
r: *Reader
std.Io.net.Stream.Reader.controlIterator
函数
遍历已缓冲的控制消息。
pub fn controlIterator(r: *const Reader) cmsg.Iterator
参数
r: *const Reader
std.Io.net.Stream.Reader.controlSlice
函数
访问原始的缓冲控制数据。
pub fn controlSlice(r: *const Reader) []align(cmsg_align) u8
参数
r: *const Reader
std.Io.net.Stream.Reader.Error
错误集合
错误
- AccessDenied Error
文件描述符不具有读取所需权限。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer Error
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- NetworkDown Error
- SocketUnconnected Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Stream.Reader.init
函数
pub fn init(stream: Stream, io: Io, buffer: []u8) Reader
参数
std.Io.net.Stream.Reader.initWithControl
函数
与 init 相同,但还提供用于存储控制数据的缓冲区。
pub fn initWithControl( stream: Stream, io: Io, buffer: []u8, control_buffer: []align(cmsg_align) u8, ) Reader
参数
std.Io.net.Stream.Reader.readVec
函数
fn readVec(io_r: *Io.Reader, data: [][]u8) Io.Reader.Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.net.Stream.Reader.streamImpl
函数
fn streamImpl(io_r: *Io.Reader, io_w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize
参数
错误
std.Io.net.Stream.readerWithControl
函数
与 reader 相同,但还提供用于存储控制数据的缓冲区。
pub fn readerWithControl( stream: Stream, io: Io, buffer: []u8, control_buffer: []align(cmsg_align) u8, ) Reader
参数
std.Io.net.Stream.ReadResult
容器
字段
data_len: usize
control_len: usize = 0
control_truncated: bool = false是否仅收到部分控制数据。
控制数据被截断时,额外数据实际上 会直接丢失。这表明存在设计问题, 例如控制缓冲区过小。
std.Io.net.Stream.readWithControl
函数
连同控制数据一起读取。
这是直接调用 Io 接口函数的底层 API。
更高层 API 参见 reader。
pub fn readWithControl(s: *const Stream, io: Io, data: [][]u8, control: []u8) Reader.Error!ReadResult
参数
错误
- AccessDenied Error
文件描述符不具有读取所需权限。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer Error
- ConnectionTimedOut Error
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- NetworkDown Error
- SocketUnconnected Error
- SystemResources Error
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Stream.shutdown
函数
pub fn shutdown(s: *const Stream, io: Io, how: ShutdownHow) ShutdownError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
- ConnectionResetByPeer
- NetworkDown
- SocketUnconnected
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.Stream.writer
函数
pub fn writer(stream: Stream, io: Io, buffer: []u8) Writer
参数
std.Io.net.Stream.Writer
容器
字段
std.Io.net.Stream.Writer.drain
函数
fn drain(io_w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.net.Stream.Writer.Error
错误集合
错误
- 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
函数
pub fn init(stream: Stream, io: Io, buffer: []u8) Writer
参数
std.Io.net.Stream.Writer.sendFile
函数
fn sendFile(io_w: *Io.Writer, file_reader: *Io.File.Reader, limit: Io.Limit) Io.Writer.FileError!usize
参数
错误
- EndOfStream
已到达正在读取的文件末尾。
- ReadFailed
详细诊断信息位于
File.Reader结构体上。- Unimplemented
表示调用方应自行读取文件;被调用方无法 提供更高效的实现。
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.net.Stream.Writer.WriteFileError
错误集合
错误
- 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
函数
fn testIp6Parse(input: []const u8) !void
参数
input: []const u8
std.Io.net.testIp6ParseTransform
函数
fn testIp6ParseTransform(expected: []const u8, input: []const u8) !void
参数
expected: []const u8
input: []const u8
std.Io.net.UnixAddress
容器
字段
path: []const u8
std.Io.net.UnixAddress.connect
函数
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
错误集合
错误
- 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
函数
pub fn init(p: []const u8) InitError!UnixAddress
参数
p: []const u8
错误
- NameTooLong
std.Io.net.UnixAddress.InitError
错误集合
错误
- NameTooLong
std.Io.net.UnixAddress.isAbstract
函数
pub fn isAbstract(ua: *const UnixAddress) bool
参数
ua: *const UnixAddress
std.Io.net.UnixAddress.listen
函数
pub fn listen(ua: *const UnixAddress, io: Io, options: ListenOptions) ListenError!Server
参数
错误
- AccessDenied
- AddressFamilyUnsupported
- AddressInUse
- AddressUnavailable
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NetworkDown
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.UnixAddress.ListenError
错误集合
错误
- AccessDenied
- AddressFamilyUnsupported
- AddressInUse
- AddressUnavailable
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NetworkDown
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.net.UnixAddress.ListenOptions
容器
字段
kernel_backlog: u31 = default_kernel_backlog内核代表应用程序接受的连接数量。 若内核中积压的连接超过此数量,客户端将开始 收到“Connection refused”。
std.Io.net.UnixAddress.max_len
常量
源码
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) ?Ip6Address {
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: []const u8) Parsed {
if (text.len < 2) return .incomplete;
const ip4_prefix = "::ffff:";
if (std.ascii.startsWithIgnoreCase(text, ip4_prefix)) {
const parsed = Ip4Address.parse(text[ip4_prefix.len..], 0) catch
return .{ .invalid_ip4_mapping = ip4_prefix.len };
const b = parsed.bytes;
return .{ .success = .{
.bytes = .{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff, b[0], b[1], b[2], b[3] },
.interface_name = null,
} };
}
// 必须使用 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 })) {
try w.print("::ffff:{d}.{d}.{d}.{d}", .{ bytes[12], bytes[13], bytes[14], bytes[15] });
} else {
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 {
const rc, _ = try (try io.operate(.{ .net_read = .{
.socket_handle = s.socket.handle,
.data = data,
} })).net_read;
return rc;
}
/// 连同控制数据一起读取。
///
/// 这是直接调用 `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: *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");
}
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");
}