Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/Io/net.zig

Source line 1

std.Io.net.assert

alias

Source line 5

Alias of std.debug.assert

std.Io.net.builtin

constant

Source line 1

std.Io.net.cmsg

namespace

Source line 1523

Utility Functions for interacting with POSIX socket control messages. See also https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_socket.h.html

std.Io.net.cmsg_align

constant

Source line 1520

std.Io.net.cmsg.cmsghdr

alias

Source line 1524

Alias of std.posix.cmsghdr

std.Io.net.cmsg.data

function

Source line 1538

Equivalent to CMSG_DATA in C.

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

Parameters

header: *align(cmsg_align) cmsghdr

std.Io.net.cmsg.Iterator

container

Source line 1544

Equivalent to CMSG_FIRSTHDR and CMSG_NXTHDR in C.

Fields

control: []align(cmsg_align) u8

std.Io.net.cmsg.Iterator.Message

container

Source line 1547

Fields

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

std.Io.net.cmsg.Iterator.next

function

Source line 1552

pub fn next(it: *Iterator) ?Message

Parameters

it: *Iterator

std.Io.net.cmsg.len

function

Source line 1533

Equivalent to CMSG_LEN in C.

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

Parameters

data_len: @FieldType(cmsghdr, "len")

std.Io.net.cmsg.space

function

Source line 1527

Equivalent to CMSG_SPACE in C.

pub fn space(data_len: usize) usize

Parameters

data_len: usize

std.Io.net.default_kernel_backlog

constant

Source line 55

std.Io.net.has_unix_sockets

constant

Source line 49

Windows 10 added support for unix sockets in build 17063, redstone 4 is the first release to support them.

std.Io.net.HostName

alias

Source line 7

Alias of std.Io.net.HostName

std.Io.net.IncomingMessage

container

Source line 944

Fields

from: IpAddress

Populated by receive functions.

data: []u8

Populated by receive functions, points into the caller-supplied buffer.

control: []u8

Supplied by caller before calling receive functions; mutated by receive functions.

flags: Flags

Populated by receive functions.

std.Io.net.IncomingMessage.Flags

container

Source line 963

Fields

eor: bool

indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET).

trunc: bool

indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied.

ctrunc: bool

indicates that some control data was discarded due to lack of space in the buffer for ancil‐ lary data.

oob: bool

indicates expedited or out-of-band data was received.

errqueue: bool

indicates that no data was received but an extended error from the socket error queue.

_: u3 = 0

std.Io.net.IncomingMessage.init

constant

Source line 956

Useful for initializing before calling receiveManyTimeout.

IncomingMessage

std.Io.net.Interface

container

Source line 1010

Fields

index: u32

Value 0 indicates none.

std.Io.net.Interface.isNone

function

Source line 1066

pub fn isNone(i: Interface) bool

Parameters

std.Io.net.Interface.name

function

Source line 1061

Asserts not none.

Corresponds to "if_indextoname" in libc.

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

Parameters

i: Interface
io: Io

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound

Out of range index.

NameTooLong

Interface name longer than Name.max_len.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Interface.Name

container

Source line 1016

Fields

bytes: [max_len:0]u8

std.Io.net.Interface.Name.fromSlice

function

Source line 1025

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

Parameters

bytes: []const u8

Errors

NameTooLong

std.Io.net.Interface.Name.fromSliceUnchecked

function

Source line 1031

Asserts bytes.len fits in max_len.

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

Parameters

bytes: []const u8

std.Io.net.Interface.Name.max_len

constant

Source line 1019

std.Io.net.Interface.Name.resolve

function

Source line 1046

Corresponds to "if_nametoindex" in libc.

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

Parameters

n: *const Name
io: Io

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Interface.Name.ResolveError

error-set

Source line 1039

Errors

AccessDenied
Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Interface.Name.toSlice

function

Source line 1021

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

Parameters

n: *const Name

std.Io.net.Interface.NameError

error-set

Source line 1051

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound

Out of range index.

NameTooLong

Interface name longer than Name.max_len.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Interface.none

constant

Source line 1014

Interface

std.Io.net.Io

alias

Source line 4

Alias of std.Io

std.Io.net.Ip4Address

container

Source line 351

An IPv4 address in binary memory layout.

Fields

bytes: [4]u8
port: u16

std.Io.net.Ip4Address.eql

function

Source line 431

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

Parameters

std.Io.net.Ip4Address.format

function

Source line 426

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

Parameters

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.net.Ip4Address.fromAny

function

Source line 379

Given an IpAddress, converts it to an Ip4Address directly, or from an IPv4-mapped IPv6 address, or returns null.

pub fn fromAny(addr: IpAddress) ?Ip4Address

Parameters

addr: IpAddress

std.Io.net.Ip4Address.fromIp6

function

Source line 370

Converts from an IPv4-mapped IPv6 address, or returns null.

pub fn fromIp6(ip6: Ip6Address) ?Ip4Address

Parameters

ip6: Ip6Address

std.Io.net.Ip4Address.loopback

function

Source line 355

pub fn loopback(port: u16) Ip4Address

Parameters

port: u16

std.Io.net.Ip4Address.parse

function

Source line 394

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

Parameters

buffer: []const u8
port: u16

Errors

Incomplete
InvalidCharacter
InvalidEnd
NonCanonical
Overflow

std.Io.net.Ip4Address.ParseError

error-set

Source line 386

Errors

Incomplete
InvalidCharacter
InvalidEnd
NonCanonical
Overflow

std.Io.net.Ip4Address.unspecified

function

Source line 362

pub fn unspecified(port: u16) Ip4Address

Parameters

port: u16

std.Io.net.Ip6Address

container

Source line 439

An IPv6 address in binary memory layout.

Fields

port: u16

Native endian

bytes: [16]u8

Big endian

flow: u32 = 0
interface: Interface = .none

std.Io.net.Ip6Address.defined_policies

constant

Source line 804

std.Io.net.Ip6Address.eql

function

Source line 760

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

Parameters

std.Io.net.Ip6Address.format

function

Source line 755

See formatResolved for an alternative that additionally prints the optional scope at the end of addresses and requires an Io parameter.

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

Parameters

a: *const Ip6Address
w: *Io.Writer

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.net.Ip6Address.FormatError

error-set

Source line 738

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound NameError

Out of range index.

NameTooLong NameError

Interface name longer than Name.max_len.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WriteFailed Error

See the Writer implementation for detailed diagnostics.

std.Io.net.Ip6Address.formatResolved

function

Source line 744

Includes the optional scope ("%foo" at the end).

See format for an alternative that omits scopes and does not require an Io parameter.

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

Parameters

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

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound NameError

Out of range index.

NameTooLong NameError

Interface name longer than Name.max_len.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WriteFailed Error

See the Writer implementation for detailed diagnostics.

std.Io.net.Ip6Address.fromAny

function

Source line 479

Given an IpAddress, converts it to an Ip6Address directly, or via constructing an IPv4-mapped IPv6 address.

pub fn fromAny(addr: IpAddress) Ip6Address

Parameters

addr: IpAddress

std.Io.net.Ip6Address.fromIp4

function

Source line 470

Constructs an IPv4-mapped IPv6 address.

pub fn fromIp4(ip4: Ip4Address) Ip6Address

Parameters

ip4: Ip4Address

std.Io.net.Ip6Address.isLinkLocal

function

Source line 768

pub fn isLinkLocal(a: Ip6Address) bool

Parameters

std.Io.net.Ip6Address.isLoopBack

function

Source line 773

