strtoul man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

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)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net