1IPSEC_ATOADDR(3) Library Functions Manual IPSEC_ATOADDR(3)
2
6 ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII
7 ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from
8 addresses
9
11 #include <freeswan.h>
12 const char *atoaddr(const char *src, size_t srclen,
14 struct in_addr *addr);
15 size_t addrtoa(struct in_addr addr, int format,
16 char *dst, size_t dstlen);
17 const char *atosubnet(const char *src, size_t srclen,
19 struct in_addr *addr, struct in_addr *mask);
20 size_t subnettoa(struct in_addr addr, struct in_addr mask,
21 int format, char *dst, size_t dstlen);
22
24 These functions are obsolete; see ipsec_ttoaddr(3) for their replace‐
25 ments.
26 Atoaddr converts an ASCII name or dotted-decimal address into a binary
28 address (in network byte order). Addrtoa does the reverse conversion,
29 back to an ASCII dotted-decimal address. Atosubnet and subnettoa do
30 likewise for the ``address/mask'' ASCII form used to write a specifica‐
31 tion of a subnet.
32 An address is specified in ASCII as a dotted-decimal address (e.g.
34 1.2.3.4), an eight-digit network-order hexadecimal number with the
35 usual C prefix (e.g. 0x01020304, which is synonymous with 1.2.3.4), an
36 eight-digit host-order hexadecimal number with a 0h prefix (e.g.
37 0h01020304, which is synonymous with 1.2.3.4 on a big-endian host and
38 4.3.2.1 on a little-endian host), a DNS name to be looked up via geth‐
39 ostbyname(3), or an old-style network name to be looked up via getnet‐
40 byname(3).
41 A dotted-decimal address may be incomplete, in which case ASCII-to-
43 binary conversion implicitly appends as many instances of .0 as neces‐
44 sary to bring it up to four components. The components of a dotted-
45 decimal address are always taken as decimal, and leading zeros are
46 ignored. For example, 10 is synonymous with 10.0.0.0, and
47 128.009.000.032 is synonymous with 128.9.0.32 (the latter example is
48 verbatim from RFC 1166). The result of addrtoa is always complete and
49 does not contain leading zeros.
50 The letters in a hexadecimal address may be uppercase or lowercase or
52 any mixture thereof. Use of hexadecimal addresses is strongly discour‐
53 aged; they are included only to save hassles when dealing with the
54 handful of perverted programs which already print network addresses in
55 hexadecimal.
56 DNS names may be complete (optionally terminated with a ``.'') or
58 incomplete, and are looked up as specified by local system configura‐
59 tion (see resolver(5)). The h_addr value returned by gethostbyname(3)
60 is used, so with current DNS implementations, the result when the name
61 corresponds to more than one address is difficult to predict. Name
62 lookup resorts to getnetbyname(3) only if gethostbyname(3) fails.
63 A subnet specification is of the form network/mask. The network and
65 mask can be any form acceptable to atoaddr. In addition, the mask can
66 be a decimal integer (leading zeros ignored) giving a bit count, in
67 which case it stands for a mask with that number of high bits on and
68 all others off (e.g., 24 means 255.255.255.0). In any case, the mask
69 must be contiguous (a sequence of high bits on and all remaining low
70 bits off). As a special case, the subnet specification %default is a
71 synonym for 0.0.0.0/0.
72 Atosubnet ANDs the mask with the address before returning, so that any
74 non-network bits in the address are turned off (e.g., 10.1.2.3/24 is
75 synonymous with 10.1.2.0/24). Subnettoa generates the decimal-integer-
76 bit-count form of the mask, with no leading zeros, unless the mask is
77 non-contiguous.
78 The srclen parameter of atoaddr and atosubnet specifies the length of
80 the ASCII string pointed to by src; it is an error for there to be any‐
81 thing else (e.g., a terminating NUL) within that length. As a conve‐
82 nience for cases where an entire NUL-terminated string is to be con‐
83 verted, a srclen value of 0 is taken to mean strlen(src).
84 The dstlen parameter of addrtoa and subnettoa specifies the size of the
86 dst parameter; under no circumstances are more than dstlen bytes writ‐
87 ten to dst. A result which will not fit is truncated. Dstlen can be
88 zero, in which case dst need not be valid and no result is written, but
89 the return value is unaffected; in all other cases, the (possibly trun‐
90 cated) result is NUL-terminated. The freeswan.h header file defines
91 constants, ADDRTOA_BUF and SUBNETTOA_BUF, which are the sizes of buf‐
92 fers just large enough for worst-case results.
93 The format parameter of addrtoa and subnettoa specifies what format is
95 to be used for the conversion. The value 0 (not the ASCII character
96 '0', but a zero value) specifies a reasonable default, and is in fact
97 the only format currently available. This parameter is a hedge against
98 future needs.
99 The ASCII-to-binary functions return NULL for success and a pointer to
101 a string-literal error message for failure; see DIAGNOSTICS. The
102 binary-to-ASCII functions return 0 for a failure, and otherwise always
103 return the size of buffer which would be needed to accommodate the full
104 conversion result, including terminating NUL; it is the caller's
105 responsibility to check this against the size of the provided buffer to
106 determine whether truncation has occurred.
107
109 inet(3)
110
112 Fatal errors in atoaddr are: empty input; attempt to allocate temporary
113 storage for a very long name failed; name lookup failed; syntax error
114 in dotted-decimal form; dotted-decimal component too large to fit in 8
115 bits.
116 Fatal errors in atosubnet are: no / in src; atoaddr error in conversion
118 of network or mask; bit-count mask too big; mask non-contiguous.
119 Fatal errors in addrtoa and subnettoa are: unknown format.
121
123 Written for the FreeS/WAN project by Henry Spencer.
124
126 The interpretation of incomplete dotted-decimal addresses (e.g. 10/24
127 means 10.0.0.0/24) differs from that of some older conversion func‐
128 tions, e.g. those of inet(3). The behavior of the older functions has
129 never been particularly consistent or particularly useful.
130 Ignoring leading zeros in dotted-decimal components and bit counts is
132 arguably the most useful behavior in this application, but it might
133 occasionally cause confusion with the historical use of leading zeros
134 to denote octal numbers.
135 It is barely possible that somebody, somewhere, might have a legitimate
137 use for non-contiguous subnet masks.
138 Getnetbyname(3) is a historical dreg.
140 The restriction of ASCII-to-binary error reports to literal strings (so
142 that callers don't need to worry about freeing them or copying them)
143 does limit the precision of error reporting.
144 The ASCII-to-binary error-reporting convention lends itself to slightly
146 obscure code, because many readers will not think of NULL as signifying
147 success. A good way to make it clearer is to write something like:
148 const char *error;
150 error = atoaddr( /* ... */ );
152 if (error != NULL) {
153 /* something went wrong */
154 11 June 2001 IPSEC_ATOADDR(3)