# z46
A Zig library for parsing, validating, formatting and classifying IPv4 and
IPv6 addresses, CIDR networks, the ranges that CIDR cannot express, and the
endpoints that pair an address with a port.
Everything is allocation-free and works at comptime as readily as at runtime.
These are values, not sockets: nothing here opens a connection or touches the
network, and conversions to and from the `std.Io.net` socket address types are
provided for when you need one.
The [API reference](https://jeff.jcollie.page/z46/) is published from the
default branch, and every function in it carries a worked example that is
compiled and run as part of the test suite. `zig build docs-serve` builds the
same pages and serves them at , with `-Ddocs-port=N` to
choose another port. A server
is needed rather than opening the files directly, because the viewer fetches
its data at runtime and a browser refuses that from a `file://` page; `zig std`
works this way for the same reason. `zig build docs` alone just writes the
pages to `zig-out/docs`.
## Quick start
```zig
const z46 = @import("z46");
const network = try z46.Ipv4Network.parse("192.168.1.0/24");
const address = try z46.Ipv4Address.parse("192.168.1.42");
std.debug.assert(network.contains(address));
std.debug.assert(address.isPrivate());
// {f} formats any of these types in canonical form.
std.debug.print("{f} in {f}\n", .{ address, network });
```
An address that remembers the network it sits on — the `192.168.1.42/24` an
operating system configures on a link, host bits and all — is an interface
rather than a network:
```zig
const eth0 = try z46.Ipv4Interface.parse("192.168.1.42/24");
std.debug.assert(eth0.address.eql(address));
std.debug.assert(eth0.network().eql(network));
std.debug.print("{f} on {f}\n", .{ eth0.address, eth0.network() });
```
The name an address is looked up under in the reverse DNS is one of the few
derived forms nobody writes out reliably by hand, so it has a function:
```zig
var buffer: [z46.Address.max_reverse_name_len]u8 = undefined;
const v4 = try z46.Ipv4Address.parse("10.2.0.52");
try expectEqualStrings("52.0.2.10.in-addr.arpa", try v4.reverseName(&buffer));
const v6 = try z46.Ipv6Address.parse("2001:db8::cb01");
// 1.0.b.c.0.0. ... .0.8.b.d.0.1.0.0.2.ip6.arpa
_ = try v6.reverseName(&buffer);
```
`writeReverseName` is the same name written straight to a `*std.Io.Writer`,
for a caller that is already writing a stream — a zone file, a log line, a
query being assembled — and has no reason to hold the name in a buffer first:
```zig
try address.writeReverseName(w);
```
Both follow the label order the DNS delegates in, so an IPv4 name is the
dotted quad read backwards under `in-addr.arpa` (RFC 1035 §3.5) and an IPv6
name is all 32 nibbles read backwards under `ip6.arpa` (RFC 3596 §2.5) — no
zero nibble elided, whatever the canonical text form compresses. The names
carry no trailing dot.
`Ipv6Address.nibbles` writes those 32 nibbles the other way round, most
significant first and with no suffix. That is the reverse name with neither
step applied, and it is worth having on its own because the nibble form turns
up where no lookup does: SPF's `%{i}` macro expands an IPv6 client to exactly
this and leaves the reversing to a separate transformer.
Note that an IPv4-mapped IPv6 address gets an `ip6.arpa` name like any other
IPv6 address, which is almost certainly not the name that answers; convert it
with `toIpv4Mapped` first if the IPv4 name is the one wanted.
When the version is not known ahead of time, use the union types:
```zig
const address = try z46.Address.parse("2001:db8::1");
switch (address) {
.ipv4 => |v4| ...,
.ipv6 => |v6| ...,
}
```
Parsing the host out of a URL, where an IPv6 address arrives in brackets and an
IPv4 address does not:
```zig
const host = try z46.Address.parseWithOptions(text, .{ .allow_brackets = true });
```
When the port comes along too, parse the authority as an endpoint:
```zig
const endpoint = try z46.Endpoint.parse("[2001:db8::1]:443");
const connect_to = endpoint.toStdAddress(); // a std.Io.net.IpAddress
```
Validation alone needs no error handling:
```zig
if (!z46.Network.isValid(user_input)) return error.BadConfig;
```
## Types
| Type | Holds |
| --- | --- |
| `Ipv4Address` | a 32-bit address |
| `Ipv6Address` | a 128-bit address |
| `Ipv4Network` | an IPv4 network in CIDR notation |
| `Ipv6Network` | an IPv6 network in CIDR notation |
| `Ipv4Interface` | an IPv4 address with the prefix length of its network |
| `Ipv6Interface` | an IPv6 address with the prefix length of its network |
| `Ipv4Range` | an inclusive range of IPv4 addresses |
| `Ipv6Range` | an inclusive range of IPv6 addresses |
| `Ipv4Endpoint` | an IPv4 address paired with a port |
| `Ipv6Endpoint` | an IPv6 address paired with a port |
| `Address` | a tagged union of either address type |
| `Network` | a tagged union of either network type |
| `Interface` | a tagged union of either interface type |
| `Range` | a tagged union of either range type |
| `Endpoint` | a tagged union of either endpoint type |
| `Family` | `.ipv4` or `.ipv6` |
| `Scope` | the one category an address falls into |
Every type provides `parse`, `isValid`, `format` (via the `{f}` specifier),
`bufPrint`, `eql`, `order`, and the `jsonStringify` and `jsonParse` that
`std.json` looks for. Addresses add `fromInt`/`toInt`, conversions
between the two versions, `next`, `prev`, `add` and `sub` for stepping through
the address space, `reverseName` and `writeReverseName` for the name
the address is looked up under in the reverse DNS, and a set of classification
predicates
(`isLoopback`, `isPrivate`, `isLinkLocal`, `isMulticast`, `isDocumentation`,
`isGlobal` and more) that follow the IANA special-purpose address registries.
Networks add `netmask`, `hostmask`, `networkAddress`, `broadcastAddress` or
`lastAddress`, `addressCount`, `hostCount`, `firstHost`, `lastHost`,
`isSingleAddress`, `contains`, `containsNetwork`, `overlaps`, `supernet`,
`exclude`, `join`, `merge`, and the `subnets`, `addresses` and `hosts`
iterators.
### Which category an address is in
The predicates each answer one question, and asking "what *is* this address"
with them means calling a dozen of them in an order that matters:
`255.255.255.255` is inside `240.0.0.0/4`, so checking the reserved block
first gets the wrong answer. `scope` runs that cascade once and returns a
single `Scope`:
```zig
switch (address.scope()) {
.private, .loopback, .link_local => return error.NotRoutable,
.global => {},
else => |other| log.warn("unexpected {f} address", .{other}),
}
```
It is a summary and not a substitute: an address can be a documentation
address *and* inside `2001::/23`, and only the predicates will say so.
### Writing an IPv6 address out in full
`format` writes the canonical RFC 5952 form, which is the one an address
should be published as. `writeExpanded` writes the other one — every group at
its full four digits, no `::` — because it is the only form with a fixed
width:
```zig
var buffer: [z46.Ipv6Address.max_expanded_len]u8 = undefined;
const text = try address.expanded(&buffer);
// 2001:0db8:0000:0000:0000:0000:0000:0001
try w.print("{f}", .{std.fmt.alt(address, .writeExpanded)});
```
That fixed width is what makes a column of addresses line up, makes them sort
lexically in the same order they sort numerically, and makes a regenerated
configuration diff a line at a time. IPv4 has no separate expanded form — its
text is already fixed in structure, and padding the octets would produce the
leading zeros this library refuses to parse — so `Address.writeExpanded`
writes an IPv4 address exactly as `format` does.
An interface is a network read the other way round. A network is
`192.168.1.0/24` and rejects anything else; an interface is `192.168.1.42/24`,
keeping the host bits that identify one machine on that network, so it is the
type for what is configured on a link or read back out of `ip addr`. It adds
`network()`, which hands back the `Ipv4Network` or `Ipv6Network` it sits on,
along with `netmask`, `hostmask`, `networkAddress`, `broadcastAddress` or
`lastAddress`, `hostBits` for the host part on its own, and the
`isNetworkAddress`, `isBroadcastAddress` and `isHostAddress` predicates that
say whether the address is one a host may actually be given.
Endpoints hold an `address` and a `port` and convert to and from the standard
library's `std.Io.net` socket address types, and to and from the C socket
address structures.
## Ranges, and the networks that cover them
`10.0.0.10-10.0.0.20` is a perfectly ordinary thing for a DHCP pool or an
access list to name, and it is not a network: it does not start on a
power-of-two boundary and its size is not a power of two. CIDR notation cannot
write it down at all. `Ipv4Range` and `Ipv6Range` hold what was meant, and
`prefixes` hands over the blocks it takes to cover it:
```zig
const pool = try z46.Ipv4Range.parse("10.0.0.10-10.0.0.20");
var it = pool.prefixes();
while (it.next()) |network| std.debug.print("{f}\n", .{network});
// 10.0.0.10/31
// 10.0.0.12/30
// 10.0.0.16/30
// 10.0.0.20/32
```
The blocks are the smallest set that covers the range exactly: nothing outside
it, everything inside it, no two overlapping. They come out in ascending
address order and are not all the same size, which is why this is not a
conversion anyone does by hand. `toNetwork` returns the single network when
the range happens to be one, and null when it is not.
Nothing in the IETF documents defines a text form for a range, so the one
parsed and written here — two addresses with a `-` between them and no spaces
— is a convention rather than a standard. It is the one `nmap` and most access
lists use.
Going the other way, `exclude` takes one network out of another:
```zig
const allowed = try z46.Ipv4Network.parse("192.0.2.0/24");
const blocked = try z46.Ipv4Network.parse("192.0.2.0/26");
var it = allowed.exclude(blocked);
while (it.next()) |network| std.debug.print("{f}\n", .{network});
// 192.0.2.128/25
// 192.0.2.64/26
```
Removing one prefix from another cannot leave one prefix behind, so the answer
is an iterator — at most 32 networks for IPv4 and 128 for IPv6, allocating
nothing, largest block first. Nothing is an error: a network that does not
overlap is not removed and comes back whole, and one that covers everything
leaves nothing behind.
`merge` is the operation that keeps a generated list from growing without
bound. It sorts a slice in place and folds it down to the smallest set of
networks covering exactly the same addresses:
```zig
var list = [_]z46.Ipv4Network{
try .parse("192.0.2.64/26"),
try .parse("192.0.2.0/26"),
try .parse("192.0.2.128/25"),
};
for (z46.Ipv4Network.merge(&list)) |network| std.debug.print("{f}\n", .{network});
// 192.0.2.0/24
```
Two things are folded away: a network already inside another disappears, and
two networks that are the two halves of one larger network become that larger
network. The second is applied repeatedly, which is why the three entries
above come back as one rather than two — the two `/26`s make a `/25`, and that
`/25` and the next one make the `/24`. `Ipv4Network.join` is that step on its
own, for when the question is whether two entries in a list can be written as
one.
This is the one operation here that takes a mutable slice rather than
returning something. Sorting is all it needs and sorting can be done in place,
so the caller keeps ownership of the storage and decides where it came from;
what is past the returned slice is still the caller's networks, merely no
longer needed, rather than freed memory. `Network.merge` takes a mixed slice
and merges the two versions independently, since nothing folds across the
boundary.
The result is checked against a bitmap of every address covered, built one
address at a time over two thousand random inputs, which is the only way to be
sure a fold was neither missed nor overreached.
`Ipv4Range.merge` is the same operation on ranges, and it folds further.
Networks combine only when they are the two halves of a larger network, which
is a question about alignment; ranges combine whenever no address separates
them, which is a question about nothing but the addresses:
```zig
var pools = [_]z46.Ipv4Range{
try .parse("10.0.0.6-10.0.0.9"),
try .parse("10.0.0.1-10.0.0.5"),
};
const one = z46.Ipv4Range.merge(&pools);
// one.len == 1, holding 10.0.0.1-10.0.0.9
```
The two networks covering those pools would have stayed apart. Folding as
ranges and re-splitting with `prefixes` afterwards therefore gives a CIDR set
no larger than merging as networks would have, which is what the command line
tool's `--merge` does.
## What an IPv6 address is carrying
Several IPv6 ranges are not just addresses but packed structures, and the
predicates that recognise them are only half the answer. These pull the
contents out:
```zig
// 6to4 (RFC 3056) names the IPv4 host doing the tunnelling.
const v4 = (try z46.Ipv6Address.parse("2002:c000:204::1")).sixtofour().?;
// Teredo (RFC 4380) packs a whole tunnel endpoint into one address.
const t = (try z46.Ipv6Address.parse("2001:0:4136:e378:8000:63bf:3fff:fdd2")).teredo().?;
// t.server 65.54.227.120, t.client 192.0.2.45, t.port 40000
```
The client address and port are stored complemented in the address, because a
NAT rewriting addresses it finds in payloads would otherwise rewrite these too
and break the tunnel. They come back in the clear.
NAT64 is the awkward one. RFC 6052 §2.2 defines six layouts, one per
translation prefix length, and only a `/32` and a `/96` keep the four octets
of the embedded IPv4 address together — bits 64 to 71 are reserved, and the
address has to step over them:
```zig
const embedded = try address.translatedIpv4(64);
```
Nothing in the address says which layout was used, which is why this takes a
prefix length rather than working it out. A caller that does not know its own
translation prefix cannot ask the question at all; the well-known prefix
`64:ff9b::/96` is the one case where the length is known without being
configured. (Building such an address is not provided — that is the
translator's job, not a parser's.)
Two derived addresses that nothing else in this family of libraries provides:
```zig
// The group neighbour discovery asks on (RFC 4291 §2.7.1).
const group = address.solicitedNodeMulticast();
// The address a MAC gives itself under SLAAC (RFC 4862, RFC 4291 appendix A).
const slaac = z46.Ipv6Address.fromMac(try .parse("2001:db8:1:2::"), mac);
const back = slaac.macFromInterfaceIdentifier(); // ?[6]u8
```
The `ff fe` that marks a MAC-derived identifier is two bytes, so an identifier
that was never derived from one has about a one in 65536 chance of answering
anyway. Read `macFromInterfaceIdentifier` as "shaped like a MAC-derived
address" rather than as proof.
## Text that means two things
`parse` is strict because the alternative is a security problem, and this is
the function that makes the argument concrete:
```zig
std.debug.assert(z46.Ipv4Address.isAmbiguous("0x7f.0.0.1"));
std.debug.assert(z46.Ipv4Address.isAmbiguous("127.1"));
std.debug.assert(z46.Ipv4Address.isAmbiguous("127.0.0.1 evil"));
std.debug.assert(!z46.Ipv4Address.isAmbiguous("127.0.0.1"));
```
A program that checks an address against a deny list with a strict parser and
then hands the original text to something that resolves or connects with the
system's own parser has two readings of one string, and a filter that can be
walked straight past. `isAmbiguous` says which text to reject loudly:
`parseLegacy` gives the other reading, for the log line that explains why.
`parseLegacy` accepts everything `inet_aton` does — fewer than four parts,
octal from a leading `0`, hexadecimal from a leading `0x`. It also stops at
the first whitespace character and discards everything after it, which is not
a shorthand but a consequence of how the C function decides it has finished,
and which turns a trailing field of any kind into something a C parser
silently throws away. That behaviour was measured against glibc rather than
read off the manual page, and the two agree on 24,000 generated strings.
The command line tool says so when it meets such text:
```
$ z46 0x7f.0.0.1
0x7f.0.0.1
invalid address: InvalidCharacter
ambiguous a C library's inet_aton reads this as 127.0.0.1
```
There is no IPv6 counterpart: `inet_pton` has no shorthands to disagree about.
## JSON
Every type declares `jsonStringify` and `jsonParse`, which `std.json` picks up
by name, so each is a JSON string holding exactly what `format` writes:
```zig
const Config = struct { listen: z46.Endpoint, allow: []const z46.Network };
const parsed = try std.json.parseFromSlice(Config, allocator, text, .{});
```
Parsing is as strict inside a document as anywhere else, so a configuration
naming `192.168.01.1` is a configuration with a bad address in it. The one
thing lost is the specific reason: `std.json`'s error set is closed and
everything arrives as `error.InvalidCharacter`, so a program that has to tell
a user what was wrong with what they wrote should read the field as a string
and call `parse` itself. Reading a string is bounded by the type's own
`max_text_len`, so a document offering a megabyte-long "address" is refused
before it is assembled.
## C socket addresses
`std.Io.net` is what most Zig code wants, but a `bind`, a `connect`, a
`getaddrinfo` result or anything reached through `std.posix` deals in the C
structures instead. Addresses and endpoints fill one in through a pointer and
read one back:
```zig
var storage: std.posix.sockaddr.storage = undefined;
const endpoint = try z46.Endpoint.parse("[2001:db8::1]:443");
// Returns the number of bytes written: the socklen_t that goes with it.
const len = endpoint.writeSockaddr(&storage);
try std.posix.connect(fd, @ptrCast(&storage), len);
// And back again, deciding the version from the structure's family.
const peer = try z46.Endpoint.fromSockaddr(&storage);
```
`std.posix.sockaddr`, `std.c.sockaddr` and `std.os.linux.sockaddr` are one
family of structures under three names, and nothing in the signature names any
of them: the pointer is taken as `anytype` and its type says which shape it
points at — a `sockaddr_in`, a `sockaddr_in6`, or the family-agnostic
`sockaddr` and `sockaddr_storage` that carry either. So the call compiles
against whichever namespace the surrounding code already uses, and a pointer
that is not a socket address at all is a compile error naming the type.
The `AF_INET` and `AF_INET6` values come from that same namespace rather than
from the host, read off the defaults its own `in` and `in6` declarations give
their `family` fields. That is worth doing rather than assuming, because
`AF_INET6` is 10 on Linux, 30 on Darwin, 28 on FreeBSD and 23 on Windows: a
constant taken from the wrong namespace is wrong silently.
| Call | Effect |
| --- | --- |
| `Ipv4Address.writeSockaddr(port, sa)` | fills in a `sockaddr_in` |
| `Ipv6Address.writeSockaddr(port, sa)` | fills in a `sockaddr_in6` |
| `Ipv4Endpoint.writeSockaddr(sa)` | fills in a `sockaddr_in` |
| `Ipv6Endpoint.writeSockaddr(sa)` | fills in a `sockaddr_in6` |
| `Address.writeSockaddr(port, sa)` | fills in whichever the version calls for |
| `Endpoint.writeSockaddr(sa)` | fills in whichever the version calls for |
| `T.fromSockaddr(sa)` | reads one back, for any of those `T` |
| `Ipv6Address.sockaddrOptions(sa)` | the flow label and scope identifier |
The whole structure is written each time, so nothing is left undefined — the
`sin_zero` padding included, which some kernels compare. Writing an IPv6
address leaves the flow label and the scope identifier zero;
`writeSockaddrWithOptions` sets them, and a link-local address wants it, since
`fe80::1` means nothing without the interface it is scoped to.
Reading is where it can fail, and only in one way:
`error.UnexpectedAddressFamily` when the structure's `family` is not one the
type being read accepts. A
pointer to an `in` or an `in6` has already settled the version and its family
is checked against the one that type declares; a pointer to a `sockaddr` or a
`sockaddr_storage` is read as whichever version its family names.
A `sockaddr` pointer says nothing about how much storage is really behind it —
that is as true here as it is in C, because it is the same pointer. A
`sockaddr_in6` is 28 bytes where a `sockaddr_in` is 16, so a `*sockaddr`
written through has to point at something large enough for the version being
written; `sockaddr.storage` is the usual way to have that, and is what
`accept` and `recvfrom` are given. A pointer to an `in` or an `in6` carries its
own size and needs no such care: writing the wrong version into one is a
compile error, as is asking either union type to write into one at all, since
the version is not known until run time.
## Parsing is strict
Only canonical text is accepted, because the alternative is a security
problem: a parser that reads `192.168.01.1` as octal and another that reads it
as decimal will disagree about which network an address belongs to.
* Exactly four decimal octets for IPv4. The `inet_aton` shorthands (`127.1`,
`0x7f.0.0.1`, octal octets) are rejected.
* No leading zeros in an IPv4 octet or in a prefix length.
* No leading or trailing whitespace.
* IPv6 accepts `::` compression, uppercase hex and a trailing dotted-quad
(`::ffff:192.0.2.1`), and rejects a `::` that compresses nothing.
* A zone identifier (`fe80::1%eth0`) is rejected by `Ipv6Address.parse`;
`Ipv6Address.parseZoned` accepts one and hands back the zone text.
* The square brackets a URL puts around an IPv6 address are rejected too.
`Ipv6Address.parseWithOptions(text, .{ .allow_brackets = true })` accepts
both `[2001:db8::1]` and the bare form, with `parseZonedWithOptions` doing
the same for `[fe80::1%eth0]` and `Address.parseWithOptions` taking the same
option for text that could be either version. Only the address is parsed, so
an authority such as `[2001:db8::1]:443` has to have its port split off
first.
* An endpoint is an address *and* a port, so a bare address is
`error.MissingPort`. An IPv6 endpoint must bracket its address
(`[2001:db8::1]:443`); without brackets the `:` before the port cannot be
told from the colons in the address, which is reported as
`error.MissingBrackets` rather than as a malformed address. Ports are
parsed as strictly as everything else: no leading zeros, and nothing above
65535. Port 0 is accepted, since that is how a caller asks the operating
system to pick one.
* Networks must have their host bits clear: `192.168.1.1/24` is
`error.HasHostBits`. Use `parseTruncate` to clear them instead, or one of
the interface types to keep them. An IPv4 network or interface may be
written with a dotted netmask (`10.0.0.0/255.0.0.0`), and text with no `/`
is read as a single host.
* A network can also be parsed by the rules of another standard, through
`parseWithOptions`. `Ipv4Network.ParseOptions.spf` and its IPv6 counterpart
are the `ip4:` and `ip6:` networks of an SPF record (RFC 7208 §5.6):
```zig
// The netmask spelling is not in SPF's grammar at all...
try expectError(
error.InvalidPrefix,
z46.Ipv4Network.parseWithOptions("10.0.0.0/255.0.0.0", .spf),
);
// ...while host bits are, since the mechanism compares only the
// high-order bits, so `ip4:192.0.2.130/24` means `192.0.2.0/24`.
const network = try z46.Ipv4Network.parseWithOptions("192.0.2.130/24", .spf);
std.debug.assert(network.eql(try z46.Ipv4Network.parse("192.0.2.0/24")));
```
Everything else §5.6 asks for — four `qnum`s with no leading zeros, a
prefix length of one or two digits (three for IPv6) with none of its own,
an omitted length meaning `/32` or `/128` — is what this parser does
anyway. Strip the `ip4:` first; only the network is parsed. The two
switches are separate, so a validator that wants to call a record sloppy
rather than read it the way a checker would can ask for
`.{ .allow_netmask = false }` and keep `error.HasHostBits`.
Errors are specific — `error.LeadingZero`, `error.OctetOutOfRange`,
`error.RedundantEllipsis`, `error.HasHostBits` — so a program can explain what
was wrong with what a user typed.
Output is canonical too: IPv6 follows RFC 5952 (lowercase, no leading zeros,
longest run of zero groups compressed, leftmost run on a tie). IPv4-mapped
addresses print as `::ffff:a.b.c.d`; the deprecated IPv4-compatible range
`::/96` prints in plain hex, so `::3` does not come out as `::0.0.0.3`.
## Using it as a dependency
```
zig fetch --save https://git.jcollie.dev/jeff/z46/archive/v0.2.0.tar.gz
```
Fetching a tag keeps the hash stable; `archive/main.tar.gz` tracks the branch
instead and changes hash on every push.
```zig
// build.zig
const z46 = b.dependency("z46", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("z46", z46.module("z46"));
```
## Command line tool
The package also builds a small `z46` binary that validates and describes its
arguments. Text holding a `-` is read as a range, text holding a `/` as a
network when its host bits are clear and as an interface when they are not,
text carrying a port as an endpoint, and everything else as an address:
```
$ z46 192.168.1.42 '[2001:db8::1]:443' 2001:db8::/126
192.168.1.42
family IPv4
canonical 192.168.1.42
scope private
reverse 42.1.168.192.in-addr.arpa
as IPv6 ::ffff:192.168.1.42
[2001:db8::1]:443
family IPv6
canonical [2001:db8::1]:443
address 2001:db8::1
port 443
scope documentation
reverse 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa
expanded 2001:0db8:0000:0000:0000:0000:0000:0001
2001:db8::/126
family IPv6
canonical 2001:db8::/126
network 2001:db8::
netmask ffff:ffff:ffff:ffff:ffff:ffff:ffff:fffc
hostmask ::3
last 2001:db8::3
hosts 2001:db8::1 - 2001:db8::3 (3)
addresses 4
```
An interface is described as the address it carries and then as the network it
sits on:
```
$ z46 192.168.1.42/24
192.168.1.42/24
family IPv4
canonical 192.168.1.42/24
address 192.168.1.42
network 192.168.1.0
netmask 255.255.255.0
hostmask 0.0.0.255
broadcast 192.168.1.255
hosts 192.168.1.1 - 192.168.1.254 (254)
scope private
reverse 42.1.168.192.in-addr.arpa
as IPv6 ::ffff:192.168.1.42
```
A range is described by its two ends and then by the blocks it takes to cover
it, which is the form a routing table or a firewall wants:
```
$ z46 10.0.0.10-10.0.0.20
10.0.0.10-10.0.0.20
family IPv4
canonical 10.0.0.10-10.0.0.20
first 10.0.0.10
last 10.0.0.20
addresses 11
networks 10.0.0.10/31 10.0.0.12/30 10.0.0.16/30 10.0.0.20/32
```
`--merge` folds the arguments together instead of describing them. Everything
is read as a range — a bare address is a range of one, a network is the range
it covers — merged, and printed as the smallest set of CIDR networks covering
exactly the same addresses, which is the form a routing table or a firewall
takes:
```
$ z46 --merge 192.0.2.0/26 192.0.2.64/26 192.0.2.128/25 10.0.0.5 2001:db8::/33 2001:db8:8000::/33
10.0.0.5/32
192.0.2.0/24
2001:db8::/32
```
Reading everything as a range rather than as a network is what makes this the
tightest answer available: two networks that merely touch cannot be written as
one network but are one range, and re-splitting afterwards costs nothing. The
two versions fold separately and IPv4 is printed first.
It exits 1 if any argument is invalid, so `z46 -q "$input"` works as a
validation check in a script. Note that this accepts an interface wherever it
accepts a network, so `10.0.0.1/8` passes; the library's `Network.isValid` is
the stricter check.
The flake packages the tool, so it runs without a checkout or a Zig toolchain:
```console
$ nix run git+https://git.jcollie.dev/jeff/z46.git -- 192.168.1.42/24
$ nix profile install git+https://git.jcollie.dev/jeff/z46.git
```
`nix build` in a checkout leaves it at `result/bin/z46`. The package is built
ReleaseSafe for a baseline CPU and runs the whole test suite before it
installs anything.
## Tests
```
zig build test
```
The suite covers the RFC text forms, the malformed text each error is meant to
catch, the classification registries, iteration at the edges of the address
space, and 10,000 seeded random round trips per type. There are also three
`std.testing.fuzz` entry points, which run once each under `zig build test`
and keep going under `zig build test --fuzz`:
```
zig build test --fuzz # until interrupted, with a web interface
zig build test --fuzz=1M # a bounded run, then a report
```
The report lists one entry per test binary, named after its first fuzz test,
but every fuzz test in that binary runs. The library's test binary is always
compiled by LLVM, even in Debug, because the fuzzer's coverage feedback and
kcov both need what the self-hosted backend leaves out.
Every function additionally has a test named after it — `test parse`, `test
isGlobal` — which Zig attaches to that declaration and the documentation
viewer shows as its worked example. They are written to be read as examples
rather than to be exhaustive, so each one shows the ordinary use and the one
edge that is easy to get wrong; the behavior tests around them carry the rest.
The private helpers have them too, where the example is what the public
function above cannot show: which byte order a field is in, what a checksum is
made of, which of two readings a piece of punctuation picks. Writing one for a
new function is part of adding it. The only functions without one are the three
`main` entry points, which take what the process gives them.
`zig build test` builds four test binaries, one per module: the library, the
CLI, the documentation server and the benchmark harness.
`zig build coverage` runs the library's tests under kcov and writes an HTML
report to `zig-out/coverage`, currently 99.67% of the 21 source files. It needs
kcov on the PATH, which the nix dev shell provides. The other three test
binaries are not included: kcov runs them without complaint but records no
lines from them.
## Benchmarks
```
zig build bench
```
This times the parsing, formatting and classification paths of every type over
seeded random corpora, always as a ReleaseFast build whatever `-Doptimize`
says, and reports the best of twenty passes for each. On one 2026 x86-64
machine, parsing sits at around 16 ns for an IPv4 address and 45–60 ns for an
IPv6 address depending on its shape, and formatting at around 11 ns and 23 ns;
the network, interface and endpoint types cost a few nanoseconds beyond the
address they wrap, and a `contains` check is fractions of a nanosecond. The
interface types look slower to parse than the networks only because their text
is longer: host bits that a network truncates away are digits an address
parser still has to read. A range holds two addresses and costs about two
addresses' worth to parse and to format.
`prefixes` is the one line that is not a per-operation cost in the same sense.
It is timed over the whole cover rather than over one block, so what it
reports is the price of a range, and that scales with how many networks the
range takes — one for a range that happens to be a network, tens of them for
a wide one whose ends line up badly. The corpus draws its spans
log-uniformly for that reason: uniformly random ends would be nearly the whole
address space every time and would measure only the worst case.
Run it on your own machine rather than trusting any of those numbers.
## RFCs referenced
The behaviour of this library is drawn from the documents below. Each is cited
in a doc comment next to the code that implements it, so `zig build docs` and
the source agree with this table.
### Notation and text representation
| RFC | Title | Used for |
| --- | --- | --- |
| [791](https://www.rfc-editor.org/rfc/rfc791) | Internet Protocol | Dotted-decimal IPv4 addresses; `0.0.0.0/8` as "this network" |
| [3986](https://www.rfc-editor.org/rfc/rfc3986) | Uniform Resource Identifier (URI): Generic Syntax | The square brackets around an IPv6 address in a URL authority, accepted by `Ipv6Address.parseWithOptions` |
| [1035](https://www.rfc-editor.org/rfc/rfc1035) | Domain Names - Implementation and Specification | §3.5's `in-addr.arpa` names, written by `Ipv4Address.reverseName` |
| [3596](https://www.rfc-editor.org/rfc/rfc3596) | DNS Extensions to Support IP Version 6 | §2.5's `ip6.arpa` nibble names, written by `Ipv6Address.reverseName` |
| [4007](https://www.rfc-editor.org/rfc/rfc4007) | IPv6 Scoped Address Architecture | Zone identifiers (`fe80::1%eth0`), accepted by `Ipv6Address.parseZoned` |
| [4291](https://www.rfc-editor.org/rfc/rfc4291) | IP Version 6 Addressing Architecture | The IPv6 text form: `::` compression, the trailing dotted-quad, `::`, `::1`, IPv4-mapped and IPv4-compatible addresses |
| [4632](https://www.rfc-editor.org/rfc/rfc4632) | Classless Inter-domain Routing (CIDR): The Internet Address Assignment and Aggregation Plan | The `address/prefix-length` notation the network and interface types parse and print |
| [5952](https://www.rfc-editor.org/rfc/rfc5952) | A Recommendation for IPv6 Address Text Representation | Canonical IPv6 output: lowercase, no leading zeros, longest zero run compressed, leftmost run on a tie |
| [6874](https://www.rfc-editor.org/rfc/rfc6874) | Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers | The `%25` escape for a zone in a URI, which `parseZonedWithOptions` leaves for the caller to undo |
| [7208](https://www.rfc-editor.org/rfc/rfc7208) | Sender Policy Framework (SPF) for Authorizing Use of Domains in Email, Version 1 | §5.6's `ip4-network` and `ip6-network`, parsed by `Ipv4Network.parseWithOptions(text, .spf)` and its IPv6 counterpart |
### Address structure
| RFC | Title | Used for |
| --- | --- | --- |
| [3021](https://www.rfc-editor.org/rfc/rfc3021) | Using 31-Bit Prefixes on IPv4 Point-to-Point Links | Both addresses of an IPv4 `/31` counting as usable hosts |
| [4291](https://www.rfc-editor.org/rfc/rfc4291) | IP Version 6 Addressing Architecture | §2.6.1's Subnet-Router anycast address, the one address `Ipv6Network.hostCount` holds back; §2.7.1's solicited-node multicast group, written by `solicitedNodeMulticast`; appendix A's modified EUI-64, which `interfaceIdentifier` builds |
| [4862](https://www.rfc-editor.org/rfc/rfc4862) | IPv6 Stateless Address Autoconfiguration | The address a host forms for itself out of a prefix and its own MAC, which `Ipv6Address.fromMac` builds |
| [8981](https://www.rfc-editor.org/rfc/rfc8981) | Temporary Address Extensions for Stateless Address Autoconfiguration | Why a host may have no MAC-derived address to find, noted on `fromMac` |
| [6164](https://www.rfc-editor.org/rfc/rfc6164) | Using 127-Bit IPv6 Prefixes on Inter-Router Links | Both addresses of an IPv6 `/127` counting as usable hosts |
| [6890](https://www.rfc-editor.org/rfc/rfc6890) | Special-Purpose IP Address Registries | The registry framework behind `isGlobal`; `192.0.0.0/24` IETF protocol assignments |
| [7346](https://www.rfc-editor.org/rfc/rfc7346) | IPv6 Multicast Address Scopes | The scope nibble returned by `Ipv6Address.multicastScope` |
### IPv4 special-purpose ranges
| RFC | Title | Range |
| --- | --- | --- |
| [919](https://www.rfc-editor.org/rfc/rfc919) | Broadcasting Internet Datagrams | `255.255.255.255`, the limited broadcast address |
| [1112](https://www.rfc-editor.org/rfc/rfc1112) | Host extensions for IP multicasting | `240.0.0.0/4`, reserved for future use |
| [1122](https://www.rfc-editor.org/rfc/rfc1122) | Requirements for Internet Hosts - Communication Layers | `127.0.0.0/8`, loopback |
| [1918](https://www.rfc-editor.org/rfc/rfc1918) | Address Allocation for Private Internets | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` |
| [2544](https://www.rfc-editor.org/rfc/rfc2544) | Benchmarking Methodology for Network Interconnect Devices | `198.18.0.0/15` |
| [3927](https://www.rfc-editor.org/rfc/rfc3927) | Dynamic Configuration of IPv4 Link-Local Addresses | `169.254.0.0/16` |
| [5737](https://www.rfc-editor.org/rfc/rfc5737) | IPv4 Address Blocks Reserved for Documentation | `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` |
| [5771](https://www.rfc-editor.org/rfc/rfc5771) | IANA Guidelines for IPv4 Multicast Address Assignments | `224.0.0.0/4` |
| [6598](https://www.rfc-editor.org/rfc/rfc6598) | IANA-Reserved IPv4 Prefix for Shared Address Space | `100.64.0.0/10`, carrier-grade NAT |
| [7526](https://www.rfc-editor.org/rfc/rfc7526) | Deprecating the Anycast Prefix for 6to4 Relay Routers | `192.88.99.0/24` |
| [7600](https://www.rfc-editor.org/rfc/rfc7600) | IPv4 Residual Deployment via IPv6 — A Stateless Solution | `192.0.0.8`, the IPv4 dummy address |
| [7723](https://www.rfc-editor.org/rfc/rfc7723) | Port Control Protocol (PCP) Anycast Addresses | `192.0.0.9`, globally reachable despite the block around it |
| [8155](https://www.rfc-editor.org/rfc/rfc8155) | Traversal Using Relays around NAT (TURN) Server Auto Discovery | `192.0.0.10`, likewise |
### IPv6 special-purpose ranges
| RFC | Title | Range |
| --- | --- | --- |
| [3056](https://www.rfc-editor.org/rfc/rfc3056) | Connection of IPv6 Domains via IPv4 Clouds | `2002::/16`, 6to4, whose embedded IPv4 address `sixtofour` returns |
| [3849](https://www.rfc-editor.org/rfc/rfc3849) | IPv6 Address Prefix Reserved for Documentation | `2001:db8::/32` |
| [4193](https://www.rfc-editor.org/rfc/rfc4193) | Unique Local IPv6 Unicast Addresses | `fc00::/7` |
| [4380](https://www.rfc-editor.org/rfc/rfc4380) | Teredo: Tunneling IPv6 over UDP through Network Address Translations (NATs) | `2001::/32`; §4's layout, which `teredo` unpacks |
| [6052](https://www.rfc-editor.org/rfc/rfc6052) | IPv6 Addressing of IPv4/IPv6 Translators | `64:ff9b::/96`, the NAT64 well-known prefix; §2.2's six layouts, read by `translatedIpv4` |
| [6666](https://www.rfc-editor.org/rfc/rfc6666) | A Discard Prefix for IPv6 | `100::/64` |
| [7343](https://www.rfc-editor.org/rfc/rfc7343) | An IPv6 Prefix for Overlay Routable Cryptographic Hash Identifiers Version 2 (ORCHIDv2) | `2001:20::/28` |
| [2928](https://www.rfc-editor.org/rfc/rfc2928) | Initial IPv6 Sub-TLA ID Assignments | `2001::/23`, IETF protocol assignments |
| [3879](https://www.rfc-editor.org/rfc/rfc3879) | Deprecating Site Local Addresses | `fec0::/10`, reported by `isSiteLocal` and by `Scope.site_local` |
| [5180](https://www.rfc-editor.org/rfc/rfc5180) | IPv6 Benchmarking Methodology for Network Interconnect Devices | `2001:2::/48` |
| [7450](https://www.rfc-editor.org/rfc/rfc7450) | Automatic Multicast Tunneling | `2001:3::/32`, globally reachable inside `2001::/23` |
| [7535](https://www.rfc-editor.org/rfc/rfc7535) | AS112 Redirection Using DNAME | `2001:4:112::/48`, likewise |
| [7723](https://www.rfc-editor.org/rfc/rfc7723) | Port Control Protocol (PCP) Anycast Addresses | `2001:1::1`, likewise |
| [8155](https://www.rfc-editor.org/rfc/rfc8155) | Traversal Using Relays around NAT (TURN) Server Auto Discovery | `2001:1::2`, likewise |
| [8215](https://www.rfc-editor.org/rfc/rfc8215) | Local-Use IPv4/IPv6 Translation Prefix | `64:ff9b:1::/48`, which unlike the well-known prefix does not route |
| [9374](https://www.rfc-editor.org/rfc/rfc9374) | DRIP Entity Tag (DET) for Unmanned Aircraft System Remote ID | `2001:30::/28` |
| [9602](https://www.rfc-editor.org/rfc/rfc9602) | Segment Routing over IPv6 (SRv6) Segment Identifiers in the IPv6 Addressing Architecture | `5f00::/16` |
| [9637](https://www.rfc-editor.org/rfc/rfc9637) | Expanding the IPv6 Documentation Space | `3fff::/20`, the second documentation block |
| [9665](https://www.rfc-editor.org/rfc/rfc9665) | Service Registration Protocol for DNS-Based Service Discovery | `2001:1::3`, globally reachable inside `2001::/23` |
| [9780](https://www.rfc-editor.org/rfc/rfc9780) | Bidirectional Forwarding Detection (BFD) for Multipoint Networks over Point-to-Multipoint MPLS LSPs | `100:0:0:1::/64`, the dummy prefix its §7.1 allocates |
Ranges that RFC 4291 defines directly — `::`, `::1`, `::ffff:0:0/96`, `::/96`,
`fe80::/10` and `ff00::/8` — are listed under notation above rather than
repeated here.
The IPv6 table is longer than its IPv4 counterpart mostly because of
`2001::/23`. The registry marks the whole block as not globally reachable and
then carves out of it several assignments that are, so each of those has to be
known by name or `isGlobal` would hide it behind the block it sits in.
## Where this lives
The canonical repository is on Forgejo:
```console
$ git clone https://git.jcollie.dev/jeff/z46.git
```
It is also on the Radicle network, where the repository's identifier is
```
rad:z2PkQaFgcSqhiwc9T9iSA3JjAJh1z
```
and `rad clone rad:z2PkQaFgcSqhiwc9T9iSA3JjAJh1z` fetches it from any node that
seeds it, needing no account and no forge. Further copies are mirrored to
and .
All four carry the same history on `main`; the Forgejo one is where the tests
and the documentation build run.
## Requirements
Zig 0.17.0. The development shell and the Nix package take the official
release binary from [zig-overlay](https://git.jcollie.dev/jeff/zig-overlay).
For Zig 0.16.0, use the `zig-0.16` branch, which holds the last of z46 to
build with it:
```console
$ git clone -b zig-0.16 https://git.jcollie.dev/jeff/z46.git
```
or, as a dependency:
```
zig fetch --save https://git.jcollie.dev/jeff/z46/archive/zig-0.16.tar.gz
```
The `v0.1.0` tag also predates the move to 0.17 and builds with 0.16.0.