atoi(3) Library Functions Manual atoi(3)
NAME
atoi, atol, strtol, strtoul - Convert 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 int atol(
const char *nptr);
long int strtol(
const char *nptr,
char **endptr,
int base);
unsigned long int strtoul(
const char *nptr,
char **endptr,
int base);
PARAMETERS
Points to the character string to convert. Points to a pointer in which the function stores the position in the string specified by the
nptr parameter where a character is found that is not a valid character for the purpose of this conversion. Specifies 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() and atol() functions convert a character string containing decimal integer constants, but the
strtol() and strtoul() functions can convert a character string containing a integer constant in octal, decimal, hexadecimal, or a base
specified by the base parameter.
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 initial portion of the character string pointed to by the nptr parameter to a long integer representa-
tion. The input character string is first broken down into three parts: White space -- an initial (possibly empty) sequence of spaces (as
specified by the isspace() function) Subject sequence -- a sequence of characters that are valid in an integer constant of the radix deter-
mined by the base parameter Unrecognized characters -- final sequence of unrecognized character codes, including the terminating null char-
acter
If possible, the subject is then converted to a long integer and the result is returned.
The base parameter can take values between 0 and 36. If the base value is 0 (zero), the subject string can be a decimal, octal, or hexa-
decimal integer constant. A decimal constant begins with a nonzero digit, and consists of a sequence of decimal digits. An octal constant
consists of the prefix 0 (zero) optionally followed by a sequence of digits in the range 0 through 7. A hexadecimal constant consists of
the prefix 0x or 0X followed by a sequence consisting of decimal digits and the letters in the range a (or A) to f (or F). If the base
value is between 2 and 36, the subject string can be a sequence of digits and letters a (or A) to z ( or Z ) that are used to represent an
integer in the specified base. Alphabetic characters represent digits with an equivalent decimal value from 10 (for the letter A) to 35
(for the letter Z). The subject string can only have digits with a value less than base and alphabetic characters with equivalent values
less than base. For example, when the value of the base parameter is 20, only the following value assignments are converted:
Character 0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J
a b c d e f g h i j
Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
The subject string can optionally be preceded by a + (plus sign) or - (minus sign), but cannot include an integer suffix (such as L). If
the subject string is preceded by a - (minus sign), the converted integer value has a negative value. If the value of base is 16, the
characters 0x or 0X may optionally precede the sequence of letters or digits, following the sign, if present.
The character string is parsed to skip the initial space characters (as determined by the isspace() function). Any nonspace character is
the starting of a potential subject string that may form an integer in the base specified by the base parameter. The subject sequence is
defined to be the longest initial substring that is of the expected form of long integer. Any character that does not satisfy this expected
form begins the final sequence of unrecognized characters. The strtol() function sets the location pointed to by the endptr parameter to
point to this final sequence of unrecognized characters except when endptr is a null pointer.
The LC_CTYPE category of the locale controls what characters are treated as spaces but does not effect the interpretation of characters as
part of the subject string. The characters in the subject string are always treated as if the locale was the C locale.
The strtoul() function is the same as the strtol() function, except that strtoul() returns an unsigned long integer.
EXAMPLES
The following example converts a character string to a signed long integer.
#include <stdio.h> #include <stdlib.h> #include <locale.h> #include <errno.h> #define LENGTH 40
main() {
char String[LENGTH], *endptr;
long int retval;
(void)setlocale(LC_ALL, "");
if (fgets(String, LENGTH, stdin) != NULL) {
errno = 0;
retval = strtol ( String, &endptr, 0 );
if (retval == 0 && (errno != 0
|| String == endptr)) {
/* No conversion could be performed */
printf("No conversion performed
");
} else if (errno !=0 && (retval == LONG_MAX
|| retval == LONG_MIN)) {
/* Error handling */
} else {
/* retval contains long integer */
printf("Integer in decimal is %d
", retval);
}
} }
RETURN VALUES
The atoi() function returns the converted value of an integer if the expected form is found. If no conversion could be performed, a value
of 0 (zero) is returned. If the converted value is outside the range of representable values, INT_MAX or INT_MIN is returned (according to
the sign of the value).
The atol() and strtol() functions return the converted value of long integer if the expected form is found. If no conversion could be per-
formed, a value of 0 (zero) is returned. If the converted value is outside the range of representable values, LONG_MAX or LONG_MIN is
returned (according to the sign of the value).
The strtoul() function returns the converted value of long integer if the expected form is found. If no conversion could be performed, a
value of 0 (zero) is returned. If the converted value is outside the range of representable values, ULONG_MAX is returned.
In the strtol() and strtoul() functions, if the endptr parameter is not a null pointer, the function stores a pointer to the final sequence
of unrecognized characters in the object pointed to by endptr except when the subject sequence is empty or invalid. In this case, the func-
tion stores the nptr pointer in the object pointed to by the endptr parameter.
Since these functions return 0 (zero), INT_MIN, INT_MAX, LONG_MIN, LONG_MAX, and ULONG_MAX in the event of an error and these values are
also valid returns if the function is successful, applications should set errno to 0 (zero) before calling these functions, and check errno
after return from the function. If errno is nonzero, an error occurred.
Additionally, for the strtol() and strtoul() functions, if 0 (zero) is returned, applications should check if the endptr parameter equals
the nptr parameter. In this case, there was no valid subject string.
ERRORS
If any of the following conditions occurs, the atoi(), atol(), strtol(), or strtoul() function sets errno to the corresponding value. The
base parameter has a value less than 0 or greater than 36.
If nptr is NULL, the functions return 0 and do not set errno. The converted value is outside the range of representable values.
RELATED INFORMATION
Functions: atof(3), scanf(3), wcstol(3), wcstoul(3). delim off
atoi(3)