---
name: "ipsec_atoul"
section: "3"
platform: "linux"
package: "openswan"
version: "1:2.6.37-3+deb7u1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/ipsec_atoul"
---

# ipsec\_atoul(3)

convert unsigned-long numbers to and from ASCII

## NAME

ipsec\_atoul, ipsec\_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 */
```