1wcstol(3C)               Standard C Library Functions               wcstol(3C)
2
3
4

NAME

6       wcstol,  wcstoll,  wstol, watol, watoll, watoi - convert wide character
7       string to long integer
8

SYNOPSIS

10       #include <wchar.h>
11
12       long wcstol(const wchar_t *restrict nptr, wchar_t **restrict endptr,
13            int base);
14
15
16       long long wcstoll(const wchar_t *restrict nptr, wchar_t **restrict endptr,
17            int base);
18
19
20       #include <widec.h>
21
22       long wstol(const wchar_t *nptr, wchar_t **endptr, int base);
23
24
25       long watol(wchar_t *nptr);
26
27
28       long long watoll(wchar_t *nptr);
29
30
31       int watoi(wchar_t *nptr);
32
33

DESCRIPTION

35       The wcstol() and wcstoll() functions convert the initial portion of the
36       wide  character  string pointed to by nptr to long and long long repre‐
37       sentation, respectively. They first decompose  the  input  string  into
38       three parts:
39
40           1.     an  initial,  possibly  empty, sequence of white-space wide-
41                  character codes (as specified by iswspace(3C))
42
43           2.     a subject sequence interpreted as an integer represented  in
44                  some radix determined by the value of base
45
46           3.     a  final  wide  character string of one or more unrecognised
47                  wide character codes, including the terminating  null  wide-
48                  character code of the input wide character string
49
50
51       They  then  attempt  to convert the subject sequence to an integer, and
52       return the result.
53
54
55       If the value of base is 0, the expected form of the subject sequence is
56       that of a decimal constant, octal constant or hexadecimal constant, any
57       of which may be preceded by a `+'  or  `−'  sign.  A  decimal  constant
58       begins  with  a  non-zero  digit, and consists of a sequence of decimal
59       digits. An octal constant consists of the prefix  `0'  optionally  fol‐
60       lowed  by  a sequence of the digits `0' to `7' only. A hexadecimal con‐
61       stant consists of the prefix `0x' or `0X' followed by a sequence of the
62       decimal  digits and letters `a' (or `A') to `f' (or `F') with values 10
63       to 15 respectively.
64
65
66       If the value of base is between 2 and 36, the expected form of the sub‐
67       ject sequence is a sequence of letters and digits representing an inte‐
68       ger with the radix specified by  base, optionally preceded by a `+'  or
69       `−' sign, but not including an integer suffix. The letters from `a' (or
70       `A') to `z' (or `Z') inclusive  are ascribed the values 10 to 35;  only
71       letters whose ascribed values are less than that of base are permitted.
72       If the value of base is 16, the wide-character code representations  of
73       `0x' or `0X' may optionally precede the sequence of letters and digits,
74       following the sign if present.
75
76
77       The subject sequence is defined as the longest initial  subsequence  of
78       the  input  wide  character  string, starting with the first non-white-
79       space wide-character code, that is of the expected  form.  The  subject
80       sequence  contains  no wide-character codes if the input wide character
81       string is empty or  consists  entirely  of  white-space  wide-character
82       code, or if the first non-white-space wide-character code is other than
83       a sign or a permissible letter or digit.
84
85
86       If the subject sequence has the expected form and the value of base  is
87       0,  the  sequence of wide-character codes starting with the first digit
88       is interpreted as an integer constant. If the subject sequence has  the
89       expected  form and the value of base is between 2 and 36, it is used as
90       the base for conversion, ascribing to each letter its  value  as  given
91       above.  If the subject sequence begins with a minus sign (-), the value
92       resulting from the conversion is negated. A pointer to the  final  wide
93       character  string  is  stored  in the object pointed to by endptr, pro‐
94       vided that  endptr is not a null pointer.
95
96
97       If the subject sequence is empty or does not have the expected form, no
98       conversion  is  performed;  the  value  of nptr is stored in the object
99       pointed to by endptr, provided that  endptr is not a null pointer.
100
101
102       These functions do not change the setting of errno if successful.
103
104
105       Since 0, {LONG_MIN} or {LLONG_MIN}, and {LONG_MAX} or  {LLONG_MAX}  are
106       returned on error and are also valid returns on success, an application
107       wanting to check for error situations should set errno to 0,  call  one
108       of these functions, then check errno.
109
110
111       The wstol() function is equivalent to wcstol().
112
113
114       The watol() function is equivalent to wstol(str,(wchar_t **)NULL, 10).
115
116
117       The  watoll()  function  is  the  long-long  (double  long)  version of
118       watol().
119
120
121       The watoi() function is equivalent to (int)watol().
122

RETURN VALUES

124       Upon successful completion, these functions return the converted value,
125       if  any.  If  no conversion could be performed, 0 is returned and errno
126       may be set to indicate the error. If the correct value is  outside  the
127       range  of representable values, {LONG_MIN}, {LONG_MAX}, {LLONG_MIN}, or
128       {LLONG_MAX} is returned (according to the sign of the value), and errno
129       is set to ERANGE.
130

ERRORS

132       These functions will fail if:
133
134       EINVAL    The value of base is not supported.
135
136
137       ERANGE    The value to be returned is not representable.
138
139
140
141       These functions may fail if:
142
143       EINVAL    No conversion could be performed.
144
145

ATTRIBUTES

147       See attributes(5) for descriptions of the following attributes:
148
149
150
151
152       ┌─────────────────────────────┬─────────────────────────────────────┐
153       │ATTRIBUTE TYPE               │ATTRIBUTE VALUE                      │
154       ├─────────────────────────────┼─────────────────────────────────────┤
155       │Interface Stability          │wcstol() and wcstoll() are Standard. │
156       ├─────────────────────────────┼─────────────────────────────────────┤
157       │MT-Level                     │MT-Safe                              │
158       └─────────────────────────────┴─────────────────────────────────────┘
159

SEE ALSO

161       iswalpha(3C), iswspace(3C), scanf(3C), wcstod(3C), attributes(5), stan‐
162       dards(5)
163

NOTES

165       Truncation from long long to long can take place upon assignment or  by
166       an explicit cast.
167
168
169
170SunOS 5.11                        1 Nov 2003                        wcstol(3C)
Impressum