1 Content-type: text/html
3 <HTML><HEAD><TITLE>Manpage of IPSEC_TTOADDR
</TITLE>
6 Section: C Library Functions (
3)
<BR>Updated:
28 Sept
2001<BR><A HREF=
"#index">Index
</A>
7 <A HREF=
"http://localhost/cgi-bin/man/man2html">Return to Main Contents
</A><HR>
10 <A NAME=
"lbAB"> </A>
13 ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text
16 ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses
17 <A NAME=
"lbAC"> </A>
20 <B>#include
<<A HREF=
"file:/usr/include/freeswan.h">freeswan.h
</A>></B>
23 <B>const char *ttoaddr(const char *src, size_t srclen,
</B>
27 <B>int af, ip_address *addr);
</B>
31 <B>const char *tnatoaddr(const char *src, size_t srclen,
</B>
35 <B>int af, ip_address *addr);
</B>
39 <B>size_t addrtot(const ip_address *addr, int format,
</B>
43 <B>char *dst, size_t dstlen);
</B>
46 <B>const char *ttosubnet(const char *src, size_t srclen,
</B>
50 <B>int af, ip_subnet *dst);
</B>
54 <B>size_t subnettot(const ip_subnet *sub, int format,
</B>
58 <B>char *dst, size_t dstlen);
</B>
60 <A NAME=
"lbAD"> </A>
65 converts a text-string name or numeric address into a binary address
66 (in network byte order).
69 does the same conversion,
70 but the only text forms it accepts are
71 the ``official'' forms of
72 numeric address (dotted-decimal for IPv4, colon-hex for IPv6).
75 does the reverse conversion, from binary address back to a text form.
81 do likewise for the ``address/mask'' form used to write a
82 specification of a subnet.
85 An IPv4 address is specified in text as a
86 dotted-decimal address (e.g.
89 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
92 which is synonymous with
95 an eight-digit host-order hexadecimal number with a
101 which is synonymous with
104 on a big-endian host and
107 on a little-endian host),
108 a DNS name to be looked up via
109 <I><A HREF=
"gethostbyname.3.html">gethostbyname
</A></I>(
3),
111 or an old-style network name to be looked up via
112 <I><A HREF=
"getnetbyname.3.html">getnetbyname
</A></I>(
3).
116 A dotted-decimal address may be incomplete, in which case
117 text-to-binary conversion implicitly appends
121 as necessary to bring it up to four components.
122 The components of a dotted-decimal address are always taken as
123 decimal, and leading zeros are ignored.
131 <B>128.009.000.032</B>
136 (the latter example is verbatim from RFC
1166).
137 The result of applying
140 to an IPv4 address is always complete and does not contain leading zeros.
143 Use of hexadecimal addresses is
148 they are included only to save hassles when dealing with
149 the handful of perverted programs which already print
150 network addresses in hexadecimal.
153 An IPv6 address is specified in text with
154 colon-hex notation (e.g.
155 <B>0:
56:
78ab:
22:
33:
44:
55:
66</B>),
160 abbreviating at most one subsequence of multiple zeros (e.g.
161 <B>99:ab::
54:
068</B>,
163 which is synonymous with
164 <B>99:ab:
0:
0:
0:
0:
54:
68</B>),
166 or a DNS name to be looked up via
167 <I><A HREF=
"gethostbyname.3.html">gethostbyname
</A></I>(
3).
169 The result of applying
172 to an IPv6 address will use
175 abbreviation if possible,
176 and will not contain leading zeros.
179 The letters in hexadecimal
180 may be uppercase or lowercase or any mixture thereof.
183 DNS names may be complete (optionally terminated with a ``.'')
184 or incomplete, and are looked up as specified by local system configuration
186 <I><A HREF=
"resolver.5.html">resolver
</A></I>(
5)).
192 <I><A HREF=
"gethostbyname2.3.html">gethostbyname2
</A></I>(
3)
195 so with current DNS implementations,
196 the result when the name corresponds to more than one address is
197 difficult to predict.
198 IPv4 name lookup resorts to
199 <I><A HREF=
"getnetbyname.3.html">getnetbyname
</A></I>(
3)
202 <I><A HREF=
"gethostbyname2.3.html">gethostbyname2
</A></I>(
3)
207 A subnet specification is of the form
<I>network
</I><B>/
</B><I>mask
</I>.
214 can be any form acceptable to
217 In addition, and preferably, the
220 can be a decimal integer (leading zeros ignored) giving a bit count,
222 it stands for a mask with that number of high bits on and all others off
227 <B>255.255.255.0</B>).
229 In any case, the mask must be contiguous
230 (a sequence of high bits on and all remaining low bits off).
231 As a special case, the subnet specification
240 in IPv4 or IPv6 respectively.
245 ANDs the mask with the address before returning,
246 so that any non-network bits in the address are turned off
255 always generates the decimal-integer-bit-count
257 with no leading zeros.
269 specifies the length of the text string pointed to by
272 it is an error for there to be anything else
273 (e.g., a terminating NUL) within that length.
274 As a convenience for cases where an entire NUL-terminated string is
296 specifies the address family of interest.
314 specifies the size of the
318 under no circumstances are more than
324 A result which will not fit is truncated.
327 can be zero, in which case
330 need not be valid and no result is written,
331 but the return value is unaffected;
332 in all other cases, the (possibly truncated) result is NUL-terminated.
336 header file defines constants,
340 <B>SUBNETTOT_BUF
</B>,
342 which are the sizes of buffers just large enough for worst-case results.
354 specifies what format is to be used for the conversion.
362 specifies a reasonable default,
363 and is in fact the only format currently available in
368 also accepts format values
371 (signifying a text form suitable for DNS reverse lookups,
373 <B>4.3.2.1.IN-ADDR.ARPA.
</B>
376 RFC
2874 format for IPv6),
380 (signifying an alternate reverse-lookup form,
381 an error for IPv4 and RFC
1886 format for IPv6).
382 Reverse-lookup names always end with a ``.''.
385 The text-to-binary functions return NULL for success and
386 a pointer to a string-literal error message for failure;
388 The binary-to-text functions return
391 for a failure, and otherwise
392 always return the size of buffer which would
394 accommodate the full conversion result, including terminating NUL;
395 it is the caller's responsibility to check this against the size of
396 the provided buffer to determine whether truncation has occurred.
397 <A NAME=
"lbAE"> </A>
400 <A HREF=
"inet.3.html">inet
</A>(
3)
401 <A NAME=
"lbAF"> </A>
409 unknown address family;
410 attempt to allocate temporary storage for a very long name failed;
412 syntax error in dotted-decimal or colon-hex form;
413 dotted-decimal or colon-hex component too large.
428 error in conversion of
434 bit-count mask too big;
446 <A NAME=
"lbAG"> </A>
449 Written for the FreeS/WAN project by Henry Spencer.
450 <A NAME=
"lbAH"> </A>
453 The interpretation of incomplete dotted-decimal addresses
460 differs from that of some older conversion
461 functions, e.g. those of
462 <I><A HREF=
"inet.3.html">inet
</A></I>(
3).
464 The behavior of the older functions has never been
465 particularly consistent or particularly useful.
468 Ignoring leading zeros in dotted-decimal components and bit counts
469 is arguably the most useful behavior in this application,
470 but it might occasionally cause confusion with the historical use of leading
471 zeros to denote octal numbers.
476 does not support the mixed colon-hex-dotted-decimal
477 convention used to embed an IPv4 address in an IPv6 address.
485 abbreviation (which can appear only once in an address) for the
488 sequence of multiple zeros in an IPv6 address.
489 One can construct addresses (unlikely ones) in which this is suboptimal.
496 conversion of an IPv6 address uses lowercase hexadecimal,
497 not the uppercase used in RFC
2874's examples.
498 It takes careful reading of RFCs
2874,
2673, and
2234 to realize
499 that lowercase is technically legitimate here,
500 and there may be software which botches this
501 and hence would have trouble with lowercase hex.
507 ought to recognize the
510 case and generate that string as its output.
511 Currently it doesn't.
514 It is barely possible that somebody, somewhere,
515 might have a legitimate use for non-contiguous subnet masks.
518 <I><A HREF=
"Getnetbyname.3.html">Getnetbyname
</A></I>(
3)
520 is a historical dreg.
525 probably should enforce completeness of dotted-decimal addresses.
528 The restriction of text-to-binary error reports to literal strings
529 (so that callers don't need to worry about freeing them or copying them)
530 does limit the precision of error reporting.
533 The text-to-binary error-reporting convention lends itself
534 to slightly obscure code,
535 because many readers will not think of NULL as signifying success.
536 A good way to make it clearer is to write something like:
541 <B>const char *error;
</B>
543 <B>error = ttoaddr( /* ... */ );
</B>
544 <B>if (error != NULL) {
</B>
545 <B> /* something went wrong */
</B>
553 <A NAME=
"index"> </A><H2>Index
</H2>
555 <DT><A HREF=
"#lbAB">NAME
</A><DD>
556 <DT><A HREF=
"#lbAC">SYNOPSIS
</A><DD>
557 <DT><A HREF=
"#lbAD">DESCRIPTION
</A><DD>
558 <DT><A HREF=
"#lbAE">SEE ALSO
</A><DD>
559 <DT><A HREF=
"#lbAF">DIAGNOSTICS
</A><DD>
560 <DT><A HREF=
"#lbAG">HISTORY
</A><DD>
561 <DT><A HREF=
"#lbAH">BUGS
</A><DD>
564 This document was created by
565 <A HREF=
"http://localhost/cgi-bin/man/man2html">man2html
</A>,
566 using the manual pages.
<BR>
567 Time:
21:
40:
18 GMT, November
11,
2003