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, 0 insertions, 569 deletions
diff --git a/doc/manpage.d/ipsec_addrtot.3.html b/doc/manpage.d/ipsec_addrtot.3.html deleted file mode 100644 index eccb946e6..000000000 --- a/doc/manpage.d/ipsec_addrtot.3.html +++ /dev/null @@ -1,569 +0,0 @@ -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> |