Parsing of Integers

These functions are declared in `stdlib.h'.

Function: long int strtol (const char *string, char **tailptr, int base)

The 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:

• A (possibly empty) sequence of whitespace characters. Which characters are whitespace is determined by the isspace function (see section Classification of Characters). These are discarded.
• An optional plus or minus sign (`+' or `-').
• A nonempty sequence of digits in the radix specified by base. If base is zero, decimal radix is assumed unless the series of digits begins with `0' (specifying octal radix), or `0x' or `0X' (specifying hexadecimal radix); in other words, the same syntax used for integer constants in C. Otherwise base must have a value between 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.
• Any remaining characters in the string. If tailptr is not a null pointer, 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.

Function: unsigned long int strtoul (const char *string, char **tailptr, int base)

The 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.

Function: long long int strtoll (const char *string, char **tailptr, int base)

The 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.

Function: long long int strtoq (const char *string, char **tailptr, int base)

strtoq ("string-to-quad-word") is the BSD name for strtoll.

Function: unsigned long long int strtoull (const char *string, char **tailptr, int base)

The 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.

Function: unsigned long long int strtouq (const char *string, char **tailptr, int base)

strtouq is the BSD name for strtoull.

Function: long int atol (const char *string)

This function is similar to the 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.

Function: int atoi (const char *string)

This function is like atol, except that it returns an int. The atoi function is also considered obsolete; use strtol instead.

Function: long long int atoll (const char *string)

This function is similar to 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.