--- name: "ttodata" section: "3" platform: "linux" package: "strongswan" version: "4.2.4-5+lenny3" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/ttodata" --- # ttodata(3) convert binary data bytes from and to text formats ## NAME ipsec ttodata, datatot - convert binary data bytes from and to text formats ## SYNOPSIS **#include \** **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. ## SEE ALSO [sprintf(3)](/sprintf/3.md), [ipsec\_atoaddr(3)](/ipsec_atoaddr/3.md) ## 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.