--- /dev/null
+Content-type: text/html
+
+<HTML><HEAD><TITLE>Manpage of IPSEC_TTOADDR</TITLE>
+</HEAD><BODY>
+<H1>IPSEC_TTOADDR</H1>
+Section: C Library Functions (3)<BR>Updated: 28 Sept 2001<BR><A HREF="#index">Index</A>
+<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
+
+
+<A NAME="lbAB"> </A>
+<H2>NAME</H2>
+
+ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text
+<BR>
+
+ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses
+<A NAME="lbAC"> </A>
+<H2>SYNOPSIS</H2>
+
+<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
+
+<P>
+<B>const char *ttoaddr(const char *src, size_t srclen,</B>
+
+<BR>
+
+<B>int af, ip_address *addr);</B>
+
+<BR>
+
+<B>const char *tnatoaddr(const char *src, size_t srclen,</B>
+
+<BR>
+
+<B>int af, ip_address *addr);</B>
+
+<BR>
+
+<B>size_t addrtot(const ip_address *addr, int format,</B>
+
+<BR>
+
+<B>char *dst, size_t dstlen);</B>
+
+<P>
+<B>const char *ttosubnet(const char *src, size_t srclen,</B>
+
+<BR>
+
+<B>int af, ip_subnet *dst);</B>
+
+<BR>
+
+<B>size_t subnettot(const ip_subnet *sub, int format,</B>
+
+<BR>
+
+<B>char *dst, size_t dstlen);</B>
+
+<A NAME="lbAD"> </A>
+<H2>DESCRIPTION</H2>
+
+<I>Ttoaddr</I>
+
+converts a text-string name or numeric address into a binary address
+(in network byte order).
+<I>Tnatoaddr</I>
+
+does the same conversion,
+but the only text forms it accepts are
+the ``official'' forms of
+numeric address (dotted-decimal for IPv4, colon-hex for IPv6).
+<I>Addrtot</I>
+
+does the reverse conversion, from binary address back to a text form.
+<I>Ttosubnet</I>
+
+and
+<I>subnettot</I>
+
+do likewise for the ``address/mask'' form used to write a
+specification of a subnet.
+<P>
+
+An IPv4 address is specified in text as a
+dotted-decimal address (e.g.
+<B>1.2.3.4</B>),
+
+an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
+<B>0x01020304</B>,
+
+which is synonymous with
+<B>1.2.3.4</B>),
+
+an eight-digit host-order hexadecimal number with a
+<B>0h</B>
+
+prefix (e.g.
+<B>0h01020304</B>,
+
+which is synonymous with
+<B>1.2.3.4</B>
+
+on a big-endian host and
+<B>4.3.2.1</B>
+
+on a little-endian host),
+a DNS name to be looked up via
+<I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3),
+
+or an old-style network name to be looked up via
+<I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3).
+
+<P>
+
+A dotted-decimal address may be incomplete, in which case
+text-to-binary conversion implicitly appends
+as many instances of
+<B>.0</B>
+
+as necessary to bring it up to four components.
+The components of a dotted-decimal address are always taken as
+decimal, and leading zeros are ignored.
+For example,
+<B>10</B>
+
+is synonymous with
+<B>10.0.0.0</B>,
+
+and
+<B>128.009.000.032</B>
+
+is synonymous with
+<B>128.9.0.32</B>
+
+(the latter example is verbatim from RFC 1166).
+The result of applying
+<I>addrtot</I>
+
+to an IPv4 address is always complete and does not contain leading zeros.
+<P>
+
+Use of hexadecimal addresses is
+<B>strongly</B>
+
+<B>discouraged</B>;
+
+they are included only to save hassles when dealing with
+the handful of perverted programs which already print
+network addresses in hexadecimal.
+<P>
+
+An IPv6 address is specified in text with
+colon-hex notation (e.g.
+<B>0:56:78ab:22:33:44:55:66</B>),
+
+colon-hex with
+<B>::</B>
+
+abbreviating at most one subsequence of multiple zeros (e.g.
+<B>99:ab::54:068</B>,
+
+which is synonymous with
+<B>99:ab:0:0:0:0:54:68</B>),
+
+or a DNS name to be looked up via
+<I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3).
+
+The result of applying
+<I>addrtot</I>
+
+to an IPv6 address will use
+<B>::</B>
+
+abbreviation if possible,
+and will not contain leading zeros.
+<P>
+
+The letters in hexadecimal
+may be uppercase or lowercase or any mixture thereof.
+<P>
+
+DNS names may be complete (optionally terminated with a ``.'')
+or incomplete, and are looked up as specified by local system configuration
+(see
+<I><A HREF="resolver.5.html">resolver</A></I>(5)).
+
+The
+<I>h_addr</I>
+
+value returned by
+<I><A HREF="gethostbyname2.3.html">gethostbyname2</A></I>(3)
+
+is used,
+so with current DNS implementations,
+the result when the name corresponds to more than one address is
+difficult to predict.
+IPv4 name lookup resorts to
+<I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3)
+
+only if
+<I><A HREF="gethostbyname2.3.html">gethostbyname2</A></I>(3)
+
+fails.
+<P>
+
+A subnet specification is of the form <I>network</I><B>/</B><I>mask</I>.
+The
+<I>network</I>
+
+and
+<I>mask</I>
+
+can be any form acceptable to
+<I>ttoaddr</I>.
+
+In addition, and preferably, the
+<I>mask</I>
+
+can be a decimal integer (leading zeros ignored) giving a bit count,
+in which case
+it stands for a mask with that number of high bits on and all others off
+(e.g.,
+<B>24</B>
+
+in IPv4 means
+<B>255.255.255.0</B>).
+
+In any case, the mask must be contiguous
+(a sequence of high bits on and all remaining low bits off).
+As a special case, the subnet specification
+<B>%default</B>
+
+is a synonym for
+<B>0.0.0.0/0</B>
+
+or
+<B>::/0</B>
+
+in IPv4 or IPv6 respectively.
+<P>
+
+<I>Ttosubnet</I>
+
+ANDs the mask with the address before returning,
+so that any non-network bits in the address are turned off
+(e.g.,
+<B>10.1.2.3/24</B>
+
+is synonymous with
+<B>10.1.2.0/24</B>).
+
+<I>Subnettot</I>
+
+always generates the decimal-integer-bit-count
+form of the mask,
+with no leading zeros.
+<P>
+
+The
+<I>srclen</I>
+
+parameter of
+<I>ttoaddr</I>
+
+and
+<I>ttosubnet</I>
+
+specifies the length of the text string pointed to by
+<I>src</I>;
+
+it is an error for there to be anything else
+(e.g., a terminating NUL) within that length.
+As a convenience for cases where an entire NUL-terminated string is
+to be converted,
+a
+<I>srclen</I>
+
+value of
+<B>0</B>
+
+is taken to mean
+<B>strlen(src)</B>.
+
+<P>
+
+The
+<I>af</I>
+
+parameter of
+<I>ttoaddr</I>
+
+and
+<I>ttosubnet</I>
+
+specifies the address family of interest.
+It should be either
+<B>AF_INET</B>
+
+or
+<B>AF_INET6</B>.
+
+<P>
+
+The
+<I>dstlen</I>
+
+parameter of
+<I>addrtot</I>
+
+and
+<I>subnettot</I>
+
+specifies the size of the
+<I>dst</I>
+
+parameter;
+under no circumstances are more than
+<I>dstlen</I>
+
+bytes written to
+<I>dst</I>.
+
+A result which will not fit is truncated.
+<I>Dstlen</I>
+
+can be zero, in which case
+<I>dst</I>
+
+need not be valid and no result is written,
+but the return value is unaffected;
+in all other cases, the (possibly truncated) result is NUL-terminated.
+The
+<I>freeswan.h</I>
+
+header file defines constants,
+<B>ADDRTOT_BUF</B>
+
+and
+<B>SUBNETTOT_BUF</B>,
+
+which are the sizes of buffers just large enough for worst-case results.
+<P>
+
+The
+<I>format</I>
+
+parameter of
+<I>addrtot</I>
+
+and
+<I>subnettot</I>
+
+specifies what format is to be used for the conversion.
+The value
+<B>0</B>
+
+(not the character
+<B>'0'</B>,
+
+but a zero value)
+specifies a reasonable default,
+and is in fact the only format currently available in
+<I>subnettot</I>.
+
+<I>Addrtot</I>
+
+also accepts format values
+<B>'r'</B>
+
+(signifying a text form suitable for DNS reverse lookups,
+e.g.
+<B>4.3.2.1.IN-ADDR.ARPA.</B>
+
+for IPv4 and
+RFC 2874 format for IPv6),
+and
+<B>'R'</B>
+
+(signifying an alternate reverse-lookup form,
+an error for IPv4 and RFC 1886 format for IPv6).
+Reverse-lookup names always end with a ``.''.
+<P>
+
+The text-to-binary functions return NULL for success and
+a pointer to a string-literal error message for failure;
+see DIAGNOSTICS.
+The binary-to-text functions return
+<B>0</B>
+
+for a failure, and otherwise
+always return the size of buffer which would
+be needed to
+accommodate the full conversion result, including terminating NUL;
+it is the caller's responsibility to check this against the size of
+the provided buffer to determine whether truncation has occurred.
+<A NAME="lbAE"> </A>
+<H2>SEE ALSO</H2>
+
+<A HREF="inet.3.html">inet</A>(3)
+<A NAME="lbAF"> </A>
+<H2>DIAGNOSTICS</H2>
+
+Fatal errors in
+<I>ttoaddr</I>
+
+are:
+empty input;
+unknown address family;
+attempt to allocate temporary storage for a very long name failed;
+name lookup failed;
+syntax error in dotted-decimal or colon-hex form;
+dotted-decimal or colon-hex component too large.
+<P>
+
+Fatal errors in
+<I>ttosubnet</I>
+
+are:
+no
+<B>/</B>
+
+in
+<I>src</I>;
+
+<I>ttoaddr</I>
+
+error in conversion of
+<I>network</I>
+
+or
+<I>mask</I>;
+
+bit-count mask too big;
+mask non-contiguous.
+<P>
+
+Fatal errors in
+<I>addrtot</I>
+
+and
+<I>subnettot</I>
+
+are:
+unknown format.
+<A NAME="lbAG"> </A>
+<H2>HISTORY</H2>
+
+Written for the FreeS/WAN project by Henry Spencer.
+<A NAME="lbAH"> </A>
+<H2>BUGS</H2>
+
+The interpretation of incomplete dotted-decimal addresses
+(e.g.
+<B>10/24</B>
+
+means
+<B>10.0.0.0/24</B>)
+
+differs from that of some older conversion
+functions, e.g. those of
+<I><A HREF="inet.3.html">inet</A></I>(3).
+
+The behavior of the older functions has never been
+particularly consistent or particularly useful.
+<P>
+
+Ignoring leading zeros in dotted-decimal components and bit counts
+is arguably the most useful behavior in this application,
+but it might occasionally cause confusion with the historical use of leading
+zeros to denote octal numbers.
+<P>
+
+<I>Ttoaddr</I>
+
+does not support the mixed colon-hex-dotted-decimal
+convention used to embed an IPv4 address in an IPv6 address.
+<P>
+
+<I>Addrtot</I>
+
+always uses the
+<B>::</B>
+
+abbreviation (which can appear only once in an address) for the
+<I>first</I>
+
+sequence of multiple zeros in an IPv6 address.
+One can construct addresses (unlikely ones) in which this is suboptimal.
+<P>
+
+<I>Addrtot</I>
+
+<B>'r'</B>
+
+conversion of an IPv6 address uses lowercase hexadecimal,
+not the uppercase used in RFC 2874's examples.
+It takes careful reading of RFCs 2874, 2673, and 2234 to realize
+that lowercase is technically legitimate here,
+and there may be software which botches this
+and hence would have trouble with lowercase hex.
+<P>
+
+Possibly
+<I>subnettot</I>
+
+ought to recognize the
+<B>%default</B>
+
+case and generate that string as its output.
+Currently it doesn't.
+<P>
+
+It is barely possible that somebody, somewhere,
+might have a legitimate use for non-contiguous subnet masks.
+<P>
+
+<I><A HREF="Getnetbyname.3.html">Getnetbyname</A></I>(3)
+
+is a historical dreg.
+<P>
+
+<I>Tnatoaddr</I>
+
+probably should enforce completeness of dotted-decimal addresses.
+<P>
+
+The restriction of text-to-binary error reports to literal strings
+(so that callers don't need to worry about freeing them or copying them)
+does limit the precision of error reporting.
+<P>
+
+The text-to-binary error-reporting convention lends itself
+to slightly obscure code,
+because many readers will not think of NULL as signifying success.
+A good way to make it clearer is to write something like:
+<P>
+
+<DL COMPACT><DT><DD>
+<PRE>
+<B>const char *error;</B>
+
+<B>error = ttoaddr( /* ... */ );</B>
+<B>if (error != NULL) {</B>
+<B> /* something went wrong */</B>
+</PRE>
+
+</DL>
+
+<P>
+
+<HR>
+<A NAME="index"> </A><H2>Index</H2>
+<DL>
+<DT><A HREF="#lbAB">NAME</A><DD>
+<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
+<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
+<DT><A HREF="#lbAE">SEE ALSO</A><DD>
+<DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
+<DT><A HREF="#lbAG">HISTORY</A><DD>
+<DT><A HREF="#lbAH">BUGS</A><DD>
+</DL>
+<HR>
+This document was created by
+<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
+using the manual pages.<BR>
+Time: 21:40:18 GMT, November 11, 2003
+</BODY>
+</HTML>
projects / thirdparty / strongswan.git / blobdiff