STRTOUL(3) | Library Functions Manual | STRTOUL(3) |

`strtoul`

, `strtoull`

,
`strtoumax`

, `strtouq`

—
convert a string to an unsigned long, unsigned long long or
uintmax_t integer

```
#include
<limits.h>
```

`#include <stdlib.h>`

`unsigned long`

`strtoul`

(`const
char *nptr`, `char
**endptr`, `int
base`);

`unsigned long long`

`strtoull`

(`const
char *nptr`, `char
**endptr`, `int
base`);

```
#include
<inttypes.h>
```

`uintmax_t`

`strtoumax`

(`const
char *nptr`, `char
**endptr`, `int
base`);

```
#include
<sys/types.h>
```

`#include <limits.h>`

`#include <stdlib.h>`

`u_quad_t`

`strtouq`

(`const
char *nptr`, `char
**endptr`, `int
base`);

The `strtoul`

() function converts the string
in `nptr` to an `unsigned long`
value. The `strtoull`

() function converts the string
in `nptr` to an `unsigned long long`
value. The `strtoumax`

() function converts the string
in `nptr` to a `umaxint_t` value.
The `strtouq`

() function is a deprecated equivalent of
`strtoull`

() and is provided for backwards
compatibility with legacy programs. The conversion is done according to the
given `base`, which must be a number between 2 and 36
inclusive or the special value 0. If the string in
`nptr` represents a negative number, it will be
converted to its unsigned equivalent. This behavior is consistent with what
happens when a signed integer type is cast to its unsigned counterpart.

The string may begin with an arbitrary amount of whitespace (as
determined by isspace(3)) followed by a
single optional ‘`+`

’ or
‘`-`

’ sign. If
`base` is zero or 16, the string may then include a
‘`0x`

’ prefix, and the number will be
read in base 16; otherwise, a zero `base` is taken as 10
(decimal) unless the next character is
‘`0`

’, in which case it is taken as 8
(octal).

The remainder of the string is converted to an
`unsigned long`, `unsigned long
long`, or `uintmax_t` value in the obvious manner,
stopping at the first character which is not a valid digit in the given
base. (In bases above 10, the letter
‘`A`

’ in either upper or lower case
represents 10, ‘`B`

’ represents 11, and
so forth, with ‘`Z`

’ representing
35.)

If `endptr` is non-null,
`strtoul`

() stores the address of the first invalid
character in `*endptr`. If there were no digits at all,
however, `strtoul`

() stores the original value of
`nptr` in `*endptr`. (Thus, if
`*nptr` is not
‘`\0`

’ but
`**endptr` is ‘`\0`

’
on return, the entire string was valid.)

The `strtoul`

(),
`strtoull`

(), `strtoumax`

() and
`strtouq`

() functions return either the result of the
conversion or, if there was a leading minus sign, the negation of the result
of the conversion, unless the original (non-negated) value would overflow.
If overflow occurs, `strtoul`

() returns
`ULONG_MAX`

, `strtoull`

()
returns `ULLONG_MAX`

,
`strtoumax`

() returns
`UINTMAX_MAX`

, `strtouq`

()
returns `ULLONG_MAX`

and the global variable
`errno` is set to `ERANGE`

.

There is no way to determine if `strtoul`

()
has processed a negative number (and returned an unsigned value) short of
examining the string in `nptr` directly.

If there is no valid digit, 0 is returned. If
`base` is invalid, 0 is returned and the global variable
`errno` is set to `EINVAL`

.

Ensuring that a string is a valid number (i.e., in range and
containing no trailing characters) requires clearing
`errno` beforehand explicitly since
`errno` is not changed on a successful call to
`strtoul`

(), and the return value of
`strtoul`

() cannot be used unambiguously to signal an
error:

char *ep; unsigned long ulval; ... errno = 0; ulval = strtoul(buf, &ep, 10); if (buf[0] == '\0' || *ep != '\0') goto not_a_number; if (errno == ERANGE && ulval == ULONG_MAX) goto out_of_range;

This example will accept “12” but not
“12foo” or “12\n”. If trailing whitespace is
acceptable, further checks must be done on `*ep`;
alternately, use sscanf(3).

The `strtoul`

(),
`strtoull`

(), and `strtoumax`

()
functions conform to ISO/IEC 9899:1999
(“ISO C99”). Setting `errno`
to `EINVAL`

is an extension to that standard required
by IEEE Std 1003.1-2008
(“POSIX.1”).

The `strtouq`

() function is a
BSD extension and is provided for backwards
compatibility with legacy programs.

Ignores the current locale.

November 30, 2014 | OpenBSD-current |