strtol, strtoul, strtoll, strtoull, atol, or atoi Subroutine

Purpose

Converts a string to a signed or unsigned long integer or long long integer.

Library

Standard C Library (libc.a)

Syntax

long strtol (String, EndPointer, Base)
const char *String;
char **EndPointer;
int Base;

unsigned long strtoul (String, EndPointer, Base)
const char *String;
char **EndPointer;
int Base;

extern long long int strtoll (String, EndPointer, Base)
char *String, **EndPointer;
int Base;

extern long long int strtoull (String, EndPointer, Base)
char *String, **EndPointer;
int Base;

long atol (String)
const char *String;

int atoi (String)
const char *String;

Description

The strtol subroutine returns a long integer whose value is represented by the character string to which the String parameter points. The strtol subroutine scans the string up to the first character that is inconsistent with the Base parameter. Leading white-space characters are ignored, and an optional sign may precede the digits.

The strtoul subroutine provides the same functions but returns an unsigned long integer.

The strtoll and strtoull subroutines provide the same functions but return long long integers.

The atol subroutine is equivalent to the strtol subroutine where the value of the EndPointer parameter is a null pointer and the Base parameter is a value of 10.

The atoi subroutine is equivalent to the strtol subroutine where the value of the EndPointer parameter is a null pointer and the Base parameter is a value of 10.

If the value of the EndPointer parameter is not null, then a pointer to the character that ended the scan is stored in EndPointer. If an integer cannot be formed, the value of the EndPointer parameter is set to that of the String parameter.

If the Base parameter is a value between 2 and 36, the subject sequence's expected form is a sequence of letters and digits representing an integer whose radix is specified by the Base parameter. This sequence is optionally preceded by a + (positive) or - (negative) sign. Letters from a (or A) to z (or Z) inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less than that of the Base parameter are permitted. If the Base parameter has a value of 16, the characters 0x or 0X optionally precede the sequence of letters and digits, following the + (positive) or - (negative) sign if present.

If the value of the Base parameter is 0, the string determines the base. Thus, after an optional leading sign, a leading 0 indicates octal conversion, and a leading 0x or 0X indicates hexadecimal conversion. The default is to use decimal conversion.

Parameters

Return Values

Upon successful completion, the strtol, strtoul, strtoll, and strtoull subroutines return the converted value. If no conversion could be performed, 0 is returned, and the errno global variable is set to indicate the error. If the correct value is outside the range of representable values, the strtol subroutine returns a value of LONG_MAX or LONG_MIN according to the sign of the value, while the strtoul subroutine returns a value of ULONG_MAX.

Error Codes

The strtol and strtoul subroutines return the following error codes:

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The atof, atoff, strtod, or strtof subroutine, scanf, fscanf, sscanf, or wsscanf subroutine, setlocale subroutine, wstrtod or watof subroutine, wstrtol, watol, or watoi subroutine.

Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.