Paul Wouters

placeholder to suppress warning

IPSEC_ATOUL 3 11 June 2001 11 June 2001 libreswan Executable programs
ipsec atoul ipsec ultoa convert unsigned-long numbers to and from ASCII

    #include <libreswan.h>

const char *`atoul` const char * src size_t srclen int base unsigned long * n

size_t `ultoa` unsigned long n int base char * dst size_t dstlen

## DESCRIPTION

These functions are obsolete; see ipsec_ttoul 3 for their replacements.

Atoul converts an ASCII number into a binary unsigned long value. Ultoa does the reverse conversion, back to an ASCII version.

Numbers are specified in ASCII 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 `atoul` specifies the length of the ASCII 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 `atoul` 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, or `13` (halfway between 10 and 16), which has the same effect as `0` except that a non-hexadecimal number is considered decimal regardless of any leading zero.

The `dstlen` parameter of `ultoa` 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 `base` parameter of `ultoa` must be `8`, `10`, or `16`.

Atoul returns NULL for success and a pointer to a string-literal error message for failure; see DIAGNOSTICS. Ultoa 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 `atoul` are: empty input; unknown `base`; non-digit character found; number too large for an unsigned long.

## HISTORY

Written for the FreeS/WAN project by Henry Spencer.

## BUGS

There is no provision for reporting an invalid `base` parameter given to `ultoa`.

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 = atoul( /* ... */ );
    if (error != NULL) {
            /* something went wrong */