- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -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:18 GMT, November 11, 2003
|
||||
</BODY>
|
||||
</HTML>
|
||||
Reference in New Issue
Block a user