pub fn isLoopBack(a: Ip6Address) bool

Parameters

std.Io.net.Ip6Address.isMultiCast

function

Source line 764

pub fn isMultiCast(a: Ip6Address) bool

Parameters

std.Io.net.Ip6Address.isSiteLocal

function

Source line 781

pub fn isSiteLocal(a: Ip6Address) bool

Parameters

std.Io.net.Ip6Address.loopback

function

Source line 455

pub fn loopback(port: u16) Ip6Address

Parameters

port: u16

std.Io.net.Ip6Address.parse

function

Source line 699

This is a pure function but it cannot handle IPv6 addresses that have scope ids ("%foo" at the end). To also handle those, resolve must be called instead, or the lower level Unresolved API may be used.

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

Parameters

buffer: []const u8
port: u16

Errors

ParseFailed

If this is returned, more detailed diagnostics can be obtained by calling Ip6Address.Parsed.init.

UnresolvedScope

If this is returned, the IPv6 address had a scope id on it ("%foo" at the end) which requires calling resolve.

std.Io.net.Ip6Address.ParseError

error-set

Source line 687

Errors

ParseFailed

If this is returned, more detailed diagnostics can be obtained by calling Ip6Address.Parsed.init.

UnresolvedScope

If this is returned, the IPv6 address had a scope id on it ("%foo" at the end) which requires calling resolve.

std.Io.net.Ip6Address.policy

function

Source line 786

pub fn policy(a: Ip6Address) *const Policy

Parameters

std.Io.net.Ip6Address.Policy

container

Source line 447

Fields

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

std.Io.net.Ip6Address.resolve

function

Source line 723

This function requires an Io parameter because it must query the operating system to convert interface name to index. For example, in "fe80::e0e:76ff:fed4:cf22%eno1", "eno1" must be resolved to an index by creating a socket and then using an ioctl syscall.

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

Parameters

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

Errors

AccessDenied ResolveError
Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound ResolveError
NameTooLong

The interface name is longer than the host operating system supports.

ParseFailed

If this is returned, more detailed diagnostics can be obtained by calling the Parsed.init function.

SystemResources ResolveError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Ip6Address.ResolveError

error-set

Source line 711

Errors

AccessDenied ResolveError
Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound ResolveError
NameTooLong

The interface name is longer than the host operating system supports.

ParseFailed

If this is returned, more detailed diagnostics can be obtained by calling the Parsed.init function.

SystemResources ResolveError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Ip6Address.scope

function

Source line 796

pub fn scope(a: Ip6Address) u8

Parameters

std.Io.net.Ip6Address.Unresolved

container

Source line 487

An IPv6 address but with Interface as a name rather than index.

Fields

bytes: [16]u8

Big endian

interface_name: ?[]const u8

Has not been checked to be a valid native interface name. Externally managed memory.

std.Io.net.Ip6Address.Unresolved.format

function

Source line 625

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

Parameters

u: *const Unresolved
w: *Io.Writer

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.net.Ip6Address.Unresolved.parse

function

Source line 504

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

Parameters

text_in: []const u8

std.Io.net.Ip6Address.Unresolved.Parsed

container

Source line 494

Fields

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

function

Source line 462

pub fn unspecified(port: u16) Ip6Address

Parameters

port: u16

std.Io.net.IpAddress

container

Source line 57

Fields

std.Io.net.IpAddress.bind

function

Source line 305

Associates an address with a Socket which can be used to receive UDP packets and other kinds of non-streaming messages. See listen for a streaming alternative.

One bound Socket can be used to receive messages from multiple different addresses.

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

Parameters

address: *const IpAddress
io: Io
options: BindOptions

Errors

AccessDenied

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported

The address is not valid for the address family of socket.

AddressInUse

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

NetworkDown

The local network interface used to reach the destination is offline.

OptionUnsupported

One of the BindOptions is not supported by the Io implementation.

ProcessFdQuotaExceeded

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

System-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory or other resource internal to the operating system.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.IpAddress.BindError

error-set

Source line 258

Errors

AccessDenied

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported

The address is not valid for the address family of socket.

AddressInUse

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

NetworkDown

The local network interface used to reach the destination is offline.

OptionUnsupported

One of the BindOptions is not supported by the Io implementation.

ProcessFdQuotaExceeded

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

System-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory or other resource internal to the operating system.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.IpAddress.BindOptions

container

Source line 284

Fields

ip6_only: ?bool = null

The socket is restricted to sending and receiving IPv6 packets only. In this case, an IPv4 and an IPv6 application can bind to a single port at the same time.

The default is determined by system configuration.

allow_broadcast: bool = false

Allow the socket to send datagrams to broadcast addresses. When not enabled any attempt to send datagrams to a broadcast address will fail with error.AccessDenied

mode: Socket.Mode
protocol: ?Protocol = null

std.Io.net.IpAddress.connect

function

Source line 345

Initiates a connection-oriented network stream.

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

Parameters

address: *const IpAddress
io: Io
options: ConnectOptions

Errors

AccessDenied

The user tried to connect to a broadcast address without having the socket broadcast flag enabled or the connection request failed because of a local firewall rule.

AddressFamilyUnsupported
AddressUnavailable
Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionPending
ConnectionRefused
ConnectionResetByPeer
HostUnreachable
NetworkDown
NetworkUnreachable
OptionUnsupported

One of the ConnectOptions is not supported by the Io implementation.

ProcessFdQuotaExceeded

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

System-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory or other resource internal to the operating system.

Timeout
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock

Non-blocking was requested and the operation cannot return immediately.

std.Io.net.IpAddress.ConnectError

error-set

Source line 309

Errors

AccessDenied

The user tried to connect to a broadcast address without having the socket broadcast flag enabled or the connection request failed because of a local firewall rule.

AddressFamilyUnsupported
AddressUnavailable
Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionPending
ConnectionRefused
ConnectionResetByPeer
HostUnreachable
NetworkDown
NetworkUnreachable
OptionUnsupported

One of the ConnectOptions is not supported by the Io implementation.

ProcessFdQuotaExceeded

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

System-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory or other resource internal to the operating system.

Timeout
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock

Non-blocking was requested and the operation cannot return immediately.

std.Io.net.IpAddress.ConnectOptions

container

Source line 338

Fields

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

std.Io.net.IpAddress.eql

function

Source line 187

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

Parameters

a: *const IpAddress
b: *const IpAddress

std.Io.net.IpAddress.Family

constant

Source line 61

std.Io.net.IpAddress.format

function

Source line 181

See formatResolved for an alternative that additionally prints the optional scope at the end of IPv6 addresses and requires an Io parameter.

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

Parameters

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.net.IpAddress.formatResolved

function

Source line 172

Includes the optional scope ("%foo" at the end) in IPv6 addresses.

See format for an alternative that omits scopes and does not require an Io parameter.

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

Parameters

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

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound NameError

Out of range index.

NameTooLong NameError

Interface name longer than Name.max_len.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WriteFailed Error

See the Writer implementation for detailed diagnostics.

std.Io.net.IpAddress.fromIp6

function

Source line 164

Converts from an IPv4-mapped IPv6 address, or returns the IPv6 address directly.

pub fn fromIp6(ip6: Ip6Address) IpAddress

Parameters

ip6: Ip6Address

std.Io.net.IpAddress.getPort

function

Source line 149

Returns the port in native endian.

pub fn getPort(a: IpAddress) u16

Parameters

std.Io.net.IpAddress.listen

function

Source line 248

Waits for a TCP connection. When using this API, bind does not need to be called. The returned Server has an open stream.

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

