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 nonnull,
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 (nonnegated) 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).


 [
EINVAL
]
 The value of base was
neither between 2 and 36 inclusive nor the special value 0.


 [
ERANGE
]
 The given string was out of range; the value converted has
been clamped.
sscanf(3),
strtol(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.12008
(“POSIX.1”).
The
strtouq() function is a
BSD extension and is provided for backwards
compatibility with legacy programs.
Ignores the current locale.