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`);

`strtoul`

() function converts the string in
`strtoull`

() function converts the string in
`strtoumax`

() function converts the string in
`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
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.)

`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
`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`

.

`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).

`strtoul`

(), `strtoull`

(), and
`strtoumax`

() functions conform to
ISO/IEC 9899:1999 (“ISO C99”).
Setting `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.

November 30, 2014 | OpenBSD-current |