Parameters

address: *const IpAddress
io: Io
options: ListenOptions

Errors

AccessDenied

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported

The requested address family (IPv4 or IPv6) is not supported by the operating system.

AddressInUse

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

NetworkDown

The local network interface used to reach the destination is offline.

OptionUnsupported

One of the ListenOptions is not supported by the Io implementation.

ProcessFdQuotaExceeded

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

System-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory or other resource internal to the operating system.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.IpAddress.ListenError

error-set

Source line 200

Errors

AccessDenied

The address is protected and the current user does not have permission to bind it.

AddressFamilyUnsupported

The requested address family (IPv4 or IPv6) is not supported by the operating system.

AddressInUse

The address is already taken. Can occur when bound port is 0 but all ephemeral ports are already in use.

AddressUnavailable

A nonexistent interface was requested or the requested address was not local.

Canceled Cancelable

Caller has requested the async operation to stop.

NetworkDown

The local network interface used to reach the destination is offline.

OptionUnsupported

One of the ListenOptions is not supported by the Io implementation.

ProcessFdQuotaExceeded

Per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

System-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory or other resource internal to the operating system.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.IpAddress.ListenOptions

container

Source line 226

Fields

kernel_backlog: u31 = default_kernel_backlog

How many connections the kernel will accept on the application's behalf. If more than this many connections pool in the kernel, clients will start seeing "Connection refused".

reuse_address: bool = false

Sets SO_REUSEADDR and SO_REUSEPORT on POSIX. Sets SO_REUSEADDR on Windows, which is roughly equivalent.

mode: Socket.Mode = .stream

Only connection-oriented modes may be used here, which includes:

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

Only connection-oriented protocols may be used here, which includes:

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

std.Io.net.IpAddress.parse

function

Source line 101

Parse the given IP address string into an IpAddress value.

This is a pure function but it cannot handle IPv6 addresses that have scope ids ("%foo" at the end). To also handle those, resolve must be called instead.

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

Parameters

text: []const u8
port: u16

std.Io.net.IpAddress.parseIp4

function

Source line 114

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

Parameters

text: []const u8
port: u16

Errors

Incomplete
InvalidCharacter
InvalidEnd
NonCanonical
Overflow

std.Io.net.IpAddress.parseIp6

function

Source line 121

This is a pure function but it cannot handle IPv6 addresses that have scope ids ("%foo" at the end). To also handle those, resolveIp6 must be called instead.

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

Parameters

text: []const u8
port: u16

Errors

ParseFailed

If this is returned, more detailed diagnostics can be obtained by calling Ip6Address.Parsed.init.

UnresolvedScope

If this is returned, the IPv6 address had a scope id on it ("%foo" at the end) which requires calling resolve.

std.Io.net.IpAddress.parseLiteral

function

Source line 73

Parse an IP address which may include a port.

For IPv4, this is written address:port.

For IPv6, RFC 3986 defines this as an "IP literal", and the port is differentiated from the address by surrounding the address part in brackets "[addr]:port". Even if the port is not given, the brackets are mandatory.

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

Parameters

text: []const u8

Errors

InvalidAddress
InvalidPort

std.Io.net.IpAddress.ParseLiteralError

error-set

Source line 63

Errors

InvalidAddress
InvalidPort

std.Io.net.IpAddress.resolve

function

Source line 131

This function requires an Io parameter because it must query the operating system to convert interface name to index. For example, in "fe80::e0e:76ff:fed4:cf22%eno1", "eno1" must be resolved to an index by creating a socket and then using an ioctl syscall.

For a pure function that cannot handle scopes, see parse.

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

Parameters

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

std.Io.net.IpAddress.resolveIp6

function

Source line 144

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

Parameters

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

Errors

AccessDenied ResolveError
Canceled Cancelable

Caller has requested the async operation to stop.

InterfaceNotFound ResolveError
NameTooLong

The interface name is longer than the host operating system supports.

ParseFailed

If this is returned, more detailed diagnostics can be obtained by calling the Parsed.init function.

SystemResources ResolveError
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.IpAddress.setPort

function

Source line 156

port is native-endian.

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

Parameters

a: *IpAddress
port: u16

std.Io.net.native_os

constant

Source line 2

std.Io.net.OutgoingMessage

container

Source line 982

Fields

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

Initialized with how many bytes of data_ptr to send. After sending succeeds, replaced with how many bytes were actually sent.

control: []const u8 = &.{}

std.Io.net.Protocol

container

Source line 10

Source of truth: Internet Assigned Numbers Authority (IANA)

Fields

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

container

Source line 937

Fields

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

std.Io.net.SendFlags

container

Source line 991

Fields

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

std.Io.net.Server

container

Source line 1567

Fields

socket: Socket
options: AcceptOptions

std.Io.net.Server.accept

function

Source line 1607

Blocks until a client connects to the server.

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

Parameters

s: *Server
io: Io

Errors

BlockedByFirewall

Firewall rules forbid connection.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionAborted

An incoming connection was indicated, but was subsequently terminated by the remote peer prior to accepting the call.

NetworkDown

The network subsystem has failed.

ProcessFdQuotaExceeded

The per-process limit on the number of open file descriptors has been reached.

ProtocolFailure
SocketNotListening

Either listen was never called, or shutdown was called (possibly while this call was blocking). This allows shutdown to be used as a concurrent cancellation mechanism.

SystemFdQuotaExceeded

The system-wide limit on the total number of open files has been reached.

SystemResources

Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock

No connection is already queued and ready to be accepted, and the socket is configured as non-blocking.

std.Io.net.Server.AcceptError

error-set

Source line 1576

Errors

BlockedByFirewall

Firewall rules forbid connection.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionAborted

An incoming connection was indicated, but was subsequently terminated by the remote peer prior to accepting the call.

NetworkDown

The network subsystem has failed.

ProcessFdQuotaExceeded

The per-process limit on the number of open file descriptors has been reached.

ProtocolFailure
SocketNotListening

Either listen was never called, or shutdown was called (possibly while this call was blocking). This allows shutdown to be used as a concurrent cancellation mechanism.

SystemFdQuotaExceeded

The system-wide limit on the total number of open files has been reached.

SystemResources

Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock

No connection is already queued and ready to be accepted, and the socket is configured as non-blocking.

std.Io.net.Server.AcceptOptions

type

Source line 1601

std.Io.net.Server.deinit

function

Source line 1571

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

Parameters

s: *Server
io: Io

std.Io.net.ShutdownError

error-set

Source line 1002

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionAborted
ConnectionResetByPeer
NetworkDown
SocketUnconnected
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.ShutdownHow

container

Source line 1000

Fields

recv
send
both

std.Io.net.Socket

container

Source line 1072

An open port with unspecified protocol.

Fields

handle: Handle
address: IpAddress

Contains the resolved ephemeral port number if requested.

std.Io.net.Socket.close

function

Source line 1100

Leaves address in a valid state.

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

Parameters

s: *const Socket
io: Io

std.Io.net.Socket.closeMany

function

Source line 1104

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

Parameters

io: Io
sockets: []const Socket

std.Io.net.Socket.createPair

function

Source line 1276

Create a set of two sockets that are connected to each other.

Also known as "socketpair".

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

Parameters

io: Io
options: CreatePairOptions

Errors

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

Caller has requested the async operation to stop.

OperationUnsupported
ProcessFdQuotaExceeded

The per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

The system-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory is available. The socket cannot be created until sufficient resources are freed.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.CreatePairError

error-set

Source line 1251

Errors

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

