NAME
strtoul,
strtoull,
strtoumax,
strtouq —
convert a string to an unsigned long, unsigned long long,
uintmax_t or u_quad_t integer
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
#include <limits.h>
unsigned long int
strtoul(
const
char * restrict nptr,
char
** restrict endptr,
int
base);
unsigned long long int
strtoull(
const
char * restrict nptr,
char
** restrict endptr,
int
base);
#include <inttypes.h>
uintmax_t
strtoumax(
const
char * restrict nptr,
char
** restrict endptr,
int
base);
#include <sys/types.h>
#include <stdlib.h>
#include <limits.h>
u_quad_t
strtouq(
const
char * restrict nptr,
char
** restrict endptr,
int
base);
DESCRIPTION
The
strtoul() function converts the string in
nptr to an
unsigned long int
value. The
strtoull() function converts the string in
nptr to an
unsigned long long int
value. The
strtoumax() function converts the string in
nptr to an
uintmax_t value. The
strtouq() function converts the string in
nptr to a
u_quad_t value.
The conversion is done according to the given
base, which
must be between 2 and 36 inclusive, or be the special value 0.
The string may begin with an arbitrary amount of white space (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
’ or
‘
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 appropriate value in the obvious
manner, stopping at the end of the string or at the first character that does
not produce 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-nil, the functions store the address of
the first invalid character in
*endptr. If there were no
digits at all, however, the functions store the original value of
nptr in
*endptr. (Thus, if
*nptr is not ‘
\0
’
but
**endptr is ‘
\0
’
on return, the entire string was valid.)
RETURN VALUES
The
strtoul() function returns 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; in
the latter case,
strtoul() returns
ULONG_MAX
,
strtoull() returns
ULLONG_MAX
,
strtoumax() returns
UINTMAX_MAX
,
strtouq() returns
UQUAD_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 the
base
argument is not supported then
errno is set to
EINVAL
and the functions return 0.
If no error occurs,
errno is left unchanged. This behavior
(which is unlike most library functions) is guaranteed by the pertinent
standards.
EXAMPLES
Because the return value of
strtoul() cannot be used
unambiguously to detect an error,
errno is left
unchanged after a successful call. To ensure that a string is a valid number
(i.e., in range and containing no trailing characters), clear
errno beforehand explicitly, then check it afterwards:
char *ep;
unsigned long ulval;
...
errno = 0;
ulval = strtoul(buf, &ep, 10);
if (ep == buf)
goto not_a_number;
if (*ep != '\0')
goto trailing_garbage;
if (errno) {
assert(errno == ERANGE);
assert(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).
ERRORS
-
-
- [
EINVAL
]
- The base is not between 2 and 36 and
does not contain the special value 0.
-
-
- [
ERANGE
]
- The given string was out of range; the value converted has
been clamped.
SEE ALSO
atof(3),
atoi(3),
atol(3),
atoll(3),
strtod(3),
strtoi(3),
strtoimax(3),
strtol(3),
strtoll(3),
strtou(3)
STANDARDS
The
strtoul() function conforms to
ANSI
X3.159-1989 (“ANSI C89”). The
strtoull() and
strtoumax() functions
conform to
ISO/IEC 9899:1999
(“ISO C99”).
The
strtouq() function is a
BSD legacy
function equivalent to
strtoull() and should not be used in
a new code.
BUGS
Ignores the current locale.