Replacing gethostbyname, gethostbyname2 and their _r variants with getaddrinfo to...
[strongswan.git] / src / libfreeswan / atoaddr.3
1 .TH IPSEC_ATOADDR 3 "11 June 2001"
2 .SH NAME
3 ipsec atoaddr, addrtoa \- convert Internet addresses to and from ASCII
4 .br
5 ipsec atosubnet, subnettoa \- convert subnet/mask ASCII form to and from addresses
6 .SH SYNOPSIS
7 .B "#include <freeswan.h>
8 .sp
9 .B "const char *atoaddr(const char *src, size_t srclen,"
10 .ti +1c
11 .B "struct in_addr *addr);"
12 .br
13 .B "size_t addrtoa(struct in_addr addr, int format,"
14 .ti +1c
15 .B "char *dst, size_t dstlen);"
16 .sp
17 .B "const char *atosubnet(const char *src, size_t srclen,"
18 .ti +1c
19 .B "struct in_addr *addr, struct in_addr *mask);"
20 .br
21 .B "size_t subnettoa(struct in_addr addr, struct in_addr mask,"
22 .ti +1c
23 .B "int format, char *dst, size_t dstlen);"
24 .SH DESCRIPTION
25 These functions are obsolete; see
26 .IR ipsec_ttoaddr (3)
27 for their replacements.
28 .PP
29 .I Atoaddr
30 converts an ASCII name or dotted-decimal address into a binary address
31 (in network byte order).
32 .I Addrtoa
33 does the reverse conversion, back to an ASCII dotted-decimal address.
34 .I Atosubnet
35 and
36 .I subnettoa
37 do likewise for the ``address/mask'' ASCII form used to write a
38 specification of a subnet.
39 .PP
40 An address is specified in ASCII as a
41 dotted-decimal address (e.g.
42 .BR 1.2.3.4 ),
43 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
44 .BR 0x01020304 ,
45 which is synonymous with
46 .BR 1.2.3.4 ),
47 an eight-digit host-order hexadecimal number with a
48 .B 0h
49 prefix (e.g.
50 .BR 0h01020304 ,
51 which is synonymous with
52 .B 1.2.3.4
53 on a big-endian host and
54 .B 4.3.2.1
55 on a little-endian host),
56 a DNS name to be looked up via
57 .IR getaddrinfo (3),
58 or an old-style network name to be looked up via
59 .IR getnetbyname (3).
60 .PP
61 A dotted-decimal address may be incomplete, in which case
62 ASCII-to-binary conversion implicitly appends
63 as many instances of
64 .B .0
65 as necessary to bring it up to four components.
66 The components of a dotted-decimal address are always taken as
67 decimal, and leading zeros are ignored.
68 For example,
69 .B 10
70 is synonymous with
71 .BR 10.0.0.0 ,
72 and
73 .B 128.009.000.032
74 is synonymous with
75 .BR 128.9.0.32
76 (the latter example is verbatim from RFC 1166).
77 The result of
78 .I addrtoa
79 is always complete and does not contain leading zeros.
80 .PP
81 The letters in
82 a hexadecimal address may be uppercase or lowercase or any mixture thereof.
83 Use of hexadecimal addresses is
84 .B strongly
85 .BR discouraged ;
86 they are included only to save hassles when dealing with
87 the handful of perverted programs which already print 
88 network addresses in hexadecimal.
89 .PP
90 DNS names may be complete (optionally terminated with a ``.'')
91 or incomplete, and are looked up as specified by local system configuration
92 (see
93 .IR resolver (5)).
94 The first value returned by
95 .IR getaddrinfo (3)
96 is used,
97 so with current DNS implementations,
98 the result when the name corresponds to more than one address is
99 difficult to predict.
100 Name lookup resorts to
101 .IR getnetbyname (3)
102 only if
103 .IR getaddrinfo (3)
104 fails.
105 .PP
106 A subnet specification is of the form \fInetwork\fB/\fImask\fR.
107 The
108 .I network
109 and
110 .I mask
111 can be any form acceptable to
112 .IR atoaddr .
113 In addition, the
114 .I mask
115 can be a decimal integer (leading zeros ignored) giving a bit count,
116 in which case
117 it stands for a mask with that number of high bits on and all others off
118 (e.g.,
119 .B 24
120 means
121 .BR 255.255.255.0 ).
122 In any case, the mask must be contiguous
123 (a sequence of high bits on and all remaining low bits off).
124 As a special case, the subnet specification
125 .B %default
126 is a synonym for
127 .BR 0.0.0.0/0 .
128 .PP
129 .I Atosubnet
130 ANDs the mask with the address before returning,
131 so that any non-network bits in the address are turned off
132 (e.g.,
133 .B 10.1.2.3/24
134 is synonymous with
135 .BR 10.1.2.0/24 ).
136 .I Subnettoa
137 generates the decimal-integer-bit-count
138 form of the mask,
139 with no leading zeros,
140 unless the mask is non-contiguous.
141 .PP
142 The
143 .I srclen
144 parameter of
145 .I atoaddr
146 and
147 .I atosubnet
148 specifies the length of the ASCII string pointed to by
149 .IR src ;
150 it is an error for there to be anything else
151 (e.g., a terminating NUL) within that length.
152 As a convenience for cases where an entire NUL-terminated string is
153 to be converted,
154 a
155 .I srclen
156 value of
157 .B 0
158 is taken to mean
159 .BR strlen(src) .
160 .PP
161 The
162 .I dstlen
163 parameter of
164 .I addrtoa
165 and
166 .I subnettoa
167 specifies the size of the
168 .I dst
169 parameter;
170 under no circumstances are more than
171 .I dstlen
172 bytes written to
173 .IR dst .
174 A result which will not fit is truncated.
175 .I Dstlen
176 can be zero, in which case
177 .I dst
178 need not be valid and no result is written,
179 but the return value is unaffected;
180 in all other cases, the (possibly truncated) result is NUL-terminated.
181 The
182 .I freeswan.h
183 header file defines constants,
184 .B ADDRTOA_BUF
185 and
186 .BR SUBNETTOA_BUF ,
187 which are the sizes of buffers just large enough for worst-case results.
188 .PP
189 The
190 .I format
191 parameter of
192 .I addrtoa
193 and
194 .I subnettoa
195 specifies what format is to be used for the conversion.
196 The value
197 .B 0
198 (not the ASCII character
199 .BR '0' ,
200 but a zero value)
201 specifies a reasonable default,
202 and is in fact the only format currently available.
203 This parameter is a hedge against future needs.
204 .PP
205 The ASCII-to-binary functions return NULL for success and
206 a pointer to a string-literal error message for failure;
207 see DIAGNOSTICS.
208 The binary-to-ASCII functions return
209 .B 0
210 for a failure, and otherwise
211 always return the size of buffer which would 
212 be needed to
213 accommodate the full conversion result, including terminating NUL;
214 it is the caller's responsibility to check this against the size of
215 the provided buffer to determine whether truncation has occurred.
216 .SH SEE ALSO
217 inet(3)
218 .SH DIAGNOSTICS
219 Fatal errors in
220 .I atoaddr
221 are:
222 empty input;
223 attempt to allocate temporary storage for a very long name failed;
224 name lookup failed;
225 syntax error in dotted-decimal form;
226 dotted-decimal component too large to fit in 8 bits.
227 .PP
228 Fatal errors in
229 .I atosubnet
230 are:
231 no
232 .B /
233 in
234 .IR src ;
235 .I atoaddr
236 error in conversion of
237 .I network
238 or
239 .IR mask ;
240 bit-count mask too big;
241 mask non-contiguous.
242 .PP
243 Fatal errors in
244 .I addrtoa
245 and
246 .I subnettoa
247 are:
248 unknown format.
249 .SH HISTORY
250 Written for the FreeS/WAN project by Henry Spencer.
251 .SH BUGS
252 The interpretation of incomplete dotted-decimal addresses
253 (e.g.
254 .B 10/24
255 means
256 .BR 10.0.0.0/24 )
257 differs from that of some older conversion
258 functions, e.g. those of
259 .IR inet (3).
260 The behavior of the older functions has never been
261 particularly consistent or particularly useful.
262 .PP
263 Ignoring leading zeros in dotted-decimal components and bit counts
264 is arguably the most useful behavior in this application,
265 but it might occasionally cause confusion with the historical use of leading 
266 zeros to denote octal numbers.
267 .PP
268 It is barely possible that somebody, somewhere,
269 might have a legitimate use for non-contiguous subnet masks.
270 .PP
271 .IR Getnetbyname (3)
272 is a historical dreg.
273 .PP
274 The restriction of ASCII-to-binary error reports to literal strings
275 (so that callers don't need to worry about freeing them or copying them)
276 does limit the precision of error reporting.
277 .PP
278 The ASCII-to-binary error-reporting convention lends itself
279 to slightly obscure code,
280 because many readers will not think of NULL as signifying success.
281 A good way to make it clearer is to write something like:
282 .PP
283 .RS
284 .nf
285 .B "const char *error;"
286 .sp
287 .B "error = atoaddr( /* ... */ );"
288 .B "if (error != NULL) {"
289 .B "        /* something went wrong */"
290 .fi
291 .RE