Caller has requested the async operation to stop.

OperationUnsupported
ProcessFdQuotaExceeded

The per-process limit on the number of open file descriptors has been reached.

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

The system-wide limit on the total number of open files has been reached.

SystemResources

Insufficient memory is available. The socket cannot be created until sufficient resources are freed.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.CreatePairOptions

container

Source line 1267

Fields

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

std.Io.net.Socket.Handle

alias

Source line 1097

Underlying platform-defined type which may or may not be interchangeable with a file system file descriptor.

Alias of std.posix.fd_t

std.Io.net.Socket.Mode

container

Source line 1077

Fields

stream

Provides sequenced, reliable, two-way, connection-based byte streams. An out-of-band data transmission mechanism may be supported.

dgram

Supports datagrams (connectionless, unreliable messages of a fixed maximum length).

seqpacket

Provides a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer is required to read an entire packet with each input system call.

raw

Provides raw network protocol access.

rdm

Provides a reliable datagram layer that does not guarantee ordering.

std.Io.net.Socket.receive

function

Source line 1183

Waits for data. Connectionless.

See also:

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

Parameters

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

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer Error

Network connection was unexpectedly closed by sender.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

PortUnreachable Error

A connectionless packet was previously sent successfully, however, it was not received because no service is operating at the destination port of the transport on the remote system. This caused an ICMP port unreachable packet to be returned to the OS where it was queued up to be reported at the next call to send or receive on the bound socket.

ProcessFdQuotaExceeded Error

Per-process limit on the number of open file descriptors has been reached.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemFdQuotaExceeded Error

System-wide limit on the total number of open files has been reached.

SystemResources Error

Insufficient memory or other resource internal to the operating system.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.ReceiveError

error-set

Source line 1177

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer Error

Network connection was unexpectedly closed by sender.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

PortUnreachable Error

A connectionless packet was previously sent successfully, however, it was not received because no service is operating at the destination port of the transport on the remote system. This caused an ICMP port unreachable packet to be returned to the OS where it was queued up to be reported at the next call to send or receive on the bound socket.

ProcessFdQuotaExceeded Error

Per-process limit on the number of open file descriptors has been reached.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemFdQuotaExceeded Error

System-wide limit on the total number of open files has been reached.

SystemResources Error

Insufficient memory or other resource internal to the operating system.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.receiveManyTimeout

type-function

Source line 1232

Waits until at least one message is delivered, possibly returning more than one message. Connectionless.

Returns number of messages received, or error.Timeout if no message arrives early enough.

See also:

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

Parameters

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

Function assumes each element has initialized control field. Initializing with IncomingMessage.init may be helpful.

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

std.Io.net.Socket.receiveTimeout

function

Source line 1205

Waits for data. Connectionless.

Returns error.Timeout if no message arrives early enough.

See also:

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

Parameters

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

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

ConcurrencyUnavailable ConcurrentError

May occur due to a temporary condition such as resource exhaustion, or to the Io implementation not supporting concurrency.

ConnectionResetByPeer Error

Network connection was unexpectedly closed by sender.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

PortUnreachable Error

A connectionless packet was previously sent successfully, however, it was not received because no service is operating at the destination port of the transport on the remote system. This caused an ICMP port unreachable packet to be returned to the OS where it was queued up to be reported at the next call to send or receive on the bound socket.

ProcessFdQuotaExceeded Error

Per-process limit on the number of open file descriptors has been reached.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemFdQuotaExceeded Error

System-wide limit on the total number of open files has been reached.

SystemResources Error

Insufficient memory or other resource internal to the operating system.

Timeout Error
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.ReceiveTimeoutError

error-set

Source line 1196

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

ConcurrencyUnavailable ConcurrentError

May occur due to a temporary condition such as resource exhaustion, or to the Io implementation not supporting concurrency.

ConnectionResetByPeer Error

Network connection was unexpectedly closed by sender.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

PortUnreachable Error

A connectionless packet was previously sent successfully, however, it was not received because no service is operating at the destination port of the transport on the remote system. This caused an ICMP port unreachable packet to be returned to the OS where it was queued up to be reported at the next call to send or receive on the bound socket.

ProcessFdQuotaExceeded Error

Per-process limit on the number of open file descriptors has been reached.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemFdQuotaExceeded Error

System-wide limit on the total number of open files has been reached.

SystemResources Error

Insufficient memory or other resource internal to the operating system.

Timeout Error
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.send

function

Source line 1111

Transfers data to dest, connectionless, in one packet.

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

Parameters

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

Errors

AccessDenied Error

An attempt was made to send to a network/broadcast address as though it was a unicast address.

AddressFamilyUnsupported Error

Operating system or protocol does not support the address family.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionRefused Error

The destination address is not listening. Can still occur for connectionless messages.

ConnectionResetByPeer Error

Network session was unexpectedly closed by recipient.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

FastOpenAlreadyInProgress Error

Another TCP Fast Open is already in progress.

HostUnreachable Error

Network reached but no route to host.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

NetworkUnreachable Error

No route to network.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemResources Error

The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. (Normally, this does not occur in Linux. Packets are just silently dropped when a device queue overflows.)

This is also caused when there is not enough kernel memory available.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.SendError

error-set

Source line 1108

Errors

AccessDenied Error

An attempt was made to send to a network/broadcast address as though it was a unicast address.

AddressFamilyUnsupported Error

Operating system or protocol does not support the address family.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionRefused Error

The destination address is not listening. Can still occur for connectionless messages.

ConnectionResetByPeer Error

Network session was unexpectedly closed by recipient.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

FastOpenAlreadyInProgress Error

Another TCP Fast Open is already in progress.

HostUnreachable Error

Network reached but no route to host.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

NetworkUnreachable Error

No route to network.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemResources Error

The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. (Normally, this does not occur in Linux. Packets are just silently dropped when a device queue overflows.)

This is also caused when there is not enough kernel memory available.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.sendMany

function

Source line 1152

Deprecated; use sendManyTimeout with a timeout of .none.

If this function returns an error, some (but not all) of messages may still have been sent. This condition is not reported by this function, but is reported by sendManyTimeout.

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

Parameters

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

Errors

AccessDenied Error

An attempt was made to send to a network/broadcast address as though it was a unicast address.

AddressFamilyUnsupported Error

Operating system or protocol does not support the address family.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionRefused Error

The destination address is not listening. Can still occur for connectionless messages.

ConnectionResetByPeer Error

Network session was unexpectedly closed by recipient.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

FastOpenAlreadyInProgress Error

Another TCP Fast Open is already in progress.

HostUnreachable Error

Network reached but no route to host.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

NetworkUnreachable Error

No route to network.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemResources Error

The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. (Normally, this does not occur in Linux. Packets are just silently dropped when a device queue overflows.)

This is also caused when there is not enough kernel memory available.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.sendManyTimeout

type-function

Source line 1162

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

Parameters

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

std.Io.net.Socket.sendTimeout

function

Source line 1129

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

Parameters

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

Errors

AccessDenied Error

An attempt was made to send to a network/broadcast address as though it was a unicast address.

AddressFamilyUnsupported Error

Operating system or protocol does not support the address family.

Canceled Cancelable

Caller has requested the async operation to stop.

ConcurrencyUnavailable ConcurrentError

May occur due to a temporary condition such as resource exhaustion, or to the Io implementation not supporting concurrency.

ConnectionRefused Error

The destination address is not listening. Can still occur for connectionless messages.

ConnectionResetByPeer Error

Network session was unexpectedly closed by recipient.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

FastOpenAlreadyInProgress Error

