NAME
strtol,
strtoll,
strtoimax,
strtoq —
convert string value to a long, long long, intmax_t or quad_t
integer
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
#include <limits.h>
long int
strtol(
const char
* restrict nptr,
char **
restrict endptr,
int
base);
long long int
strtoll(
const
char * restrict nptr,
char
** restrict endptr,
int
base);
#include <inttypes.h>
intmax_t
strtoimax(
const
char * restrict nptr,
char
** restrict endptr,
int
base);
#include <sys/types.h>
#include <stdlib.h>
#include <limits.h>
quad_t
strtoq(
const char
* restrict nptr,
char **
restrict endptr,
int
base);
DESCRIPTION
The
strtol() function converts the string in
nptr to a
long int value. The
strtoll() function converts the string in
nptr to a
long long int value. The
strtoimax() function converts the string in
nptr to an
intmax_t value. The
strtoq() function converts the string in
nptr to a
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 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-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
strtol() function returns the result of the conversion,
unless the value would underflow or overflow. If an underflow occurs,
strtol() returns
LONG_MIN
,
strtoll() returns
LLONG_MIN
, and
strtoimax() returns
INTMAX_MIN
. If
an overflow occurs,
strtol() returns
LONG_MAX
,
strtoll() returns
LLONG_MAX
, and
strtoimax() returns
INTMAX_MAX
. In these cases,
errno is set to
ERANGE
. 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
strtol() 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;
long lval;
...
errno = 0;
lval = strtol(buf, &ep, 10);
if (ep == buf)
goto not_a_number;
if (*ep != '\0')
goto trailing_garbage;
if (errno) {
assert(errno == ERANGE);
assert(lval == LONG_MAX || lval == LONG_MIN);
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).
If
strtol() is being used instead of
atoi(3), error checking is further
complicated because the desired return value is an
int
rather than a
long
; however, on some architectures
integers and long integers are the same size. Thus the following is necessary:
char *ep;
int ival;
long lval;
...
errno = 0;
lval = strtol(buf, &ep, 10);
if (ep == buf)
goto not_a_number;
if (*ep != '\0')
goto trailing_garbage;
if (errno == ERANGE || lval < INT_MIN || INT_MAX < lval)
goto out_of_range;
assert(errno == 0);
assert(INT_MIN <= lval);
assert(lval <= INT_MAX);
ival = lval;
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),
strtou(3),
strtoul(3),
strtoull(3),
strtoumax(3)
STANDARDS
The
strtol() function conforms to
ANSI
X3.159-1989 (“ANSI C89”). The
strtoll() and
strtoimax() functions
conform to
ISO/IEC 9899:1999
(“ISO C99”).
The
strtoq() function is a
BSD legacy
function equivalent to
strtoll() and should not be used in a
new code.
BUGS
Ignores the current locale.