strtol() — Convert Character String to Long

Format

#include <stdlib.h>

long int strtol(const char * __restrict__nptr, 
char ** __restrict__endptr, int base);

General Description

The strtol() function converts nptr, a character string, to a long int value.

The function decomposes the entire string into three parts:

  1. A sequence of white space characters as defined by the IBM-1047 codepage.
  2. A sequence of characters interpreted as integer in some base notation. This is the subject sequence.
  3. A sequence of unrecognized characters.
The base notation is determined by base, if base is greater than zero. If base is zero, the base notation is determined by the format of the sequence of characters that follow an optional plus—or optional minus—sign.
10
Sequence starts with nonzero decimal digit.
8
Sequence starts with 0, followed by a sequence of digits with values from 0 to 7.
16
Sequence starts with either 0x or 0X, followed by digits, and letters A through F or a through f.

If the base is greater than zero, the subject sequence contains decimal digits and letters, possibly preceded by either a plus or a minus sign. The letters a (or A) through z (or Z) represent values from 10 through 36, but only those letters whose value is less than the value of the base are allowed.

When you use the strtol() function, nptr should point to a string with the following form:
Read syntax diagramSkip visual syntax diagramwhite space +  - 00 x0Xdigits

The pointer to the converted characters, even if conversion was unsuccessful, is stored in the object pointed to by endptr, if endptr is not a NULL pointer.

Returned Value

If successful, strtol() returns the converted long int value.

If unsuccessful, strtol() returns 0 if no conversion could be performed. If the correct value is outside the range of representable values, strtol() returns LONG_MAX or LONG_MIN, according to the sign of the value. If the value of base is not supported, strtol() returns 0.

Related Information