1IPSEC_TTOADDR(3) Library Functions Manual IPSEC_TTOADDR(3)
2
6 ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and
7 from text
8 ipsec ttosubnet, subnettot - convert subnet/mask text form to and from
9 addresses
10
12 #include <freeswan.h>
13 const char *ttoaddr(const char *src, size_t srclen,
15 int af, ip_address *addr);
16 const char *tnatoaddr(const char *src, size_t srclen,
17 int af, ip_address *addr);
18 size_t addrtot(const ip_address *addr, int format,
19 char *dst, size_t dstlen);
20 const char *ttosubnet(const char *src, size_t srclen,
22 int af, ip_subnet *dst);
23 size_t subnettot(const ip_subnet *sub, int format,
24 char *dst, size_t dstlen);
25
27 Ttoaddr converts a text-string name or numeric address into a binary
28 address (in network byte order). Tnatoaddr does the same conversion,
29 but the only text forms it accepts are the ``official'' forms of
30 numeric address (dotted-decimal for IPv4, colon-hex for IPv6). Addrtot
31 does the reverse conversion, from binary address back to a text form.
32 Ttosubnet and subnettot do likewise for the ``address/mask'' form used
33 to write a specification of a subnet.
34 An IPv4 address is specified in text as a dotted-decimal address (e.g.
36 1.2.3.4), an eight-digit network-order hexadecimal number with the
37 usual C prefix (e.g. 0x01020304, which is synonymous with 1.2.3.4), an
38 eight-digit host-order hexadecimal number with a 0h prefix (e.g.
39 0h01020304, which is synonymous with 1.2.3.4 on a big-endian host and
40 4.3.2.1 on a little-endian host), a DNS name to be looked up via geth‐
41 ostbyname(3), or an old-style network name to be looked up via getnet‐
42 byname(3).
43 A dotted-decimal address may be incomplete, in which case text-to-
45 binary conversion implicitly appends as many instances of .0 as neces‐
46 sary to bring it up to four components. The components of a dotted-
47 decimal address are always taken as decimal, and leading zeros are
48 ignored. For example, 10 is synonymous with 10.0.0.0, and
49 128.009.000.032 is synonymous with 128.9.0.32 (the latter example is
50 verbatim from RFC 1166). The result of applying addrtot to an IPv4
51 address is always complete and does not contain leading zeros.
52 Use of hexadecimal addresses is strongly discouraged; they are included
54 only to save hassles when dealing with the handful of perverted pro‐
55 grams which already print network addresses in hexadecimal.
56 An IPv6 address is specified in text with colon-hex notation (e.g.
58 0:56:78ab:22:33:44:55:66), colon-hex with :: abbreviating at most one
59 subsequence of multiple zeros (e.g. 99:ab::54:068, which is synonymous
60 with 99:ab:0:0:0:0:54:68), or a DNS name to be looked up via gethostby‐
61 name(3). The result of applying addrtot to an IPv6 address will use ::
62 abbreviation if possible, and will not contain leading zeros.
63 The letters in hexadecimal may be uppercase or lowercase or any mixture
65 thereof.
66 DNS names may be complete (optionally terminated with a ``.'') or
68 incomplete, and are looked up as specified by local system configura‐
69 tion (see resolver(5)). The h_addr value returned by gethostbyname2(3)
70 is used, so with current DNS implementations, the result when the name
71 corresponds to more than one address is difficult to predict. IPv4
72 name lookup resorts to getnetbyname(3) only if gethostbyname2(3) fails.
73 A subnet specification is of the form network/mask. The network and
75 mask can be any form acceptable to ttoaddr. In addition, and prefer‐
76 ably, the mask can be a decimal integer (leading zeros ignored) giving
77 a bit count, in which case it stands for a mask with that number of
78 high bits on and all others off (e.g., 24 in IPv4 means 255.255.255.0).
79 In any case, the mask must be contiguous (a sequence of high bits on
80 and all remaining low bits off). As a special case, the subnet speci‐
81 fication %default is a synonym for 0.0.0.0/0 or ::/0 in IPv4 or IPv6
82 respectively.
83 Ttosubnet ANDs the mask with the address before returning, so that any
85 non-network bits in the address are turned off (e.g., 10.1.2.3/24 is
86 synonymous with 10.1.2.0/24). Subnettot always generates the decimal-
87 integer-bit-count form of the mask, with no leading zeros.
88 The srclen parameter of ttoaddr and ttosubnet specifies the length of
90 the text string pointed to by src; it is an error for there to be any‐
91 thing else (e.g., a terminating NUL) within that length. As a conve‐
92 nience for cases where an entire NUL-terminated string is to be con‐
93 verted, a srclen value of 0 is taken to mean strlen(src).
94 The af parameter of ttoaddr and ttosubnet specifies the address family
96 of interest. It should be either AF_INET or AF_INET6.
97 The dstlen parameter of addrtot and subnettot specifies the size of the
99 dst parameter; under no circumstances are more than dstlen bytes writ‐
100 ten to dst. A result which will not fit is truncated. Dstlen can be
101 zero, in which case dst need not be valid and no result is written, but
102 the return value is unaffected; in all other cases, the (possibly trun‐
103 cated) result is NUL-terminated. The freeswan.h header file defines
104 constants, ADDRTOT_BUF and SUBNETTOT_BUF, which are the sizes of buf‐
105 fers just large enough for worst-case results.
106 The format parameter of addrtot and subnettot specifies what format is
108 to be used for the conversion. The value 0 (not the character '0', but
109 a zero value) specifies a reasonable default, and is in fact the only
110 format currently available in subnettot. Addrtot also accepts format
111 values 'r' (signifying a text form suitable for DNS reverse lookups,
112 e.g. 4.3.2.1.IN-ADDR.ARPA. for IPv4 and RFC 2874 format for IPv6),
113 and 'R' (signifying an alternate reverse-lookup form, an error for IPv4
114 and RFC 1886 format for IPv6). Reverse-lookup names always end with a
115 ``.''.
116 The text-to-binary functions return NULL for success and a pointer to a
118 string-literal error message for failure; see DIAGNOSTICS. The binary-
119 to-text functions return 0 for a failure, and otherwise always return
120 the size of buffer which would be needed to accommodate the full con‐
121 version result, including terminating NUL; it is the caller's responsi‐
122 bility to check this against the size of the provided buffer to deter‐
123 mine whether truncation has occurred.
124
126 inet(3)
127
129 Fatal errors in ttoaddr are: empty input; unknown address family;
130 attempt to allocate temporary storage for a very long name failed; name
131 lookup failed; syntax error in dotted-decimal or colon-hex form; dot‐
132 ted-decimal or colon-hex component too large.
133 Fatal errors in ttosubnet are: no / in src; ttoaddr error in conversion
135 of network or mask; bit-count mask too big; mask non-contiguous.
136 Fatal errors in addrtot and subnettot are: unknown format.
138
140 Written for the FreeS/WAN project by Henry Spencer.
141
143 The interpretation of incomplete dotted-decimal addresses (e.g. 10/24
144 means 10.0.0.0/24) differs from that of some older conversion func‐
145 tions, e.g. those of inet(3). The behavior of the older functions has
146 never been particularly consistent or particularly useful.
147 Ignoring leading zeros in dotted-decimal components and bit counts is
149 arguably the most useful behavior in this application, but it might
150 occasionally cause confusion with the historical use of leading zeros
151 to denote octal numbers.
152 Ttoaddr does not support the mixed colon-hex-dotted-decimal convention
154 used to embed an IPv4 address in an IPv6 address.
155 Addrtot always uses the :: abbreviation (which can appear only once in
157 an address) for the first sequence of multiple zeros in an IPv6
158 address. One can construct addresses (unlikely ones) in which this is
159 suboptimal.
160 Addrtot 'r' conversion of an IPv6 address uses lowercase hexadecimal,
162 not the uppercase used in RFC 2874's examples. It takes careful read‐
163 ing of RFCs 2874, 2673, and 2234 to realize that lowercase is techni‐
164 cally legitimate here, and there may be software which botches this and
165 hence would have trouble with lowercase hex.
166 Possibly subnettot ought to recognize the %default case and generate
168 that string as its output. Currently it doesn't.
169 It is barely possible that somebody, somewhere, might have a legitimate
171 use for non-contiguous subnet masks.
172 Getnetbyname(3) is a historical dreg.
174 Tnatoaddr probably should enforce completeness of dotted-decimal
176 addresses.
177 The restriction of text-to-binary error reports to literal strings (so
179 that callers don't need to worry about freeing them or copying them)
180 does limit the precision of error reporting.
181 The text-to-binary error-reporting convention lends itself to slightly
183 obscure code, because many readers will not think of NULL as signifying
184 success. A good way to make it clearer is to write something like:
185 const char *error;
187 error = ttoaddr( /* ... */ );
189 if (error != NULL) {
190 /* something went wrong */
191 28 Sept 2001 IPSEC_TTOADDR(3)