1 .TH IPSEC_TTOADDR 3 "28 Sept 2001"
2 .\" RCSID $Id: ttoaddr.3,v 1.1 2004/03/15 20:35:26 as Exp $
4 ipsec ttoaddr, tnatoaddr, addrtot \- convert Internet addresses to and from text
6 ipsec ttosubnet, subnettot \- convert subnet/mask text form to and from addresses
8 .B "#include <freeswan.h>
10 .B "const char *ttoaddr(const char *src, size_t srclen,"
12 .B "int af, ip_address *addr);"
14 .B "const char *tnatoaddr(const char *src, size_t srclen,"
16 .B "int af, ip_address *addr);"
18 .B "size_t addrtot(const ip_address *addr, int format,"
20 .B "char *dst, size_t dstlen);"
22 .B "const char *ttosubnet(const char *src, size_t srclen,"
24 .B "int af, ip_subnet *dst);"
26 .B "size_t subnettot(const ip_subnet *sub, int format,"
28 .B "char *dst, size_t dstlen);"
31 converts a text-string name or numeric address into a binary address
32 (in network byte order).
34 does the same conversion,
35 but the only text forms it accepts are
36 the ``official'' forms of
37 numeric address (dotted-decimal for IPv4, colon-hex for IPv6).
39 does the reverse conversion, from binary address back to a text form.
43 do likewise for the ``address/mask'' form used to write a
44 specification of a subnet.
46 An IPv4 address is specified in text as a
47 dotted-decimal address (e.g.
49 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
51 which is synonymous with
53 an eight-digit host-order hexadecimal number with a
57 which is synonymous with
59 on a big-endian host and
61 on a little-endian host),
62 a DNS name to be looked up via
63 .IR gethostbyname (3),
64 or an old-style network name to be looked up via
67 A dotted-decimal address may be incomplete, in which case
68 text-to-binary conversion implicitly appends
71 as necessary to bring it up to four components.
72 The components of a dotted-decimal address are always taken as
73 decimal, and leading zeros are ignored.
82 (the latter example is verbatim from RFC 1166).
83 The result of applying
85 to an IPv4 address is always complete and does not contain leading zeros.
87 Use of hexadecimal addresses is
90 they are included only to save hassles when dealing with
91 the handful of perverted programs which already print
92 network addresses in hexadecimal.
94 An IPv6 address is specified in text with
95 colon-hex notation (e.g.
96 .BR 0:56:78ab:22:33:44:55:66 ),
99 abbreviating at most one subsequence of multiple zeros (e.g.
101 which is synonymous with
102 .BR 99:ab:0:0:0:0:54:68 ),
103 or a DNS name to be looked up via
104 .IR gethostbyname (3).
105 The result of applying
107 to an IPv6 address will use
109 abbreviation if possible,
110 and will not contain leading zeros.
112 The letters in hexadecimal
113 may be uppercase or lowercase or any mixture thereof.
115 DNS names may be complete (optionally terminated with a ``.'')
116 or incomplete, and are looked up as specified by local system configuration
122 .IR gethostbyname2 (3)
124 so with current DNS implementations,
125 the result when the name corresponds to more than one address is
126 difficult to predict.
127 IPv4 name lookup resorts to
130 .IR gethostbyname2 (3)
133 A subnet specification is of the form \fInetwork\fB/\fImask\fR.
138 can be any form acceptable to
140 In addition, and preferably, the
142 can be a decimal integer (leading zeros ignored) giving a bit count,
144 it stands for a mask with that number of high bits on and all others off
149 In any case, the mask must be contiguous
150 (a sequence of high bits on and all remaining low bits off).
151 As a special case, the subnet specification
157 in IPv4 or IPv6 respectively.
160 ANDs the mask with the address before returning,
161 so that any non-network bits in the address are turned off
167 always generates the decimal-integer-bit-count
169 with no leading zeros.
177 specifies the length of the text string pointed to by
179 it is an error for there to be anything else
180 (e.g., a terminating NUL) within that length.
181 As a convenience for cases where an entire NUL-terminated string is
196 specifies the address family of interest.
208 specifies the size of the
211 under no circumstances are more than
215 A result which will not fit is truncated.
217 can be zero, in which case
219 need not be valid and no result is written,
220 but the return value is unaffected;
221 in all other cases, the (possibly truncated) result is NUL-terminated.
224 header file defines constants,
228 which are the sizes of buffers just large enough for worst-case results.
236 specifies what format is to be used for the conversion.
242 specifies a reasonable default,
243 and is in fact the only format currently available in
246 also accepts format values
248 (signifying a text form suitable for DNS reverse lookups,
250 .B 4.3.2.1.IN-ADDR.ARPA.
252 RFC 2874 format for IPv6),
255 (signifying an alternate reverse-lookup form,
256 an error for IPv4 and RFC 1886 format for IPv6).
257 Reverse-lookup names always end with a ``.''.
259 The text-to-binary functions return NULL for success and
260 a pointer to a string-literal error message for failure;
262 The binary-to-text functions return
264 for a failure, and otherwise
265 always return the size of buffer which would
267 accommodate the full conversion result, including terminating NUL;
268 it is the caller's responsibility to check this against the size of
269 the provided buffer to determine whether truncation has occurred.
277 unknown address family;
278 attempt to allocate temporary storage for a very long name failed;
280 syntax error in dotted-decimal or colon-hex form;
281 dotted-decimal or colon-hex component too large.
291 error in conversion of
295 bit-count mask too big;
305 Written for the FreeS/WAN project by Henry Spencer.
307 The interpretation of incomplete dotted-decimal addresses
312 differs from that of some older conversion
313 functions, e.g. those of
315 The behavior of the older functions has never been
316 particularly consistent or particularly useful.
318 Ignoring leading zeros in dotted-decimal components and bit counts
319 is arguably the most useful behavior in this application,
320 but it might occasionally cause confusion with the historical use of leading
321 zeros to denote octal numbers.
324 does not support the mixed colon-hex-dotted-decimal
325 convention used to embed an IPv4 address in an IPv6 address.
330 abbreviation (which can appear only once in an address) for the
332 sequence of multiple zeros in an IPv6 address.
333 One can construct addresses (unlikely ones) in which this is suboptimal.
337 conversion of an IPv6 address uses lowercase hexadecimal,
338 not the uppercase used in RFC 2874's examples.
339 It takes careful reading of RFCs 2874, 2673, and 2234 to realize
340 that lowercase is technically legitimate here,
341 and there may be software which botches this
342 and hence would have trouble with lowercase hex.
346 ought to recognize the
348 case and generate that string as its output.
349 Currently it doesn't.
351 It is barely possible that somebody, somewhere,
352 might have a legitimate use for non-contiguous subnet masks.
355 is a historical dreg.
358 probably should enforce completeness of dotted-decimal addresses.
360 The restriction of text-to-binary error reports to literal strings
361 (so that callers don't need to worry about freeing them or copying them)
362 does limit the precision of error reporting.
364 The text-to-binary error-reporting convention lends itself
365 to slightly obscure code,
366 because many readers will not think of NULL as signifying success.
367 A good way to make it clearer is to write something like:
371 .B "const char *error;"
373 .B "error = ttoaddr( /* ... */ );"
374 .B "if (error != NULL) {"
375 .B " /* something went wrong */"
projects / thirdparty / strongswan.git / blob