strtol, strtoll, strtoq - convert string value to a long or
long long integer
#include <stdlib.h>
#include <limits.h>
long
strtol(const char *nptr, char **endptr, int base);
#include <stdlib.h>
#include <limits.h>
long long
strtoll(const char *nptr, char **endptr, int base);
#include <sys/types.h>
#include <stdlib.h>
#include <limits.h>
quad_t
strtoq(const char *nptr, char **endptr, int base);
The strtol() function converts the string in nptr to a long
value. The
strtoll() function converts the string in nptr to a long
long value. The
strtoq() function is a deprecated equivalent of strtoll()
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.
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 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-null, 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
` ' but **endptr is ` ' on return, the entire string was
valid.)
The strtol() function returns the result of the conversion,
unless the
value would underflow or overflow. If an underflow occurs,
strtol() returns
LONG_MIN. If an overflow occurs, strtol() returns
LONG_MAX. In
both cases, errno is set to ERANGE.
The strtoll() function has identical return values except
that LLONG_MIN
and LLONG_MAX are used to indicate underflow and overflow
respectively.
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 strtol(),
and the return
value of strtol() cannot be used unambiguously to signal an error:
char *ep;
long lval;
...
errno = 0;
lval = strtol(buf, &ep, 10);
if (buf[0] == ' ' || *ep != ' ')
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 ``120'.
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] == ' ' || *ep != ' ')
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] The given string was out of range; the value
converted has
been clamped.
atof(3), atoi(3), atol(3), atoll(3), sscanf(3), strtod(3),
strtoul(3)
The strtol() and strtoll() functions conform to ANSI/ISO/IEC
9899-1999
(``ANSI C99''). The strtoq() function is a BSD extension
and is provided
for backwards compatibility with legacy programs.
Ignores the current locale.
OpenBSD 3.6 June 25, 1992
[ Back ] |