atoi(3)atoi(3)NAME
atoi, atol, strtol, strtoul - Convert a character string to the speci‐
fied integer data type
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 );
LIBRARY
Standard C Library (libc)
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 con‐
vert 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 spec‐
ified 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 charac‐
ter
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 hexadecimal
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, fol‐
lowing 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.
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 out‐
side 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 function
stores the nptr pointer in the object pointed to by the endptr parame‐
ter.
Since these functions may return INT_MIN, INT_MAX, LONG_MIN, LONG_MAX,
and ULONG_MAX in the event of an error and these values may also be
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 nptr is NULL, the functions return 0 and do not set errno.
If any of the following conditions occurs, the atoi(), atol(), str‐
tol(), or strtoul() function sets errno to the corresponding value.
The base parameter has a value less than 0 or greater than 36. The
converted value is outside the range of representable values.
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\n");
} else if (errno !=0 && (retval == LONG_MAX
|| retval == LONG_MIN)) {
/* Error handling */
} else {
/* retval contains long integer */
printf("Integer in decimal is %d\n", retval);
}
}
}
SEE ALSO
Functions: atof(3), scanf(3), wcstol(3), wcstoul(3).
atoi(3)