watol(3C)




NAME

     wcstol, wstol, watol, watoll, watoi - convert wide character
     string to long integer


SYNOPSIS

     #include <wchar.h>

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

     #include <widec.h>

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

     long watol(wchar_t *nptr);

     long long watoll(wchar_t *nptr);

     int watoi(wchar_t *nptr);


DESCRIPTION

     The wcstol() and wstol() functions convert the initial  por-
     tion of the wide character string pointed to by nptr to long
     int representation. They  first  decompose  the  input  wide
     character  string  into  three  parts:  an initial, possibly
     empty, sequence  of  white-space  wide-character  codes  (as
     specified  by  iswspace(3C)), a subject sequence interpreted
     as an integer represented in some radix  determined  by  the
     value  of  base; and a final wide character string of one or
     more unrecognised wide character codes, including  the  ter-
     minating  null wide-character code of the input wide charac-
     ter  string.  They  then  attempt  to  convert  the  subject
     sequence to an integer, and return 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 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 `-' sign, but not including
     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 code representa-
     tions of `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 non-white-space wide-character code, that  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
     code, or if the first non-white-space wide-character code 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  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 nptr
     is stored in the object pointed to by endptr, provided  that
     endptr is not a null pointer.

     The watol() function is equivalent  to  wstol(str,  (wchar_t
     **)NULL, 10).

     The watoll() function is the long-long (double long) version
     of watol().

     The watoi() function is equivalent to (int)watol().


RETURN VALUES

     Upon successful completion, wcstol() and wstol() return  the
     converted  value,  if  any.  If  no conversion could be per-
     formed, 0 is returned, and errno may be set to indicate  the
     error.  If  the  correct  value  is  outside  the  range  of
     representable values, {LONG_MAX} or {LONG_MIN}  is  returned
     (according  to  the  sign of the value), and errno is set to
     ERANGE.


ERRORS

     The wcstol() and wstol() functions will fail if:

     EINVAL
           The value of base is not supported.

     ERANGE
           The value to be returned is not representable.

     The wcstol() and wstol() functions may fail if:

     EINVAL
           No conversion could be performed.


ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     iswalpha(3C), iswspace(3C),  scanf(3C),  wcstod(3C),  attri-
     butes(5)


NOTES

     Because 0, {LONG_MIN}, and {LONG_MAX} are returned on  error
     and  are also valid returns on success, an application wish-
     ing to check for error situations should  set  errno  to  0,
     call  wcstol()  or  wstol(),  then  check errno and if it is
     non-zero assume an error has occurred.

     Truncation from long  long  to  long  can  take  place  upon
     assignment or by an explicit cast.


Man(1) output converted with man2html