Content-type: text/html Man page of atoi

atoi

Section: C Library Functions (3)
Index Return to Main Contents
 

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 representation. 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 determined by the base parameter Unrecognized characters -- final sequence of unrecognized character codes, including the terminating null character

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, 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\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);
        }
    } }  

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 performed, 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 function 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


 

Index

NAME
LIBRARY
SYNOPSIS
PARAMETERS
DESCRIPTION
EXAMPLES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:36 GMT, October 02, 2010