- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -0,0 +1,439 @@
|
||||
Content-type: text/html
|
||||
|
||||
<HTML><HEAD><TITLE>Manpage of IPSEC_TTODATA</TITLE>
|
||||
</HEAD><BODY>
|
||||
<H1>IPSEC_TTODATA</H1>
|
||||
Section: C Library Functions (3)<BR>Updated: 16 August 2003<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 ttodata, datatot - convert binary data bytes from and to text formats
|
||||
<A NAME="lbAC"> </A>
|
||||
<H2>SYNOPSIS</H2>
|
||||
|
||||
<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
|
||||
|
||||
<P>
|
||||
<B>const char *ttodata(const char *src, size_t srclen,</B>
|
||||
|
||||
<BR>
|
||||
|
||||
<B>int base, char *dst, size_t dstlen, size_t *lenp);</B>
|
||||
|
||||
<BR>
|
||||
|
||||
<B>const char *ttodatav(const char *src, size_t srclen,</B>
|
||||
|
||||
<BR>
|
||||
|
||||
<B>int base, char *dst, size_t dstlen, size_t *lenp,</B>
|
||||
|
||||
<BR>
|
||||
|
||||
<B>char *errp, size_t errlen, int flags);</B>
|
||||
|
||||
<BR>
|
||||
|
||||
<B>size_t datatot(const char *src, size_t srclen,</B>
|
||||
|
||||
<BR>
|
||||
|
||||
<B>int format, char *dst, size_t dstlen);</B>
|
||||
|
||||
<A NAME="lbAD"> </A>
|
||||
<H2>DESCRIPTION</H2>
|
||||
|
||||
<I>Ttodata</I>,
|
||||
|
||||
<I>ttodatav</I>,
|
||||
|
||||
and
|
||||
<I>datatot</I>
|
||||
|
||||
convert arbitrary binary data (e.g. encryption or authentication keys)
|
||||
from and to more-or-less human-readable text formats.
|
||||
<P>
|
||||
|
||||
Currently supported formats are hexadecimal, base64, and characters.
|
||||
<P>
|
||||
|
||||
A hexadecimal text value begins with a
|
||||
<B>0x</B>
|
||||
|
||||
(or
|
||||
<B>0X</B>)
|
||||
|
||||
prefix and continues with two-digit groups
|
||||
of hexadecimal digits (0-9, and a-f or A-F),
|
||||
each group encoding the value of one binary byte, high-order digit first.
|
||||
A single
|
||||
<B>_</B>
|
||||
|
||||
(underscore)
|
||||
between consecutive groups is ignored, permitting punctuation to improve
|
||||
readability; doing this every eight digits seems about right.
|
||||
<P>
|
||||
|
||||
A base64 text value begins with a
|
||||
<B>0s</B>
|
||||
|
||||
(or
|
||||
<B>0S</B>)
|
||||
|
||||
prefix
|
||||
and continues with four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /),
|
||||
each group encoding the value of three binary bytes as described in
|
||||
section 6.8 of RFC 2045.
|
||||
If
|
||||
<B>flags</B>
|
||||
|
||||
has the
|
||||
<B>TTODATAV_IGNORESPACE</B>
|
||||
|
||||
bit on, blanks are ignore (after the prefix).
|
||||
Note that the last one or two digits of a base64 group can be
|
||||
<B>=</B>
|
||||
|
||||
to indicate that fewer than three binary bytes are encoded.
|
||||
<P>
|
||||
|
||||
A character text value begins with a
|
||||
<B>0t</B>
|
||||
|
||||
(or
|
||||
<B>0T</B>)
|
||||
|
||||
prefix
|
||||
and continues with text characters, each being the value of one binary byte.
|
||||
<P>
|
||||
|
||||
All these functions basically copy data from
|
||||
<I>src</I>
|
||||
|
||||
(whose size is specified by
|
||||
<I>srclen</I>)
|
||||
|
||||
to
|
||||
<I>dst</I>
|
||||
|
||||
(whose size is specified by
|
||||
<I>dstlen</I>),
|
||||
|
||||
doing the conversion en route.
|
||||
If the result will not fit in
|
||||
<I>dst</I>,
|
||||
|
||||
it is truncated;
|
||||
under no circumstances are more than
|
||||
<I>dstlen</I>
|
||||
|
||||
bytes of result written to
|
||||
<I>dst</I>.
|
||||
|
||||
<I>Dstlen</I>
|
||||
|
||||
can be zero, in which case
|
||||
<I>dst</I>
|
||||
|
||||
need not be valid and no result bytes are written at all.
|
||||
<P>
|
||||
|
||||
The
|
||||
<I>base</I>
|
||||
|
||||
parameter of
|
||||
<I>ttodata</I>
|
||||
|
||||
and
|
||||
<I>ttodatav</I>
|
||||
|
||||
specifies what format the input is in;
|
||||
normally it should be
|
||||
<B>0</B>
|
||||
|
||||
to signify that this gets figured out from the prefix.
|
||||
Values of
|
||||
<B>16</B>,
|
||||
|
||||
<B>64</B>,
|
||||
|
||||
and
|
||||
<B>256</B>
|
||||
|
||||
respectively signify hexadecimal, base64, and character-text formats
|
||||
without prefixes.
|
||||
<P>
|
||||
|
||||
The
|
||||
<I>format</I>
|
||||
|
||||
parameter of
|
||||
<I>datatot</I>,
|
||||
|
||||
a single character used as a type code,
|
||||
specifies which text format is wanted.
|
||||
The value
|
||||
<B>0</B>
|
||||
|
||||
(not ASCII
|
||||
<B>'0'</B>,
|
||||
|
||||
but a zero value) specifies a reasonable default.
|
||||
Other currently-supported values are:
|
||||
<DL COMPACT><DT><DD>
|
||||
<DL COMPACT>
|
||||
<DT><B>'x'</B>
|
||||
|
||||
<DD>
|
||||
continuous lower-case hexadecimal with a
|
||||
<B>0x</B>
|
||||
|
||||
prefix
|
||||
<DT><B>'h'</B>
|
||||
|
||||
<DD>
|
||||
lower-case hexadecimal with a
|
||||
<B>0x</B>
|
||||
|
||||
prefix and a
|
||||
<B>_</B>
|
||||
|
||||
every eight digits
|
||||
<DT><B>':'</B>
|
||||
|
||||
<DD>
|
||||
lower-case hexadecimal with no prefix and a
|
||||
<B>:</B>
|
||||
|
||||
(colon) every two digits
|
||||
<DT><B>16</B>
|
||||
|
||||
<DD>
|
||||
lower-case hexadecimal with no prefix or
|
||||
<B>_</B>
|
||||
|
||||
<DT><B>'s'</B>
|
||||
|
||||
<DD>
|
||||
continuous base64 with a
|
||||
<B>0s</B>
|
||||
|
||||
prefix
|
||||
<DT><B>64</B>
|
||||
|
||||
<DD>
|
||||
continuous base64 with no prefix
|
||||
</DL>
|
||||
</DL>
|
||||
|
||||
<P>
|
||||
|
||||
The default format is currently
|
||||
<B>'h'</B>.
|
||||
|
||||
<P>
|
||||
|
||||
<I>Ttodata</I>
|
||||
|
||||
returns NULL for success and
|
||||
a pointer to a string-literal error message for failure;
|
||||
see DIAGNOSTICS.
|
||||
On success,
|
||||
if and only if
|
||||
<I>lenp</I>
|
||||
|
||||
is non-NULL,
|
||||
<B>*lenp</B>
|
||||
|
||||
is set to the number of bytes required to contain the full untruncated result.
|
||||
It is the caller's responsibility to check this against
|
||||
<I>dstlen</I>
|
||||
|
||||
to determine whether he has obtained a complete result.
|
||||
The
|
||||
<B>*lenp</B>
|
||||
|
||||
value is correct even if
|
||||
<I>dstlen</I>
|
||||
|
||||
is zero, which offers a way to determine how much space would be needed
|
||||
before having to allocate any.
|
||||
<P>
|
||||
|
||||
<I>Ttodatav</I>
|
||||
|
||||
is just like
|
||||
<I>ttodata</I>
|
||||
|
||||
except that in certain cases,
|
||||
if
|
||||
<I>errp</I>
|
||||
|
||||
is non-NULL,
|
||||
the buffer pointed to by
|
||||
<I>errp</I>
|
||||
|
||||
(whose length is given by
|
||||
<I>errlen</I>)
|
||||
|
||||
is used to hold a more detailed error message.
|
||||
The return value is NULL for success,
|
||||
and is either
|
||||
<I>errp</I>
|
||||
|
||||
or a pointer to a string literal for failure.
|
||||
If the size of the error-message buffer is
|
||||
inadequate for the desired message,
|
||||
<I>ttodatav</I>
|
||||
|
||||
will fall back on returning a pointer to a literal string instead.
|
||||
The
|
||||
<I>freeswan.h</I>
|
||||
|
||||
header file defines a constant
|
||||
<B>TTODATAV_BUF</B>
|
||||
|
||||
which is the size of a buffer large enough for worst-case results.
|
||||
<P>
|
||||
|
||||
The normal return value of
|
||||
<I>datatot</I>
|
||||
|
||||
is the number of bytes required
|
||||
to contain the full untruncated result.
|
||||
It is the caller's responsibility to check this against
|
||||
<I>dstlen</I>
|
||||
|
||||
to determine whether he has obtained a complete result.
|
||||
The return value is correct even if
|
||||
<I>dstlen</I>
|
||||
|
||||
is zero, which offers a way to determine how much space would be needed
|
||||
before having to allocate any.
|
||||
A return value of
|
||||
<B>0</B>
|
||||
|
||||
signals a fatal error of some kind
|
||||
(see DIAGNOSTICS).
|
||||
<P>
|
||||
|
||||
A zero value for
|
||||
<I>srclen</I>
|
||||
|
||||
in
|
||||
<I>ttodata</I>
|
||||
|
||||
(but not
|
||||
<I>datatot</I>!)
|
||||
|
||||
is synonymous with
|
||||
<B>strlen(src)</B>.
|
||||
|
||||
A non-zero
|
||||
<I>srclen</I>
|
||||
|
||||
in
|
||||
<I>ttodata</I>
|
||||
|
||||
must not include the terminating NUL.
|
||||
<P>
|
||||
|
||||
Unless
|
||||
<I>dstlen</I>
|
||||
|
||||
is zero,
|
||||
the result supplied by
|
||||
<I>datatot</I>
|
||||
|
||||
is always NUL-terminated,
|
||||
and its needed-size return value includes space for the terminating NUL.
|
||||
<P>
|
||||
|
||||
Several obsolete variants of these functions
|
||||
(<I>atodata</I>,
|
||||
|
||||
<I>datatoa</I>,
|
||||
|
||||
<I>atobytes</I>,
|
||||
|
||||
and
|
||||
<I>bytestoa</I>)
|
||||
|
||||
are temporarily also supported.
|
||||
<A NAME="lbAE"> </A>
|
||||
<H2>SEE ALSO</H2>
|
||||
|
||||
<A HREF="sprintf.3.html">sprintf</A>(3), <A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A>(3)
|
||||
<A NAME="lbAF"> </A>
|
||||
<H2>DIAGNOSTICS</H2>
|
||||
|
||||
Fatal errors in
|
||||
<I>ttodata</I>
|
||||
|
||||
and
|
||||
<I>ttodatav</I>
|
||||
|
||||
are:
|
||||
unknown characters in the input;
|
||||
unknown or missing prefix;
|
||||
unknown base;
|
||||
incomplete digit group;
|
||||
non-zero padding in a base64 less-than-three-bytes digit group;
|
||||
zero-length input.
|
||||
<P>
|
||||
|
||||
Fatal errors in
|
||||
<I>datatot</I>
|
||||
|
||||
are:
|
||||
unknown format code;
|
||||
zero-length input.
|
||||
<A NAME="lbAG"> </A>
|
||||
<H2>HISTORY</H2>
|
||||
|
||||
Written for the FreeS/WAN project by Henry Spencer.
|
||||
<A NAME="lbAH"> </A>
|
||||
<H2>BUGS</H2>
|
||||
|
||||
<I>Datatot</I>
|
||||
|
||||
should have a format code to produce character-text output.
|
||||
<P>
|
||||
|
||||
The
|
||||
<B>0s</B>
|
||||
|
||||
and
|
||||
<B>0t</B>
|
||||
|
||||
prefixes are the author's inventions and are not a standard
|
||||
of any kind.
|
||||
They have been chosen to avoid collisions with existing practice
|
||||
(some C implementations use
|
||||
<B>0b</B>
|
||||
|
||||
for binary)
|
||||
and possible confusion with unprefixed hexadecimal.
|
||||
<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