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
)
intmax_t
strtoimax(const char * restrict nptr
, char ** restrict endptr
, int base
)
quad_t
strtoq(const char * restrict nptr
, char ** restrict endptr
, int base
)
)
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'
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 a long 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,
strtol()
stores the address of the first invalid character in
*endptr
.
If there were no digits at all, however,
strtol()
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.)
)
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 no error occurs, errno is left unchanged. This behavior (which is unlike most library functions) is guaranteed by the pertinent standards.
)
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 (buf[0] == '\0' || *ep != '\0')
goto not_a_number;
if (errno == ERANGE && (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 (buf[0] == '\0' || *ep != '\0')
goto not_a_number;
if ((errno == ERANGE && (lval == LONG_MAX || lval == LONG_MIN)) ||
(lval > INT_MAX || lval < INT_MIN))
goto out_of_range;
ival = lval;
ERANGE
]
)
function
conforms to
ANSI X3.159-1989 (``ANSI C89'') .
The
strtoll(
)
and
strtoimax(
)
functions conform to
ISO/IEC 9899:1999 (``ISO C99'') .