Footnote 283) 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 284) 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.
Footnote 285) The precision p is sufficient to distinguish values of the source type if 16 p−1 > b n where b is
FLT_RADIX and n is the number of base-b digits in the significand of the source type. 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.[286] If any argument is
not the correct type for the corresponding conversion specification, the behavior is
undefined.
Footnote 286) See ‘‘future library directions’’ (7.26.12).
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
DECIMAL_DIG, then the result should be correctly rounded.[287] If the number of
significant decimal digits is more than DECIMAL_DIG but the source value is exactly
representable with DECIMAL_DIG 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 DECIMAL_DIG 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.
Returns
Footnote 287) 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 The fwprintf function returns the number of wide characters transmitted, or a negative
value if an output or encoding error occurred.
Environmental limits
15 The number of wide characters that can be produced by any single conversion shall be at
least 4095.
16 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));
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. 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.
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 (as specified by the iswspace function) are skipped,
unless the specification includes a [, c, or n specifier.[288]
Footnote 288) 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.[289] 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 289) 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 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 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 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 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 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 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.
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.
If a length modifier appears with any conversion specifier other than as specified above,
the behavior is undefined.
12 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. The corresponding argument shall be a pointer to
signed integer.
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. The corresponding argument shall be a pointer to signed
integer.
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. The corresponding argument shall be a pointer to
unsigned integer.
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. The corresponding argument shall be a pointer to
unsigned integer.
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. The corresponding argument shall be a pointer to
unsigned integer.
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. The corresponding argument shall be a pointer to floating.
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 the initial element of a character array 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 the initial element of an array 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 the initial element of a character array 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 the initial element of an array 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 the initial element of a character array 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 the initial element of an array 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 to 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 to
signed integer into which is to be written the number of wide characters read
from the input stream so far by this call to the fwscanf function. Execution
of a %n directive does not increment the assignment count returned at the
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.[290]
Footnote 290) See ‘‘future library directions’’ (7.26.12).
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 (including new-line wide characters) is 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 any conversion. 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.
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>.1), the
wcstol, wcstoll, wcstoul, and wcstoull functions (<IP_ADDRESS>.2), 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 any conversion. 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.[291]
Returns
Footnote 291) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
invoke the va_arg macro, the value 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.[291]
Returns
Footnote 291) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
invoke the va_arg macro, the value of arg after the return is indeterminate.
3 The vfwscanf function returns the value of the macro EOF if an input failure occurs
before any conversion. 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.[291]
Returns
Footnote 291) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
invoke the va_arg macro, the value 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.[291]
Returns
Footnote 291) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
invoke the va_arg macro, the value of arg after the return is indeterminate.
3 The vswscanf function returns the value of the macro EOF if an input failure occurs
before any conversion. 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.[291]
Returns
Footnote 291) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
invoke the va_arg macro, the value 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.[291]
Returns
Footnote 291) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
invoke the va_arg macro, the value of arg after the return is indeterminate.
3 The vwscanf function returns the value of the macro EOF if an input failure occurs
before any conversion. 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 any conversion. 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.24.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 value of
the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.[292]
Footnote 292) 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
contents are indeterminate 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 nonnegative 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.[293]
Otherwise, mode is zero and the function does not alter the orientation of the stream.
Returns
Footnote 293) 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. 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
6 The ungetwc function returns the wide character pushed back, or WEOF if the operation
fails.
7.24.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 [The wcstod, wcstof, and wcstold functions]
1 Synopsis
#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
2 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 (as specified by the iswspace
function), a subject sequence resembling a floating-point 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 for the corresponding single-byte
characters in <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>;
— 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
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>, 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.[294] 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 sequences is implementation-defined.[295] 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 294) 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 may 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 295) An implementation may use the n-wchar sequence to determine extra information to be represented in
the NaN’s significand.
5 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.
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.
Recommended practice
8 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.
9 If the subject sequence has the decimal form and at most DECIMAL_DIG (defined in
<float.h>) significant digits, the result should be correctly rounded. If the subject
sequence D has the decimal form and more than DECIMAL_DIG significant digits,
consider the two bounding, adjacent decimal strings L and U, both having
DECIMAL_DIG 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.[296]
Returns
Footnote 296) DECIMAL_DIG, defined in <float.h>, should be sufficiently large that L and U will usually round
to the same internal floating value, but if not will round to adjacent values.
10 The 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, plus or
minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return
type and sign of the value), and the value of the macro ERANGE is stored in errno. 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; whether errno acquires
the value ERANGE is implementation-defined.
<IP_ADDRESS>.2 [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 (as specified by the iswspace
function), 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. 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.
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 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, 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.[297]
Footnote 297) 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.[298]
Returns
Footnote 298) 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 characters 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 terminating null wide character). If the value returned is n or greater, the contents of
the array pointed to by s1 are indeterminate.
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>.1 [The wcschr function]
1 Synopsis
#include <wchar.h>
wchar_t *wcschr(const wchar_t *s, wchar_t c);
Description
2 The wcschr 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 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 function]
1 Synopsis
#include <wchar.h>
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
Description
2 The wcspbrk 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 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 function]
1 Synopsis
#include <wchar.h>
wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
Description
2 The wcsrchr 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 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 function]
1 Synopsis
#include <wchar.h>
wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
Description
2 The wcsstr 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 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 function]
1 Synopsis
#include <wchar.h>
wchar_t *wmemchr(const wchar_t *s, wchar_t c,
size_t n);
Description
2 The wmemchr function locates the first occurrence of c in the initial n wide characters of
the object pointed to by s.
Returns
3 The wmemchr 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.24.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
corresponding 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 contents of the array are
indeterminate.
7.24.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.[299]
Footnote 299) 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 pointed-to 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 <stdio.h>
#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 <stdio.h>
#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 pointed-to
Returns
3 The mbsinit function returns nonzero if ps is a null pointer or if the pointed-to 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.20.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 at
program startup to the initial conversion state. 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 designated 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).[300]
(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 300) 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.20.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 at program startup
to the initial conversion state. 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.[301] Each conversion takes
place as if by a call to the mbrtowc function.
Footnote 301) 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.[302]
Footnote 302) 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.25 [Wide character classification and mapping utilities <wctype.h>]
7.25.1 [Introduction]
1 The header <wctype.h> declares three data types, one macro, and many functions.[303]
Footnote 303) See ‘‘future library directions’’ (7.26.13).
2 The types declared are
wint_t
described in 7.24.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.24.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.25.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.[304]
Forward references: the wctob function (<IP_ADDRESS>.2).
Footnote 304) 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.[305]
Footnote 305) 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.[306]
Footnote 306) Note that the behavior of the iswgraph and iswpunct functions may 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.[306]
Footnote 306) Note that the behavior of the iswgraph and iswpunct functions may 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.
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.25.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 corresponding 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 corresponding 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.
<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.26 [Future library directions]
1 The following names are grouped under individual headers for convenience. All external
names described below are reserved no matter what headers are included by the program.
7.26.1 [Complex arithmetic <complex.h>]
1 The function names
cerf cexpm1 clog2
cerfc clog10 clgamma
cexp2 clog1p ctgamma
and the same names suffixed with f or l may be added to the declarations in the
<complex.h> header.
7.26.2 [Character handling <ctype.h>]
1 Function names that begin with either is or to, and a lowercase letter may be added to
the declarations in the <ctype.h> header.
7.26.3 [Errors <errno.h>]
1 Macros that begin with E and a digit or E and an uppercase letter may be added to the
declarations in the <errno.h> header.
7.26.4 [Format conversion of integer types <inttypes.h>]
1 Macro names beginning with PRI or SCN followed by any lowercase letter or X may be
added to the macros defined in the <inttypes.h> header.
7.26.5 [Localization <locale.h>]
1 Macros that begin with LC_ and an uppercase letter may be added to the definitions in
the <locale.h> header.
7.26.6 [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 definitions in the <signal.h> header.
7.26.7 [Boolean type and values <stdbool.h>]
1 The ability to undefine and perhaps then redefine the macros bool, true, and false is
an obsolescent feature.
7.26.8 [Integer types <stdint.h>]
1 Typedef names beginning with int or uint and ending with _t may be added to the
types defined in the <stdint.h> header. Macro names beginning with INT or UINT
and ending with _MAX, _MIN, or _C may be added to the macros defined in the
<stdint.h> header.
7.26.9 [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 gets function is obsolescent, and is deprecated.
3 The use of ungetc on a binary stream where the file position indicator is zero prior to
the call is an obsolescent feature.
7.26.10 [General utilities <stdlib.h>]
1 Function names that begin with str and a lowercase letter may be added to the
declarations in the <stdlib.h> header.
7.26.11 [String handling <string.h>]
1 Function names that begin with str, mem, or wcs and a lowercase letter may be added
to the declarations in the <string.h> header.
7.26.12 [Extended multibyte and wide character utilities <wchar.h>]
1 Function names that begin with wcs and a lowercase letter 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.
7.26.13 [Wide character classification and mapping utilities]
1 <wctype.h>
Function names that begin with is or to and a lowercase letter 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 non-white-space character that cannot be one of the above
A.1.2 [Keywords]
(6.4.1) keyword: one of
auto enum restrict unsigned
break extern return void
case float short volatile
char for signed while
const goto sizeof _Bool
continue if static _Complex
default inline struct _Imaginary
do int switch
double long typedef
else register union
A.1.3 [Identifiers]
(<IP_ADDRESS>) identifier:
identifier-nondigit
identifier identifier-nondigit
identifier digit
(<IP_ADDRESS>) identifier-nondigit:
nondigit
universal-character-name
other implementation-defined characters
(<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
(<IP_ADDRESS>) integer-constant:
decimal-constant integer-suffixopt
octal-constant integer-suffixopt
hexadecimal-constant integer-suffixopt
(<IP_ADDRESS>) decimal-constant:
nonzero-digit
decimal-constant digit
(<IP_ADDRESS>) octal-constant:
0
octal-constant octal-digit
(<IP_ADDRESS>) hexadecimal-constant:
hexadecimal-prefix hexadecimal-digit
hexadecimal-constant hexadecimal-digit
(<IP_ADDRESS>) hexadecimal-prefix: one of
0x 0X
(<IP_ADDRESS>) nonzero-digit: one of
1 2 3 4 5 6 7 8 9
(<IP_ADDRESS>) octal-digit: one of
0 1 2 3 4 5 6 7
(<IP_ADDRESS>) hexadecimal-digit: one of
0 1 2 3 4 5 6 7 8 9
a b c d e f
A B C D E F
(<IP_ADDRESS>) integer-suffix:
unsigned-suffix long-suffixopt
unsigned-suffix long-long-suffix
long-suffix unsigned-suffixopt
long-long-suffix unsigned-suffixopt
(<IP_ADDRESS>) unsigned-suffix: one of
u U
(<IP_ADDRESS>) long-suffix: one of
l L
(<IP_ADDRESS>) long-long-suffix: one of
ll LL
(<IP_ADDRESS>) floating-constant:
decimal-floating-constant
hexadecimal-floating-constant
(<IP_ADDRESS>) decimal-floating-constant:
fractional-constant exponent-partopt floating-suffixopt
digit-sequence exponent-part floating-suffixopt
(<IP_ADDRESS>) hexadecimal-floating-constant:
hexadecimal-prefix hexadecimal-fractional-constant
binary-exponent-part floating-suffixopt
hexadecimal-prefix hexadecimal-digit-sequence
binary-exponent-part floating-suffixopt
(<IP_ADDRESS>) fractional-constant:
digit-sequenceopt . digit-sequence
digit-sequence .
(<IP_ADDRESS>) exponent-part:
e signopt digit-sequence
E signopt digit-sequence
(<IP_ADDRESS>) sign: one of
+ -
(<IP_ADDRESS>) digit-sequence:
digit
digit-sequence digit
(<IP_ADDRESS>) hexadecimal-fractional-constant:
hexadecimal-digit-sequenceopt .
hexadecimal-digit-sequence
hexadecimal-digit-sequence .
(<IP_ADDRESS>) binary-exponent-part:
p signopt digit-sequence
P signopt digit-sequence
(<IP_ADDRESS>) hexadecimal-digit-sequence:
hexadecimal-digit
hexadecimal-digit-sequence hexadecimal-digit
(<IP_ADDRESS>) floating-suffix: one of
f l F L
(<IP_ADDRESS>) enumeration-constant:
identifier
(<IP_ADDRESS>) character-constant:
' c-char-sequence '
L' c-char-sequence '
(<IP_ADDRESS>) c-char-sequence:
c-char
c-char-sequence c-char
(<IP_ADDRESS>) c-char:
any member of the source character set except
the single-quote ', backslash \, or new-line character
escape-sequence
(<IP_ADDRESS>) escape-sequence:
simple-escape-sequence
octal-escape-sequence
hexadecimal-escape-sequence
universal-character-name
(<IP_ADDRESS>) simple-escape-sequence: one of
\' \" \? \\
\a \b \f \n \r \t \v
(<IP_ADDRESS>) octal-escape-sequence:
\ octal-digit
\ octal-digit octal-digit
\ octal-digit octal-digit octal-digit
(<IP_ADDRESS>) hexadecimal-escape-sequence:
\x hexadecimal-digit
hexadecimal-escape-sequence hexadecimal-digit
A.1.6 [String literals]
(6.4.5) string-literal:
" s-char-sequenceopt "
L" s-char-sequenceopt "
(6.4.5) s-char-sequence:
s-char
s-char-sequence s-char
(6.4.5) s-char:
any member of the source character set except
the double-quote ", backslash \, or new-line character
escape-sequence
A.1.7 [Punctuators]
(6.4.6) punctuator: one of
[ ] ( ) { } . ->
++ -- & * + - ~ !
/ % << >> < > <= >= == != ^ | && ||
? : ; ...
= *= /= %= += -= <<= >>= &= ^= |=
, # ##
<: :> <% %> %: %:%:
A.1.8 [Header names]
(6.4.7) header-name:
< h-char-sequence >
" q-char-sequence "
(6.4.7) h-char-sequence:
h-char
h-char-sequence h-char
(6.4.7) h-char:
any member of the source character set except
the new-line character and >
(6.4.7) q-char-sequence:
q-char
q-char-sequence q-char
(6.4.7) q-char:
any member of the source character set except
the new-line character and "
A.1.9 [Preprocessing numbers]
(6.4.8) pp-number:
digit
. digit
pp-number digit
pp-number identifier-nondigit
pp-number e sign
pp-number E sign
pp-number p sign
pp-number P sign
pp-number .

— The end of the first operand of the following operators: logical AND && (6.5.13);
logical OR || (6.5.14); conditional ? (6.5.15); comma , (6.5.17).
— The end of a full declarator: declarators (6.7.5);
— The end of a full expression: an initializer (6.7.8); the expression in an expression
statement (6.8.3); the controlling expression of a selection statement (if or switch)
(6.8.4); the controlling expression of a while or do statement (6.8.5); each of the
expressions of a for statement (<IP_ADDRESS>); the expression in a return statement
(<IP_ADDRESS>).
— Immediately before a library function returns (7.1.4).
— After the actions associated with each formatted input/output function conversion
specifier (7.19.6, 7.24.2).
— Immediately before and immediately after each call to a comparison function, and
also between any call to a comparison function and any movement of the objects
passed as arguments to that call (7.20.5).
D. [Annex D (normative) Universal character names for identifiers]
1 This clause lists the hexadecimal code values that are valid in universal character names
in identifiers.
2 This table is reproduced unchanged from ISO/IEC TR 10176:1998, produced by ISO/IEC
JTC 1/SC 22/WG 20, except for the omission of ranges that are part of the basic character
sets.
 The
minimum magnitudes shown shall be replaced by implementation-defined magnitudes
with the same sign. The values shall all be constant expressions suitable for use in #if
preprocessing directives. The components are described further in <IP_ADDRESS>.1.
#define CHAR_BIT 8
#define CHAR_MAX UCHAR_MAX or SCHAR_MAX
#define CHAR_MIN 0 or SCHAR_MIN
#define INT_MAX +32767
#define INT_MIN -32767
#define LONG_MAX +2147483647
#define LONG_MIN -2147483647
#define LLONG_MAX +9223372036854775807
#define LLONG_MIN -9223372036854775807
#define MB_LEN_MAX 1
#define SCHAR_MAX +127
#define SCHAR_MIN -127
#define SHRT_MAX +32767
#define SHRT_MIN -32767
#define UCHAR_MAX 255
#define USHRT_MAX 65535
#define UINT_MAX 65535
#define ULONG_MAX<PHONE_NUMBER>
#define ULLONG_MAX<PHONE_NUMBER>3709551615
2 The contents of the header <float.h> are given below. All integer values, except
FLT_ROUNDS, shall be constant expressions suitable for use in #if preprocessing
directives; all floating values shall be constant expressions. The components are
described further in <IP_ADDRESS>.2.
3 The values given in the following list shall be replaced by implementation-defined
expressions:
#define FLT_EVAL_METHOD
#define FLT_ROUNDS
4 The values given in the following list shall be replaced by implementation-defined
constant expressions that are greater or equal in magnitude (absolute value) to those
#define DBL_DIG 10
#define DBL_MANT_DIG
#define DBL_MAX_10_EXP +37
#define DBL_MAX_EXP
#define DBL_MIN_10_EXP -37
#define DBL_MIN_EXP
#define DECIMAL_DIG 10
#define FLT_DIG 6
#define FLT_MANT_DIG
#define FLT_MAX_10_EXP +37
#define FLT_MAX_EXP
#define FLT_MIN_10_EXP -37
#define FLT_MIN_EXP
#define FLT_RADIX 2
#define LDBL_DIG 10
#define LDBL_MANT_DIG
#define LDBL_MAX_10_EXP +37
#define LDBL_MAX_EXP
#define LDBL_MIN_10_EXP -37
#define LDBL_MIN_EXP
5 The values given in the following list shall be replaced by implementation-defined
constant expressions with values that are greater than or equal to those shown:
#define DBL_MAX 1E+37
#define FLT_MAX 1E+37
#define LDBL_MAX 1E+37
6 The values given in the following list shall be replaced by implementation-defined
constant expressions with (positive) values that are less than or equal to those shown:
#define DBL_EPSILON 1E-9
#define DBL_MIN 1E-37
#define FLT_EPSILON 1E-5
#define FLT_MIN 1E-37
#define LDBL_EPSILON 1E-9
#define LDBL_MIN 1E-37
F. [Annex F (normative) IEC 60559 floating-point arithmetic]
F.1 [Introduction]
1 This annex specifies C language support for the IEC 60559 floating-point standard. The
IEC 60559 floating-point standard is specifically Binary floating-point arithmetic for
microprocessor systems, second edition (IEC 60559:1989), previously designated
IEC 559:1989 and as IEEE Standard for Binary Floating-Point Arithmetic
(ANSI/IEEE 754−1985). IEEE Standard for Radix-Independent Floating-Point
Arithmetic (ANSI/IEEE 854−1987) generalizes the binary standard to remove
dependencies on radix and word length. IEC 60559 generally refers to the floating-point
standard, as in IEC 60559 operation, IEC 60559 format, etc. An implementation that
defines _ _STDC_IEC_559_ _ shall conform to the specifications in this annex. Where
a binding between the C language and IEC 60559 is indicated, the IEC 60559-specified
behavior is adopted by reference, unless stated otherwise.
F.2 [Types]
1 The C floating types match the IEC 60559 formats as follows:
— The float type matches the IEC 60559 single format.
— The double type matches the IEC 60559 double format.
— The long double type matches an IEC 60559 extended format,[307] else a
non-IEC 60559 extended format, else the IEC 60559 double format.
Any non-IEC 60559 extended format used for the long double type shall have more
precision than IEC 60559 double and at least the range of IEC 60559 double.[308]
Recommended practice
Footnote 307) ‘‘Extended’’ is IEC 60559’s double-extended data format. Extended refers to both the common 80-bit
and quadruple 128-bit IEC 60559 formats.
Footnote 308) A non-IEC 60559 long double type is required to provide infinity and NaNs, as its values include
all double values.
2 The long double type should match an IEC 60559 extended format.
F.2.1 [Infinities, signed zeros, and NaNs]
1 This specification does not define the behavior of signaling NaNs.[309] It generally uses
the term NaN to denote quiet NaNs. The NAN and INFINITY macros and the nan
functions in <math.h> provide designations for IEC 60559 NaNs and infinities.
Footnote 309) Since NaNs created by IEC 60559 operations are always quiet, quiet NaNs (along with infinities) are
sufficient for closure of the arithmetic.
F.3 [Operators and functions]
1 C operators and functions provide IEC 60559 required and recommended facilities as
listed below.
— The +, −, *, and / operators provide the IEC 60559 add, subtract, multiply, and
divide operations.
— The sqrt functions in <math.h> provide the IEC 60559 square root operation.
— The remainder functions in <math.h> provide the IEC 60559 remainder
operation. The remquo functions in <math.h> provide the same operation but
with additional information.
— The rint functions in <math.h> provide the IEC 60559 operation that rounds a
floating-point number to an integer value (in the same precision). The nearbyint
functions in <math.h> provide the nearbyinteger function recommended in the
Appendix to ANSI/IEEE 854.
— The conversions for floating types provide the IEC 60559 conversions between
floating-point precisions.
— The conversions from integer to floating types provide the IEC 60559 conversions
from integer to floating point.
— The conversions from floating to integer types provide IEC 60559-like conversions
but always round toward zero.
— The lrint and llrint functions in <math.h> provide the IEC 60559
conversions, which honor the directed rounding mode, from floating point to the
long int and long long int integer formats. The lrint and llrint
functions can be used to implement IEC 60559 conversions from floating to other
integer formats.
— The translation time conversion of floating constants and the strtod, strtof,
strtold, fprintf, fscanf, and related library functions in <stdlib.h>,
<stdio.h>, and <wchar.h> provide IEC 60559 binary-decimal conversions. The
strtold function in <stdlib.h> provides the conv function recommended in the
Appendix to ANSI/IEEE 854.
— The relational and equality operators provide IEC 60559 comparisons. IEC 60559
identifies a need for additional comparison predicates to facilitate writing code that
accounts for NaNs. The comparison macros (isgreater, isgreaterequal,
isless, islessequal, islessgreater, and isunordered) in <math.h>
supplement the language operators to address this need. The islessgreater and
isunordered macros provide respectively a quiet version of the <> predicate and
the unordered predicate recommended in the Appendix to IEC 60559.
— The feclearexcept, feraiseexcept, and fetestexcept functions in
<fenv.h> provide the facility to test and alter the IEC 60559 floating-point
exception status flags. The fegetexceptflag and fesetexceptflag
functions in <fenv.h> provide the facility to save and restore all five status flags at
one time. These functions are used in conjunction with the type fexcept_t and the
floating-point exception macros (FE_INEXACT, FE_DIVBYZERO,
FE_UNDERFLOW, FE_OVERFLOW, FE_INVALID) also in <fenv.h>.
— The fegetround and fesetround functions in <fenv.h> provide the facility
to select among the IEC 60559 directed rounding modes represented by the rounding
direction macros in <fenv.h> (FE_TONEAREST, FE_UPWARD, FE_DOWNWARD,
FE_TOWARDZERO) and the values 0, 1, 2, and 3 of FLT_ROUNDS are the
IEC 60559 directed rounding modes.
— The fegetenv, feholdexcept, fesetenv, and feupdateenv functions in
<fenv.h> provide a facility to manage the floating-point environment, comprising
the IEC 60559 status flags and control modes.
— The copysign functions in <math.h> provide the copysign function
recommended in the Appendix to IEC 60559.
— The unary minus (−) operator provides the minus (−) operation recommended in the
Appendix to IEC 60559.
— The scalbn and scalbln functions in <math.h> provide the scalb function
recommended in the Appendix to IEC 60559.
— The logb functions in <math.h> provide the logb function recommended in the
Appendix to IEC 60559, but following the newer specifications in ANSI/IEEE 854.
— The nextafter and nexttoward functions in <math.h> provide the nextafter
function recommended in the Appendix to IEC 60559 (but with a minor change to
better handle signed zeros).
— The isfinite macro in <math.h> provides the finite function recommended in
the Appendix to IEC 60559.
— The isnan macro in <math.h> provides the isnan function recommended in the
Appendix to IEC 60559.
— The signbit macro and the fpclassify macro in <math.h>, used in
conjunction with the number classification macros (FP_NAN, FP_INFINITE,
FP_NORMAL, FP_SUBNORMAL, FP_ZERO), provide the facility of the class
function recommended in the Appendix to IEC 60559 (except that the classification
macros defined in 7.12.3 do not distinguish signaling from quiet NaNs).
F.4 [Floating to integer conversion]
1 If the floating value is infinite or NaN or if the integral part of the floating value exceeds
the range of the integer type, then the ‘‘invalid’’ floating-point exception is raised and the
resulting value is unspecified. Whether conversion of non-integer floating values whose
integral part is within the range of the integer type raises the ‘‘inexact’’ floating-point
exception is unspecified.[310]
Footnote 310) ANSI/IEEE 854, but not IEC 60559 (ANSI/IEEE 754), directly specifies that floating-to-integer
conversions raise the ‘‘inexact’’ floating-point exception for non-integer in-range values. In those
cases where it matters, library functions can be used to effect such conversions with or without raising
the ‘‘inexact’’ floating-point exception. See rint, lrint, llrint, and nearbyint in
<math.h>.
F.5 [Binary-decimal conversion]
1 Conversion from the widest supported IEC 60559 format to decimal with
DECIMAL_DIG digits and back is the identity function.[311]
Footnote 311) If the minimum-width IEC 60559 extended format (64 bits of precision) is supported,
DECIMAL_DIG shall be at least 21. If IEC 60559 double (53 bits of precision) is the widest
IEC 60559 format supported, then DECIMAL_DIG shall be at least 17. (By contrast, LDBL_DIG and
DBL_DIG are 18 and 15, respectively, for these formats.)
2 Conversions involving IEC 60559 formats follow all pertinent recommended practice. In
particular, conversion between any supported IEC 60559 format and decimal with
DECIMAL_DIG or fewer significant digits is correctly rounded (honoring the current
rounding mode), which assures that conversion from the widest supported IEC 60559
format to decimal with DECIMAL_DIG digits and back is the identity function.
3 Functions such as strtod that convert character sequences to floating types honor the
rounding direction. Hence, if the rounding direction might be upward or downward, the
implementation cannot convert a minus-signed sequence by negating the converted
unsigned sequence.
F.6 [Contracted expressions]
1 A contracted expression treats infinities, NaNs, signed zeros, subnormals, and the
rounding directions in a manner consistent with the basic arithmetic operations covered
by IEC 60559.
Recommended practice
2 A contracted expression should raise floating-point exceptions in a manner generally
consistent with the basic arithmetic operations. A contracted expression should deliver
the same value as its uncontracted counterpart, else should be correctly rounded (once).
F.7 [Floating-point environment]
1 The floating-point environment defined in <fenv.h> includes the IEC 60559 floating-
point exception status flags and directed-rounding control modes. It includes also
IEC 60559 dynamic rounding precision and trap enablement modes, if the
implementation supports them.[312]
Footnote 312) This specification does not require dynamic rounding precision nor trap enablement modes.
F.7.1 [Environment management]
1 IEC 60559 requires that floating-point operations implicitly raise floating-point exception
status flags, and that rounding control modes can be set explicitly to affect result values of
floating-point operations. When the state for the FENV_ACCESS pragma (defined in
<fenv.h>) is ‘‘on’’, these changes to the floating-point state are treated as side effects
which respect sequence points.[313]
Footnote 313) If the state for the FENV_ACCESS pragma is ‘‘off’’, the implementation is free to assume the floating-
point control modes will be the default ones and the floating-point status flags will not be tested,
which allows certain optimizations (see F.8).
F.7.2 [Translation]
1 During translation the IEC 60559 default modes are in effect:
— The rounding direction mode is rounding to nearest.
— The rounding precision mode (if supported) is set so that results are not shortened.
— Trapping or stopping (if supported) is disabled on all floating-point exceptions.
Recommended practice
2 The implementation should produce a diagnostic message for each translation-time
floating-point exception, other than ‘‘inexact’’;[314] the implementation should then
proceed with the translation of the program.
Footnote 314) As floating constants are converted to appropriate internal representations at translation time, their
conversion is subject to default rounding modes and raises no execution-time floating-point exceptions
(even where the state of the FENV_ACCESS pragma is ‘‘on’’). Library functions, for example
strtod, provide execution-time conversion of numeric strings.
F.7.3 [Execution]
1 At program startup the floating-point environment is initialized as prescribed by
IEC 60559:
— All floating-point exception status flags are cleared.
— The rounding direction mode is rounding to nearest.
— The dynamic rounding precision mode (if supported) is set so that results are not
shortened.
— Trapping or stopping (if supported) is disabled on all floating-point exceptions.
F.7.4 [Constant expressions]
1 An arithmetic constant expression of floating type, other than one in an initializer for an
object that has static storage duration, is evaluated (as if) during execution; thus, it is
affected by any operative floating-point control modes and raises floating-point
exceptions as required by IEC 60559 (provided the state for the FENV_ACCESS pragma
is ‘‘on’’).[315]
Footnote 315) Where the state for the FENV_ACCESS pragma is ‘‘on’’, results of inexact expressions like 1.0/3.0
are affected by rounding modes set at execution time, and expressions such as 0.0/0.0 and
1.0/0.0 generate execution-time floating-point exceptions. The programmer can achieve the
efficiency of translation-time evaluation through static initialization, such as
const static double one_third = 1.0/3.0;
2 EXAMPLE
#include <fenv.h>
#pragma STDC FENV_ACCESS ON
void f(void)
{
float w[] = { 0.0/0.0 }; // raises an exception
static float x = 0.0/0.0; // does not raise an exception
float y = 0.0/0.0; // raises an exception
double z = 0.0/0.0; // raises an exception
/* ... */
}
3 For the static initialization, the division is done at translation time, raising no (execution-time) floating-
point exceptions. On the other hand, for the three automatic initializations the invalid division occurs at
execution time.
F.7.5 [Initialization]
1 All computation for automatic initialization is done (as if) at execution time; thus, it is
affected by any operative modes and raises floating-point exceptions as required by
IEC 60559 (provided the state for the FENV_ACCESS pragma is ‘‘on’’). All computation
for initialization of objects that have static storage duration is done (as if) at translation
time.
2 EXAMPLE
#include <fenv.h>
#pragma STDC FENV_ACCESS ON
void f(void)
{
float u[] = { 1.1e75 }; // raises exceptions
static float v = 1.1e75; // does not raise exceptions
float w = 1.1e75; // raises exceptions
double x = 1.1e75; // may raise exceptions
float y = 1.1e75f; // may raise exceptions
long double z = 1.1e75; // does not raise exceptions
/* ... */
}
3 The static initialization of v raises no (execution-time) floating-point exceptions because its computation is
done at translation time. The automatic initialization of u and w require an execution-time conversion to
float of the wider value 1.1e75, which raises floating-point exceptions. The automatic initializations
of x and y entail execution-time conversion; however, in some expression evaluation methods, the
conversions is not to a narrower format, in which case no floating-point exception is raised.[316] The
automatic initialization of z entails execution-time conversion, but not to a narrower format, so no floating-
point exception is raised. Note that the conversions of the floating constants 1.1e75 and 1.1e75f to
their internal representations occur at translation time in all cases.
Footnote 316) Use of float_t and double_t variables increases the likelihood of translation-time computation.
For example, the automatic initialization
double_t x = 1.1e75;
could be done at translation time, regardless of the expression evaluation method.
F.7.6 [Changing the environment]
1 Operations defined in 6.5 and functions and macros defined for the standard libraries
change floating-point status flags and control modes just as indicated by their
specifications (including conformance to IEC 60559). They do not change flags or modes
(so as to be detectable by the user) in any other cases.
2 If the argument to the feraiseexcept function in <fenv.h> represents IEC 60559
valid coincident floating-point exceptions for atomic operations (namely ‘‘overflow’’ and
‘‘inexact’’, or ‘‘underflow’’ and ‘‘inexact’’), then ‘‘overflow’’ or ‘‘underflow’’ is raised
before ‘‘inexact’’.
F.8 [Optimization]
1 This section identifies code transformations that might subvert IEC 60559-specified
behavior, and others that do not.
F.8.1 [Global transformations]
1 Floating-point arithmetic operations and external function calls may entail side effects
which optimization shall honor, at least where the state of the FENV_ACCESS pragma is
‘‘on’’. The flags and modes in the floating-point environment may be regarded as global
variables; floating-point operations (+, *, etc.) implicitly read the modes and write the
flags.
2 Concern about side effects may inhibit code motion and removal of seemingly useless
code. For example, in
#include <fenv.h>
#pragma STDC FENV_ACCESS ON
void f(double x)
{
/* ... */
for (i = 0; i < n; i++) x + 1;
/* ... */
}
x + 1 might raise floating-point exceptions, so cannot be removed. And since the loop
body might not execute (maybe 0 ≥ n), x + 1 cannot be moved out of the loop. (Of
course these optimizations are valid if the implementation can rule out the nettlesome
cases.)
3 This specification does not require support for trap handlers that maintain information
about the order or count of floating-point exceptions. Therefore, between function calls,
floating-point exceptions need not be precise: the actual order and number of occurrences
of floating-point exceptions (> 1) may vary from what the source code expresses. Thus,
the preceding loop could be treated as
if (0 < n) x + 1;
F.8.2 [Expression transformations]
1 x / 2 ↔ x * 0.5 Although similar transformations involving inexact
constants generally do not yield numerically equivalent
expressions, if the constants are exact then such
transformations can be made on IEC 60559 machines
and others that round perfectly.
1 * x and x / 1 → x The expressions 1 * x, x / 1, and x are equivalent
(on IEC 60559 machines, among others).[317]
x / x → 1.0 The expressions x / x and 1.0 are not equivalent if x
can be zero, infinite, or NaN.
x − y ↔ x + (−y) The expressions x − y, x + (−y), and (−y) + x
are equivalent (on IEC 60559 machines, among others).
x − y ↔ −(y − x) The expressions x − y and −(y − x) are not
equivalent because 1 − 1 is +0 but −(1 − 1) is −0 (in the
default rounding direction).[318]
x − x → 0.0 The expressions x − x and 0.0 are not equivalent if
x is a NaN or infinite.
0 * x → 0.0 The expressions 0 * x and 0.0 are not equivalent if
x is a NaN, infinite, or −0.
x + 0→x The expressions x + 0 and x are not equivalent if x is
−0, because (−0) + (+0) yields +0 (in the default
rounding direction), not −0.
x − 0→x (+0) − (+0) yields −0 when rounding is downward
(toward −∞), but +0 otherwise, and (−0) − (+0) always
yields −0; so, if the state of the FENV_ACCESS pragma
is ‘‘off’’, promising default rounding, then the
implementation can replace x − 0 by x, even if x
might be zero.
−x ↔ 0 − x The expressions −x and 0 − x are not equivalent if x
is +0, because −(+0) yields −0, but 0 − (+0) yields +0
(unless rounding is downward).
Footnote 317) Strict support for signaling NaNs — not required by this specification — would invalidate these and
other transformations that remove arithmetic operators.
Footnote 318) IEC 60559 prescribes a signed zero to preserve mathematical identities across certain discontinuities.
Examples include:
1/(1/ ± ∞) is ± ∞
and
conj(csqrt(z)) is csqrt(conj(z)),
for complex z.
F.8.3 [Relational operators]
1 x != x → false The statement x != x is true if x is a NaN.
x == x → true The statement x == x is false if x is a NaN.
x < y → isless(x,y) (and similarly for <=, >, >=) Though numerically
equal, these expressions are not equivalent because of
side effects when x or y is a NaN and the state of the
FENV_ACCESS pragma is ‘‘on’’. This transformation,
which would be desirable if extra code were required to
cause the ‘‘invalid’’ floating-point exception for
unordered cases, could be performed provided the state
of the FENV_ACCESS pragma is ‘‘off’’.
The sense of relational operators shall be maintained. This includes handling unordered
cases as expressed by the source code.
2 EXAMPLE
// calls g and raises ‘‘invalid’’ if a and b are unordered
if (a < b)
f();
else
g();
is not equivalent to
// calls f and raises ‘‘invalid’’ if a and b are unordered
if (a >= b)
g();
else
f();
nor to
// calls f without raising ‘‘invalid’’ if a and b are unordered
if (isgreaterequal(a,b))
g();
else
f();
nor, unless the state of the FENV_ACCESS pragma is ‘‘off’’, to
// calls g without raising ‘‘invalid’’ if a and b are unordered
if (isless(a,b))
f();
else
g();
but is equivalent to
if (!(a < b))
g();
else
f();
F.8.4 [Constant arithmetic]
1 The implementation shall honor floating-point exceptions raised by execution-time
constant arithmetic wherever the state of the FENV_ACCESS pragma is ‘‘on’’. (See F.7.4
and F.7.5.) An operation on constants that raises no floating-point exception can be
folded during translation, except, if the state of the FENV_ACCESS pragma is ‘‘on’’, a
further check is required to assure that changing the rounding direction to downward does
not alter the sign of the result,[319] and implementations that support dynamic rounding
precision modes shall assure further that the result of the operation raises no floating-
point exception when converted to the semantic type of the operation.
Footnote 319) 0 − 0 yields −0 instead of +0 just when the rounding direction is downward.
F.9 [Mathematics <math.h>]
1 This subclause contains specifications of <math.h> facilities that are particularly suited
for IEC 60559 implementations.
2 The Standard C macro HUGE_VAL and its float and long double analogs,
HUGE_VALF and HUGE_VALL, expand to expressions whose values are positive
infinities.
3 Special cases for functions in <math.h> are covered directly or indirectly by
IEC 60559. The functions that IEC 60559 specifies directly are identified in F.3. The
other functions in <math.h> treat infinities, NaNs, signed zeros, subnormals, and
(provided the state of the FENV_ACCESS pragma is ‘‘on’’) the floating-point status flags
in a manner consistent with the basic arithmetic operations covered by IEC 60559.
4 The expression math_errhandling & MATH_ERREXCEPT shall evaluate to a
nonzero value.
5 The ‘‘invalid’’ and ‘‘divide-by-zero’’ floating-point exceptions are raised as specified in
subsequent subclauses of this annex.
6 The ‘‘overflow’’ floating-point exception is raised whenever an infinity — or, because of
rounding direction, a maximal-magnitude finite number — is returned in lieu of a value
whose magnitude is too large.
7 The ‘‘underflow’’ floating-point exception is raised whenever a result is tiny (essentially
subnormal or zero) and suffers loss of accuracy.[320]
Footnote 320) IEC 60559 allows different definitions of underflow. They all result in the same values, but differ on
when the floating-point exception is raised.
8 Whether or when library functions raise the ‘‘inexact’’ floating-point exception is
unspecified, unless explicitly specified otherwise.
9 Whether or when library functions raise an undeserved ‘‘underflow’’ floating-point
exception is unspecified.[321] Otherwise, as implied by F.7.6, the <math.h> functions do
not raise spurious floating-point exceptions (detectable by the user), other than the
‘‘inexact’’ floating-point exception.
Footnote 321) It is intended that undeserved ‘‘underflow’’ and ‘‘inexact’’ floating-point exceptions are raised only if
avoiding them would be too costly.
10 Whether the functions honor the rounding direction mode is implementation-defined,
unless explicitly specified otherwise.
11 Functions with a NaN argument return a NaN result and raise no floating-point exception,
except where stated otherwise.
12 The specifications in the following subclauses append to the definitions in <math.h>.
For families of functions, the specifications apply to all of the functions even though only
the principal function is shown. Unless otherwise specified, where the symbol ‘‘±’’
occurs in both an argument and the result, the result has the same sign as the argument.
Recommended practice
13 If a function with one or more NaN arguments returns a NaN result, the result should be
the same as one of the NaN arguments (after possible type conversion), except perhaps
for the sign.
F.9.1 [Trigonometric functions]
F.9.1.1 [The acos functions]
1 — acos(1) returns +0.
— acos(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for
| x | > 1.
F.9.1.2 [The asin functions]
1 — asin(±0) returns ±0.
— asin(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for
| x | > 1.
F.9.1.3 [The atan functions]
1 — atan(±0) returns ±0.
— atan(±∞) returns ±π /2.
F.9.1.4 [The atan2 functions]
1 — atan2(±0, −0) returns ±π .[322]
— atan2(±0, +0) returns ±0.
— atan2(±0, x) returns ±π for x < 0.
— atan2(±0, x) returns ±0 for x > 0.
— atan2(y, ±0) returns −π /2 for y < 0.
— atan2(y, ±0) returns π /2 for y > 0.
— atan2(±y, −∞) returns ±π for finite y > 0.
— atan2(±y, +∞) returns ±0 for finite y > 0.
— atan2(±∞, x) returns ±π /2 for finite x.
— atan2(±∞, −∞) returns ±3π /4.
— atan2(±∞, +∞) returns ±π /4.
Footnote 322) atan2(0, 0) does not raise the ‘‘invalid’’ floating-point exception, nor does atan2( y , 0) raise
the ‘‘divide-by-zero’’ floating-point exception.
F.9.1.5 [The cos functions]
1 — cos(±0) returns 1.
— cos(±∞) returns a NaN and raises the ‘‘invalid’’ floating-point exception.
F.9.1.6 [The sin functions]
1 — sin(±0) returns ±0.
— sin(±∞) returns a NaN and raises the ‘‘invalid’’ floating-point exception.
F.9.1.7 [The tan functions]
1 — tan(±0) returns ±0.
— tan(±∞) returns a NaN and raises the ‘‘invalid’’ floating-point exception.
F.9.2 [Hyperbolic functions]
F.9.2.1 [The acosh functions]
1 — acosh(1) returns +0.
— acosh(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for x < 1.
— acosh(+∞) returns +∞.
F.9.2.2 [The asinh functions]
1 — asinh(±0) returns ±0.
— asinh(±∞) returns ±∞.
F.9.2.3 [The atanh functions]
1 — atanh(±0) returns ±0.
— atanh(±1) returns ±∞ and raises the ‘‘divide-by-zero’’ floating-point exception.
— atanh(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for
| x | > 1.
F.9.2.4 [The cosh functions]
1 — cosh(±0) returns 1.
— cosh(±∞) returns +∞.
F.9.2.5 [The sinh functions]
1 — sinh(±0) returns ±0.
— sinh(±∞) returns ±∞.
F.9.2.6 [The tanh functions]
1 — tanh(±0) returns ±0.
— tanh(±∞) returns ±1.
F.9.3 [Exponential and logarithmic functions]
F.9.3.1 [The exp functions]
1 — exp(±0) returns 1.
— exp(−∞) returns +0.
— exp(+∞) returns +∞.
F.9.3.2 [The exp2 functions]
1 — exp2(±0) returns 1.
— exp2(−∞) returns +0.
— exp2(+∞) returns +∞.
F.9.3.3 [The expm1 functions]
1 — expm1(±0) returns ±0.
— expm1(−∞) returns −1.
— expm1(+∞) returns +∞.
F.9.3.4 [The frexp functions]
1 — frexp(±0, exp) returns ±0, and stores 0 in the object pointed to by exp.
— frexp(±∞, exp) returns ±∞, and stores an unspecified value in the object
pointed to by exp.
— frexp(NaN, exp) stores an unspecified value in the object pointed to by exp
(and returns a NaN).
2 frexp raises no floating-point exceptions.
3 On a binary system, the body of the frexp function might be
{
*exp = (value == 0) ? 0 : (int)(1 + logb(value));
return scalbn(value, -(*exp));
}
F.9.3.5 [The ilogb functions]
1 If the correct result is outside the range of the return type, the numeric result is
unspecified and the ‘‘invalid’’ floating-point exception is raised.
F.9.3.6 [The ldexp functions]
1 On a binary system, ldexp(x, exp) is equivalent to scalbn(x, exp).
F.9.3.7 [The log functions]
1 — log(±0) returns −∞ and raises the ‘‘divide-by-zero’’ floating-point exception.
— log(1) returns +0.
— log(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for x < 0.
— log(+∞) returns +∞.
F.9.3.8 [The log10 functions]
1 — log10(±0) returns −∞ and raises the ‘‘divide-by-zero’’ floating-point exception.
— log10(1) returns +0.
— log10(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for x < 0.
— log10(+∞) returns +∞.
F.9.3.9 [The log1p functions]
1 — log1p(±0) returns ±0.
— log1p(−1) returns −∞ and raises the ‘‘divide-by-zero’’ floating-point exception.
— log1p(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for
x < −1.
— log1p(+∞) returns +∞.
F.9.3.10 [The log2 functions]
1 — log2(±0) returns −∞ and raises the ‘‘divide-by-zero’’ floating-point exception.
— log2(1) returns +0.
— log2(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for x < 0.
— log2(+∞) returns +∞.
F.9.3.11 [The logb functions]
1 — logb(±0) returns −∞ and raises the ‘‘divide-by-zero’’ floating-point exception.
— logb(±∞) returns +∞.
F.9.3.12 [The modf functions]
1 — modf(±x, iptr) returns a result with the same sign as x.
— modf(±∞, iptr) returns ±0 and stores ±∞ in the object pointed to by iptr.
— modf(NaN, iptr) stores a NaN in the object pointed to by iptr (and returns a
NaN).
2 modf behaves as though implemented by
#include <math.h>
#include <fenv.h>
#pragma STDC FENV_ACCESS ON
double modf(double value, double *iptr)
{
int save_round = fegetround();
fesetround(FE_TOWARDZERO);
*iptr = nearbyint(value);
fesetround(save_round);
return copysign(
isinf(value) ? 0.0 :
value - (*iptr), value);
}
F.9.3.13 [The scalbn and scalbln functions]
1 — scalbn(±0, n) returns ±0.
— scalbn(x, 0) returns x.
— scalbn(±∞, n) returns ±∞.
F.9.4 [Power and absolute value functions]
F.9.4.1 [The cbrt functions]
1 — cbrt(±0) returns ±0.
— cbrt(±∞) returns ±∞.
F.9.4.2 [The fabs functions]
1 — fabs(±0) returns +0.
— fabs(±∞) returns +∞.
F.9.4.3 [The hypot functions]
1 — hypot(x, y), hypot(y, x), and hypot(x, −y) are equivalent.
— hypot(x, ±0) is equivalent to fabs(x).
— hypot(±∞, y) returns +∞, even if y is a NaN.
F.9.4.4 [The pow functions]
1 — pow(±0, y) returns ±∞ and raises the ‘‘divide-by-zero’’ floating-point exception
for y an odd integer < 0.
— pow(±0, y) returns +∞ and raises the ‘‘divide-by-zero’’ floating-point exception
for y < 0 and not an odd integer.
— pow(±0, y) returns ±0 for y an odd integer > 0.
— pow(±0, y) returns +0 for y > 0 and not an odd integer.
— pow(−1, ±∞) returns 1.
— pow(+1, y) returns 1 for any y, even a NaN.
— pow(x, ±0) returns 1 for any x, even a NaN.
— pow(x, y) returns a NaN and raises the ‘‘invalid’’ floating-point exception for
finite x < 0 and finite non-integer y.
— pow(x, −∞) returns +∞ for | x | < 1.
— pow(x, −∞) returns +0 for | x | > 1.
— pow(x, +∞) returns +0 for | x | < 1.
— pow(x, +∞) returns +∞ for | x | > 1.
— pow(−∞, y) returns −0 for y an odd integer < 0.
— pow(−∞, y) returns +0 for y < 0 and not an odd integer.
— pow(−∞, y) returns −∞ for y an odd integer > 0.
— pow(−∞, y) returns +∞ for y > 0 and not an odd integer.
— pow(+∞, y) returns +0 for y < 0.
— pow(+∞, y) returns +∞ for y > 0.
F.9.4.5 [The sqrt functions]
1 sqrt is fully specified as a basic arithmetic operation in IEC 60559.
F.9.5 [Error and gamma functions]
F.9.5.1 [The erf functions]
1 — erf(±0) returns ±0.
— erf(±∞) returns ±1.
F.9.5.2 [The erfc functions]
1 — erfc(−∞) returns 2.
— erfc(+∞) returns +0.
F.9.5.3 [The lgamma functions]
1 — lgamma(1) returns +0.
— lgamma(2) returns +0.
— lgamma(x) returns +∞ and raises the ‘‘divide-by-zero’’ floating-point exception for
x a negative integer or zero.
— lgamma(−∞) returns +∞.
— lgamma(+∞) returns +∞.
F.9.5.4 [The tgamma functions]
1 — tgamma(±0) returns ±∞ and raises the ‘‘divide-by-zero’’ floating-point exception.
— tgamma(x) returns a NaN and raises the ‘‘invalid’’ floating-point exception for x a
negative integer.
— tgamma(−∞) returns a NaN and raises the ‘‘invalid’’ floating-point exception.
— tgamma(+∞) returns +∞.
F.9.6 [Nearest integer functions]
F.9.6.1 [The ceil functions]
1 — ceil(±0) returns ±0.
— ceil(±∞) returns ±∞.
2 The double version of ceil behaves as though implemented by
#include <math.h>
#include <fenv.h>
#pragma STDC FENV_ACCESS ON
double ceil(double x)
{
double result;
int save_round = fegetround();
fesetround(FE_UPWARD);
result = rint(x); // or nearbyint instead of rint
fesetround(save_round);
return result;
}
F.9.6.2 [The floor functions]
1 — floor(±0) returns ±0.
— floor(±∞) returns ±∞.
2 See the sample implementation for ceil in F.9.6.1.
F.9.6.3 [The nearbyint functions]
1 The nearbyint functions use IEC 60559 rounding according to the current rounding
direction. They do not raise the ‘‘inexact’’ floating-point exception if the result differs in
value from the argument.
— nearbyint(±0) returns ±0 (for all rounding directions).
— nearbyint(±∞) returns ±∞ (for all rounding directions).
F.9.6.4 [The rint functions]
1 The rint functions differ from the nearbyint functions only in that they do raise the
‘‘inexact’’ floating-point exception if the result differs in value from the argument.
F.9.6.5 [The lrint and llrint functions]
1 The lrint and llrint functions provide floating-to-integer conversion as prescribed
by IEC 60559. They round according to the current rounding direction. If the rounded
value is outside the range of the return type, the numeric result is unspecified and the
‘‘invalid’’ floating-point exception is raised. When they raise no other floating-point
exception and the result differs from the argument, they raise the ‘‘inexact’’ floating-point
exception.
F.9.6.6 [The round functions]
1 — round(±0) returns ±0.
— round(±∞) returns ±∞.
2 The double version of round behaves as though implemented by
#include <math.h>
#include <fenv.h>
#pragma STDC FENV_ACCESS ON
double round(double x)
{
double result;
fenv_t save_env;
feholdexcept(&save_env);
result = rint(x);
if (fetestexcept(FE_INEXACT)) {
fesetround(FE_TOWARDZERO);
result = rint(copysign(0.5 + fabs(x), x));
}
feupdateenv(&save_env);
return result;
}
The round functions may, but are not required to, raise the ‘‘inexact’’ floating-point
exception for non-integer numeric arguments, as this implementation does.
F.9.6.7 [The lround and llround functions]
1 The lround and llround functions differ from the lrint and llrint functions
with the default rounding direction just in that the lround and llround functions
round halfway cases away from zero and need not raise the ‘‘inexact’’ floating-point
exception for non-integer arguments that round to within the range of the return type.
F.9.6.8 [The trunc functions]
1 The trunc functions use IEC 60559 rounding toward zero (regardless of the current
rounding direction).
— trunc(±0) returns ±0.
— trunc(±∞) returns ±∞.
F.9.7 [Remainder functions]
F.9.7.1 [The fmod functions]
1 — fmod(±0, y) returns ±0 for y not zero.
— fmod(x, y) returns a NaN and raises the ‘‘invalid’’ floating-point exception for x
infinite or y zero.
— fmod(x, ±∞) returns x for x not infinite.
2 The double version of fmod behaves as though implemented by
#include <math.h>
#include <fenv.h>
#pragma STDC FENV_ACCESS ON
double fmod(double x, double y)
{
double result;
result = remainder(fabs(x), (y = fabs(y)));
if (signbit(result)) result += y;
return copysign(result, x);
}
F.9.7.2 [The remainder functions]
1 The remainder functions are fully specified as a basic arithmetic operation in
IEC 60559.
F.9.7.3 [The remquo functions]
1 The remquo functions follow the specifications for the remainder functions. They
have no further specifications special to IEC 60559 implementations.
F.9.8 [Manipulation functions]
F.9.8.1 [The copysign functions]
1 copysign is specified in the Appendix to IEC 60559.
F.9.8.2 [The nan functions]
1 All IEC 60559 implementations support quiet NaNs, in all floating formats.
F.9.8.3 [The nextafter functions]
1 — nextafter(x, y) raises the ‘‘overflow’’ and ‘‘inexact’’ floating-point exceptions
for x finite and the function value infinite.
— nextafter(x, y) raises the ‘‘underflow’’ and ‘‘inexact’’ floating-point