Manual Pages for UNIX Operating System command usage for man strtoul

Standard C Library Functions                          strtoul(3C)



NAME
     strtoul, strtoull - convert string to unsigned long

SYNOPSIS
     #include 

     unsigned long strtoul(const char *restrict str,
          char **restrict endptr, int base);


     unsigned long long strtoull(const char *restrict str,
          char **restrict endptr, int base);


DESCRIPTION
     The strtoul() function converts the initial portion  of  the
     string  pointed  to  by  str  to  a  type  unsigned long int
     representation. First it decomposes the  input  string  into
     three  parts: an initial, possibly empty, sequence of white-
     space characters (as specified by  isspace(3C));  a  subject
     sequence interpreted as an integer represented in some radix
     determined by the value of base; and a final string  of  one
     or  more  unrecognised characters, including the terminating
     null byte of the input string. Then it attempts  to  convert
     the subject sequence to an unsigned integer, and returns the
     result.


     If the value of base is 0, the expected form of the  subject
     sequence  is  that  of a decimal constant, octal constant or
     hexadecimal constant, any of which may be preceded by a + or
     - sign. A decimal constant begins with a non-zero digit, and
     consists of a sequence of decimal digits. An octal  constant
     consists  of  the prefix 0 optionally followed by a sequence
     of the digits 0 to 7 only. A hexadecimal  constant  consists
     of the prefix 0x or 0X followed by a sequence of the decimal
     digits and letters a (or A) to f (or F) with values 10 to 15
     respectively.


     If the value of base is between 2 and 36, the expected  form
     of  the subject sequence is a sequence of letters and digits
     representing an integer with the radix  specified  by  base,
     optionally preceded by a + or - sign. The letters from a (or
     A) to z (or Z) inclusive are ascribed the values 10  to  35;
     only  letters  whose  ascribed  values are less than that of
     base are permitted. If the value of base is 16, the  charac-
     ters 0x or 0X may optionally precede the sequence of letters
     and digits, following the sign if present.






SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                          strtoul(3C)



     The subject sequence  is  defined  as  the  longest  initial
     subsequence  of  the  input  string, starting with the first
     non-white-space character, that is of the expected form. The
     subject  sequence contains no characters if the input string
     is empty or consists entirely of white-space characters,  or
     if  the first non-white-space character is other than a sign
     or a permissible letter or digit.


     If the subject sequence has the expected form and the  value
     of  base  is 0, the sequence of characters starting with the
     first digit is interpreted as an integer  constant.  If  the
     subject sequence has the expected form and the value of base
     is between 2 and 36, it is used as the base for  conversion,
     ascribing  to  each  letter its value as given above. If the
     subject sequence begins with a minus sign, the value result-
     ing  from  the conversion is negated. A pointer to the final
     string is stored in the object pointed to  by  endptr,  pro-
     vided that endptr is not a null pointer.


     In other than the POSIX locale,  additional  implementation-
     dependent subject sequence forms may be accepted.


     If the subject sequence  is  empty  or  does  not  have  the
     expected  form, no conversion is performed; the value of str
     is stored in the object pointed to by endptr, provided  that
     endptr is not a null pointer.


     The strtoull() function is  identical  to  strtoul()  except
     that  it returns the value represented by str as an unsigned
     long long.

RETURN VALUES
     Upon successful completion strtoul() returns  the  converted
     value,  if  any.  If  no conversion could be performed, 0 is
     returned and errno may be set  to  EINVAL.  If  the  correct
     value   is   outside  the  range  of  representable  values,
     ULONG_MAX is returned and errno is set to ERANGE.

ERRORS
     The strtoul() function will fail if:

     EINVAL    The value of base is not supported.


     ERANGE    The value to be returned is not representable.






SunOS 5.11           Last change: 1 Nov 2003                    2






Standard C Library Functions                          strtoul(3C)



     The strtoul() function may fail if:

     EINVAL    No conversion could be performed.


USAGE
     Because 0 and ULONG_MAX are returned on error and  are  also
     valid  returns  on  success, an application wishing to check
     for error situations  should  set  errno  to  0,  then  call
     strtoul(), then check errno and if it is non-zero, assume an
     error has occurred.


     Unlike strtod(3C)  and  strtol(3C),  strtoul()  must  always
     return  a non-negative number; so, using the return value of
     strtoul() for  out-of-range  numbers  with  strtoul()  could
     cause  more  severe  problems than just loss of precision if
     those numbers can ever be negative.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     isalpha(3C), isspace(3C), scanf(3C), strtod(3C), strtol(3C),
     attributes(5), standards(5)
















SunOS 5.11           Last change: 1 Nov 2003                    3