From aa0f5b38aec14428b4b80e06f90ff781f8bca5f1 Mon Sep 17 00:00:00 2001 From: Rene Mayrhofer Date: Mon, 22 May 2006 05:12:18 +0000 Subject: Import initial strongswan 2.7.0 version into SVN. --- doc/manpage.d/ipsec_datatot.3.html | 439 +++++++++++++++++++++++++++++++++++++ 1 file changed, 439 insertions(+) create mode 100644 doc/manpage.d/ipsec_datatot.3.html (limited to 'doc/manpage.d/ipsec_datatot.3.html') diff --git a/doc/manpage.d/ipsec_datatot.3.html b/doc/manpage.d/ipsec_datatot.3.html new file mode 100644 index 000000000..628558001 --- /dev/null +++ b/doc/manpage.d/ipsec_datatot.3.html @@ -0,0 +1,439 @@ +Content-type: text/html + +Manpage of IPSEC_TTODATA + +

IPSEC_TTODATA

+Section: C Library Functions (3)
Updated: 16 August 2003
Index +Return to Main Contents

+ + + +

NAME

+ +ipsec ttodata, datatot - convert binary data bytes from and to text formats + +

SYNOPSIS

+ +#include <freeswan.h> + +

+const char *ttodata(const char *src, size_t srclen, + +
+ +int base, char *dst, size_t dstlen, size_t *lenp); + +
+ +const char *ttodatav(const char *src, size_t srclen, + +
+ +int base, char *dst, size_t dstlen, size_t *lenp, + +
+ +char *errp, size_t errlen, int flags); + +
+ +size_t datatot(const char *src, size_t srclen, + +
+ +int format, char *dst, size_t dstlen); + + +

DESCRIPTION

+ +Ttodata, + +ttodatav, + +and +datatot + +convert arbitrary binary data (e.g. encryption or authentication keys) +from and to more-or-less human-readable text formats. +

+ +Currently supported formats are hexadecimal, base64, and characters. +

+ +A hexadecimal text value begins with a +0x + +(or +0X) + +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 +_ + +(underscore) +between consecutive groups is ignored, permitting punctuation to improve +readability; doing this every eight digits seems about right. +

+ +A base64 text value begins with a +0s + +(or +0S) + +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 +flags + +has the +TTODATAV_IGNORESPACE + +bit on, blanks are ignore (after the prefix). +Note that the last one or two digits of a base64 group can be += + +to indicate that fewer than three binary bytes are encoded. +

+ +A character text value begins with a +0t + +(or +0T) + +prefix +and continues with text characters, each being the value of one binary byte. +

+ +All these functions basically copy data from +src + +(whose size is specified by +srclen) + +to +dst + +(whose size is specified by +dstlen), + +doing the conversion en route. +If the result will not fit in +dst, + +it is truncated; +under no circumstances are more than +dstlen + +bytes of result written to +dst. + +Dstlen + +can be zero, in which case +dst + +need not be valid and no result bytes are written at all. +

+ +The +base + +parameter of +ttodata + +and +ttodatav + +specifies what format the input is in; +normally it should be +0 + +to signify that this gets figured out from the prefix. +Values of +16, + +64, + +and +256 + +respectively signify hexadecimal, base64, and character-text formats +without prefixes. +

+ +The +format + +parameter of +datatot, + +a single character used as a type code, +specifies which text format is wanted. +The value +0 + +(not ASCII +'0', + +but a zero value) specifies a reasonable default. +Other currently-supported values are: +

'x' + +: +continuous lower-case hexadecimal with a +0x + +prefix +
'h' + +: +lower-case hexadecimal with a +0x + +prefix and a +_ + +every eight digits +
':' + +: +lower-case hexadecimal with no prefix and a +: + +(colon) every two digits +
16 + +: +lower-case hexadecimal with no prefix or +_ + +
's' + +: +continuous base64 with a +0s + +prefix +
64 + +: +continuous base64 with no prefix +

+ +

+ +The default format is currently +'h'. + +

+ +Ttodata + +returns NULL for success and +a pointer to a string-literal error message for failure; +see DIAGNOSTICS. +On success, +if and only if +lenp + +is non-NULL, +*lenp + +is set to the number of bytes required to contain the full untruncated result. +It is the caller's responsibility to check this against +dstlen + +to determine whether he has obtained a complete result. +The +*lenp + +value is correct even if +dstlen + +is zero, which offers a way to determine how much space would be needed +before having to allocate any. +

+ +Ttodatav + +is just like +ttodata + +except that in certain cases, +if +errp + +is non-NULL, +the buffer pointed to by +errp + +(whose length is given by +errlen) + +is used to hold a more detailed error message. +The return value is NULL for success, +and is either +errp + +or a pointer to a string literal for failure. +If the size of the error-message buffer is +inadequate for the desired message, +ttodatav + +will fall back on returning a pointer to a literal string instead. +The +freeswan.h + +header file defines a constant +TTODATAV_BUF + +which is the size of a buffer large enough for worst-case results. +

+ +The normal return value of +datatot + +is the number of bytes required +to contain the full untruncated result. +It is the caller's responsibility to check this against +dstlen + +to determine whether he has obtained a complete result. +The return value is correct even if +dstlen + +is zero, which offers a way to determine how much space would be needed +before having to allocate any. +A return value of +0 + +signals a fatal error of some kind +(see DIAGNOSTICS). +

+ +A zero value for +srclen + +in +ttodata + +(but not +datatot!) + +is synonymous with +strlen(src). + +A non-zero +srclen + +in +ttodata + +must not include the terminating NUL. +

+ +Unless +dstlen + +is zero, +the result supplied by +datatot + +is always NUL-terminated, +and its needed-size return value includes space for the terminating NUL. +

+ +Several obsolete variants of these functions +(atodata, + +datatoa, + +atobytes, + +and +bytestoa) + +are temporarily also supported. + +

DIAGNOSTICS

+ +Fatal errors in +ttodata + +and +ttodatav + +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. +

+ +Fatal errors in +datatot + +are: +unknown format code; +zero-length input. + +

HISTORY

+ +Written for the FreeS/WAN project by Henry Spencer. + +

BUGS

+ +Datatot + +should have a format code to produce character-text output. +

+ +The +0s + +and +0t + +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 +0b + +for binary) +and possible confusion with unprefixed hexadecimal. +

+ +

+This document was created by +man2html, +using the manual pages.
+Time: 21:40:17 GMT, November 11, 2003 + + -- cgit v1.2.3