Go to the first, previous, next, last section, table of contents.

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:

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.

Because the value 0l is a correct result for strtol the user who is interested in handling errors should set the global variable errno to 0 before calling this function, so that the program can later test whether an error occurred.

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 deals with unsigned numbers, and returns its value with type unsigned long int. No `+' or `-' sign may appear before the number, but the syntax is otherwise the same as described above for strtol. The value returned in case of overflow is ULONG_MAX (see section Range of an Integer Type).

Like strtol this function sets errno and returns the value 0ul in case the value for base is not in the legal range. For strtoul this can happen in another situation. In case the number to be converted is negative strtoul also sets errno to EINVAL and returns 0ul.

Function: long long int strtoq (const char *string, char **tailptr, int base)
The strtoq ("string-to-quad-word") function is like strtol except that is deals with extra long numbers and it returns its value with type long long int.

If the string has valid syntax for an integer but the value is not representable because of overflow, strtoq 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.

Function: long long int strtoll (const char *string, char **tailptr, int base)
strtoll is only an commonly used other name for the strtoq function. Everything said for strtoq applies to strtoll as well.

Function: unsigned long long int strtouq (const char *string, char **tailptr, int base)
The strtouq ("string-to-unsigned-quad-word") function is like strtoul except that is deals with extra long numbers and it returns its value with type unsigned long long int. The value returned in case of overflow is ULONG_LONG_MAX (see section Range of an Integer Type).

Function: unsigned long long int strtoull (const char *string, char **tailptr, int base)
strtoull is only an commonly used other name for the strtouq function. Everything said for strtouq applies to strtoull as well.

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 value rather than long int. The atoi function is also considered obsolete; use strtol instead.

The POSIX locales contain some information about how to format numbers (see section Generic Numeric Formatting Parameters). This mainly deals with representing numbers for better readability for humans. The functions present so far in this section cannot handle numbers in this form.

If this functionality is needed in a program one can use the functions from the scanf family which know about the flag `'' for parsing numeric input (see section Numeric Input Conversions). Sometimes it is more desirable to have finer control.

In these situation one could use the function __strtoXXX_internal. XXX here stands for any of the above forms. All numeric conversion functions (including the functions to process floating-point numbers) have such a counterpart. The difference to the normal form is the extra argument at the end of the parameter list. If this value has an non-zero value the handling of number grouping is enabled. The advantage of using these functions is that the tailptr parameters allow to determine which part of the input is processed. The scanf functions don't provide this information. The drawback of using these functions is that they are not portable. They only exist in the GNU C library.

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.