+++ /dev/null
-Content-type: text/html
-
-<HTML><HEAD><TITLE>Manpage of IPSEC_TTOSA</TITLE>
-</HEAD><BODY>
-<H1>IPSEC_TTOSA</H1>
-Section: C Library Functions (3)<BR>Updated: 26 Nov 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 ttosa, satot - convert IPsec Security Association IDs to and from text
-<BR>
-
-ipsec initsaid - initialize an SA ID
-<A NAME="lbAC"> </A>
-<H2>SYNOPSIS</H2>
-
-<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
-
-<P>
-<B>typedef struct {</B>
-
-<BR>
-
-<B>ip_address dst;</B>
-
-<BR>
-
-<B>ipsec_spi_t spi;</B>
-
-<BR>
-
-<B>int proto;</B>
-
-<BR>
-
-<B>} ip_said;</B>
-
-<P>
-<B>const char *ttosa(const char *src, size_t srclen,</B>
-
-<BR>
-
-<B>ip_said *sa);</B>
-
-<BR>
-
-<B>size_t satot(const ip_said *sa, int format,</B>
-
-<BR>
-
-<B>char *dst, size_t dstlen);</B>
-
-<BR>
-
-<B>void initsaid(const ip_address *addr, ipsec_spi_t spi,</B>
-
-<BR>
-
-<B>int proto, ip_said *dst);</B>
-
-<A NAME="lbAD"> </A>
-<H2>DESCRIPTION</H2>
-
-<I>Ttosa</I>
-
-converts an ASCII Security Association (SA) specifier into an
-<B>ip_said</B>
-
-structure (containing
-a destination-host address
-in network byte order,
-an SPI number in network byte order, and
-a protocol code).
-<I>Satot</I>
-
-does the reverse conversion, back to a text SA specifier.
-<I>Initsaid</I>
-
-initializes an
-<B>ip_said</B>
-
-from separate items of information.
-<P>
-
-An SA is specified in text with a mail-like syntax, e.g.
-<B><A HREF="mailto:esp.5a7@1.2.3.4">esp.5a7@1.2.3.4</A></B>.
-
-An SA specifier contains
-a protocol prefix (currently
-<B>ah</B>,
-
-<B>esp</B>,
-
-<B>tun</B>,
-
-<B>comp</B>,
-
-or
-<B>int</B>),
-
-a single character indicating the address family
-(<B>.</B>
-
-for IPv4,
-<B>:</B>
-
-for IPv6),
-an unsigned integer SPI number in hexadecimal (with no
-<B>0x</B>
-
-prefix),
-and an IP address.
-The IP address can be any form accepted by
-<I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3),
-
-e.g. dotted-decimal IPv4 address,
-colon-hex IPv6 address,
-or DNS name.
-<P>
-
-As a special case, the SA specifier
-<B>%passthrough4</B>
-
-or
-<B>%passthrough6</B>
-
-signifies the special SA used to indicate that packets should be
-passed through unaltered.
-(At present, these are synonyms for
-<B><A HREF="mailto:tun.0@0.0.0.0">tun.0@0.0.0.0</A></B>
-
-and
-<B>tun:0@::</B>
-
-respectively,
-but that is subject to change without notice.)
-<B>%passthrough</B>
-
-is a historical synonym for
-<B>%passthrough4</B>.
-
-These forms are known to both
-<I>ttosa</I>
-
-and
-<I>satot</I>,
-
-so the internal representation is never visible.
-<P>
-
-Similarly, the SA specifiers
-<B>%pass</B>,
-
-<B>%drop</B>,
-
-<B>%reject</B>,
-
-<B>%hold</B>,
-
-<B>%trap</B>,
-
-and
-<B>%trapsubnet</B>
-
-signify special ``magic'' SAs used to indicate that packets should be
-passed, dropped, rejected (dropped with ICMP notification),
-held,
-and trapped (sent up to
-<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8),
-
-with either of two forms of
-<B>%hold</B>
-
-automatically installed)
-respectively.
-These forms too are known to both routines,
-so the internal representation of the magic SAs should never be visible.
-<P>
-
-The
-<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
-
-header file supplies the
-<B>ip_said</B>
-
-structure, as well as a data type
-<B>ipsec_spi_t</B>
-
-which is an unsigned 32-bit integer.
-(There is no consistency between kernel and user on what such a type
-is called, hence the header hides the differences.)
-<P>
-
-The protocol code uses the same numbers that IP does.
-For user convenience, given the difficulty in acquiring the exact set of
-protocol names used by the kernel,
-<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
-
-defines the names
-<B>SA_ESP</B>,
-
-<B>SA_AH</B>,
-
-<B>SA_IPIP</B>,
-
-and
-<B>SA_COMP</B>
-
-to have the same values as the kernel names
-<B>IPPROTO_ESP</B>,
-
-<B>IPPROTO_AH</B>,
-
-<B>IPPROTO_IPIP</B>,
-
-and
-<B>IPPROTO_COMP</B>.
-
-<P>
-
-<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
-
-also defines
-<B>SA_INT</B>
-
-to have the value
-<B>61</B>
-
-(reserved by IANA for ``any host internal protocol'')
-and
-<B>SPI_PASS</B>,
-
-<B>SPI_DROP</B>,
-
-<B>SPI_REJECT</B>,
-
-<B>SPI_HOLD</B>,
-
-and
-<B>SPI_TRAP</B>
-
-to have the values 256-260 (in <I>host</I> byte order) respectively.
-These are used in constructing the magic SAs
-(which always have address
-<B>0.0.0.0</B>).
-
-<P>
-
-If
-<I>satot</I>
-
-encounters an unknown protocol code, e.g. 77,
-it yields output using a prefix
-showing the code numerically, e.g. ``unk77''.
-This form is
-<I>not</I>
-
-recognized by
-<I>ttosa</I>.
-
-<P>
-
-The
-<I>srclen</I>
-
-parameter of
-<I>ttosa</I>
-
-specifies the length of the 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>dstlen</I>
-
-parameter of
-<I>satot</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
-<B><<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
-
-header file defines a constant,
-<B>SATOT_BUF</B>,
-
-which is the size of a buffer just large enough for worst-case results.
-<P>
-
-The
-<I>format</I>
-
-parameter of
-<I>satot</I>
-
-specifies what format is to be used for the conversion.
-The value
-<B>0</B>
-
-(not the ASCII character
-<B>'0'</B>,
-
-but a zero value)
-specifies a reasonable default
-(currently
-lowercase protocol prefix, lowercase hexadecimal SPI,
-dotted-decimal or colon-hex address).
-The value
-<B>'f'</B>
-
-is similar except that the SPI is padded with
-<B>0</B>s
-
-to a fixed 32-bit width, to ease aligning displayed tables.
-<P>
-
-<I>Ttosa</I>
-
-returns
-<B>NULL</B>
-
-for success and
-a pointer to a string-literal error message for failure;
-see DIAGNOSTICS.
-<I>Satot</I>
-
-returns
-<B>0</B>
-
-for a failure, and otherwise
-always returns 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.
-<P>
-
-There is also, temporarily, support for some obsolete
-forms of SA specifier which lack the address-family indicator.
-<A NAME="lbAE"> </A>
-<H2>SEE ALSO</H2>
-
-<A HREF="ipsec_ttoul.3.html">ipsec_ttoul</A>(3), <A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A>(3), <A HREF="ipsec_samesaid.3.html">ipsec_samesaid</A>(3), <A HREF="inet.3.html">inet</A>(3)
-<A NAME="lbAF"> </A>
-<H2>DIAGNOSTICS</H2>
-
-Fatal errors in
-<I>ttosa</I>
-
-are:
-empty input;
-input too small to be a legal SA specifier;
-no
-<B>@</B>
-
-in input;
-unknown protocol prefix;
-conversion error in
-<I>ttoul</I>
-
-or
-<I>ttoaddr</I>.
-
-<P>
-
-Fatal errors in
-<I>satot</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 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 = ttosa( /* ... */ );</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