Replacing gethostbyname, gethostbyname2 and their _r variants with getaddrinfo to...
[strongswan.git] / src / libfreeswan / ttoaddr.3
1 .TH IPSEC_TTOADDR 3 "28 Sept 2001"
2 .SH NAME
3 ipsec ttoaddr, tnatoaddr, addrtot \- convert Internet addresses to and from text
4 .br
5 ipsec ttosubnet, subnettot \- convert subnet/mask text form to and from addresses
6 .SH SYNOPSIS
7 .B "#include <freeswan.h>
8 .sp
9 .B "const char *ttoaddr(const char *src, size_t srclen,"
10 .ti +1c
11 .B "int af, ip_address *addr);"
12 .br
13 .B "const char *tnatoaddr(const char *src, size_t srclen,"
14 .ti +1c
15 .B "int af, ip_address *addr);"
16 .br
17 .B "size_t addrtot(const ip_address *addr, int format,"
18 .ti +1c
19 .B "char *dst, size_t dstlen);"
20 .sp
21 .B "const char *ttosubnet(const char *src, size_t srclen,"
22 .ti +1c
23 .B "int af, ip_subnet *dst);"
24 .br
25 .B "size_t subnettot(const ip_subnet *sub, int format,"
26 .ti +1c
27 .B "char *dst, size_t dstlen);"
28 .SH DESCRIPTION
29 .I Ttoaddr
30 converts a text-string name or numeric address into a binary address
31 (in network byte order).
32 .I Tnatoaddr
33 does the same conversion,
34 but the only text forms it accepts are
35 the ``official'' forms of
36 numeric address (dotted-decimal for IPv4, colon-hex for IPv6).
37 .I Addrtot
38 does the reverse conversion, from binary address back to a text form.
39 .I Ttosubnet
40 and
41 .I subnettot
42 do likewise for the ``address/mask'' form used to write a
43 specification of a subnet.
44 .PP
45 An IPv4 address is specified in text as a
46 dotted-decimal address (e.g.
47 .BR 1.2.3.4 ),
48 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
49 .BR 0x01020304 ,
50 which is synonymous with
51 .BR 1.2.3.4 ),
52 an eight-digit host-order hexadecimal number with a
53 .B 0h
54 prefix (e.g.
55 .BR 0h01020304 ,
56 which is synonymous with
57 .B 1.2.3.4
58 on a big-endian host and
59 .B 4.3.2.1
60 on a little-endian host),
61 a DNS name to be looked up via
62 .IR getaddrinfo (3),
63 or an old-style network name to be looked up via
64 .IR getnetbyname (3).
65 .PP
66 A dotted-decimal address may be incomplete, in which case
67 text-to-binary conversion implicitly appends
68 as many instances of
69 .B .0
70 as necessary to bring it up to four components.
71 The components of a dotted-decimal address are always taken as
72 decimal, and leading zeros are ignored.
73 For example,
74 .B 10
75 is synonymous with
76 .BR 10.0.0.0 ,
77 and
78 .B 128.009.000.032
79 is synonymous with
80 .BR 128.9.0.32
81 (the latter example is verbatim from RFC 1166).
82 The result of applying
83 .I addrtot
84 to an IPv4 address is always complete and does not contain leading zeros.
85 .PP
86 Use of hexadecimal addresses is
87 .B strongly
88 .BR discouraged ;
89 they are included only to save hassles when dealing with
90 the handful of perverted programs which already print 
91 network addresses in hexadecimal.
92 .PP
93 An IPv6 address is specified in text with
94 colon-hex notation (e.g.
95 .BR 0:56:78ab:22:33:44:55:66 ),
96 colon-hex with
97 .B ::
98 abbreviating at most one subsequence of multiple zeros (e.g.
99 .BR 99:ab::54:068 ,
100 which is synonymous with
101 .BR 99:ab:0:0:0:0:54:68 ),
102 or a DNS name to be looked up via
103 .IR getaddrinfo (3).
104 The result of applying
105 .I addrtot
106 to an IPv6 address will use
107 .B ::
108 abbreviation if possible,
109 and will not contain leading zeros.
110 .PP
111 The letters in hexadecimal
112 may be uppercase or lowercase or any mixture thereof.
113 .PP
114 DNS names may be complete (optionally terminated with a ``.'')
115 or incomplete, and are looked up as specified by local system configuration
116 (see
117 .IR resolver (5)).
118 The first value returned by
119 .IR getaddrinfo (3)
120 is used,
121 so with current DNS implementations,
122 the result when the name corresponds to more than one address is
123 difficult to predict.
124 IPv4 name lookup resorts to
125 .IR getnetbyname (3)
126 only if
127 .IR getaddrinfo (3)
128 fails.
129 .PP
130 A subnet specification is of the form \fInetwork\fB/\fImask\fR.
131 The
132 .I network
133 and
134 .I mask
135 can be any form acceptable to
136 .IR ttoaddr .
137 In addition, and preferably, the
138 .I mask
139 can be a decimal integer (leading zeros ignored) giving a bit count,
140 in which case
141 it stands for a mask with that number of high bits on and all others off
142 (e.g.,
143 .B 24
144 in IPv4 means
145 .BR 255.255.255.0 ).
146 In any case, the mask must be contiguous
147 (a sequence of high bits on and all remaining low bits off).
148 As a special case, the subnet specification
149 .B %default
150 is a synonym for
151 .B 0.0.0.0/0
152 or
153 .B ::/0
154 in IPv4 or IPv6 respectively.
155 .PP
156 .I Ttosubnet
157 ANDs the mask with the address before returning,
158 so that any non-network bits in the address are turned off
159 (e.g.,
160 .B 10.1.2.3/24
161 is synonymous with
162 .BR 10.1.2.0/24 ).
163 .I Subnettot
164 always generates the decimal-integer-bit-count
165 form of the mask,
166 with no leading zeros.
167 .PP
168 The
169 .I srclen
170 parameter of
171 .I ttoaddr
172 and
173 .I ttosubnet
174 specifies the length of the text string pointed to by
175 .IR src ;
176 it is an error for there to be anything else
177 (e.g., a terminating NUL) within that length.
178 As a convenience for cases where an entire NUL-terminated string is
179 to be converted,
180 a
181 .I srclen
182 value of
183 .B 0
184 is taken to mean
185 .BR strlen(src) .
186 .PP
187 The
188 .I af
189 parameter of
190 .I ttoaddr
191 and
192 .I ttosubnet
193 specifies the address family of interest.
194 It should be either
195 .B AF_INET
196 or
197 .BR AF_INET6 .
198 .PP
199 The
200 .I dstlen
201 parameter of
202 .I addrtot
203 and
204 .I subnettot
205 specifies the size of the
206 .I dst
207 parameter;
208 under no circumstances are more than
209 .I dstlen
210 bytes written to
211 .IR dst .
212 A result which will not fit is truncated.
213 .I Dstlen
214 can be zero, in which case
215 .I dst
216 need not be valid and no result is written,
217 but the return value is unaffected;
218 in all other cases, the (possibly truncated) result is NUL-terminated.
219 The
220 .I freeswan.h
221 header file defines constants,
222 .B ADDRTOT_BUF
223 and
224 .BR SUBNETTOT_BUF ,
225 which are the sizes of buffers just large enough for worst-case results.
226 .PP
227 The
228 .I format
229 parameter of
230 .I addrtot
231 and
232 .I subnettot
233 specifies what format is to be used for the conversion.
234 The value
235 .B 0
236 (not the character
237 .BR '0' ,
238 but a zero value)
239 specifies a reasonable default,
240 and is in fact the only format currently available in
241 .IR subnettot .
242 .I Addrtot
243 also accepts format values
244 .B 'r'
245 (signifying a text form suitable for DNS reverse lookups,
246 e.g.
247 .B 4.3.2.1.IN-ADDR.ARPA.
248 for IPv4 and
249 RFC 2874 format for IPv6),
250 and
251 .B 'R'
252 (signifying an alternate reverse-lookup form,
253 an error for IPv4 and RFC 1886 format for IPv6).
254 Reverse-lookup names always end with a ``.''.
255 .PP
256 The text-to-binary functions return NULL for success and
257 a pointer to a string-literal error message for failure;
258 see DIAGNOSTICS.
259 The binary-to-text functions return
260 .B 0
261 for a failure, and otherwise
262 always return the size of buffer which would 
263 be needed to
264 accommodate the full conversion result, including terminating NUL;
265 it is the caller's responsibility to check this against the size of
266 the provided buffer to determine whether truncation has occurred.
267 .SH SEE ALSO
268 inet(3)
269 .SH DIAGNOSTICS
270 Fatal errors in
271 .I ttoaddr
272 are:
273 empty input;
274 unknown address family;
275 attempt to allocate temporary storage for a very long name failed;
276 name lookup failed;
277 syntax error in dotted-decimal or colon-hex form;
278 dotted-decimal or colon-hex component too large.
279 .PP
280 Fatal errors in
281 .I ttosubnet
282 are:
283 no
284 .B /
285 in
286 .IR src ;
287 .I ttoaddr
288 error in conversion of
289 .I network
290 or
291 .IR mask ;
292 bit-count mask too big;
293 mask non-contiguous.
294 .PP
295 Fatal errors in
296 .I addrtot
297 and
298 .I subnettot
299 are:
300 unknown format.
301 .SH HISTORY
302 Written for the FreeS/WAN project by Henry Spencer.
303 .SH BUGS
304 The interpretation of incomplete dotted-decimal addresses
305 (e.g.
306 .B 10/24
307 means
308 .BR 10.0.0.0/24 )
309 differs from that of some older conversion
310 functions, e.g. those of
311 .IR inet (3).
312 The behavior of the older functions has never been
313 particularly consistent or particularly useful.
314 .PP
315 Ignoring leading zeros in dotted-decimal components and bit counts
316 is arguably the most useful behavior in this application,
317 but it might occasionally cause confusion with the historical use of leading 
318 zeros to denote octal numbers.
319 .PP
320 .I Ttoaddr
321 does not support the mixed colon-hex-dotted-decimal
322 convention used to embed an IPv4 address in an IPv6 address.
323 .PP
324 .I Addrtot
325 always uses the
326 .B ::
327 abbreviation (which can appear only once in an address) for the
328 .I first
329 sequence of multiple zeros in an IPv6 address.
330 One can construct addresses (unlikely ones) in which this is suboptimal.
331 .PP
332 .I Addrtot
333 .B 'r'
334 conversion of an IPv6 address uses lowercase hexadecimal,
335 not the uppercase used in RFC 2874's examples.
336 It takes careful reading of RFCs 2874, 2673, and 2234 to realize
337 that lowercase is technically legitimate here,
338 and there may be software which botches this
339 and hence would have trouble with lowercase hex.
340 .PP
341 Possibly
342 .I subnettot
343 ought to recognize the
344 .B %default
345 case and generate that string as its output.
346 Currently it doesn't.
347 .PP
348 It is barely possible that somebody, somewhere,
349 might have a legitimate use for non-contiguous subnet masks.
350 .PP
351 .IR Getnetbyname (3)
352 is a historical dreg.
353 .PP
354 .I Tnatoaddr
355 probably should enforce completeness of dotted-decimal addresses.
356 .PP
357 The restriction of text-to-binary error reports to literal strings
358 (so that callers don't need to worry about freeing them or copying them)
359 does limit the precision of error reporting.
360 .PP
361 The text-to-binary error-reporting convention lends itself
362 to slightly obscure code,
363 because many readers will not think of NULL as signifying success.
364 A good way to make it clearer is to write something like:
365 .PP
366 .RS
367 .nf
368 .B "const char *error;"
369 .sp
370 .B "error = ttoaddr( /* ... */ );"
371 .B "if (error != NULL) {"
372 .B "        /* something went wrong */"
373 .fi
374 .RE