ipsec_ttoul(3) [centos man page]
IPSEC_TTOUL(3) 16 Aug 2000 IPSEC_TTOUL(3) NAME
ipsec_ttoul, ipsec_ultot - convert unsigned-long numbers to and from text SYNOPSIS
#include <freeswan.h> const char *ttoul(const char * src, size_t srclen, int base, unsigned long * n); size_t ultot(unsigned long n, int format, char * dst, size_t dstlen); DESCRIPTION
Ttoul converts a text-string number into a binary unsigned long value. Ultot does the reverse conversion, back to a text version. Numbers are specified in text as decimal (e.g. 123), octal with a leading zero (e.g. 012, which has value 10), or hexadecimal with a leading 0x (e.g. 0x1f, which has value 31) in either upper or lower case. The srclen parameter of ttoul specifies the length of the string pointed to by src; 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 srclen value of 0 is taken to mean strlen(src). The base parameter of ttoul can be 8, 10, or 16, in which case the number supplied is assumed to be of that form (and in the case of 16, to lack any 0x prefix). It can also be 0, in which case the number is examined for a leading zero or a leading 0x to determine its base. The dstlen parameter of ultot specifies the size of the dst parameter; under no circumstances are more than dstlen bytes written to dst. A result which will not fit is truncated. Dstlen can be zero, in which case dst 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 freeswan.h header file defines a constant, ULTOT_BUF, which is the size of a buffer just large enough for worst-case results. The format parameter of ultot must be one of: 'o' octal conversion with leading 0 8 octal conversion with no leading 0 'd' decimal conversion 10 same as d 'x' hexadecimal conversion, including leading 0x 16 hexadecimal conversion with no leading 0x 17 like 16 except padded on left with 0s to eight digits (full width of a 32-bit number) Ttoul returns NULL for success and a pointer to a string-literal error message for failure; see DIAGNOSTICS. Ultot returns 0 for a failure, and otherwise 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). SEE ALSO
atol(3), strtoul(3) DIAGNOSTICS
Fatal errors in ttoul are: empty input; unknown base; non-digit character found; number too large for an unsigned long. Fatal errors in ultot are: unknown format. HISTORY
Written for the FreeS/WAN project by Henry Spencer. BUGS
Conversion of 0 with format o yields 00. Ultot format 17 is a bit of a kludge. The restriction of 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. The 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: const char *error; error = ttoul( /* ... */ ); if (error != NULL) { /* something went wrong */ 16 Aug 2000 11/14/2008 IPSEC_TTOUL(3)
Check Out this Related Man Page
IPSEC_TTODATA(3) 16 August 2003 IPSEC_TTODATA(3) NAME
ipsec_ttodata, ipsec_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. SEE ALSO
sprintf(3), ipsec_atoaddr(3) 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. 16 August 2003 11/14/2008 IPSEC_TTODATA(3)