| 1 |
.. _net-addresses: |
| 2 |
|
| 3 |
***************** |
| 4 |
Network addresses |
| 5 |
***************** |
| 6 |
|
| 7 |
.. highlight:: c |
| 8 |
|
| 9 |
:: |
| 10 |
|
| 11 |
#include <libcork/core.h> |
| 12 |
|
| 13 |
|
| 14 |
IP addresses |
| 15 |
------------ |
| 16 |
|
| 17 |
libcork provides C types for storing IPv4 and IPv6 addresses, as well as |
| 18 |
a union type for storing a generic IP address, regardless of whether |
| 19 |
it's IPv4 or IPv6. (This lets you distinguish between an IPv4 address |
| 20 |
and the equivalent ``::ffff:0:0/96`` IPv4-mapped IPv6 address.) |
| 21 |
|
| 22 |
.. type:: struct cork_ipv4 |
| 23 |
struct cork_ipv6 |
| 24 |
|
| 25 |
An IPv4 or IPv6 address. The address is stored in memory exactly as |
| 26 |
it would be if sent over a network connection — i.e., in |
| 27 |
network-endian order, regardless of the endianness of the current |
| 28 |
host. The types are also guaranteed to be exactly the size of an |
| 29 |
actual IPv4 or IPv6 address (without additional padding), so they can |
| 30 |
be embedded directly into ``struct`` types that represent binary |
| 31 |
disk/wire formats. |
| 32 |
|
| 33 |
The contents of these types should be considered opaque. You should |
| 34 |
use the accessor functions defined below to interact with the IP |
| 35 |
address. |
| 36 |
|
| 37 |
.. type:: struct cork_ip |
| 38 |
|
| 39 |
A single union type that can contain either an IPv4 or IPv6 address. |
| 40 |
This type contains a discriminator field, so you can't use it |
| 41 |
directly in a binary disk/wire format type. |
| 42 |
|
| 43 |
.. member:: unsigned int version |
| 44 |
|
| 45 |
Either ``4`` or ``6``, indicating whether the current IP address |
| 46 |
is an IPv4 address or an IPv6 address. |
| 47 |
|
| 48 |
.. member:: struct cork_ipv4 ip.v4 |
| 49 |
struct cork_ipv6 ip.v6 |
| 50 |
|
| 51 |
Gives you access to the underlying :c:type:`cork_ipv4` or |
| 52 |
:c:type:`cork_ipv6` instance for the current address. It's your |
| 53 |
responsibility to check the :c:member:`cork_ip.version` field and |
| 54 |
only access the union branch that corresponds to the current IP |
| 55 |
version. |
| 56 |
|
| 57 |
|
| 58 |
.. function:: void cork_ipv4_copy(struct cork_ipv4 \*addr, const void \*src) |
| 59 |
void cork_ipv6_copy(struct cork_ipv6 \*addr, const void \*src) |
| 60 |
void cork_ip_from_ipv4(struct cork_ip \*addr, const void \*src) |
| 61 |
void cork_ip_from_ipv6(struct cork_ip \*addr, const void \*src) |
| 62 |
|
| 63 |
Initializes a :c:type:`cork_ipv4`, :c:type:`cork_ipv6`, or |
| 64 |
:c:type:`cork_ip` instance from an existing IP address somewhere in |
| 65 |
memory. The existing address doesn't have to be an instance of the |
| 66 |
:c:type:`cork_ipv4` or :c:type:`cork_ipv6` types, but it does have to |
| 67 |
be a well-formed address. (For IPv4, it must be 4 bytes long; for |
| 68 |
IPv6, 16 bytes long. And in both cases, the address must already be |
| 69 |
in network-endian order, regardless of the host's endianness.) |
| 70 |
|
| 71 |
|
| 72 |
.. function:: int cork_ipv4_init(struct cork_ipv4 \*addr, const char \*str) |
| 73 |
int cork_ipv6_init(struct cork_ipv6 \*addr, const char \*str) |
| 74 |
int cork_ip_init(struct cork_ip \*addr, const char \*str) |
| 75 |
|
| 76 |
Initializes a :c:type:`cork_ipv4`, :c:type:`cork_ipv6`, or |
| 77 |
:c:type:`cork_ip` instance from the string representation of an IP |
| 78 |
address. *str* must point to a string containing a well-formed IP |
| 79 |
address. (Dotted-quad for an IPv4, and colon-hex for IPv6.) |
| 80 |
Moreover, the version of the IP address in *str* must be compatible |
| 81 |
with the function that you call: it can't be an IPv6 address if you |
| 82 |
call ``cork_ipv4_init``, and it can't be an IPv4 address if you call |
| 83 |
``cork_ipv6_init``. |
| 84 |
|
| 85 |
If *str* doesn't represent a valid address (of a compatible IP |
| 86 |
version), then we leave *addr* unchanged, fill in the current error |
| 87 |
condition with a :c:data:`CORK_NET_ADDRESS_PARSE_ERROR` error, and |
| 88 |
return ``-1``. |
| 89 |
|
| 90 |
|
| 91 |
.. function:: bool cork_ipv4_equal(const struct cork_ipv4 \*addr1, const struct cork_ipv4 \*addr2) |
| 92 |
bool cork_ipv6_equal(const struct cork_ipv6 \*addr1, const struct cork_ipv6 \*addr2) |
| 93 |
bool cork_ip_equal(const struct cork_ip \*addr1, const struct cork_ip \*addr2) |
| 94 |
|
| 95 |
Checks two IP addresses for equality. |
| 96 |
|
| 97 |
|
| 98 |
.. macro:: CORK_IPV4_STRING_LENGTH |
| 99 |
CORK_IPV6_STRING_LENGTH |
| 100 |
CORK_IP_STRING_LENGTH |
| 101 |
|
| 102 |
The maximum length of the string representation of an IPv4, IPv6, or |
| 103 |
generic IP address, including a ``NUL`` terminator. |
| 104 |
|
| 105 |
.. function:: void cork_ipv4_to_raw_string(const struct cork_ipv4 \*addr, char \*dest) |
| 106 |
void cork_ipv6_to_raw_string(const struct cork_ipv6 \*addr, char \*dest) |
| 107 |
void cork_ip_to_raw_string(const struct cork_ip \*addr, char \*dest) |
| 108 |
|
| 109 |
Fills in *dest* with the string representation of an IPv4, IPv6, or |
| 110 |
generic IP address. You are responsible for ensuring that *dest* is |
| 111 |
large enough to hold the string representation of any valid IP |
| 112 |
address of the given version. The |
| 113 |
:c:macro:`CORK_IPV4_STRING_LENGTH`, |
| 114 |
:c:macro:`CORK_IPV6_STRING_LENGTH`, and |
| 115 |
:c:macro:`CORK_IP_STRING_LENGTH` macros can be helpful for this:: |
| 116 |
|
| 117 |
char buf[CORK_IPV4_STRING_LENGTH]; |
| 118 |
struct cork_ipv4 addr; |
| 119 |
cork_ipv4_to_raw_string(&addr, buf); |
| 120 |
|
| 121 |
|
| 122 |
.. function:: bool cork_ipv4_is_valid_network(const struct cork_ipv4 \*addr, unsigned int cidr_prefix) |
| 123 |
bool cork_ipv6_is_valid_network(const struct cork_ipv6 \*addr, unsigned int cidr_prefix) |
| 124 |
bool cork_ip_is_valid_network(const struct cork_ipv6 \*addr, unsigned int cidr_prefix) |
| 125 |
|
| 126 |
Checks an IP address for alignment with a CIDR block prefix. For example, |
| 127 |
10.1.2.4/24 is invalid, but 10.1.2.4/30 is valid. |
| 128 |
|
| 129 |
|
| 130 |
.. macro:: CORK_NET_ADDRESS_ERROR |
| 131 |
CORK_NET_ADDRESS_PARSE_ERROR |
| 132 |
|
| 133 |
The error class and codes used for the :ref:`error conditions |
| 134 |
<errors>` described in this section. |