ip.h File Reference

Layer 3 (Network) - a family-tagged IP address (IPv4 or IPv6) with RFC-faithful text parsing, canonical formatting, and scope classification. More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Classes
struct	pc_ip
	A v4 or v6 address in network (big-endian) byte order. More...

Macros
#define	PC_IP_STR_MAX   46
	Longest text an pc_ip_format can produce, including the NUL (RFC 5952 v4-mapped).

Enumerations
enum class	pc_ip_family : uint8_t { PC_IP_NONE = 0 , PC_IP_V4 = 4 , PC_IP_V6 = 6 }
	Address family tag. More...
enum class	pc_ip_scope : uint8_t {   PC_IP_SCOPE_UNSPECIFIED = 0 , PC_IP_SCOPE_LOOPBACK , PC_IP_SCOPE_LINK_LOCAL , PC_IP_SCOPE_PRIVATE ,   PC_IP_SCOPE_MULTICAST , PC_IP_SCOPE_GLOBAL }
	Address scope, in rough order of reachability (used for allow/deny policy + logging). More...

Functions
bool	pc_ip_parse (const char *s, pc_ip *out)
	Parse an IPv4 or IPv6 textual address (RFC 4291 §2.2) into out.
size_t	pc_ip_format (const pc_ip *ip, char *out, size_t cap)
	Format ip into out as its RFC 5952 canonical text.
pc_ip_scope	pc_ip_classify (const pc_ip *ip)
	Classify ip into a pc_ip_scope.
bool	pc_ip_equal (const pc_ip *a, const pc_ip *b)
	True if a and b are the same family and address.
bool	pc_ip_is_v4_mapped (const pc_ip *ip)
	True if ip is an IPv4-mapped IPv6 address (::ffff:a.b.c.d, RFC 4291 §2.5.5.2).
pc_ip	pc_ip_from_v4_octets (uint8_t a, uint8_t b, uint8_t c, uint8_t d)
	Build a v4 pc_ip from four octets (a.b.c.d).
pc_ip	pc_ip_from_v6_bytes (const uint8_t bytes[16])
	Build a v6 pc_ip from 16 address bytes in network (big-endian) order.
uint32_t	pc_ip_to_v4_be (const pc_ip *ip)
	The v4 address as a big-endian (network-order) uint32 (a<<24 | b<<16 | c<<8 | d).
bool	pc_ip_is_unspecified (const pc_ip *ip)
	True if ip is empty (pc_ip_family::PC_IP_NONE) or the all-zero unspecified address (0.0.0.0 / ::).
bool	pc_ip_prefix_match (const pc_ip *addr, const pc_ip *net, uint8_t prefix_len)
	CIDR containment: is addr inside the net / prefix_len block?

Detailed Description

Layer 3 (Network) - a family-tagged IP address (IPv4 or IPv6) with RFC-faithful text parsing, canonical formatting, and scope classification.

One representation for both address families so the rest of the stack can carry a peer address without caring whether it is v4 or v6. The address bytes are stored in network (big-endian, left-to-right) order: a v4 address uses bytes[0..3], a v6 address bytes[0..15].

Pure and host-testable - no lwIP, no Arduino, no heap, no stdlib parsing. The parser implements RFC 4291 §2.2 text forms (dotted-quad v4; v6 with :: zero-compression and the embedded-v4 ::ffff:a.b.c.d tail); the formatter emits the RFC 5952 canonical form (lower-case, no leading zeros, the longest zero run compressed to ::, v4-mapped shown as dotted). ESP32 dual-stack bring-up (enabling IPv6 on the netif) lives in the physical layer behind PC_ENABLE_IPV6; the TCP/UDP listeners already bind IPADDR_TYPE_ANY, so the server accepts v6 connections the moment the interface has a v6 address.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file ip.h.

Macro Definition Documentation

PC_IP_STR_MAX

#define PC_IP_STR_MAX   46

Longest text an pc_ip_format can produce, including the NUL (RFC 5952 v4-mapped).

Definition at line 58 of file ip.h.

Enumeration Type Documentation

pc_ip_family

enum class pc_ip_family : uint8_t

strong

Address family tag.

Enumerator
PC_IP_NONE	empty / unparsed
PC_IP_V4	IPv4 (bytes[0..3])
PC_IP_V6	IPv6 (bytes[0..15])

Definition at line 32 of file ip.h.

pc_ip_scope

enum class pc_ip_scope : uint8_t

strong

Address scope, in rough order of reachability (used for allow/deny policy + logging).

