atoi(3) — Subroutines
OSF
NAME
atoi, atol, strtol, strtoul - Converts a character string to the specified integer data type
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <stdlib.h>
int atoi(
const char ∗nptr) ;
long atol(
const char ∗nptr)
long strtol(
const char ∗nptr,
char ∗∗endptr,
int base) ;
unsigned long int strtoul(
const char ∗nptr,
char ∗∗endptr,
int base) ;
PARAMETERS
nptrPoints to the character string to convert.
endptrPoints to a character string that ends the scan or to a null pointer.
baseSpecifies the radix to use for the conversion.
DESCRIPTION
The atoi(), atol(), strtol(), and strtoul() functions are used to convert a character string pointed to by the nptr parameter to an integer having a specified data type.
The atoi() function converts the character string pointed to by the nptr parameter up to the first character inconsistent with the format of a decimal integer to an integer data type. Leading white-space characters are ignored. A call to this function is equivalent to a call to strtol(nptr, (char∗∗) NULL, 10). The int value of the input string is returned.
The atol() function converts the character string pointed to by the nptr parameter up to the first character inconsistent with the format of a decimal integer to a long integer data type. Leading white-space characters are ignored. A call to this function is equivalent to a call to strtol(nptr, (char∗∗) NULL, 10). The long int value of the input string is returned.
The strtol() function converts the character string pointed to by the nptr parameter up to the first character inconsistent with the format of a decimal integer to a long integer data type. Leading white-space characters are ignored. First the input string is decomposed into the following three parts:
•An initial, possibly empty, sequence of white-space characters (as specified by the isspace() function).
•A subject sequence interpreted as an integer represented in some radix determined by the value of the base parameter.
•A final string of one or more unrecognized characters, including the terminating null character of the input string.
After decomposition of the string, the subject sequence is converted to a long integer and the resulting value is returned. A subject sequence is defined as the longest initial subsequence of the input string, starting with the first nonwhite-space character that is of the expected form. The expected form and order of the subject sequence depends on the value of the base parameter:
•When the value of the base parameter is 0 (zero), the expected form of the subject sequence is that of an integer-constant optionally preceded by a + (plus sign) or - (minus sign), but not including an integer suffix. The sequence of characters starting with the first digit is interpreted as an integer constant.
•When the value of the base parameter is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with its radix specified by the value of the base parameter, optionally preceded by a + (plus sign) or - (minus sign) and not including an integer suffix.
•Alphabetic characters from "a" or "A" through "z" or "Z" are assigned decimal values 10 through 35, respectively. Only alphabetic characters with assigned values less than that of the base parameter are converted. For example, when the value of the base parameter is 20, only the following value assignments are converted: Char0 1 2 3 4 5 6 7 8 9 A B C D E ... Val0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 ...
•When the value of the base is 16 (hexadecimal), the expected form of the subject sequence is a string of alphanumeric characters optionally preceded by characters "0x" or "0X", which must follow an optional initial sign character, when present.
•When the expected form of the subject seqeunce is preceded by a - (minus sign), the converted integer value has a negative value.
When the input string is empty or does not have the expected form, conversion does not take place. The value of the nptr parameter is stored in the object pointed to by the endptr parameter, whenever this parameter is not a null pointer.
The strtoul() function is the same as the strtol() function, except that it does not accept a leading sign character and it returns an unsigned long integer.
RETURN VALUES
For the strtol() and stroul() functions, when the value of the endptr parameter is not (char ∗∗) NULL, a pointer to the character that terminated the scan is stored in the location pointed to by the nptr parameter.
For the strtol() and stroul() functions, when an integer result cannot be formed, the ∗nptr parameter is set to the value of endptr, and 0 (zero) is returned.
For the strtol() and stroul() functions, when the base parameter is positive but not greater than 36, the value of base is used as the conversion radix. After an optional leading sign, leading zeros are ignored. Whenever the base parameter is 16, "0x" or "0X" is ignored.
For the strtol() and stroul() functions, when the base parameter is 0 (zero), the string pointed to by the nptr parameter determines the radix. Thus, after an optional leading sign, a leading 0 (zero) indicates octal conversion, and a leading "0x" or "0X" indicates hexadecimal conversion. The default conversion is to decimal values.
Upon successful completion, these functions return the proper data type and value of the converted integer.
ERRORS
If any of these functions fail, errno may be set to one of the following values:
[ERANGE]The input string is out of range (that is, the subject sequence can not be converted to the proper data type and value without causing overflow).
[EINVAL]The radix value specified for the base parameter is not supported.