wcstoul(3C)




NAME

     wcstoul - convert wide character string to unsigned long


SYNOPSIS

     #include <wchar.h>

     unsigned  long  int  wcstoul(const  wchar_t  *nptr,  wchar_t
     **endptr, int base);


DESCRIPTION

     The wcstoul() function converts the initial portion  of  the
     wide   character  string pointed to by nptr to unsigned long
     int representation.  It first  decomposes  the  input  wide-
     character  string   into  three  parts: an initial, possibly
     empty, sequence  of  white-space  wide-character  codes  (as
     specified  by the function iswspace(3C)); a subject sequence
     interpreted as an integer represented in some  radix  deter-
     mined  by  the  value  of  base;  and a final wide-character
     string of one or more  unrecognized  wide  character  codes,
     including  the  terminating  null wide-character code of the
     input wide character string. It then 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, an octal constant,
     or a hexadecimal constant, any of which may be preceded by a
     `+' or a `-' 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 fol-
     lowed by a sequence of the digits `0' to `7' only. A hexade-
     cimal 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 a `-' sign, but not includ-
     ing an integer suffix. 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 wide-character
     codes `0x' or `0X' may optionally precede  the  sequence  of
     letters and digits, following the sign, if present.

     The subject sequence  is  defined  as  the  longest  initial
     subsequence  of  the  input  wide-character string, starting
     with the first wide-character code that is not a white space
     and  is  of the expected form. The subject sequence contains
     no wide-character codes if the input  wide-character  string
     is  empty or consists entirely of white-space wide-character
     codes, or if the first wide-character code  that  is  not  a
     white space  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 wide-character codes 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  resulting  from  the  conversion  is  negated. A
     pointer to the final wide character string is  stored in the
     object  pointed to by endptr, provided that  endptr is not a
     null pointer.

     In other than the POSIX locale, additional  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 nptr
     is stored in the object pointed to by endptr, provided  that
     endptr is not a null pointer.

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


RETURN VALUE

     Upon successful completion, wcstoul() returns the  converted
     value,  if any, and does not change the setting of errno. If
     no conversion could be performed, 0 is  returned  and  errno
     may  be  set  to indicate the error. If the correct value is
     outside the range  of  representable  values,  ULONG_MAX  is
     returned and errno is set to ERANGE.


ERRORS

     The wcstoul() function will fail if:

     EINVAL
           The value of base is not supported.

     ERANGE
           The value to be returned is not representable.

     The wcstoul() function may fail if:

     EINVAL
           No conversion could be performed.


USAGE

     Unlike wcstod(3C)  and  wcstol(3C),  wcstoul()  must  always
     return  a  non-negative  number;  using  the return value of
     wcstoul() for  out-of-range  numbers  with  wcstoul()  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       |
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     isspace(3C),    iswalpha(3C),     scanf(3C),     wcstod(3C),
     wcstol(3C), attributes(5)


Man(1) output converted with man2html