Enumerator
PC_IP_SCOPE_UNSPECIFIED	0.0.0.0 / ::
PC_IP_SCOPE_LOOPBACK	127.0.0.0/8 / ::1
PC_IP_SCOPE_LINK_LOCAL	169.254.0.0/16 / fe80::/10
PC_IP_SCOPE_PRIVATE	RFC1918 (10/8, 172.16/12, 192.168/16) / ULA fc00::/7.
PC_IP_SCOPE_MULTICAST	224.0.0.0/4 / ff00::/8
PC_IP_SCOPE_GLOBAL	globally routable unicast

Definition at line 40 of file ip.h.

Function Documentation

pc_ip_parse()

bool pc_ip_parse	(	const char *	s,
		pc_ip *	out
	)

Parse an IPv4 or IPv6 textual address (RFC 4291 §2.2) into out.

Returns

true on success (out->family set to pc_ip_family::PC_IP_V4/V6), false if s is malformed.

Definition at line 436 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, PC_IP_V4, and PC_IP_V6.

Referenced by listener_ip_allow_add_cidr().

pc_ip_format()

size_t pc_ip_format	(	const pc_ip *	ip,
		char *	out,
		size_t	cap
	)

Format ip into out as its RFC 5952 canonical text.

Returns

the length written (excluding the NUL), or 0 if ip is empty or cap is too small (need up to PC_IP_STR_MAX).

Definition at line 488 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, pc_ip_is_v4_mapped(), PC_IP_STR_MAX, PC_IP_V4, and PC_IP_V6.

pc_ip_classify()

pc_ip_scope pc_ip_classify

(

const pc_ip *

ip

)

Classify ip into a pc_ip_scope.

Definition at line 568 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, PC_IP_SCOPE_UNSPECIFIED, PC_IP_V4, and PC_IP_V6.

pc_ip_equal()

bool pc_ip_equal	(	const pc_ip *	a,
		const pc_ip *	b
	)

True if a and b are the same family and address.

Definition at line 585 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, PC_IP_V4, and PC_IP_V6.

Referenced by listener_accept_allowed_ip().

pc_ip_is_v4_mapped()

bool pc_ip_is_v4_mapped

(

const pc_ip *

ip

)

True if ip is an IPv4-mapped IPv6 address (::ffff:a.b.c.d, RFC 4291 §2.5.5.2).

Definition at line 563 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, and PC_IP_V6.

Referenced by pc_ip_format(), and pc_ip_to_v4_be().

pc_ip_from_v4_octets()

pc_ip pc_ip_from_v4_octets	(	uint8_t	a,
		uint8_t	b,
		uint8_t	c,
		uint8_t	d
	)

Build a v4 pc_ip from four octets (a.b.c.d).

Definition at line 607 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, and PC_IP_V4.

Referenced by pc_lwip_to_ip().

pc_ip_from_v6_bytes()

pc_ip pc_ip_from_v6_bytes

(

const uint8_t

bytes[16]

)

Build a v6 pc_ip from 16 address bytes in network (big-endian) order.

Definition at line 619 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, and PC_IP_V6.

Referenced by pc_lwip_to_ip().

pc_ip_to_v4_be()

uint32_t pc_ip_to_v4_be

(

const pc_ip *

ip

)

The v4 address as a big-endian (network-order) uint32 (a<<24 | b<<16 | c<<8 | d).

Returns

0 if ip is not a v4 (or v4-mapped) address.

Definition at line 627 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, pc_ip_is_v4_mapped(), and PC_IP_V4.

pc_ip_is_unspecified()

bool pc_ip_is_unspecified

(

const pc_ip *

ip

)

True if ip is empty (pc_ip_family::PC_IP_NONE) or the all-zero unspecified address (0.0.0.0 / ::).

Definition at line 645 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, PC_IP_NONE, and PC_IP_V4.

Referenced by listener_accept_allowed_ip().

pc_ip_prefix_match()

bool pc_ip_prefix_match	(	const pc_ip *	addr,
		const pc_ip *	net,
		uint8_t	prefix_len
	)

CIDR containment: is addr inside the net / prefix_len block?

The two must be the same family. prefix_len is 0..32 for v4, 0..128 for v6; the top prefix_len bits of the address bytes must match net (a prefix of 0 matches everything). This is the standard v4/v6 allowlist match.

Returns

true if addr is covered; false on a family mismatch or an out-of-range prefix.

Definition at line 662 of file ip.cpp.

References pc_ip::bytes, pc_ip::family, PC_IP_V4, and PC_IP_V6.

Referenced by listener_ip_allowed().