strtol - Convert a string into a whole number (long int)

Definition

#include <stdlib.h>

long int strtol(const char *s, char **p, int base);

strtol converts a string to which s points into an integer of type long int. The string to be converted may be structured as follows:

[{tab | 'BLANK' } ...][+ | -][0 | 0X]digit...

All control characters for white space may be used for tab (see definition under isspace).

Depending on the base (see base), the digits 0 to 9 and the letters a (or A) to z (or Z) may be used for digit.

strtol also recognizes strings that start with convertible digits (including octal and hexadecimal digits) but then end with any character. In such cases, strtol first truncates the numeric part and converts it.

strtol additionally provides a pointer (*p) to the first non-convertible character in string s via the second argument p of type char **. However, this occurs only if p is not passed as a NULL pointer.

A third argument, base, defines the base (e.g. decimal, octal or hexadecimal) for the conversion.

Parameters

const char *s

Pointer to the string to be converted.

char **p

A pointer (*p) to the first character in s that terminates the conversion is returned if p is not a NULL pointer.
If no conversion is possible at all, *p is set to the start address of string s.

int base

Integer from 0 to 36, which is to be used as the base for the computation.

From base 11 to base 36, letters a (or A) to z (or Z) in the string to be converted are assumed to be digits with the corresponding values 10 (a/A) to 35 (z/Z).

If base is equal to 0, the base will be determined from the structure of string s as shown below:

leading 0	base 8
leading 0X or 0x	base 16
otherwise	base 10

If the parameter base = 16 is used for calculations, the characters 0X and 0x are ignored after any sign in string s.

Return val.

Integer value of type long int

for strings that have a structure as described above and represent a numeric value.

0

for strings that do not conform to the syntax described above. No conversion is performed.
If the value of base is not supported, errno is set to EINVAL.

LONG_MAX or LONG_MIN depending on the sign

if the result overflows.
errno is set to ERANGE to indicate the error.

Note

If p is a NULL pointer and base is equal to 10, strtol is executed like the function atol:
atol(s) is equivalent to strtol(s, NULL, 10).

Example

#include <stdio.h>
#include <stdlib.h>
int main(void)
{
  char *str1 = "  0x1ff";
  char *str2 = "h0***";
  char *end;
  long l;
  l = strtol(str1, &end, 0);          /* Base 16 is derived */
                                      /* from the string str1. */
  printf("First value: %ld\n", l);    /* 511 is output. */
  l = strtol(str2, &end, 20);         /* Base = 20 */
  printf("Second value: %ld\n", l);   /* 340 (17*20) is output. */
  printf("Rest of str2: %s\n", end);  /* "***" is output. */
  return 0; }

See also

atol, atoi, strtod, strtoll, strtoul, strtoull, wcstol, wcstoll, wcstoul, wcstoull