Another TCP Fast Open is already in progress.

HostUnreachable Error

Network reached but no route to host.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

NetworkUnreachable Error

No route to network.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemResources Error

The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. (Normally, this does not occur in Linux. Packets are just silently dropped when a device queue overflows.)

This is also caused when there is not enough kernel memory available.

Timeout Error
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Socket.SendTimeoutError

error-set

Source line 1127

Errors

AccessDenied Error

An attempt was made to send to a network/broadcast address as though it was a unicast address.

AddressFamilyUnsupported Error

Operating system or protocol does not support the address family.

Canceled Cancelable

Caller has requested the async operation to stop.

ConcurrencyUnavailable ConcurrentError

May occur due to a temporary condition such as resource exhaustion, or to the Io implementation not supporting concurrency.

ConnectionRefused Error

The destination address is not listening. Can still occur for connectionless messages.

ConnectionResetByPeer Error

Network session was unexpectedly closed by recipient.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

FastOpenAlreadyInProgress Error

Another TCP Fast Open is already in progress.

HostUnreachable Error

Network reached but no route to host.

MessageOversize Error

The socket type requires that message be sent atomically, and the size of the message to be sent made this impossible. The message was not transmitted, or was partially transmitted.

NetworkDown Error

The local network interface used to reach the destination is offline.

NetworkUnreachable Error

No route to network.

SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemResources Error

The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. (Normally, this does not occur in Linux. Packets are just silently dropped when a device queue overflows.)

This is also caused when there is not enough kernel memory available.

Timeout Error
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.std

alias

Source line 3

Alias of std

std.Io.net.Stream

container

Source line 1284

An open socket connection with a network protocol that guarantees sequencing, delivery, and prevents repetition. Typically TCP or UNIX domain socket.

Fields

socket: Socket

std.Io.net.Stream.close

function

Source line 1321

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

Parameters

s: *const Stream
io: Io

std.Io.net.Stream.max_iovecs_len

constant

Source line 1287

std.Io.net.Stream.read

function

Source line 1302

This is a low-level API that calls the Io interface function directly. For a higher level API, see reader.

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

Parameters

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

Errors

AccessDenied Error

File descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer Error
ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

NetworkDown Error
SocketUnconnected Error
SystemResources Error
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Stream.reader

function

Source line 1501

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

Parameters

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Reader

container

Source line 1329

Fields

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

function

Source line 1412

Clear buffered control data.

pub fn clearControl(r: *Reader) void

Parameters

r: *Reader

std.Io.net.Stream.Reader.controlIterator

function

Source line 1407

Iterate over buffered control messages.

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

Parameters

r: *const Reader

std.Io.net.Stream.Reader.controlSlice

function

Source line 1402

Access raw buffered control data.

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

Parameters

r: *const Reader

std.Io.net.Stream.Reader.Error

error-set

Source line 1338

Errors

AccessDenied Error

File descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer Error
ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

NetworkDown Error
SocketUnconnected Error
SystemResources Error
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Stream.Reader.init

function

Source line 1340

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

Parameters

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Reader.initWithControl

function

Source line 1345

Same as init, but also provides a buffer for storing control data.

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

Parameters

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

std.Io.net.Stream.Reader.readVec

function

Source line 1378

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

Parameters

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

Errors

EndOfStream
ReadFailed

See the Reader implementation for detailed diagnostics.

std.Io.net.Stream.Reader.streamImpl

function

Source line 1370

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

Parameters

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

Errors

EndOfStream

End of stream indicated from the Reader. This error cannot originate from the Writer.

ReadFailed

See the Reader implementation for detailed diagnostics.

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.net.Stream.readerWithControl

function

Source line 1506

Same as reader, but also provides a buffer for storing control data.

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

Parameters

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

std.Io.net.Stream.ReadResult

container

Source line 1289

Fields

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

Whether only some of the control data was received.

When control data is truncated, the extra data essentially disappears into the ether. This is indicative of a design problem, such as the control buffer being too small.

std.Io.net.Stream.readWithControl

function

Source line 1313

Read with control data.

This is a low-level API that calls the Io interface function directly. For a higher level API, see reader.

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

Parameters

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

Errors

AccessDenied Error

File descriptor does not hold the required rights to read from it.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionResetByPeer Error
ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

NetworkDown Error
SocketUnconnected Error
SystemResources Error
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Stream.shutdown

function

Source line 1325

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

Parameters

s: *const Stream
io: Io
how: ShutdownHow

Errors

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionAborted
ConnectionResetByPeer
NetworkDown
SocketUnconnected
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Stream.writer

function

Source line 1515

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

Parameters

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Writer

container

Source line 1418

Fields

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

Will be sent on next drain, then set back to an empty slice.

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

std.Io.net.Stream.Writer.drain

function

Source line 1455

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

Parameters

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

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.net.Stream.Writer.Error

error-set

Source line 1427

Errors

AddressFamilyUnsupported Error

The passed address didn't have the correct address family in its sa_family field.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionRefused Error

The destination address is not listening.

ConnectionResetByPeer Error

Network session was unexpectedly closed by recipient.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

FastOpenAlreadyInProgress Error

Another TCP Fast Open is already in progress.

HostUnreachable Error

Network reached but no route to host.

NetworkDown Error

The local network interface used to reach the destination is down.

NetworkUnreachable Error

No route to network.

SocketNotBound Error
SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemResources Error

The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. (Normally, this does not occur in Linux. Packets are just silently dropped when a device queue overflows.)

This is also caused when there is not enough kernel memory available.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.Stream.Writer.init

function

Source line 1441

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

Parameters

stream: Stream
io: Io
buffer: []u8

std.Io.net.Stream.Writer.sendFile

function

Source line 1478

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

Parameters

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

Errors

EndOfStream

Reached the end of the file being read.

ReadFailed

Detailed diagnostics are found on the File.Reader struct.

Unimplemented

Indicates the caller should do its own file reading; the callee cannot offer a more efficient implementation.

WriteFailed

See the Writer implementation for detailed diagnostics.

std.Io.net.Stream.Writer.WriteFileError

error-set

Source line 1429

Errors

AddressFamilyUnsupported Error

The passed address didn't have the correct address family in its sa_family field.

Canceled Cancelable

Caller has requested the async operation to stop.

ConnectionRefused Error

The destination address is not listening.

ConnectionResetByPeer Error

Network session was unexpectedly closed by recipient.

ConnectionTimedOut Error

The remote peer did not respond to ongoing communication, causing the OS to abort the connection.

EndOfStream

Reached the end of the file being read.

FastOpenAlreadyInProgress Error

Another TCP Fast Open is already in progress.

HostUnreachable Error

Network reached but no route to host.

NetworkDown Error

The local network interface used to reach the destination is down.

NetworkUnreachable Error

No route to network.

ReadFailed

The source File.Reader failed; detailed diagnostics are found on that struct.

SocketNotBound Error
SocketUnconnected Error

Local end has been shut down on a connection-oriented socket, or the socket was never connected.

SystemResources Error

The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. (Normally, this does not occur in Linux. Packets are just silently dropped when a device queue overflows.)

This is also caused when there is not enough kernel memory available.

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

Unimplemented

The Io implementation cannot offer a more efficient file-to-socket path; the caller should fall back to read-based copying. See Io.Writer.sendFile.

std.Io.net.testIp6Parse

function

Source line 1636

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

Parameters

input: []const u8

std.Io.net.testIp6ParseTransform

function

Source line 1640

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

Parameters

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

std.Io.net.UnixAddress

container

Source line 857

