1 Content-type: text/html
3 <HTML><HEAD><TITLE>Manpage of IPSEC_TTOADDR</TITLE>
6 Section: C Library Functions (3)<BR>Updated: 15 Dec 2000<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 attempt to allocate temporary storage for a very long name failed;
411 syntax error in dotted-decimal or colon-hex form;
412 dotted-decimal or colon-hex component too large.
427 error in conversion of
433 bit-count mask too big;
445 <A NAME="lbAG"> </A>
448 Written for the FreeS/WAN project by Henry Spencer.
449 <A NAME="lbAH"> </A>
452 The interpretation of incomplete dotted-decimal addresses
459 differs from that of some older conversion
460 functions, e.g. those of
461 <I><A HREF="inet.3.html">inet</A></I>(3).
463 The behavior of the older functions has never been
464 particularly consistent or particularly useful.
467 Ignoring leading zeros in dotted-decimal components and bit counts
468 is arguably the most useful behavior in this application,
469 but it might occasionally cause confusion with the historical use of leading
470 zeros to denote octal numbers.
475 does not support the mixed colon-hex-dotted-decimal
476 convention used to embed an IPv4 address in an IPv6 address.
484 abbreviation (which can appear only once in an address) for the
487 sequence of multiple zeros in an IPv6 address.
488 One can construct addresses (unlikely ones) in which this is suboptimal.
495 conversion of an IPv6 address uses lowercase hexadecimal,
496 not the uppercase used in RFC 2874's examples.
497 It takes careful reading of RFCs 2874, 2673, and 2234 to realize
498 that lowercase is technically legitimate here,
499 and there may be software which botches this
500 and hence would have trouble with lowercase hex.
506 ought to recognize the
509 case and generate that string as its output.
510 Currently it doesn't.
513 It is barely possible that somebody, somewhere,
514 might have a legitimate use for non-contiguous subnet masks.
517 <I><A HREF="Getnetbyname.3.html">Getnetbyname</A></I>(3)
519 is a historical dreg.
524 probably should enforce completeness of dotted-decimal addresses.
527 The restriction of text-to-binary error reports to literal strings
528 (so that callers don't need to worry about freeing them or copying them)
529 does limit the precision of error reporting.
532 The text-to-binary error-reporting convention lends itself
533 to slightly obscure code,
534 because many readers will not think of NULL as signifying success.
535 A good way to make it clearer is to write something like:
540 <B>const char *error;</B>
542 <B>error = ttoaddr( /* ... */ );</B>
543 <B>if (error != NULL) {</B>
544 <B> /* something went wrong */</B>
552 <A NAME="index"> </A><H2>Index</H2>
554 <DT><A HREF="#lbAB">NAME</A><DD>
555 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
556 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
557 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
558 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
559 <DT><A HREF="#lbAG">HISTORY</A><DD>
560 <DT><A HREF="#lbAH">BUGS</A><DD>
563 This document was created by
564 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
565 using the manual pages.<BR>
566 Time: 05:09:34 GMT, June 19, 2001