These functions are declared in `stdlib.h'.
strtol
("string-to-long") function converts the initial
part of string to a signed integer, which is returned as a value
of type long int
.
This function attempts to decompose string as follows:
isspace
function
(see section Classification of Characters). These are discarded.
2
and 35
.
If base is 16
, the digits may optionally be preceded by
`0x' or `0X'. If base has no legal value the value returned
is 0l
and the global variable errno
is set to EINVAL
.
strtol
stores a pointer to this tail in
*tailptr
.
If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for an integer in the
specified base, no conversion is performed. In this case,
strtol
returns a value of zero and the value stored in
*tailptr
is the value of string.
In a locale other than the standard "C"
locale, this function
may recognize additional implementation-dependent syntax.
If the string has valid syntax for an integer but the value is not
representable because of overflow, strtol
returns either
LONG_MAX
or LONG_MIN
(see section Range of an Integer Type), as
appropriate for the sign of the value. It also sets errno
to ERANGE
to indicate there was overflow.
You should not check for errors by examining the return value of
strtol
, because the string might be a valid representation of
0l
, LONG_MAX
, or LONG_MIN
. Instead, check whether
tailptr points to what you expect after the number
(e.g. '\0'
if the string should end after the number). You also
need to clear errno before the call and check it afterward, in
case there was overflow.
There is an example at the end of this section.
strtoul
("string-to-unsigned-long") function is like
strtol
except it returns an unsigned long int
value. If
the number has a leading `-' sign, the return value is negated.
The syntax is the same as described above for strtol
. The value
returned on overflow is ULONG_MAX
(see section Range of an Integer Type).
strtoul
sets errno to EINVAL
if base is out of
range, or ERANGE
on overflow.
strtoll
function is like strtol
except that it returns
a long long int
value, and accepts numbers with a correspondingly
larger range.
If the string has valid syntax for an integer but the value is not
representable because of overflow, strtoll
returns either
LONG_LONG_MAX
or LONG_LONG_MIN
(see section Range of an Integer Type), as
appropriate for the sign of the value. It also sets errno
to
ERANGE
to indicate there was overflow.
The strtoll
function was introduced in ISO C 9x.
strtoq
("string-to-quad-word") is the BSD name for strtoll
.
strtoull
function is like strtoul
except that it
returns an unsigned long long int
. The value returned on overflow
is ULONG_LONG_MAX
(see section Range of an Integer Type).
The strtoull
function was introduced in ISO C 9x.
strtouq
is the BSD name for strtoull
.
strtol
function with a base
argument of 10
, except that it need not detect overflow errors.
The atol
function is provided mostly for compatibility with
existing code; using strtol
is more robust.
atol
, except that it returns an int
.
The atoi
function is also considered obsolete; use strtol
instead.
atol
, except it returns a long
long int
.
The atoll
function was introduced in ISO C 9x. It too is
obsolete (despite having just been added); use strtoll
instead.
Some locales specify a printed syntax for numbers other than the one
that these functions understand. If you need to read numbers formatted
in some other locale, you can use the strtoX_l
functions. Each
of the strtoX
functions has a counterpart with `_l' added to
its name. The `_l' counterparts take an additional argument: a
pointer to an locale_t
structure, which describes how the numbers
to be read are formatted. See section Locales and Internationalization.
Portability Note: These functions are all GNU extensions. You
can also use scanf
or its relatives, which have the `'' flag
for parsing numeric input according to the current locale
(see section Numeric Input Conversions). This feature is standard.
Here is a function which parses a string as a sequence of integers and returns the sum of them:
int sum_ints_from_string (char *string) { int sum = 0; while (1) { char *tail; int next; /* Skip whitespace by hand, to detect the end. */ while (isspace (*string)) string++; if (*string == 0) break; /* There is more nonwhitespace, */ /* so it ought to be another number. */ errno = 0; /* Parse it. */ next = strtol (string, &tail, 0); /* Add it in, if not overflow. */ if (errno) printf ("Overflow\n"); else sum += next; /* Advance past it. */ string = tail; } return sum; }
Go to the first, previous, next, last section, table of contents.