Fields

path: []const u8

std.Io.net.UnixAddress.connect

function

Source line 928

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

Parameters

ua: *const UnixAddress
io: Io

Errors

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

Caller has requested the async operation to stop.

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

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock

std.Io.net.UnixAddress.ConnectError

error-set

Source line 910

Errors

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

Caller has requested the async operation to stop.

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

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

WouldBlock

std.Io.net.UnixAddress.init

function

Source line 867

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

Parameters

p: []const u8

Errors

NameTooLong

std.Io.net.UnixAddress.InitError

error-set

Source line 865

Errors

NameTooLong

std.Io.net.UnixAddress.isAbstract

function

Source line 872

pub fn isAbstract(ua: *const UnixAddress) bool

Parameters

ua: *const UnixAddress

std.Io.net.UnixAddress.listen

function

Source line 899

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

Parameters

ua: *const UnixAddress
io: Io
options: ListenOptions

Errors

AccessDenied
AddressFamilyUnsupported
AddressInUse
AddressUnavailable
Canceled Cancelable

Caller has requested the async operation to stop.

FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.UnixAddress.ListenError

error-set

Source line 876

Errors

AccessDenied
AddressFamilyUnsupported
AddressInUse
AddressUnavailable
Canceled Cancelable

Caller has requested the async operation to stop.

FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

std.Io.net.UnixAddress.ListenOptions

container

Source line 892

Fields

kernel_backlog: u31 = default_kernel_backlog

How many connections the kernel will accept on the application's behalf. If more than this many connections pool in the kernel, clients will start seeing "Connection refused".

std.Io.net.UnixAddress.max_len

constant

Source line 860

Source code

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");

/// Source of truth: Internet Assigned Numbers Authority (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 added support for unix sockets in build 17063, redstone 4 is the
/// first release to support them.
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 };

    /// Parse an IP address which may include a port.
    ///
    /// For IPv4, this is written `address:port`.
    ///
    /// For IPv6, RFC 3986 defines this as an "IP literal", and the port is
    /// differentiated from the address by surrounding the address part in
    /// brackets "[addr]:port". Even if the port is not given, the brackets are
    /// mandatory.
    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;
    }

    /// Parse the given IP address string into an `IpAddress` value.
    ///
    /// This is a pure function but it cannot handle IPv6 addresses that have
    /// scope ids ("%foo" at the end). To also handle those, `resolve` must be
    /// called instead.
    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) };
    }

    /// This is a pure function but it cannot handle IPv6 addresses that have
    /// scope ids ("%foo" at the end). To also handle those, `resolveIp6` must be
    /// called instead.
    pub fn parseIp6(text: []const u8, port: u16) Ip6Address.ParseError!IpAddress {
        return .{ .ip6 = try Ip6Address.parse(text, port) };
    }

    /// This function requires an `Io` parameter because it must query the operating
    /// system to convert interface name to index. For example, in
    /// "fe80::e0e:76ff:fed4:cf22%eno1", "eno1" must be resolved to an index by
    /// creating a socket and then using an `ioctl` syscall.
    ///
    /// For a pure function that cannot handle scopes, see `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) };
    }

    /// Returns the port in native endian.
    pub fn getPort(a: IpAddress) u16 {
        return switch (a) {
            inline .ip4, .ip6 => |x| x.port,
        };
    }

    /// `port` is native-endian.
    pub fn setPort(a: *IpAddress, port: u16) void {
        switch (a.*) {
            .ip4 => a.ip4.port = port,
            .ip6 => a.ip6.port = port,
        }
    }

    /// Converts from an IPv4-mapped IPv6 address, or returns the IPv6 address directly.
    pub fn fromIp6(ip6: Ip6Address) IpAddress {
        return if (Ip4Address.fromIp6(ip6)) |ip4| .{ .ip4 = ip4 } else .{ .ip6 = ip6 };
    }

    /// Includes the optional scope ("%foo" at the end) in IPv6 addresses.
    ///
    /// See `format` for an alternative that omits scopes and does
    /// not require an `Io` parameter.
    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),
        }
    }

    /// See `formatResolved` for an alternative that additionally prints the optional
    /// scope at the end of IPv6 addresses and requires an `Io` parameter.
    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{
        /// The address is protected and the current user does not have permission to bind it.
        AccessDenied,
        /// The address is already taken. Can occur when bound port is 0 but
        /// all ephemeral ports are already in use.
        AddressInUse,
        /// A nonexistent interface was requested or the requested address was not local.
        AddressUnavailable,
        /// The local network interface used to reach the destination is offline.
        NetworkDown,
        /// Insufficient memory or other resource internal to the operating system.
        SystemResources,
        /// Per-process limit on the number of open file descriptors has been reached.
        ProcessFdQuotaExceeded,
        /// System-wide limit on the total number of open files has been reached.
        SystemFdQuotaExceeded,
        /// The requested address family (IPv4 or IPv6) is not supported by the operating system.
        AddressFamilyUnsupported,
        ProtocolUnsupportedBySystem,
        ProtocolUnsupportedByAddressFamily,
        SocketModeUnsupported,
        /// One of the `ListenOptions` is not supported by the Io
        /// implementation.
        OptionUnsupported,
    } || Io.UnexpectedError || Io.Cancelable;

    pub const ListenOptions = struct {
        /// How many connections the kernel will accept on the application's behalf.
        /// If more than this many connections pool in the kernel, clients will start
        /// seeing "Connection refused".
        kernel_backlog: u31 = default_kernel_backlog,
        /// Sets SO_REUSEADDR and SO_REUSEPORT on POSIX.
        /// Sets SO_REUSEADDR on Windows, which is roughly equivalent.
        reuse_address: bool = false,
        /// Only connection-oriented modes may be used here, which includes:
        /// * `Socket.Mode.stream`
        /// * `Socket.Mode.seqpacket`
        mode: Socket.Mode = .stream,
        /// Only connection-oriented protocols may be used here, which includes:
        /// * `Protocol.tcp`
        /// * `Protocol.tp`
        /// * `Protocol.dccp`
        /// * `Protocol.sctp`
        protocol: Protocol = .tcp,
    };

    /// Waits for a TCP connection. When using this API, `bind` does not need
    /// to be called. The returned `Server` has an open `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{
        /// The address is protected and the current user does not have permission to bind it.
        AccessDenied,
        /// The address is already taken. Can occur when bound port is 0 but
        /// all ephemeral ports are already in use.
        AddressInUse,
        /// A nonexistent interface was requested or the requested address was not local.
        AddressUnavailable,
        /// The address is not valid for the address family of socket.
        AddressFamilyUnsupported,
        /// Insufficient memory or other resource internal to the operating system.
        SystemResources,
        /// The local network interface used to reach the destination is offline.
        NetworkDown,
        ProtocolUnsupportedBySystem,
        ProtocolUnsupportedByAddressFamily,
        /// Per-process limit on the number of open file descriptors has been reached.
        ProcessFdQuotaExceeded,
        /// System-wide limit on the total number of open files has been reached.
        SystemFdQuotaExceeded,
        SocketModeUnsupported,
        /// One of the `BindOptions` is not supported by the Io
        /// implementation.
        OptionUnsupported,
    } || Io.UnexpectedError || Io.Cancelable;

    pub const BindOptions = struct {
        /// The socket is restricted to sending and receiving IPv6 packets only.
        /// In this case, an IPv4 and an IPv6 application can bind to a single port
        /// at the same time.
        ///
        /// The default is determined by system configuration.
        ip6_only: ?bool = null,
        /// Allow the socket to send datagrams to broadcast addresses.
        /// When not enabled any attempt to send datagrams to a broadcast address
        /// will fail with `error.AccessDenied`
        allow_broadcast: bool = false,
        mode: Socket.Mode,
        protocol: ?Protocol = null,
    };

    /// Associates an address with a `Socket` which can be used to receive UDP
    /// packets and other kinds of non-streaming messages. See `listen` for a
    /// streaming alternative.
    ///
    /// One bound `Socket` can be used to receive messages from multiple
    /// different addresses.
    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,
        /// Insufficient memory or other resource internal to the operating system.
        SystemResources,
        ConnectionPending,
        ConnectionRefused,
        ConnectionResetByPeer,
        HostUnreachable,
        NetworkUnreachable,
        Timeout,
        /// One of the `ConnectOptions` is not supported by the Io
        /// implementation.
        OptionUnsupported,
        /// Per-process limit on the number of open file descriptors has been reached.
        ProcessFdQuotaExceeded,
        /// System-wide limit on the total number of open files has been reached.
        SystemFdQuotaExceeded,
        ProtocolUnsupportedBySystem,
        ProtocolUnsupportedByAddressFamily,
        SocketModeUnsupported,
        /// The user tried to connect to a broadcast address without having the socket broadcast flag enabled or
        /// the connection request failed because of a local firewall rule.
        AccessDenied,
        /// Non-blocking was requested and the operation cannot return immediately.
        WouldBlock,
        NetworkDown,
    } || Io.Timeout.Error || Io.UnexpectedError || Io.Cancelable;

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

    /// Initiates a connection-oriented network stream.
    pub fn connect(address: *const IpAddress, io: Io, options: ConnectOptions) ConnectError!Stream {
        return .{ .socket = try io.vtable.netConnectIp(io.userdata, address, options) };
    }
};

