Debian Codegraph @

docs/old/net-addresses.rst

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
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.