diff options
Diffstat (limited to 'doc/manpage.d/ipsec_addrtot.3.html')
| -rw-r--r-- | doc/manpage.d/ipsec_addrtot.3.html | 569 |
1 files changed, 569 insertions, 0 deletions
diff --git a/doc/manpage.d/ipsec_addrtot.3.html b/doc/manpage.d/ipsec_addrtot.3.html new file mode 100644 index 000000000..eccb946e6 --- /dev/null +++ b/doc/manpage.d/ipsec_addrtot.3.html @@ -0,0 +1,569 @@ +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:17 GMT, November 11, 2003 +</BODY> +</HTML> |