/// An IPv4 address in binary memory layout.
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,
        };
    }

    /// Converts from an IPv4-mapped IPv6 address, or returns `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;
    }

    /// Given an `IpAddress`, converts it to an `Ip4Address` directly, or from
    /// an IPv4-mapped IPv6 address, or returns `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;
    }
};

/// An IPv6 address in binary memory layout.
pub const Ip6Address = struct {
    /// Native endian
    port: u16,
    /// Big endian
    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,
        };
    }

    /// Constructs an IPv4-mapped IPv6 address.
    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,
        };
    }

    /// Given an `IpAddress`, converts it to an `Ip6Address` directly, or via
    /// constructing an IPv4-mapped IPv6 address.
    pub fn fromAny(addr: IpAddress) Ip6Address {
        return switch (addr) {
            .ip4 => |ip4| fromIp4(ip4),
            .ip6 => |ip6| ip6,
        };
    }

    /// An IPv6 address but with `Interface` as a name rather than index.
    pub const Unresolved = struct {
        /// Big endian
        bytes: [16]u8,
        /// Has not been checked to be a valid native interface name.
        /// Externally managed memory.
        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; // so we can alias v4_amended if needed
            if (text.len < 2) return .incomplete;

            // Pre-processing for trailing :IPv4 - If there is no "%iface", and
            // the part after the last ':' has a '.', parse it as ipv4 and
            // convert to IPv6 ASCII text in v4_amended as the new "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];
                }
            }

            // Has to be u16 elements to handle 3-digit hex numbers from compression.
            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),
            };

            // Find the longest zero run
            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;
                }
            }

            // Only compress if the longest zero run is 2 or more
            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) {
                    // Emit "::" for the longest zero run
                    try w.writeAll(if (i == 0) "::" else ":");
                    i += longest_len - 1; // Skip the compressed range
                    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{
        /// If this is returned, more detailed diagnostics can be obtained by
        /// calling `Ip6Address.Parsed.init`.
        ParseFailed,
        /// If this is returned, the IPv6 address had a scope id on it ("%foo"
        /// at the end) which requires calling `resolve`.
        UnresolvedScope,
    };

    /// This is a pure function but it cannot handle IPv6 addresses that have
    /// scope ids ("%foo" at the end). To also handle those, `resolve` must be
    /// called instead, or the lower level `Unresolved` API may be used.
    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{
        /// If this is returned, more detailed diagnostics can be obtained by
        /// calling the `Parsed.init` function.
        ParseFailed,
        /// The interface name is longer than the host operating system supports.
        NameTooLong,
    } || Interface.Name.ResolveError;

    /// This function requires an `Io` parameter because it must query the operating
    /// system to convert interface name to index. For example, in
    /// "fe80::e0e:76ff:fed4:cf22%eno1", "eno1" must be resolved to an index by
    /// creating a socket and then using an `ioctl` syscall.
    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;

    /// Includes the optional scope ("%foo" at the end).
    ///
    /// See `format` for an alternative that omits scopes and does
    /// not require an `Io` parameter.
    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 });
    }

    /// See `formatResolved` for an alternative that additionally prints the optional
    /// scope at the end of addresses and requires an `Io` parameter.
    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,
        },
        //  These are deprecated and/or returned to the address
        //  pool, so despite the RFC, treating them as special
        //  is probably wrong.
        // { "", 11, 0xff, 1, 3 },
        // { "\xfe\xc0", 1, 0xc0, 1, 11 },
        // { "\x3f\xfe", 1, 0xff, 1, 12 },
        // Last rule must match all addresses to stop loop.
        .{
            .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 {
        /// How many connections the kernel will accept on the application's behalf.
        /// If more than this many connections pool in the kernel, clients will start
        /// seeing "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 {
    /// Populated by receive functions.
    from: IpAddress,
    /// Populated by receive functions, points into the caller-supplied buffer.
    data: []u8,
    /// Supplied by caller before calling receive functions; mutated by receive
    /// functions.
    control: []u8,
    /// Populated by receive functions.
    flags: Flags,

    /// Useful for initializing before calling `receiveManyTimeout`.
    pub const init: IncomingMessage = .{
        .from = undefined,
        .data = undefined,
        .control = &.{},
        .flags = undefined,
    };

    pub const Flags = packed struct(u8) {
        /// indicates end-of-record; the data returned completed a record
        /// (generally used with sockets of type SOCK_SEQPACKET).
        eor: bool,
        /// indicates that the trailing portion of a datagram was discarded
        /// because the datagram was larger than the buffer supplied.
        trunc: bool,
        /// indicates that some control data was discarded due to lack of
        /// space in the buffer for ancil‐ lary data.
        ctrunc: bool,
        /// indicates expedited or out-of-band data was received.
        oob: bool,
        /// indicates that no data was received but an extended error from the
        /// socket error queue.
        errqueue: bool,
        _: u3 = 0,
    };
};

pub const OutgoingMessage = struct {
    address: *const IpAddress,
    data_ptr: [*]const u8,
    /// Initialized with how many bytes of `data_ptr` to send. After sending
    /// succeeds, replaced with how many bytes were actually sent.
    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 {
    /// Value 0 indicates `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);
        }

        /// Asserts bytes.len fits in `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;

        /// Corresponds to "if_nametoindex" in libc.
        pub fn resolve(n: *const Name, io: Io) ResolveError!Interface {
            return io.vtable.netInterfaceNameResolve(io.userdata, n);
        }
    };

    pub const NameError = error{
        /// Out of range `index`.
        InterfaceNotFound,
        /// Interface name longer than `Name.max_len`.
        NameTooLong,
    } || Io.UnexpectedError || Io.Cancelable;

    /// Asserts not `none`.
    ///
    /// Corresponds to "if_indextoname" in libc.
    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;
    }
};

