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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

119       None.
120

APPLICATION USAGE

122       None.
123

RATIONALE

125       None.
126

FUTURE DIRECTIONS

128       None.
129

SEE ALSO

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