70671145e625ef624ab0065329906c12c37cfcec
[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 gethostbyname (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 gethostbyname (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
119 .I h_addr
120 value returned by
121 .IR gethostbyname2 (3)
122 is used,
123 so with current DNS implementations,
124 the result when the name corresponds to more than one address is
125 difficult to predict.
126 IPv4 name lookup resorts to
127 .IR getnetbyname (3)
128 only if
129 .IR gethostbyname2 (3)
130 fails.
131 .PP
132 A subnet specification is of the form \fInetwork\fB/\fImask\fR.
133 The
134 .I network
135 and
136 .I mask
137 can be any form acceptable to
138 .IR ttoaddr .
139 In addition, and preferably, the
140 .I mask
141 can be a decimal integer (leading zeros ignored) giving a bit count,
142 in which case
143 it stands for a mask with that number of high bits on and all others off
144 (e.g.,
145 .B 24
146 in IPv4 means
147 .BR 255.255.255.0 ).
148 In any case, the mask must be contiguous
149 (a sequence of high bits on and all remaining low bits off).
150 As a special case, the subnet specification
151 .B %default
152 is a synonym for
153 .B 0.0.0.0/0
154 or
155 .B ::/0
156 in IPv4 or IPv6 respectively.
157 .PP
158 .I Ttosubnet
159 ANDs the mask with the address before returning,
160 so that any non-network bits in the address are turned off
161 (e.g.,
162 .B 10.1.2.3/24
163 is synonymous with
164 .BR 10.1.2.0/24 ).
165 .I Subnettot
166 always generates the decimal-integer-bit-count
167 form of the mask,
168 with no leading zeros.
169 .PP
170 The
171 .I srclen
172 parameter of
173 .I ttoaddr
174 and
175 .I ttosubnet
176 specifies the length of the text string pointed to by
177 .IR src ;
178 it is an error for there to be anything else
179 (e.g., a terminating NUL) within that length.
180 As a convenience for cases where an entire NUL-terminated string is
181 to be converted,
182 a
183 .I srclen
184 value of
185 .B 0
186 is taken to mean
187 .BR strlen(src) .
188 .PP
189 The
190 .I af
191 parameter of
192 .I ttoaddr
193 and
194 .I ttosubnet
195 specifies the address family of interest.
196 It should be either
197 .B AF_INET
198 or
199 .BR AF_INET6 .
200 .PP
201 The
202 .I dstlen
203 parameter of
204 .I addrtot
205 and
206 .I subnettot
207 specifies the size of the
208 .I dst
209 parameter;
210 under no circumstances are more than
211 .I dstlen
212 bytes written to
213 .IR dst .
214 A result which will not fit is truncated.
215 .I Dstlen
216 can be zero, in which case
217 .I dst
218 need not be valid and no result is written,
219 but the return value is unaffected;
220 in all other cases, the (possibly truncated) result is NUL-terminated.
221 The
222 .I freeswan.h
223 header file defines constants,
224 .B ADDRTOT_BUF
225 and
226 .BR SUBNETTOT_BUF ,
227 which are the sizes of buffers just large enough for worst-case results.
228 .PP
229 The
230 .I format
231 parameter of
232 .I addrtot
233 and
234 .I subnettot
235 specifies what format is to be used for the conversion.
236 The value
237 .B 0
238 (not the character
239 .BR '0' ,
240 but a zero value)
241 specifies a reasonable default,
242 and is in fact the only format currently available in
243 .IR subnettot .
244 .I Addrtot
245 also accepts format values
246 .B 'r'
247 (signifying a text form suitable for DNS reverse lookups,
248 e.g.
249 .B 4.3.2.1.IN-ADDR.ARPA.
250 for IPv4 and
251 RFC 2874 format for IPv6),
252 and
253 .B 'R'
254 (signifying an alternate reverse-lookup form,
255 an error for IPv4 and RFC 1886 format for IPv6).
256 Reverse-lookup names always end with a ``.''.
257 .PP
258 The text-to-binary functions return NULL for success and
259 a pointer to a string-literal error message for failure;
260 see DIAGNOSTICS.
261 The binary-to-text functions return
262 .B 0
263 for a failure, and otherwise
264 always return the size of buffer which would 
265 be needed to
266 accommodate the full conversion result, including terminating NUL;
267 it is the caller's responsibility to check this against the size of
268 the provided buffer to determine whether truncation has occurred.
269 .SH SEE ALSO
270 inet(3)
271 .SH DIAGNOSTICS
272 Fatal errors in
273 .I ttoaddr
274 are:
275 empty input;
276 unknown address family;
277 attempt to allocate temporary storage for a very long name failed;
278 name lookup failed;
279 syntax error in dotted-decimal or colon-hex form;
280 dotted-decimal or colon-hex component too large.
281 .PP
282 Fatal errors in
283 .I ttosubnet
284 are:
285 no
286 .B /
287 in
288 .IR src ;
289 .I ttoaddr
290 error in conversion of
291 .I network
292 or
293 .IR mask ;
294 bit-count mask too big;
295 mask non-contiguous.
296 .PP
297 Fatal errors in
298 .I addrtot
299 and
300 .I subnettot
301 are:
302 unknown format.
303 .SH HISTORY
304 Written for the FreeS/WAN project by Henry Spencer.
305 .SH BUGS
306 The interpretation of incomplete dotted-decimal addresses
307 (e.g.
308 .B 10/24
309 means
310 .BR 10.0.0.0/24 )
311 differs from that of some older conversion
312 functions, e.g. those of
313 .IR inet (3).
314 The behavior of the older functions has never been
315 particularly consistent or particularly useful.
316 .PP
317 Ignoring leading zeros in dotted-decimal components and bit counts
318 is arguably the most useful behavior in this application,
319 but it might occasionally cause confusion with the historical use of leading 
320 zeros to denote octal numbers.
321 .PP
322 .I Ttoaddr
323 does not support the mixed colon-hex-dotted-decimal
324 convention used to embed an IPv4 address in an IPv6 address.
325 .PP
326 .I Addrtot
327 always uses the
328 .B ::
329 abbreviation (which can appear only once in an address) for the
330 .I first
331 sequence of multiple zeros in an IPv6 address.
332 One can construct addresses (unlikely ones) in which this is suboptimal.
333 .PP
334 .I Addrtot
335 .B 'r'
336 conversion of an IPv6 address uses lowercase hexadecimal,
337 not the uppercase used in RFC 2874's examples.
338 It takes careful reading of RFCs 2874, 2673, and 2234 to realize
339 that lowercase is technically legitimate here,
340 and there may be software which botches this
341 and hence would have trouble with lowercase hex.
342 .PP
343 Possibly
344 .I subnettot
345 ought to recognize the
346 .B %default
347 case and generate that string as its output.
348 Currently it doesn't.
349 .PP
350 It is barely possible that somebody, somewhere,
351 might have a legitimate use for non-contiguous subnet masks.
352 .PP
353 .IR Getnetbyname (3)
354 is a historical dreg.
355 .PP
356 .I Tnatoaddr
357 probably should enforce completeness of dotted-decimal addresses.
358 .PP
359 The restriction of text-to-binary error reports to literal strings
360 (so that callers don't need to worry about freeing them or copying them)
361 does limit the precision of error reporting.
362 .PP
363 The text-to-binary error-reporting convention lends itself
364 to slightly obscure code,
365 because many readers will not think of NULL as signifying success.
366 A good way to make it clearer is to write something like:
367 .PP
368 .RS
369 .nf
370 .B "const char *error;"
371 .sp
372 .B "error = ttoaddr( /* ... */ );"
373 .B "if (error != NULL) {"
374 .B "        /* something went wrong */"
375 .fi
376 .RE