/// An open port with unspecified protocol.
pub const Socket = struct {
    handle: Handle,
    /// Contains the resolved ephemeral port number if requested.
    address: IpAddress,

    pub const Mode = enum {
        /// Provides sequenced, reliable, two-way, connection-based byte
        /// streams. An out-of-band data transmission mechanism may be
        /// supported.
        stream,
        /// Supports datagrams (connectionless, unreliable messages of a fixed
        /// maximum length).
        dgram,
        /// Provides  a  sequenced,  reliable,  two-way connection-based data
        /// transmission path for datagrams of fixed maximum length; a consumer
        /// is required to read an entire packet with each input system call.
        seqpacket,
        /// Provides raw network protocol access.
        raw,
        /// Provides a reliable datagram layer that does not guarantee ordering.
        rdm,
    };

    /// Underlying platform-defined type which may or may not be
    /// interchangeable with a file system file descriptor.
    pub const Handle = std.posix.fd_t;

    /// Leaves `address` in a valid state.
    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;

    /// Transfers `data` to `dest`, connectionless, in one packet.
    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;
    }

    /// Deprecated; use `sendManyTimeout` with a timeout of `.none`.
    ///
    /// If this function returns an error, some (but not all) of `messages` may
    /// still have been sent. This condition is not reported by this function,
    /// but is reported by `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;

    /// Waits for data. Connectionless.
    ///
    /// See also:
    /// * `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;

    /// Waits for data. Connectionless.
    ///
    /// Returns `error.Timeout` if no message arrives early enough.
    ///
    /// See also:
    /// * `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;
    }

    /// Waits until at least one message is delivered, possibly returning more
    /// than one message. Connectionless.
    ///
    /// Returns number of messages received, or `error.Timeout` if no message
    /// arrives early enough.
    ///
    /// See also:
    /// * `receive`
    /// * `receiveTimeout`
    pub fn receiveManyTimeout(
        s: *const Socket,
        io: Io,
        /// Function assumes each element has initialized `control` field.
        /// Initializing with `IncomingMessage.init` may be helpful.
        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,
        /// The per-process limit on the number of open file descriptors has been reached.
        ProcessFdQuotaExceeded,
        /// The system-wide limit on the total number of open files has been reached.
        SystemFdQuotaExceeded,
        /// Insufficient memory is available. The socket cannot be created
        /// until sufficient resources are freed.
        SystemResources,
        ProtocolUnsupportedByAddressFamily,
        SocketModeUnsupported,
    } || Io.UnexpectedError || Io.Cancelable;

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

    /// Create a set of two sockets that are connected to each other.
    ///
    /// Also known as "socketpair".
    pub fn createPair(io: Io, options: CreatePairOptions) CreatePairError![2]Socket {
        return io.vtable.netSocketCreatePair(io.userdata, options);
    }
};

/// An open socket connection with a network protocol that guarantees
/// sequencing, delivery, and prevents repetition. Typically TCP or UNIX domain
/// socket.
pub const Stream = struct {
    socket: Socket,

    const max_iovecs_len = 8;

    pub const ReadResult = struct {
        data_len: usize,
        control_len: usize = 0,
        /// Whether only some of the control data was received.
        ///
        /// When control data is truncated, the extra data essentially
        /// disappears into the ether. This is indicative of a design problem,
        /// such as the control buffer being too small.
        control_truncated: bool = false,
    };

    /// This is a low-level API that calls the `Io` interface function directly.
    /// For a higher level API, see `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;
    }

    /// Read with control data.
    ///
    /// This is a low-level API that calls the `Io` interface function directly.
    /// For a higher level API, see `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, &.{});
        }

        /// Same as `init`, but also provides a buffer for storing control data.
        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;
        }

        /// Access raw buffered control data.
        pub fn controlSlice(r: *const Reader) []align(cmsg_align) u8 {
            return r.control_buffer[0..r.control_len];
        }

        /// Iterate over buffered control messages.
        pub fn controlIterator(r: *const Reader) cmsg.Iterator {
            return .{ .control = r.controlSlice() };
        }

        /// Clear buffered control data.
        pub fn clearControl(r: *Reader) void {
            r.control_len = 0;
            r.control_truncated = false;
        }
    };

    pub const Writer = struct {
        io: Io,
        interface: Io.Writer,
        /// Will be sent on next drain, then set back to an empty slice.
        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{
            /// The `Io` implementation cannot offer a more efficient
            /// file-to-socket path; the caller should fall back to read-based
            /// copying. See `Io.Writer.sendFile`.
            Unimplemented,
            /// Reached the end of the file being read.
            EndOfStream,
            /// The source `File.Reader` failed; detailed diagnostics are found
            /// on that struct.
            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);
    }

    /// Same as `reader`, but also provides a buffer for storing control data.
    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;
/// Utility Functions for interacting with POSIX socket control messages.
/// See also https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_socket.h.html
pub const cmsg = struct {
    const cmsghdr = std.posix.cmsghdr;

    /// Equivalent to `CMSG_SPACE` in C.
    pub fn space(data_len: usize) usize {
        return std.mem.alignForward(usize, @sizeOf(cmsghdr), cmsg_align) +
            std.mem.alignForward(usize, data_len, cmsg_align);
    }

    /// Equivalent to `CMSG_LEN` in C.
    pub fn len(data_len: @FieldType(cmsghdr, "len")) @TypeOf(data_len) {
        return std.mem.alignForward(@TypeOf(data_len), @sizeOf(cmsghdr), cmsg_align) + data_len;
    }

    /// Equivalent to `CMSG_DATA` in C.
    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)..]);
    }

    /// Equivalent to `CMSG_FIRSTHDR` and `CMSG_NXTHDR` in C.
    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{
        /// The per-process limit on the number of open file descriptors has been reached.
        ProcessFdQuotaExceeded,
        /// The system-wide limit on the total number of open files has been reached.
        SystemFdQuotaExceeded,
        /// Not enough free memory. This often means that the memory allocation is limited
        /// by the socket buffer limits, not by the system memory.
        SystemResources,
        /// Either `listen` was never called, or `shutdown` was called (possibly while
        /// this call was blocking). This allows `shutdown` to be used as a concurrent
        /// cancellation mechanism.
        SocketNotListening,
        /// The network subsystem has failed.
        NetworkDown,
        /// No connection is already queued and ready to be accepted, and
        /// the socket is configured as non-blocking.
        WouldBlock,
        /// An incoming connection was indicated, but was subsequently terminated by the
        /// remote peer prior to accepting the call.
        ConnectionAborted,
        /// Firewall rules forbid connection.
        BlockedByFirewall,
        ProtocolFailure,
    } || Io.UnexpectedError || Io.Cancelable;

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

    /// Blocks until a client connects to the server.
    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"); // IPv4 Mapped
    try testIp6Parse("64:ff9b::192.0.2.1"); // RFC 6052 Well-Known Prefix
    try testIp6Parse("fe80::e0e:76ff:fed4:cf22%iface.123"); // edge case for :ipv4 parsing
    try testIp6ParseTransform("::c000:201", "::192.0.2.1"); // Deprecated "IPv4 Compatible"
    try testIp6ParseTransform("::ffff:192.0.2.1", "::ffff:c000:201"); // Non-canonical in Mapped
    try testIp6ParseTransform("2001:db8::c000:201", "2001:db8::192.0.2.1"); // arbitrary prefix
    try testIp6ParseTransform("2001:db8::201", "2001:db8::0.0.2.1"); // Compression+:IPv4 edge case
}
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");
}