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)