---
name: "atoul"
section: "3"
platform: "linux"
package: "strongswan"
version: "4.2.4-5+lenny3"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/atoul"
---

# atoul(3)

convert unsigned-long numbers to and from ASCII

## NAME

ipsec atoul, ultoa - convert unsigned-long numbers to and from ASCII

## SYNOPSIS

**#include \<freeswan.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)](/ipsec_ttoul/3.md) 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)](/atol/3.md), [strtoul(3)](/strtoul/3.md)

## 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 */
```