1WCSTOL(3P)                 POSIX Programmer's Manual                WCSTOL(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       wcstol, wcstoll — convert a wide-character string to a long integer
14

SYNOPSIS

16       #include <wchar.h>
17
18       long wcstol(const wchar_t *restrict nptr, wchar_t **restrict endptr,
19           int base);
20       long long wcstoll(const wchar_t *restrict nptr,
21           wchar_t **restrict endptr, int base);
22

DESCRIPTION

24       The functionality described on this reference page is aligned with  the
25       ISO C  standard.  Any  conflict between the requirements described here
26       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2008
27       defers to the ISO C standard.
28
29       These functions shall convert the initial portion of the wide-character
30       string pointed to by nptr to long and long long,  respectively.  First,
31       they shall decompose the input string into three parts:
32
33        1. An  initial, possibly empty, sequence of white-space wide-character
34           codes (as specified by iswspace())
35
36        2. A subject sequence interpreted as an integer  represented  in  some
37           radix determined by the value of base
38
39        3. A  final  wide-character  string  of one or more unrecognized wide-
40           character codes, including the terminating null wide-character code
41           of the input wide-character string
42
43       Then  they shall attempt to convert the subject sequence to an integer,
44       and return the result.
45
46       If base is 0, the expected form of the subject sequence is  that  of  a
47       decimal constant, octal constant, or hexadecimal constant, any of which
48       may be preceded by a '+' or '−' sign. A decimal constant begins with  a
49       non-zero  digit, and consists of a sequence of decimal digits. An octal
50       constant consists of the prefix '0' optionally followed by  a  sequence
51       of  the  digits '0' to '7' only. A hexadecimal constant consists of the
52       prefix 0x or 0X followed by a sequence of the decimal digits  and  let‐
53       ters 'a' (or 'A') to 'f' (or 'F') with values 10 to 15 respectively.
54
55       If the value of base is between 2 and 36, the expected form of the sub‐
56       ject sequence is a sequence of letters and digits representing an inte‐
57       ger  with  the radix specified by base, optionally preceded by a '+' or
58       '−' sign, but not including an integer suffix. The letters from 'a' (or
59       'A')  to  'z' (or 'Z') inclusive are ascribed the values 10 to 35; only
60       letters whose ascribed values are less than that of base shall be  per‐
61       mitted. If the value of base is 16, the wide-character code representa‐
62       tions of 0x or 0X may optionally precede the sequence  of  letters  and
63       digits, following the sign if present.
64
65       The  subject  sequence is defined as the longest initial subsequence of
66       the input wide-character string, starting  with  the  first  non-white-
67       space  wide-character  code  that  is of the expected form. The subject
68       sequence contains no wide-character codes if the  input  wide-character
69       string  is  empty  or  consists  entirely of white-space wide-character
70       code, or if the first non-white-space wide-character code is other than
71       a sign or a permissible letter or digit.
72
73       If  the  subject  sequence  has  the  expected  form and base is 0, the
74       sequence of wide-character codes starting with the first digit shall be
75       interpreted  as  an  integer  constant. If the subject sequence has the
76       expected form and the value of base is between 2 and 36,  it  shall  be
77       used  as the base for conversion, ascribing to each letter its value as
78       given above. If the subject sequence  begins  with  a  minus-sign,  the
79       value  resulting from the conversion shall be negated. A pointer to the
80       final wide-character string shall be stored in the object pointed to by
81       endptr, provided that endptr is not a null pointer.
82
83       In other than the C or POSIX locales, other implementation-defined sub‐
84       ject sequences may be accepted.
85
86       If the subject sequence is empty or does not have the expected form, no
87       conversion shall be performed; the value of nptr shall be stored in the
88       object pointed to by  endptr,  provided  that  endptr  is  not  a  null
89       pointer.
90
91       These functions shall not change the setting of errno if successful.
92
93       Since  0,  {LONG_MIN}  or {LLONG_MIN} and {LONG_MAX} or {LLONG_MAX} are
94       returned on error and are also valid returns on success, an application
95       wishing  to check for error situations should set errno to 0, then call
96       wcstol() or wcstoll(), then check errno.
97

RETURN VALUE

99       Upon successful completion, these functions shall return the  converted
100       value, if any. If no conversion could be performed, 0 shall be returned
101       and errno may be set to indicate the error.  If the  correct  value  is
102       outside  the  range  of  representable  values, {LONG_MIN}, {LONG_MAX},
103       {LLONG_MIN}, or {LLONG_MAX} shall be returned (according to the sign of
104       the value), and errno set to [ERANGE].
105

ERRORS

107       These functions shall fail if:
108
109       EINVAL The value of base is not supported.
110
111       ERANGE The value to be returned is not representable.
112
113       These functions may fail if:
114
115       EINVAL No conversion could be performed.
116
117       The following sections are informative.
118

EXAMPLES

120       None.
121

APPLICATION USAGE

123       None.
124

RATIONALE

126       None.
127

FUTURE DIRECTIONS

129       None.
130

SEE ALSO

132       fscanf(), iswalpha(), wcstod()
133
134       The Base Definitions volume of POSIX.1‐2008, <wchar.h>
135
137       Portions  of  this text are reprinted and reproduced in electronic form
138       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
139       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
140       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
141       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
142       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
143       event of any discrepancy between this version and the original IEEE and
144       The Open Group Standard, the original IEEE and The Open Group  Standard
145       is  the  referee document. The original Standard can be obtained online
146       at http://www.unix.org/online.html .
147
148       Any typographical or formatting errors that appear  in  this  page  are
149       most likely to have been introduced during the conversion of the source
150       files to man page format. To report such errors,  see  https://www.ker
151       nel.org/doc/man-pages/reporting_bugs.html .
152
153
154
155IEEE/The Open Group                  2013                           WCSTOL(3P)
Impressum