sequences). When c32 is not a valid wide character, an encoding error occurs: the function stores the
value of the macro EILSEQ in errno and returns (size_t) (−1);the conversion state is unspecified.
7.31 [Extended multibyte and wide character utilities <wchar.h>]
7.31.1 [Introduction]
1 The header <wchar.h> defines four macros, and declares four data types, one tag, and many
functions.[398]
Footnote 398) See "future library directions" (7.33.20).
2 The types declared are wchar_t and size_t (both described in 7.21);
mbstate_t
which is a complete object type other than an array type that can hold the conversion state informa-
tion necessary to convert between sequences of multibyte characters and wide characters;
wint_t
which is an integer type unchanged by default argument promotions that can hold any value
corresponding to members of the extended character set, as well as at least one value that does not
correspond to any member of the extended character set (see WEOF below);[399] and
struct tm
which is declared as an incomplete structure type (the contents are described in 7.29.1).
Footnote 399) wchar_t and wint_t can be the same integer type.
3 The macros defined are NULL (described in 7.21); WCHAR_MIN, WCHAR_MAX, and WCHAR_WIDTH (de-
scribed in 7.22); and
WEOF
which expands to a constant expression of type wint_t whose value does not correspond to any
member of the extended character set.[400] It is accepted (and returned) by several functions in
this subclause to indicate end-of-file, that is, no more input from a stream. It is also used as a wide
character value that does not correspond to any member of the extended character set.
Footnote 400) The value of the macro WEOF can differ from that of EOF and need not be negative.
4 The functions declared are grouped as follows:
— Functions that perform input and output of wide characters, or multibyte characters, or both;
— Functions that provide wide string numeric conversion;
— Functions that perform general wide string manipulation;
— Functions for wide string date and time conversion; and
— Functions that provide extended capabilities for conversion between multibyte and wide
character sequences.
5 Arguments to the functions in this subclause may point to arrays containing wchar_t values that do
not correspond to members of the extended character set. Such values shall be processed according
to the specified semantics, except that it is unspecified whether an encoding error occurs if such a
value appears in the format string for a function in 7.31.2 or 7.31.5 and the specified semantics do
not require that value to be processed by wcrtomb.
6 Unless explicitly stated otherwise, if the execution of a function described in this subclause causes
copying to take place between objects that overlap, the behavior is undefined.
7.31.2 [Formatted wide character input/output functions]
1 The formatted wide character input/output functions shall behave as if there is a sequence point
after the actions associated with each specifier.[401]
Footnote 401) The fwprintf functions perform writes to memory for the %n specifier.
<IP_ADDRESS> [The fwprintf function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
int fwprintf(FILE * restrict stream, const wchar_t * restrict format, ...);
Description
2 The fwprintf function writes output to the stream pointed to by stream, under control of the wide
string pointed to by format that specifies how subsequent arguments are converted for output. If
there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted
while arguments remain, the excess arguments are evaluated (as always) but are otherwise ignored.
The fwprintf function returns when the end of the format string is encountered.
3 The format is composed of zero or more directives: ordinary wide characters (not %), which are
copied unchanged to the output stream; and conversion specifications, each of which results in
fetching zero or more subsequent arguments, converting them, if applicable, according to the
corresponding conversion specifier, and then writing the result to the output stream.
4 Each conversion specification is introduced by the wide character %. After the %, the following
appear in sequence:
— Zero or more flags (in any order) that modify the meaning of the conversion specification.
— An optional minimum field width. If the converted value has fewer wide characters than the
field width, it is padded with spaces (by default) on the left (or right, if the left adjustment flag,
described later, has been given) to the field width. The field width takes the form of an asterisk
* (described later) or a nonnegative decimal integer.[402]
— An optional precision that gives the minimum number of digits to appear for the b, d, i, o, u,
x, and X conversions, the number of digits to appear after the decimal-point wide character
for a, A, e, E, f, and F conversions, the maximum number of significant digits for the g and G
conversions, or the maximum number of wide characters to be written for s conversions. The
precision takes the form of a period (.) followed either by an asterisk * (described later) or by
an optional nonnegative decimal integer; if only the period is specified, the precision is taken
as zero. If a precision appears with any other conversion specifier, the behavior is undefined.
— An optional length modifier that specifies the size of the argument.
— A conversion specifier wide character that specifies the type of conversion to be applied.
Footnote 402) Note that 0 is taken as a flag, not as the beginning of a field width.
5 As noted above, a field width, or precision, or both, may be indicated by an asterisk. In this case,
an int argument supplies the field width or precision. The arguments specifying field width, or
precision, or both, shall appear (in that order) before the argument (if any) to be converted. A
negative field width argument is taken as a - flag followed by a positive field width. A negative
precision argument is taken as if the precision were omitted.
6 The flag wide characters and their meanings are:
- The result of the conversion is left-justified within the field. (It is right-justified if this flag is
not specified.)
+ The result of a signed conversion always begins with a plus or minus sign. (It begins with a
sign only when a value with a negative sign is converted if this flag is not specified.) [403]
space If the first wide character of a signed conversion is not a sign, or if a signed conversion results
in no wide characters, a space is prefixed to the result. If the space and + flags both appear,
the space flag is ignored.
# The result is converted to an "alternative form". For o conversion, it increases the precision, if
and only if necessary, to force the first digit of the result to be a zero (if the value and precision
are both 0, a single 0 is printed). For b conversion, a nonzero result has 0b prefixed to it. For
x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g, and G
conversions, the result of converting a floating-point number always contains a decimal-point
wide character, even if no digits follow it. (Normally, a decimal-point wide character appears
in the result of these conversions only if a digit follows it.) For g and G conversions, trailing
zeros are not removed from the result. For other conversions, the behavior is undefined.
0 For b, d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, leading zeros (following any
indication of sign or base) are used to pad to the field width rather than performing space
padding, except when converting an infinity or NaN. If the 0 and - flags both appear, the
0 flag is ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 0 flag is
ignored. For other conversions, the behavior is undefined.
Footnote 403) The results of all floating conversions of a negative zero, and of negative values that round to zero, include a minus sign.
7 The length modifiers and their meanings are:
hh Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a
signed char or unsigned char argument (the argument will have been promoted
according to the integer promotions, but its value shall be converted to signed char or
unsigned char before printing); or that a following n conversion specifier applies to a
pointer to a signed char argument.
h Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a short int
or unsigned short int argument (the argument will have been promoted accord-
ing to the integer promotions, but its value shall be converted to short int or
unsigned short int before printing); or that a following n conversion specifier applies
to a pointer to a short int argument.
l (ell) Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a long int
or unsigned long int argument; that a following n conversion specifier applies to
a pointer to a long int argument; that a following c conversion specifier applies to
a wint_t argument; that a following s conversion specifier applies to a pointer to a
wchar_t argument; or has no effect on a following a, A, e, E, f, F, g, or G conversion
specifier.
ll (ell-ell) Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a
long long int or unsigned long long int argument; or that a following n con-
version specifier applies to a pointer to a long long int argument.
j Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to an intmax_t
or uintmax_t argument; or that a following n conversion specifier applies to a pointer
to an intmax_t argument.
z Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a size_t
or the corresponding signed integer type argument; or that a following n conversion
specifier applies to a pointer to a signed integer type corresponding to size_t argument.
t Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a ptrdiff_t
or the corresponding unsigned integer type argument; or that a following n conversion
specifier applies to a pointer to a ptrdiff_t argument.
wN Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to an integer
argument with a specific width where N is a positive decimal integer with no leading
zeros (the argument will have been promoted according to the integer promotions, but
its value shall be converted to the unpromoted type); or that a following n conversion
specifier applies to a pointer to an integer type argument with a width of N bits. All
minimum-width integer types (<IP_ADDRESS>) and exact-width integer types (<IP_ADDRESS>) de-
fined in the header <stdint.h> shall be supported. Other supported values of N are
implementation-defined.
wfN Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a fastest
minimum-width integer argument with a specific width where N is a positive decimal
integer with no leading zeros (the argument will have been promoted according to
the integer promotions, but its value shall be converted to the unpromoted type); or
that a following n conversion specifier applies to a pointer to a fastest minimum-width
integer type argument with a width of N bits. All fastest minimum-width integer types
(<IP_ADDRESS>) defined in the header <stdint.h> shall be supported. Other supported values
of N are implementation-defined.
L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
long double argument.
H Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
_Decimal32 argument.
D Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
_Decimal64 argument.
DD Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
_Decimal128 argument.
If a length modifier appears with any conversion specifier other than as specified above, the behavior
is undefined.
8 The conversion specifiers and their meanings are:
d,i The int argument is converted to signed decimal in the style [-]dddd. The precision
specifies the minimum number of digits to appear; if the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is no wide characters.
b, o,u,x,X The unsigned int argument is converted to unsigned binary (b), unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (x or X) in the style dddd; the
letters abcdef are used for x conversion and the letters ABCDEF for X conversion. The
precision specifies the minimum number of digits to appear; if the value being converted
can be represented in fewer digits, it is expanded with leading zeros. The default precision
is 1. The result of converting a zero value with a precision of zero is no wide characters.
f,F A double argument representing a floating-point number is converted to decimal notation
in the style [-]ddd.ddd, where the number of digits after the decimal-point wide character
is equal to the precision specification. If the precision is missing, it is taken as 6; if the
precision is zero and the # flag is not specified, no decimal-point wide character appears.
If a decimal-point wide character appears, at least one digit appears before it. The value is
rounded to the appropriate number of digits.
A double argument representing an infinity is converted in one of the styles [-]inf or
[-]infinity — which style is implementation-defined. A double argument representing
a NaN is converted in one of the styles [-]nan or [-]nan(n-wchar-sequence) — which style,
and the meaning of any n-wchar-sequence, is implementation-defined. The F conversion
specifier produces INF, INFINITY, or NAN instead of inf, infinity, or nan, respectively.[404]
e,E A double argument representing a floating-point number is converted in the style
[-]d.ddde±dd, where there is one digit (which is nonzero if the argument is nonzero)
before the decimal-point wide character and the number of digits after it is equal to the
precision; if the precision is missing, it is taken as 6; if the precision is zero and the #
flag is not specified, no decimal-point wide character appears. The value is rounded to
the appropriate number of digits. The E conversion specifier produces a number with E
instead of e introducing the exponent. The exponent always contains at least two digits,
and only as many more digits as necessary to represent the exponent. If the value is zero,
the exponent is zero.
A double argument representing an infinity or NaN is converted in the style of an f or F
conversion specifier.
g,G A double argument representing a floating-point number is converted in style f or e (or
in style F or E in the case of a G conversion specifier), depending on the value converted
and the precision. Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if
the precision is zero. Then, if a conversion with style E would have an exponent of X:
if P > X ≥ −4, the conversion is with style f (or F) and precision P − (X + 1).
otherwise, the conversion is with style e (or E) and precision P − 1.
Finally, unless the # flag is used, any trailing zeros are removed from the fractional portion
of the result and the decimal-point wide character is removed if there is no fractional
portion remaining.
A double argument representing an infinity or NaN is converted in the style of an f or F
conversion specifier.
a,A A double argument representing a floating-point number is converted in the style
[-]0xh.hhhhp±d, where there is one hexadecimal digit (which is nonzero if the argument is a
normalized floating-point number and is otherwise unspecified) before the decimal-point
wide character[405] and the number of hexadecimal digits after it is equal to the precision;
if the precision is missing and FLT_RADIX is a power of 2, then the precision is sufficient
for an exact representation of the value; if the precision is missing and FLT_RADIX is not a
power of 2, then the precision is sufficient to distinguish[406] values of type double, except
that trailing zeros may be omitted; if the precision is zero and the # flag is not specified, no
decimal-point wide character appears. The letters abcdef are used for a conversion and
the letters ABCDEF for A conversion. The A conversion specifier produces a number with
X and P instead of x and p. The exponent always contains at least one digit, and only as
many more digits as necessary to represent the decimal exponent of 2. If the value is zero,
the exponent is zero.
A double argument representing an infinity or NaN is converted in the style of an f or F
conversion specifier.
If an H, D, or DD modifier is present and the precision is missing, then for a decimal
floating type argument represented by a triple of integers (s, c, q), where n is the number
of significant digits in the coefficient c,
— if −(n + 5) ≤ q ≤ 0, use style f (or style F in the case of an A conversion specifier)
with formatting precision equal to −q,
— otherwise, use style e (or style E in the case of an A conversion specifier) with format-
ting precision equal to n − 1, with the exceptions that if c = 0 then the digit-sequence
in the exponent-part shall have the value q (rather than 0), and that the exponent is
[405] Binary implementations can choose the hexadecimal digit to the left of the decimal-point wide character so that subsequent
digits align to nibble (4-bit) boundaries. This implementation choice affects numerical values printed with a precision P
that is insufficient to represent all values exactly. Implementations with different conventions about the most significant
hexadecimal digit will round at different places, affecting the numerical value of the hexadecimal result. For example,
possible printed output for the code
#include <stdio.h>
/* ... */
double x = 123.0;
printf("%.1a", x);
include "0x1.fp+6 " and "0xf.6p+3 " whose numerical values are 124 and 123, respectively. Portable code seeking identical
numerical results on different platforms should avoid precisions P that require rounding.
[406] The formatting precision P is sufficient to distinguish values of the source type if 16P > bp where b (not a power of 2)
and p are the base and precision of the source type (<IP_ADDRESS>.2). A smaller P might suffice depending on the implementation’s
scheme for determining the digit to the left of the decimal-point wide character.
always expressed with the minimum number of digits required to represent its value
(the exponent never contains a leading zero).
If the precision P is present (in the conversion specification) and is zero or at least as
large as the precision p (<IP_ADDRESS>.2) of the decimal floating type, the conversion is as if the
precision were missing. If the precision P is present (and nonzero) and less than the
precision p of the decimal floating type, the conversion first obtains an intermediate result
as follows, where n is the number of significant digits in the coefficient:
— If n ≤ P , set the intermediate result to the input.
— If n > P , round the input value, according to the current rounding direction for
decimal floating-point operations, to P decimal digits, with unbounded exponent
range, representing the result with a P -digit integer coefficient when in the form
(s, c, q).
Convert the intermediate result in the manner described above for the case where the
precision is missing.
c If no l length modifier is present, the int argument is converted to a wide character as if
by calling btowc and the resulting wide character is written.
If an l length modifier is present, the wint_t argument is converted to wchar_t and
written.
s If no l length modifier is present, the argument shall be a pointer to storage of character
type containing a multibyte character sequence beginning in the initial shift state. Charac-
ters from the storage are converted as if by repeated calls to the mbrtowc function, with
the conversion state described by an mbstate_t object initialized to zero before the first
multibyte character is converted, and written up to (but not including) the terminating
null wide character. If the precision is specified, no more than that many wide characters
are written. If the precision is not specified or is greater than the size of the converted
storage, the converted storage shall contain a null wide character.
If an l length modifier is present, the argument shall be a pointer to storage of wchar_t
type. Wide characters from the storage are written up to (but not including) a terminating
null wide character. If the precision is specified, no more than that many wide characters
are written. If the precision is not specified or is greater than the size of the array, the
storage shall contain a null wide character.
p The argument shall be a pointer to void or a pointer to a character type. The value of
the pointer is converted to a sequence of printing wide characters, in an implementation-
defined manner.
n The argument shall be a pointer to signed integer whose type is specified by the length
modifiers, if any, for the conversion specification, or shall be int if no length modifiers
are specified for the conversion specification. The number of wide characters written to
the output stream so far by this call to fwprintf is stored into the integer object pointed
to by the argument. No argument is converted, but one is consumed. If the conversion
specification includes any flags, a field width, or a precision, the behavior is undefined.
% A % wide character is written. No argument is converted. The complete conversion
specification shall be %%.
Footnote 404) When applied to infinite and NaN values, the -, +, and space flag wide characters have their usual meaning; the # and 0
flag wide characters have no effect.
Footnote 405) Binary implementations can choose the hexadecimal digit to the left of the decimal-point wide character so that subsequent
digits align to nibble (4-bit) boundaries. This implementation choice affects numerical values printed with a precision P
that is insufficient to represent all values exactly. Implementations with different conventions about the most significant
hexadecimal digit will round at different places, affecting the numerical value of the hexadecimal result. For example,
possible printed output for the code
#include <stdio.h>
/* ... */
double x = 123.0;
printf("%.1a", x);
include "0x1.fp+6 " and "0xf.6p+3 " whose numerical values are 124 and 123, respectively. Portable code seeking identical
numerical results on different platforms should avoid precisions P that require rounding.
Footnote 406) The formatting precision P is sufficient to distinguish values of the source type if 16P > bp where b (not a power of 2)
and p are the base and precision of the source type (<IP_ADDRESS>.2). A smaller P might suffice depending on the implementation’s
scheme for determining the digit to the left of the decimal-point wide character.
Footnote 405) Binary implementations can choose the hexadecimal digit to the left of the decimal-point wide character so that subsequent
digits align to nibble (4-bit) boundaries. This implementation choice affects numerical values printed with a precision P
that is insufficient to represent all values exactly. Implementations with different conventions about the most significant
hexadecimal digit will round at different places, affecting the numerical value of the hexadecimal result. For example,
possible printed output for the code
#include <stdio.h>
/* ... */
double x = 123.0;
printf("%.1a", x);
include "0x1.fp+6 " and "0xf.6p+3 " whose numerical values are 124 and 123, respectively. Portable code seeking identical
numerical results on different platforms should avoid precisions P that require rounding.
Footnote 406) The formatting precision P is sufficient to distinguish values of the source type if 16P > bp where b (not a power of 2)
and p are the base and precision of the source type (<IP_ADDRESS>.2). A smaller P might suffice depending on the implementation’s
scheme for determining the digit to the left of the decimal-point wide character.
9 If a conversion specification is invalid, the behavior is undefined.[407] fwprintf shall behave as if it
uses va_arg with a type argument naming the type resulting from applying the default argument
promotions to the type corresponding to the conversion specification and then converting the result
of the va_arg expansion to the type corresponding to the conversion specification.[408]
Footnote 407) See "future library directions" (7.33.20).
Footnote 408) The behavior is undefined when the types differ as specified for va_arg <IP_ADDRESS>.
10 In no case does a nonexistent or small field width cause truncation of a field; if the result of a
conversion is wider than the field width, the field is expanded to contain the conversion result.
11 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded to a hexadecimal
floating number with the given precision.
Recommended practice
12 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly representable
in the given precision, the result should be one of the two adjacent numbers in hexadecimal floating
style with the given precision, with the extra stipulation that the error should have a correct sign for
the current rounding direction.
13 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most the maximum
value M of the T_DECIMAL_DIG macros (defined in <float.h>), then the result should be correctly
rounded.[409] If the number of significant decimal digits is more than M but the source value is
exactly representable with M digits, then the result should be an exact representation with trailing
zeros. Otherwise, the source value is bounded by two adjacent decimal strings L < U, both having
M significant digits; the value of the resultant decimal string D should satisfy L ≤ D ≤ U, with the
extra stipulation that the error should have a correct sign for the current rounding direction.
Footnote 409) For binary-to-decimal conversion, the result format’s values are the numbers representable with the given format specifier.
The number of significant digits is determined by the format specifier, and in the case of fixed-point conversion by the source
value as well.
14 An uppercase B format specifier is not covered by the description above, because it used to be
available for extensions in previous versions of this standard.
Implementations that did not use an uppercase B as their own extension before are encouraged to
implement it similar to conversion specifier b as standardized above, with the alternative form (#B)
generating 0B as prefix for nonzero values.
Returns
15 The fwprintf function returns the number of wide characters transmitted, or a negative value if
an output or encoding error occurred or if the implementation does not support a specified width
length modifier.
Environmental limits
16 The number of wide characters that can be produced by any single conversion shall be at least 4095.
17 EXAMPLE To print a date and time in the form "Sunday, July 3, 10:02" followed by π to five decimal places:
#include <math.h>
#include <stdio.h>
#include <wchar.h>
/* ... */
wchar_t *weekday, *month; // pointers to wide strings
int day, hour, min;
fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
fwprintf(stdout, L"pi = %.5f\n", 4 * atan(1.0));
18 EXAMPLE 1 In this example, multibyte characters do not have a state-dependent encoding, and the members of the extended
character set that consist of more than one byte each consist of exactly two bytes, the first of which is denoted here by a □
and the second by an uppercase letter.
19 Given the following wide string with length seven,
static wchar_t wstr[] = L"□X□Yabc□Z□W";
the seven calls
fprintf(stdout, "|1234567890123|\n");
fprintf(stdout, "|%13ls|\n", wstr);
fprintf(stdout, "|%-13.9ls|\n", wstr);
fprintf(stdout, "|%13.10ls|\n", wstr);
fprintf(stdout, "|%13.11ls|\n", wstr);
fprintf(stdout, "|%13.15ls|\n", &wstr[2]);
fprintf(stdout, "|%13lc|\n", (wint_t) wstr[5]);
will print the following seven lines:
|1234567890123|
| □X□Yabc□Z□W|
|□X□Yabc□Z |
| □X□Yabc□Z|
| □X□Yabc□Z□W|
| abc□Z□W|
| □Z|
20 EXAMPLE 2 Following are representations of _Decimal64 arguments as triples (s, c, q) and the corresponding character
sequences fprintf produces with "%Da":
(+1, 123, 0) 123
(−1, 123, 0) -123
(+1, 123, −2) 1.23
(+1, 123, 1) 1.23e+3
(−1, 123, 1) -1.23e+3
(+1, 123, −8) 0.00000123
(+1, 123, −9) 1.23e-7
(+1, 120, −8) 0.00000120
(+1, 120, −9) 1.20e-7
(+1,<PHONE_NUMBER>123456, 0)<PHONE_NUMBER>123456
(+1,<PHONE_NUMBER>123456, 1) 1.234567890123456e+16
(+1,<PHONE_NUMBER>123456, −1)<PHONE_NUMBER>12345.6
(+1,<PHONE_NUMBER>123456, −21) 0.000001234567890123456
(+1,<PHONE_NUMBER>123456, −22) 1.234567890123456e-7
(+1, 0, 0) 0
(−1, 0, 0) -0
(+1, 0, −6) 0.000000
(+1, 0, −7) 0e-7
(+1, 0, 2) 0e+2
(+1, 5, −6) 0.000005
(+1, 50, −7) 0.0000050
(+1, 5, −7) 5e-7
To illustrate the effects of a precision specification, the sequence:
_Decimal32 x = 6543.00DF; // (+1, 654300, -2)
fprintf(stdout, "%Ha\n", x);
fprintf(stdout, "%.6Ha\n", x);
fprintf(stdout, "%.5Ha\n", x);
fprintf(stdout, "%.4Ha\n", x);
fprintf(stdout, "%.3Ha\n", x);
fprintf(stdout, "%.2Ha\n", x);
fprintf(stdout, "%.1Ha\n", x);
fprintf(stdout, "%.0Ha\n", x);
assuming default rounding, results in:
6543.00
6543.00
6543.0
6543
6.54e+3
6.5e+3
7e+3
6543.00
To illustrate the effects of the exponent range, the sequence:
_Decimal32 x = 9543210e87DF; // (+1, 9543210, 87)
_Decimal32 y = 9500000e90DF; // (+1, 9500000, 90)
fprintf(stdout, "%.6Ha\n", x);
fprintf(stdout, "%.5Ha\n", x);
fprintf(stdout, "%.4Ha\n", x);
fprintf(stdout, "%.3Ha\n", x);
fprintf(stdout, "%.2Ha\n", x);
fprintf(stdout, "%.1Ha\n", x);
fprintf(stdout, "%.1Ha\n", y);
assuming default rounding, results in:
9.54321e+93
9.5432e+93
9.543e+93
9.54e+93
9.5e+93
1e+94
1e+97
To further illustrate the effects of the exponent range, the sequence:
_Decimal32 x = 9512345e90DF; // (+1, 9512345, 90)
_Decimal32 y = 9512345e86DF; // (+1, 9512345, 86)
fprintf(stdout, "%.3Ha\n", x);
fprintf(stdout, "%.2Ha\n", x);
fprintf(stdout, "%.1Ha\n", x);
fprintf(stdout, "%.2Ha\n", y);
assuming default rounding, results in:
9.51e+96
9.5e+96
1e+97
9.5e+92
Forward references: the btowc function (<IP_ADDRESS>.1), the mbrtowc function (<IP_ADDRESS>.2).
<IP_ADDRESS> [The fwscanf function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
int fwscanf(FILE * restrict stream, const wchar_t * restrict format, ...);
Description
2 The fwscanf function reads input from the stream pointed to by stream, under control of the wide
string pointed to by format that specifies the admissible input sequences and how they are to be
converted for assignment, using subsequent arguments as pointers to the objects to receive the
converted input. If there are insufficient arguments for the format, the behavior is undefined. If the
format is exhausted while arguments remain, the excess arguments are evaluated (as always) but
are otherwise ignored.
3 The format is composed of zero or more directives: one or more white-space wide characters, an
ordinary wide character (neither % nor a white-space wide character), or a conversion specification.
Each conversion specification is introduced by the wide character %. After the %, the following
appear in sequence:
— An optional assignment-suppressing wide character *.
— An optional decimal integer greater than zero that specifies the maximum field width (in wide
characters).
— An optional length modifier that specifies the size of the receiving object.
— A conversion specifier wide character that specifies the type of conversion to be applied.
4 The fwscanf function executes each directive of the format in turn. When all directives have been
executed, or if a directive fails (as detailed below), the function returns. Failures are described as
input failures (due to the occurrence of an encoding error or the unavailability of input characters),
or matching failures (due to inappropriate input).
5 A directive composed of white-space wide character(s) is executed by reading input up to the first
non-white-space wide character (which remains unread), or until no more wide characters can be
read. The directive never fails.
6 A directive that is an ordinary wide character is executed by reading the next wide character of
the stream. If that wide character differs from the directive,the directive fails and the differing and
subsequent wide characters remain unread. Similarly, if end-of-file, an encoding error, or a read
error prevents a wide character from being read, the directive fails.
7 A directive that is a conversion specification defines a set of matching input sequences, as described
below for each specifier. A conversion specification is executed in the following steps:
8 Input white-space wide characters are skipped, unless the specification includes a [, c, or n speci-
fier.[410]
Footnote 410) These white-space wide characters are not counted against a specified field width.
9 An input item is read from the stream, unless the specification includes an n specifier. An input item
is defined as the longest sequence of input wide characters which does not exceed any specified
field width and which is, or is a prefix of, a matching input sequence.[411] The first wide character, if
any, after the input item remains unread. If the length of the input item is zero, the execution of the
directive fails; this condition is a matching failure unless end-of-file, an encoding error, or a read
error prevented input from the stream, in which case it is an input failure.
Footnote 411) fwscanf pushes back at most one input wide character onto the input stream. Therefore, some sequences that are
acceptable to wcstod, wcstol, etc., are unacceptable to fwscanf.
10 Except in the case of a % specifier, the input item (or, in the case of a %n directive, the count of input
wide characters) is converted to a type appropriate to the conversion specifier. If the input item is
not a matching sequence, the execution of the directive fails: this condition is a matching failure.
Unless assignment suppression was indicated by a *, the result of the conversion is placed in the
object pointed to by the first argument following the format argument that has not already received
a conversion result. If this object does not have an appropriate type, or if the result of the conversion
cannot be represented in the object, the behavior is undefined.
11 The length modifiers and their meanings are:
hh Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to signed char or unsigned char.
h Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to short int or unsigned short int.
l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to long int or unsigned long int; that a following a, A, e, E, f, F,
g, or G conversion specifier applies to an argument with type pointer to double; or that
a following c, s, or [ conversion specifier applies to an argument with type pointer to
wchar_t .
ll (ell-ell) Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to long long int or unsigned long long int.
j Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to intmax_t or uintmax_t.
z Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to size_t or the corresponding signed integer type.
t Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to ptrdiff_t or the corresponding unsigned integer type.
wN Specifies that a following b, d, i, o, u, x, or X, or n conversion specifier applies to an
argument which is a pointer to an integer with a specific width where N is a positive
decimal integer with no leading zeros. All minimum-width integer types (<IP_ADDRESS>) and
exact-width integer types (<IP_ADDRESS>) defined in the header <stdint.h> shall be supported.
Other supported values of N are implementation-defined.
wfN Specifies that a following b, d, i, o, u, x, or X, or n conversion specifier applies to an
argument which is a pointer to a fastest minimum-width integer with a specific width
where N is a positive decimal integer with no leading zeros. All fastest minimum-width
integer types (<IP_ADDRESS>) defined in the header <stdint.h> shall be supported. Other
supported values of N are implementation-defined.
L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to long double.
H Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to _Decimal32 .
D Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to _Decimal64 .
DD Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to _Decimal128 .
If a length modifier appears with any conversion specifier other than as specified above, the behavior
is undefined.
12 In the following, the type of the corresponding argument for a conversion specifier shall be a pointer
to a type determined by the length modifiers, if any, or specified by the conversion specifier. The
conversion specifiers and their meanings are:
d Matches an optionally signed decimal integer, whose format is the same as expected for
the subject sequence of the wcstol function with the value 10 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
int.
b Matches an optionally signed binary integer, whose format is the same as expected for the
subject sequence of the wcstol function with the value 2 for the base argument. Unless a
length modifier is specified, the corresponding argument shall be a pointer to unsigned
int.
i Matches an optionally signed integer, whose format is the same as expected for the subject
sequence of the wcstol function with the value 0 for the base argument. Unless a length
modifier is specified, the corresponding argument shall be a pointer to int.
o Matches an optionally signed octal integer, whose format is the same as expected for
the subject sequence of the wcstoul function with the value 8 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
unsigned int.
u Matches an optionally signed decimal integer, whose format is the same as expected for
the subject sequence of the wcstoul function with the value 10 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
unsigned int.
x Matches an optionally signed hexadecimal integer, whose format is the same as expected
for the subject sequence of the wcstoul function with the value 16 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
unsigned int.
a,e,f,g Matches an optionally signed floating-point number, infinity, or NaN, whose format is
the same as expected for the subject sequence of the wcstod function. Unless a length
modifier is specified, the corresponding argument shall be a pointer to float.
c Matches a sequence of wide characters of exactly the number specified by the field width
(1 if no field width is present in the directive).
If no l length modifier is present, characters from the input field are converted as if
by repeated calls to the wcrtomb function, with the conversion state described by an
mbstate_t object initialized to zero before the first wide character is converted. The
corresponding argument shall be a pointer to char, signed char, unsigned char, or
void that points to storage large enough to accept the sequence. No null character is
added.
If an l length modifier is present, the corresponding argument shall be a pointer to storage
of wchar_t large enough to accept the sequence.No null wide character is added.
s Matches a sequence of non-white-space wide characters.
If no l length modifier is present, characters from the input field are converted as if
by repeated calls to the wcrtomb function, with the conversion state described by an
mbstate_t object initialized to zero before the first wide character is converted. The
corresponding argument shall be a pointer to char, signed char, unsigned char, or
void that points to storage large enough to accept the sequence and a terminating null
character, which will be added automatically.
If an l length modifier is present, the corresponding argument shall be a pointer to storage
of wchar_t large enough to accept the sequence and the terminating null wide character,
which will be added automatically.
[ Matches a nonempty sequence of wide characters from a set of expected characters (the
scanset).
If no l length modifier is present, characters from the input field are converted as if
by repeated calls to the wcrtomb function, with the conversion state described by an
mbstate_t object initialized to zero before the first wide character is converted. The
corresponding argument shall be a pointer to char, signed char, unsigned char, or
void that points to storage large enough to accept the sequence and a terminating null
character, which will be added automatically.
If an l length modifier is present, the corresponding argument shall be a pointer that
points to storage of wchar_t large enough to accept the sequence and the terminating null
wide character, which will be added automatically.
The conversion specifier includes all subsequent wide characters in the format string,
up to and including the matching right bracket (]). The wide characters between the
brackets (the scanlist) compose the scanset, unless the wide character after the left bracket
is a circumflex (^), in which case the scanset contains all wide characters that do not
appear in the scanlist between the circumflex and the right bracket. If the conversion
specifier begins with [] or [^], the right bracket wide character is in the scanlist and
the next following right bracket wide character is the matching right bracket that ends
the specification; otherwise the first following right bracket wide character is the one
that ends the specification. If a - wide character is in the scanlist and is not the first, nor
the second where the first wide character is a ^, nor the last character, the behavior is
implementation-defined.
p Matches an implementation-defined set of sequences, which should be the same as the
set of sequences that may be produced by the %p conversion of the fwprintf function.
The corresponding argument shall be a pointer to a pointer of void. The input item is
converted to a pointer value in an implementation-defined manner. If the input item is a
value converted earlier during the same program execution, the pointer that results shall
compare equal to that value; otherwise the behavior of the %p conversion is undefined.
n No input is consumed. The corresponding argument shall be a pointer of a signed integer
type. The number of wide characters read from the input stream so far by this call to the
fwscanf function is stored into the integer object pointed to by the argument. Execution
of a %n directive does not increment the assignment count returned at the completion of
execution of the fwscanf function. No argument is converted, but one is consumed. If
the conversion specification includes an assignment-suppressing wide character or a field
width, the behavior is undefined.
% Matches a single % wide character; no conversion or assignment occurs. The complete
conversion specification shall be %%.
13 If a conversion specification is invalid, the behavior is undefined.[412]
Footnote 412) See "future library directions" (7.33.20).
14 The conversion specifiers A, E, F, G, and X are also valid and behave the same as, respectively, a, e, f,
g, and x.
15 Trailing white-space wide characters(including new-line wide characters) are left unread unless
matched by a directive. The success of literal matches and suppressed assignments is not directly
determinable other than via the %n directive.
Returns
16 The fwscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the function returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure or if the implementation does not support a specific width length modifier.
17 EXAMPLE 1 The call:
#include <stdio.h>
#include <wchar.h>
/* ... */
int n, i; float x; wchar_t name[50];
n = fwscanf(stdin, L"%d%f%ls", &i, &x, name);
with the input line:
25 54.32E-1 thompson
will assign to n the value 3, to i the value 25, to x the value 5.432, and to name the sequence thompson\0.
18 EXAMPLE 2 The call:
#include <stdio.h>
#include <wchar.h>
/* ... */
int i; float x; double y;
fwscanf(stdin, L"%2d%f%*d %lf", &i, &x, &y);
with input:
56789 0123 56a72
will assign to i the value 56 and to x the value 789.0, will skip past 0123, and will assign to y the value 56.0. The next wide
character read from the input stream will be a.
Forward references: the wcstod, wcstof, and wcstold functions (<IP_ADDRESS>.2), the wcstol, wcstoll,
wcstoul , and wcstoull functions (<IP_ADDRESS>.4), the wcrtomb function (<IP_ADDRESS>.3).
<IP_ADDRESS> [The swprintf function]
1 Synopsis
#include <wchar.h>
int swprintf(wchar_t * restrict s, size_t n, const wchar_t * restrict format,
...);
Description
2 The swprintf function is equivalent to fwprintf, except that the argument s specifies an array of
wide characters into which the generated output is to be written, rather than written to a stream.
No more than n wide characters are written, including a terminating null wide character, which is
always added (unless n is zero).
Returns
3 The swprintf function returns the number of wide characters written in the array, not counting the
terminating null wide character, or a negative value if an encoding error occurred or if n or more
wide characters were requested to be written.
<IP_ADDRESS> [The swscanf function]
1 Synopsis
#include <wchar.h>
int swscanf(const wchar_t * restrict s, const wchar_t * restrict format, ...);
Description
2 The swscanf function is equivalent to fwscanf, except that the argument s specifies a wide string
from which the input is to be obtained, rather than from a stream. Reaching the end of the wide
string is equivalent to encountering end-of-file for the fwscanf function.
Returns
3 The swscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the swscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The vfwprintf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
#include <wchar.h>
int vfwprintf(FILE * restrict stream, const wchar_t * restrict format,
va_list arg);
Description
2 The vfwprintf function is equivalent to fwprintf, with the variable argument list replaced by arg,
which shall have been initialized by the va_start macro (and possibly subsequent va_arg calls).
The vfwprintf function does not invoke the va_end macro[413] .
Returns
Footnote 413) As the functions vfwprintf , vswprintf , vfwscanf , vwprintf , vwscanf , and vswscanf invoke the va_arg macro, the
representation of arg after the return is indeterminate.
3 The vfwprintf function returns the number of wide characters transmitted, or a negative value if
an output or encoding error occurred.
4 EXAMPLE The following shows the use of the vfwprintf function in a general error-reporting routine.
#include <stdarg.h>
#include <stdio.h>
#include <wchar.h>
void error(char *function_name, wchar_t *format, ...)
{
va_list args;
va_start(args, format);
// print out name of function causing error
fwprintf(stderr, L"ERROR in %s: ", function_name);
// print out remainder of message
vfwprintf(stderr, format, args);
va_end(args);
}
<IP_ADDRESS> [The vfwscanf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
#include <wchar.h>
int vfwscanf(FILE * restrict stream, const wchar_t * restrict format,
va_list arg);
Description
2 The vfwscanf function is equivalent to fwscanf, with the variable argument list replaced by arg,
which shall have been initialized by the va_start macro (and possibly subsequent va_arg calls).
The vfwscanf function does not invoke the va_end macro.[413]
Returns
Footnote 413) As the functions vfwprintf , vswprintf , vfwscanf , vwprintf , vwscanf , and vswscanf invoke the va_arg macro, the
representation of arg after the return is indeterminate.
3 The vfwscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the vfwscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The vswprintf function]
1 Synopsis
#include <stdarg.h>
#include <wchar.h>
int vswprintf(wchar_t * restrict s, size_t n, const wchar_t * restrict format,
va_list arg);
Description
2 The vswprintf function is equivalent to swprintf, with the variable argument list replaced by arg,
which shall have been initialized by the va_start macro (and possibly subsequent va_arg calls).
The vswprintf function does not invoke the va_end macro.[413]
Returns
Footnote 413) As the functions vfwprintf , vswprintf , vfwscanf , vwprintf , vwscanf , and vswscanf invoke the va_arg macro, the
representation of arg after the return is indeterminate.
3 The vswprintf function returns the number of wide characters written in the array, not counting
the terminating null wide character, or a negative value if an encoding error occurred or if n or more
wide characters were requested to be generated.
<IP_ADDRESS> [The vswscanf function]
1 Synopsis
#include <stdarg.h>
#include <wchar.h>
int vswscanf(const wchar_t * restrict s, const wchar_t * restrict format,
va_list arg);
Description
2 The vswscanf function is equivalent to swscanf, with the variable argument list replaced by arg,
which shall have been initialized by the va_start macro (and possibly subsequent va_arg calls).
The vswscanf function does not invoke the va_end macro.[413]
Returns
Footnote 413) As the functions vfwprintf , vswprintf , vfwscanf , vwprintf , vwscanf , and vswscanf invoke the va_arg macro, the
representation of arg after the return is indeterminate.
3 The vswscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the vswscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The vwprintf function]
1 Synopsis
#include <stdarg.h>
#include <wchar.h>
int vwprintf(const wchar_t * restrict format, va_list arg);
Description
2 The vwprintf function is equivalent to wprintf, with the variable argument list replaced by arg,
which shall have been initialized by the va_start macro (and possibly subsequent va_arg calls).
The vwprintf function does not invoke the va_end macro.[413]
Returns
Footnote 413) As the functions vfwprintf , vswprintf , vfwscanf , vwprintf , vwscanf , and vswscanf invoke the va_arg macro, the
representation of arg after the return is indeterminate.
3 The vwprintf function returns the number of wide characters transmitted, or a negative value if an
output or encoding error occurred.
<IP_ADDRESS> [The vwscanf function]
1 Synopsis
#include <stdarg.h>
#include <wchar.h>
int vwscanf(const wchar_t * restrict format, va_list arg);
Description
2 The vwscanf function is equivalent to wscanf, with the variable argument list replaced by arg,
which shall have been initialized by the va_start macro (and possibly subsequent va_arg calls).
The vwscanf function does not invoke the va_end macro.[413]
Returns
Footnote 413) As the functions vfwprintf , vswprintf , vfwscanf , vwprintf , vwscanf , and vswscanf invoke the va_arg macro, the
representation of arg after the return is indeterminate.
3 The vwscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the vwscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The wprintf function]
1 Synopsis
#include <wchar.h>
int wprintf(const wchar_t * restrict format, ...);
Description
2 The wprintf function is equivalent to fwprintf with the argument stdout interposed before the
arguments to wprintf.
Returns
3 The wprintf function returns the number of wide characters transmitted, or a negative value if an
output or encoding error occurred.
<IP_ADDRESS> [The wscanf function]
1 Synopsis
#include <wchar.h>
int wscanf(const wchar_t * restrict format, ...);
Description
2 The wscanf function is equivalent to fwscanf with the argument stdin interposed before the
arguments to wscanf.
Returns
3 The wscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the wscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
7.31.3 [Wide character input/output functions]
<IP_ADDRESS> [The fgetwc function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
wint_t fgetwc(FILE *stream);
Description
2 If the end-of-file indicator for the input stream pointed to by stream is not set and a next wide
character is present, the fgetwc function obtains that wide character as a wchar_t converted to a
wint_t and advances the associated file position indicator for the stream (if defined).
Returns
3 If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-of-file
indicator for the stream is set and the fgetwc function returns WEOF. Otherwise, the fgetwc function
returns the next wide character from the input stream pointed to by stream. If a read error occurs,
the error indicator for the stream is set and the fgetwc function returns WEOF. If an encoding error
occurs (including too few bytes), the error indicator for the stream is set and the value of the macro
EILSEQ is stored in errno and the fgetwc function returns WEOF.[414]
Footnote 414) An end-of-file and a read error can be distinguished by use of the feof and ferror functions. Also, errno will be set to
EILSEQ by input/output functions only if an encoding error occurs.
<IP_ADDRESS> [The fgetws function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
wchar_t *fgetws(wchar_t * restrict s, int n, FILE * restrict stream);
Description
2 The fgetws function reads at most one less than the number of wide characters specified by n from
the stream pointed to by stream into the array pointed to by s. No additional wide characters are
read after a new-line wide character (which is retained) or after end-of-file. A null wide character is
written immediately after the last wide character read into the array.
Returns
3 The fgetws function returns s if successful. If end-of-file is encountered and no characters have
been read into the array, the contents of the array remain unchanged and a null pointer is returned.
If a read or encoding error occurs during the operation, the array members have an indeterminate
representation and a null pointer is returned.
<IP_ADDRESS> [The fputwc function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
wint_t fputwc(wchar_t c, FILE *stream);
Description
2 The fputwc function writes the wide character specified by c to the output stream pointed to by
stream, at the position indicated by the associated file position indicator for the stream (if defined),
and advances the indicator appropriately. If the file cannot support positioning requests, or if the
stream was opened with append mode, the character is appended to the output stream.
Returns
3 The fputwc function returns the wide character written. If a write error occurs, the error indicator
for the stream is set and fputwc returns WEOF. If an encoding error occurs, the value of the macro
EILSEQ is stored in errno and fputwc returns WEOF .
<IP_ADDRESS> [The fputws function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
int fputws(const wchar_t * restrict s, FILE * restrict stream);
Description
2 The fputws function writes the wide string pointed to by s to the stream pointed to by stream. The
terminating null wide character is not written.
Returns
3 The fputws function returns EOF if a write or encoding error occurs; otherwise, it returns a nonnega-
tive value.
<IP_ADDRESS> [The fwide function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
int fwide(FILE *stream, int mode);
Description
2 The fwide function determines the orientation of the stream pointed to by stream. If mode is greater
than zero, the function first attempts to make the stream wide oriented. If mode is less than zero,
the function first attempts to make the stream byte oriented.[415] Otherwise, mode is zero and the
function does not alter the orientation of the stream.
Returns
Footnote 415) If the orientation of the stream has already been determined, fwide does not change it.
3 The fwide function returns a value greater than zero if, after the call, the stream has wide orientation,
a value less than zero if the stream has byte orientation, or zero if the stream has no orientation.
<IP_ADDRESS> [The getwc function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
wint_t getwc(FILE *stream);
Description
2 The getwc function is equivalent to fgetwc, except that if it is implemented as a macro, it may
evaluate stream more than once, so the argument should never be an expression with side effects.
Returns
3 The getwc function returns the next wide character from the input stream pointed to by stream, or
WEOF .
<IP_ADDRESS> [The getwchar function]
1 Synopsis
#include <wchar.h>
wint_t getwchar(void);
Description
2 The getwchar function is equivalent to getwc with the argument stdin.
Returns
3 The getwchar function returns the next wide character from the input stream pointed to by stdin,
or WEOF.
<IP_ADDRESS> [The putwc function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
wint_t putwc(wchar_t c, FILE *stream);
Description
2 The putwc function is equivalent to fputwc, except that if it is implemented as a macro, it may
evaluate stream more than once, so that argument should never be an expression with side effects.
Returns
3 The putwc function returns the wide character written, or WEOF.
<IP_ADDRESS> [The putwchar function]
1 Synopsis
#include <wchar.h>
wint_t putwchar(wchar_t c);
Description
2 The putwchar function is equivalent to putwc with the second argument stdout.
Returns
3 The putwchar function returns the character written, or WEOF.
<IP_ADDRESS> [The ungetwc function]
1 Synopsis
#include <stdio.h>
#include <wchar.h>
wint_t ungetwc(wint_t c, FILE *stream);
Description
2 The ungetwc function pushes the wide character specified by c back onto the input stream pointed
to by stream. Pushed-back wide characters will be returned by subsequent reads on that stream
in the reverse order of their pushing. A successful intervening call (with the stream pointed to by
stream) to a file positioning function (fseek, fsetpos, or rewind) discards any pushed-back wide
characters for the stream. The external storage corresponding to the stream is unchanged.
3 One wide character of pushback is guaranteed, even if the call to the ungetwc function follows just
after a call to a formatted wide character input function fwscanf, vfwscanf, vwscanf, or wscanf. If
the ungetwc function is called too many times on the same stream without an intervening read or
file positioning operation on that stream, the operation may fail.
4 If the value of c equals that of the macro WEOF, the operation fails and the input stream is unchanged.
5 A successful call to the ungetwc function clears the end-of-file indicator for the stream. The value of
the file position indicator for the stream after reading or discarding all pushed-back wide characters
is the same as it was before the wide characters were pushed back.[416] For a text or binary stream,
the value of its file position indicator after a successful call to the ungetwc function is unspecified
until all pushed-back wide characters are read or discarded.
Returns
Footnote 416) Note that a file positioning function could further modify the file position indicator after discarding any pushed-back
wide characters.
6 The ungetwc function returns the wide character pushed back, or WEOF if the operation fails.
7.31.4 [General wide string utilities]
1 The header <wchar.h> declares a number of functions useful for wide string manipulation. Various
methods are used for determining the lengths of the arrays, but in all cases a wchar_t* argument
points to the initial (lowest addressed) element of the array. If an array is accessed beyond the end
of an object, the behavior is undefined.
2 Where an argument declared as size_t n determines the length of the array for a function, n can
have the value zero on a call to that function. Unless explicitly stated otherwise in the description of
a particular function in this subclause, pointer arguments on such a call shall still have valid values,
as described in 7.1.4. On such a call, a function that locates a wide character finds no occurrence, a
function that compares two wide character sequences returns zero, and a function that copies wide
characters copies zero wide characters.
<IP_ADDRESS> [Wide string numeric conversion functions]
<IP_ADDRESS>.1 [General]
This subclause describes wide string analogs of the strtod family of functions (<IP_ADDRESS>, <IP_ADDRESS>)417) .
<IP_ADDRESS>.2 [The wcstod, wcstof, and wcstold functions]
1 #include <wchar.h>
double wcstod(const wchar_t * restrict nptr, wchar_t ** restrict endptr);
float wcstof(const wchar_t * restrict nptr, wchar_t ** restrict endptr);
long double wcstold(const wchar_t * restrict nptr, wchar_t ** restrict endptr);
Description
The wcstod, wcstof, and wcstold functions convert the initial portion of the wide string pointed to
by nptr to double, float, and long double representation, respectively. First, they decompose the
input string into three parts: an initial, possibly empty, sequence of white-space wide characters, a
subject sequence resembling a floating constant or representing an infinity or NaN; and a final wide
string of one or more unrecognized wide characters, including the terminating null wide character
of the input wide string. Then, they attempt to convert the subject sequence to a floating-point
number, and return the result.
2 The expected form of the subject sequence is an optional plus or minus sign, then one of the
following:
— a nonempty sequence of decimal digits optionally containing a decimal-point wide character,
then an optional exponent part as defined for the corresponding single-byte characters in
<IP_ADDRESS>, excluding any digit separators (<IP_ADDRESS>);
— a 0x or 0X, then a nonempty sequence of hexadecimal digits optionally containing a decimal-
point wide character, then an optional binary exponent part as defined in <IP_ADDRESS>, excluding
any digit separators (<IP_ADDRESS>);
— INF or INFINITY, or any other wide string equivalent except for case
— NAN or NAN(n-wchar-sequenceopt ), or any other wide string equivalent except for case in the NAN
part, where:
n-wchar-sequence:
digit
nondigit
n-wchar-sequence digit
n-wchar-sequence nondigit
The subject sequence is defined as the longest initial subsequence of the input wide string, starting
with the first non-white-space wide character, that is of the expected form. The subject sequence
contains no wide characters if the input wide string is not of the expected form.
3 If the subject sequence has the expected form for a floating-point number, the sequence of wide
characters starting with the first digit or the decimal-point wide character (whichever occurs first) is
interpreted as a floating constant according to the rules of <IP_ADDRESS>, except that the decimal-point wide
character is used in place of a period, and that if neither an exponent part nor a decimal-point wide
character appears in a decimal floating-point number, or if a binary exponent part does not appear
in a hexadecimal floating-point number, an exponent part of the appropriate type with value zero is
assumed to follow the last digit in the string.
If the subject sequence begins with a minus sign, the sequence is interpreted as negated.[418]
A wide character sequence INF or INFINITY is interpreted as an infinity, if representable in the
return type, else like a floating constant that is too large for the range of the return type. A wide
character sequence NAN or NAN(n-wchar-sequenceopt ) is interpreted as a quiet NaN, if supported in
the return type, else like a subject sequence part that does not have the expected form; the meaning
of the n-wchar sequence is implementation-defined.[419]
A pointer to the final wide string is stored in the object pointed to by endptr, provided that endptr
is not a null pointer.
Footnote 418) It is unspecified whether a minus-signed sequence is converted to a negative number directly or by negating the value
resulting from converting the corresponding unsigned sequence (see F.5); the two methods could yield different results if
rounding is toward positive or negative infinity. In either case, the functions honor the sign of zero if floating-point arithmetic
supports signed zeros.
Footnote 419) An implementation can use the n-wchar sequence to determine extra information to be represented in the NaN’s
significand.
4 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the value resulting
from the conversion is correctly rounded.
5 In other than the "C" locale, additional locale-specific subject sequence forms may be accepted.
6 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.
Recommended practice
7 If the subject sequence has the hexadecimal form, FLT_RADIX is not a power of 2, and the result is
not exactly representable, the result should be one of the two numbers in the appropriate internal
format that are adjacent to the hexadecimal floating source value, with the extra stipulation that the
error should have a correct sign for the current rounding direction.
8 If the subject sequence has the decimal form and at most M significant digits, where M is the
maximum value of the T_DECIMAL_DIG macros (defined in <float.h>), the result should be correctly
rounded. If the subject sequence D has the decimal form and more than M significant digits, consider
the two bounding, adjacent decimal strings L and U, both having M significant digits, such that the
values of L, D, and U satisfy L ≤ D ≤ U. The result should be one of the (equal or adjacent) values
that would be obtained by correctly rounding L and U according to the current rounding direction,
with the extra stipulation that the error with respect to D should have a correct sign for the current
rounding direction.[420]
Returns
Footnote 420) M is sufficiently large that L and U will usually correctly round to the same internal floating value, but if not will correctly
round to adjacent values.
9 The functions return the converted value, if any. If no conversion could be performed, zero is
returned.
If the correct value overflows and default rounding is in effect (7.12.1), plus or minus HUGE_VAL,
HUGE_VALF, or HUGE_VALL is returned (according to the return type and sign of the value); if the
integer expression math_errhandling & MATH_ERRNO is nonzero, the integer expression errno
acquires the value of ERANGE; if the integer expression math_errhandling & MATH_ERREXCEPT is
nonzero, the "overflow" floating-point exception is raised.
If the result underflows (7.12.1), the functions return a value whose magnitude is no greater
than the smallest normalized positive number in the return type; if the integer expression
math_errhandling & MATH_ERRNO is nonzero, whether errno acquires the value ERANGE is
implementation-defined; if the integer expression math_errhandling & MATH_ERREXCEPT is
nonzero, whether the "underflow" floating-point exception is raised is implementation-defined.
<IP_ADDRESS>.3 [The wcstodN functions]
1 Synopsis
#include <wchar.h>
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 wcstod32(const wchar_t * restrict nptr, char ** restrict endptr);
_Decimal64 wcstod64(const wchar_t * restrict nptr,char ** restrict endptr);
_Decimal128 wcstod128(const wchar_t * restrict nptr,char ** restrict endptr);
#endif
Description
2 The wcstodN functions convert the initial portion of the wide string pointed to by nptr to decimal
floating type representation. First, they decompose the input wide string into three parts: an initial,
possibly empty, sequence of white-space wide characters; a subject sequence resembling a floating
constant or representing an infinity or NaN; and a final wide string of one or more unrecognized
wide characters, including the terminating null wide character of the input wide string. Then, they
attempt to convert the subject sequence to a floating-point number, and return the result.
3 The expected form of the subject sequence is an optional plus or minus sign, then one of the
following:
— a nonempty sequence of decimal digits optionally containing a decimal-point wide character,
then an optional exponent part as defined in <IP_ADDRESS>, excluding any digit separators (<IP_ADDRESS>)
— INF or INFINITY, ignoring case
— NAN or NAN(d-wchar-sequenceopt ), ignoring case in the NAN part, where: d-wchar-
sequence:
digit
nondigit
d-wchar-sequence digit
d-wchar-sequence nondigit
The subject sequence is defined as the longest initial subsequence of the input wide string, starting
with the first non-white-space wide character, that is of the expected form. The subject sequence
contains no wide characters if the input wide string is not of the expected form.
4 If the subject sequence has the expected form for a floating-point number, the sequence of wide
characters starting with the first digit or the decimal-point wide character (whichever occurs first) is
interpreted as a floating constant according to the rules of <IP_ADDRESS>, including correct rounding and
determination of the coefficient c and the quantum exponent q, with the following exceptions:
— It is not a hexadecimal floating number.
— The decimal-point wide character is used in place of a period.
— If neither an exponent part nor a decimal-point wide character appears in a decimal floating-
point number, an exponent part of the appropriate type with value zero is assumed to follow
the last digit in the wide string.
If the subject sequence begins with a minus sign, the sequence is interpreted as negated (before
rounding) and the sign s is set to −1, else s is set to 1. A wide character sequence INF or INFINITY is
interpreted as an infinity. A wide character sequence NAN or NAN(d-wchar-sequenceopt ), is interpreted
as a quiet NaN; the meaning of the d-wchar sequence is implementation-defined.[421] A pointer to
the final wide string is stored in the object pointed to by endptr, provided that endptr is not a null
pointer.
Footnote 421) An implementation may use the d-wchar sequence to determine extra information to be represented in the NaN’s
significand.
5 In other than the "C" locale, additional locale-specific subject sequence forms may be accepted.
6 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.
Returns
7 The wcstodN functions return the correctly rounded converted value, if any. If no conversion could
be performed, the value of the triple (+1, 0, 0) is returned. If the correct value overflows:
— the value of the macro ERANGE is stored in errno if the integer expression
math_errhandling & MATH_ERRNO is nonzero;
— the "overflow" floating-point exception is raised if the integer expression
math_errhandling & MATH_ERREXCEPT is nonzero.
If the result underflows (7.12.1), whether errno acquires the value ERANGE if the integer expression
math_errhandling & MATH_ERRNO is nonzero is implementation-defined; if the integer expres-
sion math_errhandling & MATH_ERREXCEPT is nonzero, whether the "underflow" floating-point
exception is raised is implementation-defined.
<IP_ADDRESS>.4 [The wcstol, wcstoll, wcstoul, and wcstoull functions]
1 Synopsis
#include <wchar.h>
long int wcstol(const wchar_t * restrict nptr, wchar_t ** restrict endptr,
int base);
long long int wcstoll(const wchar_t * restrict nptr, wchar_t ** restrict endptr,
int base);
unsigned long int wcstoul(const wchar_t * restrict nptr,
wchar_t ** restrict endptr, int base);
unsigned long long int wcstoull(const wchar_t * restrict nptr,
wchar_t ** restrict endptr, int base);
Description
2 The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial portion of the
wide string pointed to by nptr to long int, long long int, unsigned long int, and
unsigned long long int representation, respectively. First, they decompose the input string into
three parts: an initial, possibly empty, sequence of white-space wide characters, a subject sequence
resembling an integer represented in some radix determined by the value of base, and a final wide
string of one or more unrecognized wide characters, including the terminating null wide character
of the input wide string. Then, they attempt to convert the subject sequence to an integer, and return
the result.
3 If the value of base is zero, the expected form of the subject sequence is that of an integer constant
as described for the corresponding single-byte characters in <IP_ADDRESS>, optionally preceded by a plus or
minus sign, but not including an integer suffix or any optional digit separators (<IP_ADDRESS>). If the value
of base is between 2 and 36 (inclusive), 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
plus or minus sign, but not including an integer suffix or any optional digit separators. The letters
from a (or A) through z (or Z) are ascribed the values 10 through 35; only letters and digits whose
ascribed values are less than that of base are permitted. If the value of base is 2, the characters 0b or
0B may optionally precede the sequence of letters and digits, following the sign if present. If the
value of base is 16, the wide characters 0x or 0X may optionally precede the sequence of letters and
digits, following the sign if present.
4 The subject sequence is defined as the longest initial subsequence of the input wide string, starting
with the first non-white-space wide character, that is of the expected form. The subject sequence
contains no wide characters if the input wide string is empty or consists entirely of white-space
wide characters, or if the first non-white-space wide character is other than a sign or a permissible
letter or digit.
5 If the subject sequence has the expected form and the value of base is zero, the sequence of wide
characters starting with the first digit is interpreted as an integer constant according to the rules
of <IP_ADDRESS>. 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 (in the return
type). A pointer to the final wide string is stored in the object pointed to by endptr, provided that
endptr is not a null pointer.
6 In other than the "C" locale, additional locale-specific subject sequence forms may be accepted.
7 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.
Returns
8 The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted value, if any. If
no conversion could be performed, zero is returned. If the correct value is outside the range of
representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX, ULONG_MAX, or ULLONG_MAX is
returned (according to the return type sign of the value, if any), and the value of the macro ERANGE
is stored in errno.
<IP_ADDRESS> [Wide string copying functions]
<IP_ADDRESS>.1 [The wcscpy function]
1 Synopsis
#include <wchar.h>
wchar_t *wcscpy(wchar_t * restrict s1, const wchar_t * restrict s2);
Description
2 The wcscpy function copies the wide string pointed to by s2 (including the terminating null wide
character) into the array pointed to by s1.
Returns
3 The wcscpy function returns the value of s1.
<IP_ADDRESS>.2 [The wcsncpy function]
1 Synopsis
#include <wchar.h>
wchar_t *wcsncpy(wchar_t * restrict s1, const wchar_t * restrict s2, size_t n);
Description
2 The wcsncpy function copies not more than n wide characters (those that follow a null wide character
are not copied) from the array pointed to by s2 to the array pointed to by s1.[422]
Footnote 422) Thus, if there is no null wide character in the first n wide characters of the array pointed to by s2, the result will not be
null-terminated.
3 If the array pointed to by s2 is a wide string that is shorter than n wide characters, null wide
characters are appended to the copy in the array pointed to by s1, until n wide characters in all have
been written.
Returns
4 The wcsncpy function returns the value of s1.
<IP_ADDRESS>.3 [The wmemcpy function]
1 Synopsis
#include <wchar.h>
wchar_t *wmemcpy(wchar_t * restrict s1, const wchar_t * restrict s2, size_t n);
Description
2 The wmemcpy function copies n wide characters from the object pointed to by s2 to the object pointed
to by s1.
Returns
3 The wmemcpy function returns the value of s1.
<IP_ADDRESS>.4 [The wmemmove function]
1 Synopsis
#include <wchar.h>
wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);
Description
2 The wmemmove function copies n wide characters from the object pointed to by s2 to the object
pointed to by s1. Copying takes place as if the n wide characters from the object pointed to by s2
are first copied into a temporary array of n wide characters that does not overlap the objects pointed
to by s1 or s2, and then the n wide characters from the temporary array are copied into the object
pointed to by s1.
Returns
3 The wmemmove function returns the value of s1.
<IP_ADDRESS> [Wide string concatenation functions]
<IP_ADDRESS>.1 [The wcscat function]
1 Synopsis
#include <wchar.h>
wchar_t *wcscat(wchar_t * restrict s1, const wchar_t * restrict s2);
Description
2 The wcscat function appends a copy of the wide string pointed to by s2 (including the terminating
null wide character) to the end of the wide string pointed to by s1. The initial wide character of s2
overwrites the null wide character at the end of s1.
Returns
3 The wcscat function returns the value of s1.
<IP_ADDRESS>.2 [The wcsncat function]
1 Synopsis
#include <wchar.h>
wchar_t *wcsncat(wchar_t * restrict s1, const wchar_t * restrict s2, size_t n);
Description
2 The wcsncat function appends not more than n wide characters (a null wide character and those
that follow it are not appended) from the array pointed to by s2 to the end of the wide string pointed
to by s1. The initial wide character of s2 overwrites the null wide character at the end of s1. A
terminating null wide character is always appended to the result.[423]
Returns
Footnote 423) Thus, the maximum number of wide characters that can end up in the array pointed to by s1 is wcslen(s1)+n+1 .
3 The wcsncat function returns the value of s1.
<IP_ADDRESS> [Wide string comparison functions]
1 Unless explicitly stated otherwise, the functions described in this subclause order two wide charac-
ters the same way as two integers of the underlying integer type designated by wchar_t.
<IP_ADDRESS>.1 [The wcscmp function]
1 Synopsis
#include <wchar.h>
int wcscmp(const wchar_t *s1, const wchar_t *s2);
Description
2 The wcscmp function compares the wide string pointed to by s1 to the wide string pointed to by s2.
Returns
3 The wcscmp function returns an integer greater than, equal to, or less than zero, accordingly as the
wide string pointed to by s1 is greater than, equal to, or less than the wide string pointed to by s2.
<IP_ADDRESS>.2 [The wcscoll function]
1 Synopsis
#include <wchar.h>
int wcscoll(const wchar_t *s1, const wchar_t *s2);
Description
2 The wcscoll function compares the wide string pointed to by s1 to the wide string pointed to by
s2, both interpreted as appropriate to the LC_COLLATE category of the current locale.
Returns
3 The wcscoll function returns an integer greater than, equal to, or less than zero, accordingly as the
wide string pointed to by s1 is greater than, equal to, or less than the wide string pointed to by s2
when both are interpreted as appropriate to the current locale.
<IP_ADDRESS>.3 [The wcsncmp function]
1 Synopsis
#include <wchar.h>
int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);
Description
2 The wcsncmp function compares not more than n wide characters (those that follow a null wide
character are not compared) from the array pointed to by s1 to the array pointed to by s2.
Returns
3 The wcsncmp function returns an integer greater than, equal to, or less than zero, accordingly as the
possibly null-terminated array pointed to by s1 is greater than, equal to, or less than the possibly
null-terminated array pointed to by s2.
<IP_ADDRESS>.4 [The wcsxfrm function]
1 Synopsis
#include <wchar.h>
size_t wcsxfrm(wchar_t * restrict s1, const wchar_t * restrict s2, size_t n);
Description
2 The wcsxfrm function transforms the wide string pointed to by s2 and places the resulting wide
string into the array pointed to by s1. The transformation is such that if the wcscmp function is
applied to two transformed wide strings, it returns a value greater than, equal to, or less than zero,
corresponding to the result of the wcscoll function applied to the same two original wide strings.
No more than n wide characters are placed into the resulting array pointed to by s1, including the
terminating null wide character. If n is zero, s1 is permitted to be a null pointer.
Returns
3 The wcsxfrm function returns the length of the transformed wide string (not including the terminat-
ing null wide character). If the value returned is n or greater, the members of the array pointed to by
s1 have an indeterminate representation.
4 EXAMPLE The value of the following expression is the length of the array needed to hold the transformation of the wide
string pointed to by s:
1 + wcsxfrm(NULL, s, 0)
<IP_ADDRESS>.5 [The wmemcmp function]
1 Synopsis
#include <wchar.h>
int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);
Description
2 The wmemcmp function compares the first n wide characters of the object pointed to by s1 to the first
n wide characters of the object pointed to by s2.
Returns
3 The wmemcmp function returns an integer greater than, equal to, or less than zero, accordingly as the
object pointed to by s1 is greater than, equal to, or less than the object pointed to by s2.
<IP_ADDRESS> [Wide string search functions]
<IP_ADDRESS> [Introduction]
1 The stateless search functions in this section (wcschr, wcspbrk, wcsrchr, wmemchr, wcsstr) are
generic functions. These functions are generic in the qualification of the array to be searched and
will return a result pointer to an element with the same qualification as the passed array. If the array
to be searched is const-qualified, the result pointer will be to a const-qualified element. If the array
to be searched is not const-qualified[424] , the result pointer will be to an unqualified element.
Footnote 424) The null pointer constant is not a pointer to a const-qualified type, and therefore the result expression has the type of a
pointer to an unqualified element; however, evaluating such a call is undefined.
2 The external declarations of these generic functions have a concrete function type that returns a
pointer to an unqualified element of type wchar_t (named QWchar_t), and accepts a pointer to a
const-qualified array of the same type to search. This signature supports all correct uses. If a macro
definition of any of these generic functions is suppressed in order to access an actual function, the
external declaration with this concrete type is visible[425] .
Footnote 425) This is an obsolescent feature.
3 The volatile and restrict qualifiers are not accepted on the elements of the array to search.
<IP_ADDRESS>.1 [The wcschr generic function]
1 Synopsis
#include <wchar.h>
QWchar_t *wcschr(QWchar_t *s, wchar_t c);
Description
2 The wcschr generic function locates the first occurrence of c in the wide string pointed to by s. The
terminating null wide character is considered to be part of the wide string.
Returns
3 The wcschr generic function returns a pointer to the located wide character, or a null pointer if the
wide character does not occur in the wide string.
<IP_ADDRESS>.2 [The wcscspn function]
1 Synopsis
#include <wchar.h>
size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
Description
2 The wcscspn function computes the length of the maximum initial segment of the wide string
pointed to by s1 which consists entirely of wide characters not from the wide string pointed to by
s2.
Returns
3 The wcscspn function returns the length of the segment.
<IP_ADDRESS>.3 [The wcspbrk generic function]
1 Synopsis
#include <wchar.h>
QWchar_t *wcspbrk(QWchar_t *s1, const wchar_t *s2);
Description
2 The wcspbrk generic function locates the first occurrence in the wide string pointed to by s1 of any
wide character from the wide string pointed to by s2.
Returns
3 The wcspbrk generic function returns a pointer to the wide character in s1, or a null pointer if no
wide character from s2 occurs in s1.
<IP_ADDRESS>.4 [The wcsrchr generic function]
1 Synopsis
#include <wchar.h>
QWchar_t *wcsrchr(const wchar_t *s, wchar_t c);
Description
2 The wcsrchr generic function locates the last occurrence of c in the wide string pointed to by s. The
terminating null wide character is considered to be part of the wide string.
Returns
3 The wcsrchr generic function returns a pointer to the wide character, or a null pointer if c does not
occur in the wide string.
<IP_ADDRESS>.5 [The wcsspn function]
1 Synopsis
#include <wchar.h>
size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
Description
2 The wcsspn function computes the length of the maximum initial segment of the wide string pointed
to by s1 which consists entirely of wide characters from the wide string pointed to by s2.
Returns
3 The wcsspn function returns the length of the segment.
<IP_ADDRESS>.6 [The wcsstr generic function]
1 Synopsis
#include <wchar.h>
QWchar_t *wcsstr(QWchar_t *s1, const wchar_t *s2);
Description
2 The wcsstr generic function locates the first occurrence in the wide string pointed to by s1 of the
sequence of wide characters (excluding the terminating null wide character) in the wide string
pointed to by s2.
Returns
3 The wcsstr generic function returns a pointer to the located wide string, or a null pointer if the
wide string is not found. If s2 points to a wide string with zero length, the function returns s1.
<IP_ADDRESS>.7 [The wcstok function]
1 Synopsis
#include <wchar.h>
wchar_t *wcstok(wchar_t * restrict s1, const wchar_t * restrict s2,
wchar_t ** restrict ptr);
Description
2 A sequence of calls to the wcstok function breaks the wide string pointed to by s1 into a sequence
of tokens, each of which is delimited by a wide character from the wide string pointed to by s2. The
third argument points to a caller-provided wchar_t pointer into which the wcstok function stores
information necessary for it to continue scanning the same wide string.
3 The first call in a sequence has a non-null first argument and stores an initial value in the object
pointed to by ptr. Subsequent calls in the sequence have a null first argument and the object pointed
to by ptr is required to have the value stored by the previous call in the sequence, which is then
updated. The separator wide string pointed to by s2 may be different from call to call.
4 The first call in the sequence searches the wide string pointed to by s1 for the first wide character
that is not contained in the current separator wide string pointed to by s2. If no such wide character
is found, then there are no tokens in the wide string pointed to by s1 and the wcstok function
returns a null pointer. If such a wide character is found, it is the start of the first token.
5 The wcstok function then searches from there for a wide character that is contained in the current
separator wide string. If no such wide character is found, the current token extends to the end of the
wide string pointed to by s1, and subsequent searches in the same wide string for a token return
a null pointer. If such a wide character is found, it is overwritten by a null wide character, which
terminates the current token.
6 In all cases, the wcstok function stores sufficient information in the pointer pointed to by ptr so
that subsequent calls, with a null pointer for s1 and the unmodified pointer value for ptr, shall start
searching just past the element overwritten by a null wide character (if any).
Returns
7 The wcstok function returns a pointer to the first wide character of a token, or a null pointer if there
is no token.
8 EXAMPLE
#include <wchar.h>
static wchar_t str1[] = L"?a???b,,,#c";
static wchar_t str2[] = L"\t \t";
wchar_t *t, *ptr1, *ptr2;
t = wcstok(str1, L"?", &ptr1); // t points to the token L"a"
t = wcstok(NULL, L",", &ptr1); // t points to the token L"??b"
t = wcstok(str2, L" \t", &ptr2); // t is a null pointer
t = wcstok(NULL, L"#,", &ptr1); // t points to the token L"c"
t = wcstok(NULL, L"?", &ptr1); // t is a null pointer
<IP_ADDRESS>.8 [The wmemchr generic function]
1 Synopsis
#include <wchar.h>
QWchar_t *wmemchr(QWchar_t *s, wchar_t c, size_t n);
Description
2 The wmemchr generic function locates the first occurrence of c in the initial n wide characters of the
object pointed to by s.
Returns
3 The wmemchr generic function returns a pointer to the located wide character, or a null pointer if the
wide character does not occur in the object.
<IP_ADDRESS> [Miscellaneous functions]
<IP_ADDRESS>.1 [The wcslen function]
1 Synopsis
#include <wchar.h>
size_t wcslen(const wchar_t *s);
Description
2 The wcslen function computes the length of the wide string pointed to by s.
Returns
3 The wcslen function returns the number of wide characters that precede the terminating null wide
character.
<IP_ADDRESS>.2 [The wmemset function]
1 Synopsis
#include <wchar.h>
wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
Description
2 The wmemset function copies the value of c into each of the first n wide characters of the object
pointed to by s.
Returns
3 The wmemset function returns the value of s.
7.31.5 [Wide character time conversion functions]
<IP_ADDRESS> [The wcsftime function]
1 Synopsis
#include <time.h>
#include <wchar.h>
size_t wcsftime(wchar_t * restrict s, size_t maxsize,
const wchar_t * restrict format, const struct tm * restrict timeptr);
Description
2 The wcsftime function is equivalent to the strftime function, except that:
— The argument s points to the initial element of an array of wide characters into which the
generated output is to be placed.
— The argument maxsize indicates the limiting number of wide characters.
— The argument format is a wide string and the conversion specifiers are replaced by corre-
sponding sequences of wide characters.
— The return value indicates the number of wide characters.
Returns
3 If the total number of resulting wide characters including the terminating null wide character is not
more than maxsize, the wcsftime function returns the number of wide characters placed into the
array pointed to by s not including the terminating null wide character. Otherwise, zero is returned
and the members of the array have an indeterminate representation.
7.31.6 [Extended multibyte/wide character conversion utilities]
1 The header <wchar.h> declares an extended set of functions useful for conversion between multibyte
characters and wide characters.
2 Most of the following functions — those that are listed as "restartable", <IP_ADDRESS> and <IP_ADDRESS> — take
as a last argument a pointer to an object of type mbstate_t that is used to describe the current
conversion state from a particular multibyte character sequence to a wide character sequence (or the
reverse) under the rules of a particular setting for the LC_CTYPE category of the current locale.
3 The initial conversion state corresponds, for a conversion in either direction, to the beginning of a
new multibyte character in the initial shift state. A zero-valued mbstate_t object is (at least) one
way to describe an initial conversion state. A zero-valued mbstate_t object can be used to initiate
conversion involving any multibyte character sequence, in any LC_CTYPE category setting. If an
mbstate_t object has been altered by any of the functions described in this subclause, and is then
used with a different multibyte character sequence, or in the other conversion direction, or with a
different LC_CTYPE category setting than on earlier function calls, the behavior is undefined.[426]
Footnote 426) Thus, a particular mbstate_t object can be used, for example, with both the mbrtowc and mbsrtowcs functions as long
as they are used to step sequentially through the same multibyte character string.
4 On entry, each function takes the described conversion state (either internal or pointed to by an
argument) as current. The conversion state described by the referenced object is altered as needed
to track the shift state, and the position within a multibyte character, for the associated multibyte
character sequence.
<IP_ADDRESS> [Single-byte/wide character conversion functions]
<IP_ADDRESS>.1 [The btowc function]
1 Synopsis
#include <wchar.h>
wint_t btowc(int c);
Description
2 The btowc function determines whether c constitutes a valid single-byte character in the initial shift
state.
Returns
3 The btowc function returns WEOF if c has the value EOF or if (unsigned char)c does not constitute
a valid single-byte character in the initial shift state. Otherwise, it returns the wide character
representation of that character.
<IP_ADDRESS>.2 [The wctob function]
1 Synopsis
#include <wchar.h>
int wctob(wint_t c);
Description
2 The wctob function determines whether c corresponds to a member of the extended character set
whose multibyte character representation is a single byte when in the initial shift state.
Returns
3 The wctob function returns EOF if c does not correspond to a multibyte character with length one
in the initial shift state. Otherwise, it returns the single-byte representation of that character as an
unsigned char converted to an int.
<IP_ADDRESS> [Conversion state functions]
<IP_ADDRESS>.1 [The mbsinit function]
1 Synopsis
#include <wchar.h>
int mbsinit(const mbstate_t *ps);
Description
2 If ps is not a null pointer, the mbsinit function determines whether the referenced mbstate_t object
describes an initial conversion state.
Returns
3 The mbsinit function returns nonzero if ps is a null pointer or if the referenced object describes an
initial conversion state; otherwise, it returns zero.
<IP_ADDRESS> [Restartable multibyte/wide character conversion functions]
1 These functions differ from the corresponding multibyte character functions of 7.24.7 (mblen, mbtowc,
and wctomb) in that they have an extra parameter, ps, of type pointer to mbstate_t that points
to an object that can completely describe the current conversion state of the associated multibyte
character sequence. If ps is a null pointer, each function uses its own internal mbstate_t object
instead, which is initialized prior to the first call to the function to the initial conversion state; the
functions are not required to avoid data races with other calls to the same function in this case. It
is implementation-defined whether the internal mbstate_t object has thread storage duration; if
it has thread storage duration, it is initialized to the initial conversion state prior to the first call to
the function on the new thread. The implementation behaves as if no library function calls these
functions with a null pointer for ps.
2 Also unlike their corresponding functions, the return value does not represent whether the encoding
is state-dependent.
<IP_ADDRESS>.1 [The mbrlen function]
1 Synopsis
#include <wchar.h>
size_t mbrlen(const char * restrict s, size_t n, mbstate_t * restrict ps);
Description
2 The mbrlen function is equivalent to the call:
mbrtowc(NULL, s, n, ps != NULL ? ps: &internal)
where internal is the mbstate_t object for the mbrlen function, except that the expression desig-
nated by ps is evaluated only once.
Returns
3 The mbrlen function returns a value between zero and n, inclusive, (size_t) (−2), or (size_t) (−1).
Forward references: the mbrtowc function (<IP_ADDRESS>.2).
<IP_ADDRESS>.2 [The mbrtowc function]
1 Synopsis
#include <wchar.h>
size_t mbrtowc(wchar_t * restrict pwc, const char * restrict s, size_t n,
mbstate_t * restrict ps);
Description
2 If s is a null pointer, the mbrtowc function is equivalent to the call:
mbrtowc(NULL, "", 1, ps)
In this case, the values of the parameters pwc and n are ignored.
3 If s is not a null pointer, the mbrtowc function inspects at most n bytes beginning with the byte
pointed to by s to determine the number of bytes needed to complete the next multibyte character
(including any shift sequences). If the function determines that the next multibyte character is
complete and valid, it determines the value of the corresponding wide character and then, if pwc
is not a null pointer, stores that value in the object pointed to by pwc. If the corresponding wide
character is the null wide character, the resulting state described is the initial conversion state.
Returns
4 The mbrtowc function returns the first of the following that applies (given the current conversion
state):
0 if the next n or fewer bytes complete the multibyte character that corresponds to
the null wide character (which is the value stored).
between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte character (which
is the value stored); the value returned is the number of bytes that complete the
multibyte character.
(size_t) (−2) if the next n bytes contribute to an incomplete (but potentially valid) multibyte
character, and all n bytes have been processed (no value is stored).[427]
(size_t)(-1) if an encoding error occurs, in which case the next n or fewer bytes do not contribute
to a complete and valid multibyte character (no value is stored); the value of the
macro EILSEQ is stored in errno, and the conversion state is unspecified.
Footnote 427) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a sequence of redundant
shift sequences (for implementations with state-dependent encodings).
<IP_ADDRESS>.3 [The wcrtomb function]
1 Synopsis
#include <wchar.h>
size_t wcrtomb(char * restrict s, wchar_t wc, mbstate_t * restrict ps);
Description
2 If s is a null pointer, the wcrtomb function is equivalent to the call
wcrtomb(buf, L’\0’, ps)
where buf is an internal buffer.
3 If s is not a null pointer, the wcrtomb function determines the number of bytes needed to represent
the multibyte character that corresponds to the wide character given by wc (including any shift
sequences), and stores the multibyte character representation in the array whose first element is
pointed to by s. At most MB_CUR_MAX bytes are stored. If wc is a null wide character, a null byte is
stored, preceded by any shift sequence needed to restore the initial shift state; the resulting state
described is the initial conversion state.
Returns
4 The wcrtomb function returns the number of bytes stored in the array object (including any shift
sequences). When wc is not a valid wide character, an encoding error occurs: the function stores the
value of the macro EILSEQ in errno and returns (size_t) (−1); the conversion state is unspecified.
<IP_ADDRESS> [Restartable multibyte/wide string conversion functions]
1 These functions differ from the corresponding multibyte string functions of 7.24.8 (mbstowcs and
wcstombs) in that they have an extra parameter, ps, of type pointer to mbstate_t that points to
an object that can completely describe the current conversion state of the associated multibyte
character sequence. If ps is a null pointer, each function uses its own internal mbstate_t object
instead, which is initialized prior to the first call to the function to the initial conversion state; the
functions are not required to avoid data races with other calls to the same function in this case. It
is implementation-defined whether the internal mbstate_t object has thread storage duration; if
it has thread storage duration, it is initialized to the initial conversion state prior to the first call to
the function on the new thread. The implementation behaves as if no library function calls these
functions with a null pointer for ps.
2 Also unlike their corresponding functions, the conversion source parameter, src, has a pointer-to-
pointer type. When the function is storing the results of conversions (that is, when dst is not a null
pointer), the pointer object pointed to by this parameter is updated to reflect the amount of the
source processed by that invocation.
<IP_ADDRESS>.1 [The mbsrtowcs function]
1 Synopsis
#include <wchar.h>
size_t mbsrtowcs(wchar_t * restrict dst, const char ** restrict src, size_t len,
mbstate_t * restrict ps);
Description
2 The mbsrtowcs function converts a sequence of multibyte characters that begins in the conversion
state described by the object pointed to by ps, from the array indirectly pointed to by src into a
sequence of corresponding wide characters. If dst is not a null pointer, the converted characters are
stored into the array pointed to by dst. Conversion continues up to and including a terminating
null character, which is also stored. Conversion stops earlier in two cases: when a sequence of bytes
is encountered that does not form a valid multibyte character, or (if dst is not a null pointer) when
len wide characters have been stored into the array pointed to by dst.[428] Each conversion takes
place as if by a call to the mbrtowc function.
Footnote 428) Thus, the value of len is ignored if dst is a null pointer.
3 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if
conversion stopped due to reaching a terminating null character) or the address just past the last
multibyte character converted (if any). If conversion stopped due to reaching a terminating null
character and if dst is not a null pointer, the resulting state described is the initial conversion state.
Returns
4 If the input conversion encounters a sequence of bytes that do not form a valid multibyte character,
an encoding error occurs: the mbsrtowcs function stores the value of the macro EILSEQ in errno
and returns (size_t)(-1) ; the conversion state is unspecified. Otherwise, it returns the number of
multibyte characters successfully converted, not including the terminating null character (if any).
<IP_ADDRESS>.2 [The wcsrtombs function]
1 Synopsis
#include <wchar.h>
size_t wcsrtombs(char * restrict dst, const wchar_t ** restrict src, size_t len,
mbstate_t * restrict ps);
Description
2 The wcsrtombs function converts a sequence of wide characters from the array indirectly pointed to
by src into a sequence of corresponding multibyte characters that begins in the conversion state
described by the object pointed to by ps. If dst is not a null pointer, the converted characters are then
stored into the array pointed to by dst. Conversion continues up to and including a terminating null
wide character, which is also stored. Conversion stops earlier in two cases: when a wide character
is reached that does not correspond to a valid multibyte character, or (if dst is not a null pointer)
when the next multibyte character would exceed the limit of len total bytes to be stored into the
array pointed to by dst. Each conversion takes place as if by a call to the wcrtomb function.[429]
Footnote 429) If conversion stops because a terminating null wide character has been reached, the bytes stored include those necessary
to reach the initial shift state immediately before the null byte.
3 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if
conversion stopped due to reaching a terminating null wide character) or the address just past the
last wide character converted (if any). If conversion stopped due to reaching a terminating null wide
character, the resulting state described is the initial conversion state.
Returns
4 If conversion stops because a wide character is reached that does not correspond to a valid multibyte
character, an encoding error occurs: the wcsrtombs function stores the value of the macro EILSEQ
in errno and returns (size_t) (−1); the conversion state is unspecified. Otherwise, it returns the
number of bytes in the resulting multibyte character sequence, not including the terminating null
character (if any).
7.32 [Wide character classification and mapping utilities <wctype.h>]
7.32.1 [Introduction]
1 The header <wctype.h> defines one macro, and declares three data types and many functions.[430]
Footnote 430) See "future library directions" (7.33.21).
2 The types declared are wint_t described in 7.31.1;
wctrans_t
which is a scalar type that can hold values which represent locale-specific character mappings; and
wctype_t
which is a scalar type that can hold values which represent locale-specific character classifications.
3 The macro defined is WEOF (described in 7.31.1).
4 The functions declared are grouped as follows:
— Functions that provide wide character classification;
— Extensible functions that provide wide character classification;
— Functions that provide wide character case mapping;
— Extensible functions that provide wide character mapping.
5 For all functions described in this subclause that accept an argument of type wint_t, the value shall
be representable as a wchar_t or shall equal the value of the macro WEOF. If this argument has any
other value, the behavior is undefined.
6 The behavior of these functions is affected by the LC_CTYPE category of the current locale.
7.32.2 [Wide character classification utilities]
1 The header <wctype.h> declares several functions useful for classifying wide characters.
2 The term printing wide character refers to a member of a locale-specific set of wide characters, each of
which occupies at least one printing position on a display device. The term control wide character
refers to a member of a locale-specific set of wide characters that are not printing wide characters.
<IP_ADDRESS> [Wide character classification functions]
1 The functions in this subclause return nonzero (true) if and only if the value of the argument wc
conforms to that in the description of the function.
2 Each of the following functions returns true for each wide character that corresponds (as if by a call
to the wctob function) to a single-byte character for which the corresponding character classification
function from 7.4.1 returns true, except that the iswgraph and iswpunct functions may differ with
respect to wide characters other than L’ ’ that are both printing and white-space wide characters.[431]
Forward references: the wctob function (<IP_ADDRESS>.2).
Footnote 431) For example, if the expression isalpha(wctob(wc)) evaluates to true, then the call iswalpha(wc) also returns true.
But, if the expression isgraph(wctob(wc)) evaluates to true (which cannot occur for wc == L’’ of course), then either
iswgraph(wc) or iswprint(wc)&& iswspace(wc) is true, but not both.
<IP_ADDRESS>.1 [The iswalnum function]
1 Synopsis
#include <wctype.h>
int iswalnum(wint_t wc);
Description
2 The iswalnum function tests for any wide character for which iswalpha or iswdigit is true.
<IP_ADDRESS>.2 [The iswalpha function]
1 Synopsis
#include <wctype.h>
int iswalpha(wint_t wc);
Description
2 The iswalpha function tests for any wide character for which iswupper or iswlower is true, or any
wide character that is one of a locale-specific set of alphabetic wide characters for which none of
iswcntrl, iswdigit, iswpunct, or iswspace is true.[432]
Footnote 432) The functions iswlower and iswupper test true or false separately for each of these additional wide characters; all four
combinations are possible.
<IP_ADDRESS>.3 [The iswblank function]
1 Synopsis
#include <wctype.h>
int iswblank(wint_t wc);
Description
2 The iswblank function tests for any wide character that is a standard blank wide character or is one
of a locale-specific set of wide characters for which iswspace is true and that is used to separate
words within a line of text. The standard blank wide characters are the following: space (L’ ’),
and horizontal tab (L’\t’). In the "C" locale, iswblank returns true only for the standard blank
characters.
<IP_ADDRESS>.4 [The iswcntrl function]
1 Synopsis
#include <wctype.h>
int iswcntrl(wint_t wc);
Description
2 The iswcntrl function tests for any control wide character.
<IP_ADDRESS>.5 [The iswdigit function]
1 Synopsis
#include <wctype.h>
int iswdigit(wint_t wc);
Description
2 The iswdigit function tests for any wide character that corresponds to a decimal-digit character (as
defined in 5.2.1).
<IP_ADDRESS>.6 [The iswgraph function]
1 Synopsis
#include <wctype.h>
int iswgraph(wint_t wc);
Description
2 The iswgraph function tests for any wide character for which iswprint is true and iswspace is
false.[433]
Footnote 433) Note that the behavior of the iswgraph and iswpunct functions can differ from their corresponding functions in 7.4.1
with respect to printing, white-space, single-byte execution characters other than ’ ’ .
<IP_ADDRESS>.7 [The iswlower function]
1 Synopsis
#include <wctype.h>
int iswlower(wint_t wc);
Description
2 The iswlower function tests for any wide character that corresponds to a lowercase letter or is one
of a locale-specific set of wide characters for which none of iswcntrl, iswdigit, iswpunct, or
iswspace is true.
<IP_ADDRESS>.8 [The iswprint function]
1 Synopsis
#include <wctype.h>
int iswprint(wint_t wc);
Description
2 The iswprint function tests for any printing wide character.
<IP_ADDRESS>.9 [The iswpunct function]
1 Synopsis
#include <wctype.h>
int iswpunct(wint_t wc);
Description
2 The iswpunct function tests for any printing wide character that is one of a locale-specific set of
punctuation wide characters for which neither iswspace nor iswalnum is true.[433]
Footnote 433) Note that the behavior of the iswgraph and iswpunct functions can differ from their corresponding functions in 7.4.1
with respect to printing, white-space, single-byte execution characters other than ’ ’ .
<IP_ADDRESS>.10 [The iswspace function]
1 Synopsis
#include <wctype.h>
int iswspace(wint_t wc);
Description
2 The iswspace function tests for any wide character that corresponds to a locale-specific set of
white-space wide characters for which none of iswalnum, iswgraph, or iswpunct is true.
<IP_ADDRESS>.11 [The iswupper function]
1 Synopsis
#include <wctype.h>
int iswupper(wint_t wc);
Description
2 The iswupper function tests for any wide character that corresponds to an uppercase letter or is
one of a locale-specific set of wide characters for which none of iswcntrl, iswdigit, iswpunct, or
iswspace is true.
<IP_ADDRESS>.12 [The iswxdigit function]
1 Synopsis
#include <wctype.h>
int iswxdigit(wint_t wc);
Description
2 The iswxdigit function tests for any wide character that corresponds to a hexadecimal-digit
character (as defined in <IP_ADDRESS>).
<IP_ADDRESS> [Extensible wide character classification functions]
1 The functions wctype and iswctype provide extensible wide character classification as well as
testing equivalent to that performed by the functions described in the previous subclause (<IP_ADDRESS>).
<IP_ADDRESS>.1 [The iswctype function]
1 Synopsis
#include <wctype.h>
int iswctype(wint_t wc, wctype_t desc);
Description
2 The iswctype function determines whether the wide character wc has the property described by
desc. The current setting of the LC_CTYPE category shall be the same as during the call to wctype
that returned the value desc.
3 Each of the following expressions has a truth-value equivalent to the call to the wide character
classification function (<IP_ADDRESS>) in the comment that follows the expression:
iswctype(wc, wctype("alnum")) // iswalnum(wc)
iswctype(wc, wctype("alpha")) // iswalpha(wc)
iswctype(wc, wctype("blank")) // iswblank(wc)
iswctype(wc, wctype("cntrl")) // iswcntrl(wc)
iswctype(wc, wctype("digit")) // iswdigit(wc)
iswctype(wc, wctype("graph")) // iswgraph(wc)
iswctype(wc, wctype("lower")) // iswlower(wc)
iswctype(wc, wctype("print")) // iswprint(wc)
iswctype(wc, wctype("punct")) // iswpunct(wc)
iswctype(wc, wctype("space")) // iswspace(wc)
iswctype(wc, wctype("upper")) // iswupper(wc)
iswctype(wc, wctype("xdigit")) // iswxdigit(wc)
Returns
4 The iswctype function returns nonzero (true) if and only if the value of the wide character wc has
the property described by desc. If desc is zero, the iswctype function returns zero (false).
Forward references: the wctype function (<IP_ADDRESS>.2).
<IP_ADDRESS>.2 [The wctype function]
1 Synopsis
#include <wctype.h>
wctype_t wctype(const char *property);
Description
2 The wctype function constructs a value with type wctype_t that describes a class of wide characters
identified by the string argument property.
3 The strings listed in the description of the iswctype function shall be valid in all locales as property
arguments to the wctype function.
Returns
4 If property identifies a valid class of wide characters according to the LC_CTYPE category of the
current locale, the wctype function returns a nonzero value that is valid as the second argument to
the iswctype function; otherwise, it returns zero.
7.32.3 [Wide character case mapping utilities]
1 The header <wctype.h> declares several functions useful for mapping wide characters.
<IP_ADDRESS> [Wide character case mapping functions]
<IP_ADDRESS>.1 [The towlower function]
1 Synopsis
#include <wctype.h>
wint_t towlower(wint_t wc);
Description
2 The towlower function converts an uppercase letter to a corresponding lowercase letter.
Returns
3 If the argument is a wide character for which iswupper is true and there are one or more correspond-
ing wide characters, as specified by the current locale, for which iswlower is true, the towlower
function returns one of the corresponding wide characters (always the same one for any given
locale); otherwise, the argument is returned unchanged.
<IP_ADDRESS>.2 [The towupper function]
1 Synopsis
#include <wctype.h>
wint_t towupper(wint_t wc);
Description
2 The towupper function converts a lowercase letter to a corresponding uppercase letter.
Returns
3 If the argument is a wide character for which iswlower is true and there are one or more correspond-
ing wide characters, as specified by the current locale, for which iswupper is true, the towupper
function returns one of the corresponding wide characters (always the same one for any given
locale); otherwise, the argument is returned unchanged.
<IP_ADDRESS> [Extensible wide character case mapping functions]
1 The functions wctrans and towctrans provide extensible wide character mapping as well as case
mapping equivalent to that performed by the functions described in the previous subclause (<IP_ADDRESS>).
<IP_ADDRESS>.1 [The towctrans function]
1 Synopsis
#include <wctype.h>
wint_t towctrans(wint_t wc, wctrans_t desc);
Description
2 The towctrans function maps the wide character wc using the mapping described by desc. The
current setting of the LC_CTYPE category shall be the same as during the call to wctrans that returned
the value desc.
3 Each of the following expressions behaves the same as the call to the wide character case mapping
function (<IP_ADDRESS>) in the comment that follows the expression:
towctrans(wc, wctrans("tolower")) // towlower(wc)
towctrans(wc, wctrans("toupper")) // towupper(wc)
Returns
4 The towctrans function returns the mapped value of wc using the mapping described by desc. If
desc is zero, the towctrans function returns the value of wc .
<IP_ADDRESS>.2 [The wctrans function]
1 Synopsis
#include <wctype.h>
wctrans_t wctrans(const char *property);
Description
2 The wctrans function constructs a value with type wctrans_t that describes a mapping between
wide characters identified by the string argument property.
3 The strings listed in the description of the towctrans function shall be valid in all locales as
property arguments to the wctrans function.
Returns
4 If property identifies a valid mapping of wide characters according to the LC_CTYPE category of the
current locale, the wctrans function returns a nonzero value that is valid as the second argument to
the towctrans function; otherwise, it returns zero.
7.33 [Future library directions]
1 Although grouped under individual headers, all of the external names identified as reserved
identifiers or potentially reserved identifiers in this subclause remain so regardless of which headers
are included in the program.
7.33.1 [Complex arithmetic <complex.h>]
1 The function names
cacospi cexp10m1 clog10 crootn
casinpi cexp10 clog1p crsqrt
catanpi cexp2m1 clog2p1 csinpi
ccompoundn cexp2 clog2 ctanpi
ccospi cexpm1 clogp1 ctgamma
cerfc clgamma cpown
cerf clog10p1 cpowr
and the same names suffixed with f or l are potentially reserved identifiers and may be added to
the declarations in the <complex.h> header.
7.33.2 [Character handling <ctype.h>]
1 Function names that begin with either is or to, and a lowercase letter are potentially reserved
identifiers and may be added to the declarations in the <ctype.h> header.
7.33.3 [Errors <errno.h>]
1 Macros that begin with E and a digit or E and an uppercase letter may be added to the macros
defined in the <errno.h> header by a future revision of this document or by an implementation.
7.33.4 [Floating-point environment <fenv.h>]
1 Macros that begin with FE_ and an uppercase letter may be added to the macros defined in the
<fenv.h> header by a future revision of this document.
7.33.5 [Characteristics of floating types <float.h>]
1 Macros that begin with DBL_, DEC32_, DEC64_, DEC128_, DEC_, FLT_, or LDBL_ and an uppercase
letter are potentially reserved identifiers and may be added to the macros defined in the <float.h>
header.
2 Use of the DECIMAL_DIG macro is an obsolescent feature. A similar type-specific macro, such as
LDBL_DECIMAL_DIG, can be used instead.
3 The use of FLT_HAS_SUBNORM, DBL_HAS_SUBNORM, and LDBL_HAS_SUBNORM macros is an obsolescent
feature.
7.33.6 [Format conversion of integer types <inttypes.h>]
1 Macros that begin with either PRI or SCN, and either a lowercase letter or X are potentially reserved
identifiers and may be added to the macros defined in the <inttypes.h> header.
2 Function names that begin with str, or wcs and a lowercase letter are potentially reserved identifiers
may be added to the declarations in the <inttypes.h> header.
7.33.7 [Localization <locale.h>]
1 Macros that begin with LC_ and an uppercase letter may be added to the macros defined in the
<locale.h> header by a future revision of this document or by an implementation.
7.33.8 [Mathematics <math.h>]
1 Macros that begin with FP_ or MATH_ and an uppercase letter may be added to the macros defined
in the <math.h> header by a future revision of this document or by an implementation.
2 Macros that begin with MATH_ and an uppercase letter are potentially reserved identifiers and may
be added to the macros in the <math.h> header.
3 Function names that begin with is and a lowercase letter are potentially reserved identifiers and
may be added to the declarations in the <math.h> header.
4 Function names that begin with cr_ are potentially reserved identifiers and may be added to the
<math.h> header. The cr_ prefix is intended to indicate a correctly rounded version of the function.
5 Use of the macros INFINITY, DEC_INFINITY, NAN, and DEC_NAN in <math.h> is an obsolescent
feature. Instead, use the same macros in <float.h>.
7.33.9 [Signal handling <signal.h>]
1 Macros that begin with either SIG and an uppercase letter or SIG_ and an uppercase letter may be
added to the macros defined in the <signal.h> header by a fture revision of this document or by an
implementation.
7.33.10 [Atomics <stdatomic.h>]
1 Macros that begin with ATOMIC_ and an uppercase letter are potentially reserved identifiers and
may be added to the macros defined in the <stdatomic.h> header. Typedef names that begin with
either atomic_ or memory_, and a lowercase letter are potentially reserved identifiers and may be
added to the declarations in the <stdatomic.h> header. Enumeration constants that begin with
memory_order_ and a lowercase letter are potentially reserved identifiers and may be added to
the definition of the memory_order type in the <stdatomic.h> header. Function names that begin
with atomic_ and a lowercase letter are potentially reserved identifiers and may be added to the
declarations in the <stdatomic.h> header.
7.33.11 [Boolean type and values <stdbool.h>]
1 The macro __bool_true_false_are_defined is an obsolescent feature.
7.33.12 [Bit and byte utilities <stdbit.h>]
1 Type and function names that begin with stdc_ are potentially reserved identifiers and may be
added to the declarations in the <stdbit.h> header.
7.33.13 [Checked Arithmetic Functions <stdckdint.h>]
1 Type and function names that begin with ckd_ are potentially reserved identifiers and may be added
to the declarations in the <stdckdint.h> header.
7.33.14 [Integer types <stdint.h>]
1 Typedef names beginning with int or uint and ending with _t are potentially reserved identifiers
and may be added to the types defined in the <stdint.h> header. Macro names beginning with
INT or UINT and ending with _MAX , _MIN , _WIDTH , or _C are potentially reserved identifiers and may
be added to the macros defined in the <stdint.h> header.
7.33.15 [Input/output <stdio.h>]
1 Lowercase letters may be added to the conversion specifiers and length modifiers in fprintf and
fscanf. Other characters may be used in extensions.
2 The use of ungetc on a binary stream where the file position indicator is zero prior to the call is an
obsolescent feature.
7.33.16 [General utilities <stdlib.h>]
1 Function names that begin with str or wcs and a lowercase letter are potentially reserved identifiers
and may be added to the declarations in the <stdlib.h> header.
2 Suppressing the macro definition of bsearch in order to access the actual function is an obsolescent
feature.
7.33.17 [String handling <string.h>]
1 Function names that begin with str, mem, or wcs and a lowercase letter are potentially reserved
identifiers and may be added to the declarations in the <string.h> header.
2 Suppressing the macro definitions of memchr, strchr, strpbrk, strrchr, or strstr in order to
access the corresponding actual function is an obsolescent feature.
7.33.18 [Date and time <time.h>]
Macros beginning with TIME_ and an uppercase letter may be added to the macros in the <time.h>
header by a future revision of this document or by an implementation.
7.33.19 [Threads <threads.h>]
1 Function names, type names, and enumeration constants that begin with either cnd_, mtx_, thrd_, or
tss_, and a lowercase letter are potentially reserved identifiers and may be added to the declarations
in the <threads.h> header.
7.33.20 [Extended multibyte and wide character utilities <wchar.h>]
1 Function names that begin with wcs and a lowercase letter are potentially reserved identifiers and
may be added to the declarations in the <wchar.h> header.
2 Lowercase letters may be added to the conversion specifiers and length modifiers in fwprintf and
fwscanf. Other characters may be used in extensions.
3 Suppressing the macro definitions of wcschr, wcspbrk, wcsrchr, wmemchr, or wcsstr in order to
access the corresponding actual function is an obsolescent feature.
7.33.21 [Wide character classification and mapping utilities <wctype.h>]
1 Function names that begin with is or to and a lowercase letter are potentially reserved identifiers
and may be added to the declarations in the <wctype.h> header.
A. [Annex A (informative) Language syntax summary]
1 NOTE The notation is described in 6.1.
A.1 [Lexical grammar]
A.1.1 [Lexical elements]
(6.4) token:
keyword
identifier
constant
string-literal
punctuator
(6.4) preprocessing-token:
header-name
identifier
pp-number
character-constant
string-literal
punctuator
each universal-character-name that cannot be one of the above
each non-white-space character that cannot be one of the above
A.1.2 [Keywords]
(6.4.1) keyword: one of
alignas enum short void
alignof extern signed volatile
auto false sizeof while
bool float static _Atomic
break for static_assert _BitInt
case goto struct _Complex
char if switch _Decimal128
const inline thread_local _Decimal32
constexpr int true _Decimal64
continue long typedef _Generic
default nullptr typeof _Imaginary
do register typeof_unqual _Noreturn
double restrict union
else return unsigned
A.1.3 [Identifiers]
(<IP_ADDRESS>) identifier:
identifier-start
identifier identifier-continue
(<IP_ADDRESS>) identifier-start:
nondigit
XID_Start character
universal-character-name of class XID_Start
(<IP_ADDRESS>) identifier-continue:
digit
nondigit
XID_Continue character
universal-character-name of class XID_Continue
(<IP_ADDRESS>) nondigit: one of
_ a b c d e f g h i j k l m
n o p q r s t u v w x y z
A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z
(<IP_ADDRESS>) digit: one of
0 1 2 3 4 5 6 7 8 9
A.1.4 [Universal character names]
(6.4.3) universal-character-name:
\u hex-quad
\U hex-quad hex-quad
(6.4.3) hex-quad:
hexadecimal-digit hexadecimal-digit hexadecimal-digit hexadecimal-digit
A.1.5 [Constants]
(6.4.4) constant:
integer-constant
floating-constant
enumeration-constant
character-constant
predefined-constant
(<IP_ADDRESS>) integer-constant:
decimal-constant integer-suffixopt
octal-constant integer-suffixopt
hexadecimal-constant integer-suffixopt
binary-constant integer-suffixopt
(<IP_ADDRESS>) decimal-constant:
nonzero-digit
decimal-constant ’opt digit
(<IP_ADDRESS>) octal-constant:
0
octal-constant ’opt octal-digit
(<IP_ADDRESS>) hexadecimal-constant:
hexadecimal-prefix hexadecimal-digit-sequence
(<IP_ADDRESS>) binary-constant: