1WCSTOUL(3P)                POSIX Programmer's Manual               WCSTOUL(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       wcstoul, wcstoull — convert a wide-character string to an unsigned long
13

SYNOPSIS

15       #include <wchar.h>
16
17       unsigned long wcstoul(const wchar_t *restrict nptr,
18           wchar_t **restrict endptr, int base);
19       unsigned long long wcstoull(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       The  wcstoul()  and wcstoull() functions shall convert the initial por‐
29       tion of the wide-character string pointed to by nptr to  unsigned  long
30       and  unsigned long long representation, respectively. First, they shall
31       decompose the input wide-character 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  unsigned
44       integer, 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 codes 0x  or  0X
62       may  optionally  precede  the sequence of letters and digits, following
63       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 wide-character
67       code that is not white space and 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       codes,  or  if the first wide-character code that is not white space is
71       other than 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 <hyphen-minus>, 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 locale, additional locale-specific subject
84       sequence forms 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, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and  0  is
94       also  a  valid  return  on success, an application wishing to check for
95       error situations  should  set  errno  to  0,  then  call  wcstoul()  or
96       wcstoull(), then check errno.
97

RETURN VALUE

99       Upon  successful  completion,  the  wcstoul()  and wcstoull() functions
100       shall return the converted value, if any. If  no  conversion  could  be
101       performed,  0  shall  be  returned and errno may be set to indicate the
102       error.  If the correct value is outside the range of representable val‐
103       ues,  {ULONG_MAX}  or  {ULLONG_MAX}  respectively shall be returned and
104       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(), wcstol()
133
134       The Base Definitions volume of POSIX.1‐2017, <wchar.h>
135
137       Portions of this text are reprinted and reproduced in  electronic  form
138       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
139       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
140       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
141       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
142       event of any discrepancy between this version and the original IEEE and
143       The Open Group Standard, the original IEEE and The Open Group  Standard
144       is  the  referee document. The original Standard can be obtained online
145       at http://www.opengroup.org/unix/online.html .
146
147       Any typographical or formatting errors that appear  in  this  page  are
148       most likely to have been introduced during the conversion of the source
149       files to man page format. To report such errors,  see  https://www.ker
150       nel.org/doc/man-pages/reporting_bugs.html .
151
152
153
154IEEE/The Open Group                  2017                          WCSTOUL(3P)
Impressum