Programming languages — C (INTERNATIONAL STANDARD ISO/IEC 9899:TC3)

7.24.2.6 The

vfwscanf

function

Synopsis

#include <stdarg.h>

#include <stdio.h>

#include <wchar.h>

int vfwscanf(FILE * restrict stream,

const wchar_t * restrict format,

va_list arg);

Description

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

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.

7.24.2.7 The

vswprintf

function

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

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

The

vswprintf

function returns the number of wide characters written in the array, not

counting the terminating null wide character, or a neg ative value if an encoding error
occurred or if

or more wide characters were requested to be generated.

364 Library

§7.24.2.7

7.24.2.8 The

vswscanf

function

Synopsis

#include <stdarg.h>

#include <wchar.h>

int vswscanf(const wchar_t * restrict s,

const wchar_t * restrict format,

va_list arg);

Description

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

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.

7.24.2.9 The

vwprintf

function

Synopsis

#include <stdarg.h>

#include <wchar.h>

int vwprintf(const wchar_t * restrict format,

va_list arg);

Description

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

The

vwprintf

function returns the number of wide characters transmitted, or a negative

value if an output or encoding error occurred.

§7.24.2.9 Library

365

7.24.2.10 The

vwscanf

function

Synopsis

#include <stdarg.h>

#include <wchar.h>

int vwscanf(const wchar_t * restrict format,

va_list arg);

Description

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

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.

7.24.2.11 The

wprintf

function

Synopsis

#include <wchar.h>

int wprintf(const wchar_t * restrict format, ...);

Description

The

wprintf

function is equivalent to

fwprintf

with the argument

stdout

interposed before the arguments to

wprintf

Returns

The

wprintf

function returns the number of wide characters transmitted, or a negative

value if an output or encoding error occurred.

7.24.2.12 The

wscanf

function

Synopsis

#include <wchar.h>

int wscanf(const wchar_t * restrict format, ...);

Description

The

wscanf

function is equivalent to

fwscanf

with the argument

stdin

interposed

before the arguments to

wscanf

366 Library

§7.24.2.12

Returns

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

7.24.3.1 The

fgetwc

function

Synopsis

#include <stdio.h>

#include <wchar.h>

wint_t fgetwc(FILE *stream);

Description

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

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)

7.24.3.2 The

fgetws

function

Synopsis

#include <stdio.h>

#include <wchar.h>

wchar_t *fgetws(wchar_t * restrict s,

int n, FILE * restrict stream);

Description

The

fgetws

function reads at most one less than the number of wide characters

specified by

from the stream pointed to by

stream

into the array pointed to by

. No

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.

§7.24.3.2 Library

367

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

The

fgetws

function returns

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.

7.24.3.3 The

fputwc

function

Synopsis

#include <stdio.h>

#include <wchar.h>

wint_t fputwc(wchar_t c, FILE *stream);

Description

The

fputwc

function writes the wide character specified by

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

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

7.24.3.4 The

fputws

function

Synopsis

#include <stdio.h>

#include <wchar.h>

int fputws(const wchar_t * restrict s,

FILE * restrict stream);

Description

The

fputws

function writes the wide string pointed to by

to the stream pointed to by

stream

. The terminating null wide character is not written.

Returns

The

fputws

function returns

EOF

if a write or encoding error occurs; otherwise, it

returns a nonnegative value.

368 Library

§7.24.3.4

7.24.3.5 The

fwide

function

Synopsis

#include <stdio.h>

#include <wchar.h>

int fwide(FILE *stream, int mode);

Description

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

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.

7.24.3.6 The

getwc

function

Synopsis

#include <stdio.h>

#include <wchar.h>

wint_t getwc(FILE *stream);

Description

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

The

getwc

function returns the next wide character from the input stream pointed to by

stream

, or

WEOF

7.24.3.7 The

getwchar

function

Synopsis

#include <wchar.h>

wint_t getwchar(void);

293) If the orientation of the stream has already been determined,

fwide

does not change it.

§7.24.3.7 Library

369

Description

The

getwchar

function is equivalent to

getwc

with the argument

stdin

Returns

The

getwchar

function returns the next wide character from the input stream pointed to

stdin

, or

WEOF

7.24.3.8 The

putwc

function

Synopsis

#include <stdio.h>

#include <wchar.h>

wint_t putwc(wchar_t c, FILE *stream);

Description

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

The

putwc

function returns the wide character written, or

WEOF

7.24.3.9 The

putwchar

function

Synopsis

#include <wchar.h>

wint_t putwchar(wchar_t c);

Description

The

putwchar

function is equivalent to

putwc

with the second argument

stdout

Returns

The

putwchar

function returns the character written, or

WEOF

7.24.3.10 The

ungetwc

function

Synopsis

#include <stdio.h>

#include <wchar.h>

wint_t ungetwc(wint_t c, FILE *stream);

Description

The

ungetwc

function pushes the wide character specified by

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

370 Library

§7.24.3.10

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.

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.

If the value of

equals that of the macro

WEOF

, the operation fails and the input stream is

unchanged.

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

The

ungetwc

function returns the wide character pushed back, or

WEOF

if the operation

fails.

7.24.4 General wide string utilities

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.

Where an argument declared as

size_t n

determines the length of the array for a

function,

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.

§7.24.4 Library

371

7.24.4.1 Wide string numeric conversion functions

7.24.4.1.1 The

wcstod

wcstof

, and

wcstold

functions

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

The

wcstod

wcstof

, and

wcstold

functions convert the initial portion of the wide

string pointed to by

nptr

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.

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 6.4.4.2;

— a

, then a nonempty sequence of hexadecimal digits optionally containing a

decimal-point wide character, then an optional binary exponent part as defined in
6.4.4.2;

—

INF

INFINITY

, or any other wide string equivalent except for case

—

NAN

NAN(

n-wchar-sequence

opt

)

, or any other wide string equivalent except for

case in the

NAN

part, where:

n-wchar-sequence:

digit
nondigit
n-wchar-sequence digit
n-wchar-sequence nondigit

The subject sequence is defined as the longest initial subsequence of the input wide
string, starting with the first non-white-space wide character, that is of the expected form.

372 Library

§7.24.4.1.1

The subject sequence contains no wide characters if the input wide string is not of the
expected form.

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
6.4.4.2, 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

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

NAN(

n-wchar-sequence

opt

)

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

not a null pointer.

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.

In other than the

"C"

locale, additional locale-specific subject sequence forms may be

accepted.

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

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.

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 neg ative infinity. In either case,
the functions honor the sign of zero if floating-point arithmetic supports signed zeros.

295) An implementation may use the n-wchar sequence to determine extra information to be represented in

the NaN’s significand.

§7.24.4.1.1 Library

373

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

≤

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

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.

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.

374 Library

§7.24.4.1.1

7.24.4.1.2 The

wcstol

wcstoll

wcstoul

, and

wcstoull

functions

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

The

wcstol

wcstoll

wcstoul

, and

wcstoull

functions convert the initial

portion of the wide string pointed to by

nptr

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.

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 6.4.4.1,
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

(or

) through

(or

) 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

may optionally precede the sequence

of letters and digits, following the sign if present.

§7.24.4.1.2 Library

375

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.

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 6.4.4.1. 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.

In other than the

"C"

locale, additional locale-specific subject sequence forms may be

accepted.

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

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

7.24.4.2 Wide string copying functions

7.24.4.2.1 The

wcscpy

function

Synopsis

#include <wchar.h>

wchar_t *wcscpy(wchar_t * restrict s1,

const wchar_t * restrict s2);

Description

The

wcscpy

function copies the wide string pointed to by

(including the terminating

null wide character) into the array pointed to by

Returns

The

wcscpy

function returns the value of

376 Library

§7.24.4.2.1

7.24.4.2.2 The

wcsncpy

function

Synopsis

#include <wchar.h>

wchar_t *wcsncpy(wchar_t * restrict s1,

const wchar_t * restrict s2,

size_t n);

Description

The

wcsncpy

function copies not more than

wide characters (those that follow a null

wide character are not copied) from the array pointed to by

to the array pointed to by

297)

If the array pointed to by

is a wide string that is shorter than

wide characters, null

wide characters are appended to the copy in the array pointed to by

, until

wide

characters in all have been written.

Returns

The

wcsncpy

function returns the value of

7.24.4.2.3 The

wmemcpy

function

Synopsis

#include <wchar.h>

wchar_t *wmemcpy(wchar_t * restrict s1,

const wchar_t * restrict s2,

size_t n);

Description

The

wmemcpy

function copies

wide characters from the object pointed to by

to the

object pointed to by

Returns

The

wmemcpy

function returns the value of

297) Thus, if there is no null wide character in the first

wide characters of the array pointed to by

, the

result will not be null-terminated.

§7.24.4.2.3 Library

377

7.24.4.2.4 The

wmemmove

function

Synopsis

#include <wchar.h>

wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,

size_t n);

Description

The

wmemmove

function copies

wide characters from the object pointed to by

the object pointed to by

. Copying takes place as if the

wide characters from the

object pointed to by

are first copied into a temporary array of

wide characters that

does not overlap the objects pointed to by

, and then the

wide characters from

the temporary array are copied into the object pointed to by

Returns

The

wmemmove

function returns the value of

7.24.4.3 Wide string concatenation functions

7.24.4.3.1 The

wcscat

function

Synopsis

#include <wchar.h>

wchar_t *wcscat(wchar_t * restrict s1,

const wchar_t * restrict s2);

Description

The

wcscat

function appends a copy of the wide string pointed to by

(including the

terminating null wide character) to the end of the wide string pointed to by

. The initial

wide character of

overwrites the null wide character at the end of

Returns

The

wcscat

function returns the value of

7.24.4.3.2 The

wcsncat

function

Synopsis

#include <wchar.h>

wchar_t *wcsncat(wchar_t * restrict s1,

const wchar_t * restrict s2,

size_t n);

Description

The

wcsncat

function appends not more than

wide characters (a null wide character

and those that follow it are not appended) from the array pointed to by

to the end of

378 Library

§7.24.4.3.2

the wide string pointed to by

. The initial wide character of

overwrites the null

wide character at the end of

. A terminating null wide character is always appended to

the result.

298)

Returns

The

wcsncat

function returns the value of

7.24.4.4 Wide string comparison functions

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

7.24.4.4.1 The

wcscmp

function

Synopsis

#include <wchar.h>

int wcscmp(const wchar_t *s1, const wchar_t *s2);

Description

The

wcscmp

function compares the wide string pointed to by

to the wide string

pointed to by

Returns

The

wcscmp

function returns an integer greater than, equal to, or less than zero,

accordingly as the wide string pointed to by

is greater than, equal to, or less than the

wide string pointed to by

7.24.4.4.2 The

wcscoll

function

Synopsis

#include <wchar.h>

int wcscoll(const wchar_t *s1, const wchar_t *s2);

Description

The

wcscoll

function compares the wide string pointed to by

to the wide string

pointed to by

, both interpreted as appropriate to the

LC_COLLATE

category of the

current locale.

Returns

The

wcscoll

function returns an integer greater than, equal to, or less than zero,

accordingly as the wide string pointed to by

is greater than, equal to, or less than the

298) Thus, the maximum number of wide characters that can end up in the array pointed to by

wcslen(s1)+n+1

§7.24.4.4.2 Library

379

wide string pointed to by

when both are interpreted as appropriate to the current

locale.

7.24.4.4.3 The

wcsncmp

function

Synopsis

#include <wchar.h>

int wcsncmp(const wchar_t *s1, const wchar_t *s2,

size_t n);

Description

The

wcsncmp

function compares not more than

wide characters (those that follow a

null wide character are not compared) from the array pointed to by

to the array

pointed to by

Returns

The

wcsncmp

function returns an integer greater than, equal to, or less than zero,

accordingly as the possibly null-terminated array pointed to by

is greater than, equal

to, or less than the possibly null-terminated array pointed to by

7.24.4.4.4 The

wcsxfrm

function

Synopsis

#include <wchar.h>

size_t wcsxfrm(wchar_t * restrict s1,

const wchar_t * restrict s2,

size_t n);

Description

The

wcsxfrm

function transforms the wide string pointed to by

and places the

resulting wide string into the array pointed to by

. 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

wide characters are placed

into the resulting array pointed to by

, including the terminating null wide character. If

is zero,

is permitted to be a null pointer.

Returns

The

wcsxfrm

function returns the length of the transformed wide string (not including

the terminating null wide character). If the value returned is

or greater, the contents of

the array pointed to by

are indeterminate.

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

380 Library

§7.24.4.4.4

1 + wcsxfrm(NULL, s, 0)

7.24.4.4.5 The

wmemcmp

function

Synopsis

#include <wchar.h>

int wmemcmp(const wchar_t *s1, const wchar_t *s2,

size_t n);

Description

The

wmemcmp

function compares the first

wide characters of the object pointed to by

to the first

wide characters of the object pointed to by

Returns

The

wmemcmp

function returns an integer greater than, equal to, or less than zero,

accordingly as the object pointed to by

is greater than, equal to, or less than the object

pointed to by

7.24.4.5 Wide string search functions

7.24.4.5.1 The

wcschr

function

Synopsis

#include <wchar.h>

wchar_t *wcschr(const wchar_t *s, wchar_t c);

Description

The

wcschr

function locates the first occurrence of

in the wide string pointed to by

The terminating null wide character is considered to be part of the wide string.

Returns

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.

7.24.4.5.2 The

wcscspn

function

Synopsis

#include <wchar.h>

size_t wcscspn(const wchar_t *s1, const wchar_t *s2);

Description

The

wcscspn

function computes the length of the maximum initial segment of the wide

string pointed to by

which consists entirely of wide characters not from the wide

string pointed to by

§7.24.4.5.2 Library

381

Returns

The

wcscspn

function returns the length of the segment.

7.24.4.5.3 The

wcspbrk

function

Synopsis

#include <wchar.h>

wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);

Description

The

wcspbrk

function locates the first occurrence in the wide string pointed to by

any wide character from the wide string pointed to by

Returns

The

wcspbrk

function returns a pointer to the wide character in

, or a null pointer if

no wide character from

occurs in

7.24.4.5.4 The

wcsrchr

function

Synopsis

#include <wchar.h>

wchar_t *wcsrchr(const wchar_t *s, wchar_t c);

Description

The

wcsrchr

function locates the last occurrence of

in the wide string pointed to by

. The terminating null wide character is considered to be part of the wide string.

Returns

The

wcsrchr

function returns a pointer to the wide character, or a null pointer if

does

not occur in the wide string.

7.24.4.5.5 The

wcsspn

function

Synopsis

#include <wchar.h>

size_t wcsspn(const wchar_t *s1, const wchar_t *s2);

Description

The

wcsspn

function computes the length of the maximum initial segment of the wide

string pointed to by

which consists entirely of wide characters from the wide string

pointed to by

Returns

The

wcsspn

function returns the length of the segment.

382 Library

§7.24.4.5.5

7.24.4.5.6 The

wcsstr

function

Synopsis

#include <wchar.h>

wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);

Description

The

wcsstr

function locates the first occurrence in the wide string pointed to by

the sequence of wide characters (excluding the terminating null wide character) in the
wide string pointed to by

Returns

The

wcsstr

function returns a pointer to the located wide string, or a null pointer if the

wide string is not found. If

points to a wide string with zero length, the function

returns

7.24.4.5.7 The

wcstok

function

Synopsis

#include <wchar.h>

wchar_t *wcstok(wchar_t * restrict s1,

const wchar_t * restrict s2,

wchar_t ** restrict ptr);

Description

A sequence of calls to the

wcstok

function breaks the wide string pointed to by

into

a sequence of tokens, each of which is delimited by a wide character from the wide string
pointed to by

. 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.

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

may be

different from call to call.

The first call in the sequence searches the wide string pointed to by

for the first wide

character that is not contained in the current separator wide string pointed to by

. If no

such wide character is found, then there are no tokens in the wide string pointed to by

and the

wcstok

function returns a null pointer. If such a wide character is found, it is

the start of the first token.

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

§7.24.4.5.7 Library

383

extends to the end of the wide string pointed to by

, 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.

In all cases, the

wcstok

function stores sufficient information in the pointer pointed to

ptr

so that subsequent calls, with a null pointer for

and the unmodified pointer

value for

ptr

, shall start searching just past the element overwritten by a null wide

character (if any).

Returns

The

wcstok

function returns a pointer to the first wide character of a token, or a null

pointer if there is no token.

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

7.24.4.5.8 The

wmemchr

function

Synopsis

#include <wchar.h>

wchar_t *wmemchr(const wchar_t *s, wchar_t c,

size_t n);

Description

The

wmemchr

function locates the first occurrence of

in the initial

wide characters of

the object pointed to by

Returns

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.

384 Library

§7.24.4.5.8

7.24.4.6 Miscellaneous functions

7.24.4.6.1 The

wcslen

function

Synopsis

#include <wchar.h>

size_t wcslen(const wchar_t *s);

Description

The

wcslen

function computes the length of the wide string pointed to by

Returns

The

wcslen

function returns the number of wide characters that precede the terminating

null wide character.

7.24.4.6.2 The

wmemset

function

Synopsis

#include <wchar.h>

wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);

Description

The

wmemset

function copies the value of

into each of the first

wide characters of

the object pointed to by

Returns

The

wmemset

function returns the value of

7.24.5 Wide character time conversion functions

7.24.5.1 The

wcsftime

function

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

The

wcsftime

function is equivalent to the

strftime

function, except that:

— The argument

points to the initial element of an array of wide characters into which

the generated output is to be placed.

§7.24.5.1 Library

385

— 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

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

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

The header

<wchar.h>

declares an extended set of functions useful for conversion

between multibyte characters and wide characters.

Most of the following functions — those that are listed as ‘‘restartable’’, 7.24.6.3 and
7.24.6.4 — 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.

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)

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.

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.

386 Library

§7.24.6

and ‘‘hard to ignore’’ message (see LIA−1 subclause 6.1.2)

LIA−1 does not make the distinction between floating-point and integer for ‘‘undefined’’.
This documentation makes that distinction because

<fenv.h>

covers only the floating-

point indicators.

H.3.1.2 Traps

C is compatible with LIA−1’s trap requirements for arithmetic operations, but not for
math library functions (which are not permitted to generate any externally visible
exceptional conditions). An implementation can provide an alternative of notification
through termination with a ‘‘hard-to-ignore’’ message (see LIA−1 subclause 6.1.3).

LIA−1 does not require that traps be precise.

C does require that

SIGFPE

be the signal corresponding to arithmetic exceptions, if there

is any signal raised for them.

C supports signal handlers for

SIGFPE

and allows trapping of arithmetic exceptions.

When arithmetic exceptions do trap, C’s signal-handler mechanism allows trap-and-
terminate (either default implementation behavior or user replacement for it) or trap-and-
resume, at the programmer’s option.

486 Language independent arithmetic

§H.3.1.2

Annex I

(informative)

Common warnings

An implementation may generate warnings in many situations, none of which are
specified as part of this International Standard. The following are a few of the more
common situations.

— A new

struct

union

type appears in a function prototype (6.2.1, 6.7.2.3).

— A block with initialization of an object that has automatic storage duration is jumped

into (6.2.4).

— An implicit narrowing conversion is encountered, such as the assignment of a

long

int

or a

double

to an

int

, or a pointer to

void

to a pointer to any type other than

a character type (6.3).

— A hexadecimal floating constant cannot be represented exactly in its evaluation format

(6.4.4.2).

— An integer character constant includes more than one character or a wide character

constant includes more than one multibyte character (6.4.4.4).

— The characters

are found in a comment (6.4.7).

— An ‘‘unordered’’ binary operator (not comma,

, or

) contains a side effect to an

lvalue in one operand, and a side effect to, or an access to the value of, the identical
lvalue in the other operand (6.5).

— A function is called but no prototype has been supplied (6.5.2.2).

— The arguments in a function call do not agree in number and type with those of the

parameters in a function definition that is not a prototype (6.5.2.2).

— An object is defined but not used (6.7).

— A value is given to an object of an enumerated type other than by assignment of an

enumeration constant that is a member of that type, or an enumeration object that has
the same type, or the value of a function that returns the same enumerated type
(6.7.2.2).

— An aggregate has a partly bracketed initialization (6.7.7).

— A statement cannot be reached (6.8).

— A statement with no apparent effect is encountered (6.8).

— A constant expression is used as the controlling expression of a selection statement

(6.8.4).

§I Common warnings 487

Annex J

(informative)

Portability issues

This annex collects some information about portability that appears in this International
Standard.

J.1 Unspecified behavior

The following are unspecified:

— The manner and timing of static initialization (5.1.2).

— The termination status returned to the hosted environment if the return type of

main

is not compatible with int (5.1.2.2.3).

— The behavior of the display device if a printing character is written when the active

position is at the final position of a line (5.2.2).

— The behavior of the display device if a backspace character is written when the active

position is at the initial position of a line (5.2.2).

— The behavior of the display device if a horizontal tab character is written when the

active position is at or past the last defined horizontal tabulation position (5.2.2).

— The behavior of the display device if a vertical tab character is written when the active

position is at or past the last defined vertical tabulation position (5.2.2).

— How an extended source character that does not correspond to a universal character

name counts toward the significant initial characters in an external identifier (5.2.4.1).

— Many aspects of the representations of types (6.2.6).

— The value of padding bytes when storing values in structures or unions (6.2.6.1).

— The value of a union member other than the last one stored into (6.2.6.1).

— The representation used when storing a value in an object that has more than one

object representation for that value (6.2.6.1).

— The values of any padding bits in integer representations (6.2.6.2).

— Whether certain operators can generate negative zeros and whether a negative zero

becomes a normal zero when stored in an object (6.2.6.2).

— Whether two string literals result in distinct arrays (6.4.5).

— The order in which subexpressions are evaluated and the order in which side effects

take place, except as specified for the function-call

()

, and comma

operators (6.5).

§J.1 Portability issues 489

— The order in which the function designator, arguments, and subexpressions within the

arguments are evaluated in a function call (6.5.2.2).

— The order of side effects among compound literal initialization list expressions

(6.5.2.5).

— The order in which the operands of an assignment operator are evaluated (6.5.16).

— The alignment of the addressable storage unit allocated to hold a bit-field (6.7.2.1).

— Whether a call to an inline function uses the inline definition or the external definition

of the function (6.7.4).

— Whether or not a size expression is evaluated when it is part of the operand of a

sizeof

operator and changing the value of the size expression would not affect the

result of the operator (6.7.5.2).

— The order in which any side effects occur among the initialization list expressions in

an initializer (6.7.8).

— The layout of storage for function parameters (6.9.1).

— When a fully expanded macro replacement list contains a function-like macro name

as its last preprocessing token and the next preprocessing token from the source file is
a

(

, and the fully expanded replacement of that macro ends with the name of the first

macro and the next preprocessing token from the source file is again a

(

, whether that

is considered a nested replacement (6.10.3).

— The order in which

and

operations are evaluated during macro substitution

(6.10.3.2, 6.10.3.3).

— Whether

errno

is a macro or an identifier with external linkage (7.5).

— The state of the floating-point status flags when execution passes from a part of the

program translated with

FENV_ACCESS

‘‘off’’ to a part translated with

FENV_ACCESS

‘‘on’’ (7.6.1).

— The order in which

feraiseexcept

raises floating-point exceptions, except as

stated in F.7.6 (7.6.2.3).

— Whether

math_errhandling

is a macro or an identifier with external linkage

(7.12).

— The results of the

frexp

functions when the specified value is not a floating-point

number (7.12.6.4).

— The numeric result of the

ilogb

functions when the correct value is outside the

range of the return type (7.12.6.5, F.9.3.5).

— The result of rounding when the value is out of range (7.12.9.5, 7.12.9.7, F.9.6.5).

490 Portability issues §J.1

— The value stored by the

remquo

functions in the object pointed to by

quo

when

zero (7.12.10.3).

— Whether

setjmp

is a macro or an identifier with external linkage (7.13).

— Whether

va_copy

and

va_end

are macros or identifiers with external linkage

(7.15.1).

— The hexadecimal digit before the decimal point when a non-normalized floating-point

number is printed with an

conversion specifier (7.19.6.1, 7.24.2.1).

— The value of the file position indicator after a successful call to the

ungetc

function

for a text stream, or the

ungetwc

function for any stream, until all pushed-back

characters are read or discarded (7.19.7.11, 7.24.3.10).

— The details of the value stored by the

fgetpos

function (7.19.9.1).

— The details of the value returned by the

ftell

function for a text stream (7.19.9.4).

— Whether the

strtod

strtof

strtold

wcstod

wcstof

, and

wcstold

functions convert a minus-signed sequence to a negative number directly or by
negating the value resulting from converting the corresponding unsigned sequence
(7.20.1.3, 7.24.4.1.1).

— The order and contiguity of storage allocated by successive calls to the

calloc

malloc

, and

realloc

functions (7.20.3).

— The amount of storage allocated by a successful call to the

calloc

malloc

, or

realloc

function when 0 bytes was requested (7.20.3).

— Which of two elements that compare as equal is matched by the

bsearch

function

(7.20.5.1).

— The order of two elements that compare as equal in an array sorted by the

qsort

function (7.20.5.2).

— The encoding of the calendar time returned by the

time

function (7.23.2.4).

— The characters stored by the

strftime

wcsftime

function if any of the time

values being converted is outside the normal range (7.23.3.5, 7.24.5.1).

— The conversion state after an encoding error occurs (7.24.6.3.2, 7.24.6.3.3, 7.24.6.4.1,

7.24.6.4.2,

— The resulting value when the ‘‘invalid’’ floating-point exception is raised during

IEC 60559 floating to integer conversion (F.4).

— Whether conversion of non-integer IEC 60559 floating values to integer raises the

‘‘inexact’’ floating-point exception (F.4).

§J.1 Portability issues 491

— Whether or when library functions in

<math.h>

raise the ‘‘inexact’’ floating-point

exception in an IEC 60559 conformant implementation (F.9).

— Whether or when library functions in

<math.h>

raise an undeserved ‘‘underflow’’

floating-point exception in an IEC 60559 conformant implementation (F.9).

— The exponent value stored by

frexp

for a NaN or infinity (F.9.3.4).

— The numeric result returned by the

lrint

llrint

lround

, and

llround

functions if the rounded value is outside the range of the return type (F.9.6.5, F.9.6.7).

— The sign of one part of the

complex

result of several math functions for certain

exceptional values in IEC 60559 compatible implementations (G.6.1.1, G.6.2.2,
G.6.2.3, G.6.2.4, G.6.2.5, G.6.2.6, G.6.3.1, G.6.4.2).

J.2 Undefined behavior

The behavior is undefined in the following circumstances:

— A ‘‘shall’’ or ‘‘shall not’’ requirement that appears outside of a constraint is violated

(clause 4).

— A nonempty source file does not end in a new-line character which is not immediately

preceded by a backslash character or ends in a partial preprocessing token or
comment (5.1.1.2).

— Token concatenation produces a character sequence matching the syntax of a

universal character name (5.1.1.2).

— A program in a hosted environment does not define a function named

main

using one

of the specified forms (5.1.2.2.1).

— A character not in the basic source character set is encountered in a source file, except

in an identifier, a character constant, a string literal, a header name, a comment, or a
preprocessing token that is never converted to a token (5.2.1).

— An identifier, comment, string literal, character constant, or header name contains an

invalid multibyte character or does not begin and end in the initial shift state (5.2.1.2).

— The same identifier has both internal and external linkage in the same translation unit

(6.2.2).

— An object is referred to outside of its lifetime (6.2.4).

— The value of a pointer to an object whose lifetime has ended is used (6.2.4).

— The value of an object with automatic storage duration is used while it is

indeterminate (6.2.4, 6.7.8, 6.8).

— A trap representation is read by an lvalue expression that does not have character type

(6.2.6.1).

492 Portability issues §J.2

— A trap representation is produced by a side effect that modifies any part of the object

using an lvalue expression that does not have character type (6.2.6.1).

— The arguments to certain operators are such that could produce a negative zero result,

but the implementation does not support negative zeros (6.2.6.2).

— Two declarations of the same object or function specify types that are not compatible

(6.2.7).

— Conversion to or from an integer type produces a value outside the range that can be

represented (6.3.1.4).

— Demotion of one real floating type to another produces a value outside the range that

can be represented (6.3.1.5).

— An lvalue does not designate an object when evaluated (6.3.2.1).

— A non-array lvalue with an incomplete type is used in a context that requires the value

of the designated object (6.3.2.1).

— An lvalue having array type is converted to a pointer to the initial element of the

array, and the array object has register storage class (6.3.2.1).

— An attempt is made to use the value of a void expression, or an implicit or explicit

conversion (except to

void

) is applied to a void expression (6.3.2.2).

— Conversion of a pointer to an integer type produces a value outside the range that can

be represented (6.3.2.3).

— Conversion between two pointer types produces a result that is incorrectly aligned

(6.3.2.3).

— A pointer is used to call a function whose type is not compatible with the pointed-to

type (6.3.2.3).

— An unmatched

character is encountered on a logical source line during

tokenization (6.4).

— A reserved keyword token is used in translation phase 7 or 8 for some purpose other

than as a keyword (6.4.1).

— A universal character name in an identifier does not designate a character whose

encoding falls into one of the specified ranges (6.4.2.1).

— The initial character of an identifier is a universal character name designating a digit

(6.4.2.1).

— Two identifiers differ only in nonsignificant characters (6.4.2.1).

— The identifier

_ _func_ _

is explicitly declared (6.4.2.2).

§J.2 Portability issues 493

— The program attempts to modify a string literal (6.4.5).

— The characters

, or

occur in the sequence between the

and

delimiters, or the characters

, or

occur in the sequence between the

delimiters, in a header name preprocessing token (6.4.7).

— Between two sequence points, an object is modified more than once, or is modified

and the prior value is read other than to determine the value to be stored (6.5).

— An exceptional condition occurs during the evaluation of an expression (6.5).

— An object has its stored value accessed other than by an lvalue of an allowable type

(6.5).

— An attempt is made to modify the result of a function call, a conditional operator, an

assignment operator, or a comma operator, or to access it after the next sequence
point (6.5.2.2, 6.5.15, 6.5.16, 6.5.17).

— For a call to a function without a function prototype in scope, the number of

arguments does not equal the number of parameters (6.5.2.2).

— For call to a function without a function prototype in scope where the function is

defined with a function prototype, either the prototype ends with an ellipsis or the
types of the arguments after promotion are not compatible with the types of the
parameters (6.5.2.2).

— For a call to a function without a function prototype in scope where the function is not

defined with a function prototype, the types of the arguments after promotion are not
compatible with those of the parameters after promotion (with certain exceptions)
(6.5.2.2).

— A function is defined with a type that is not compatible with the type (of the

expression) pointed to by the expression that denotes the called function (6.5.2.2).

— The operand of the unary

operator has an invalid value (6.5.3.2).

— A pointer is converted to other than an integer or pointer type (6.5.4).

— The value of the second operand of the

operator is zero (6.5.5).

— Addition or subtraction of a pointer into, or just beyond, an array object and an

integer type produces a result that does not point into, or just beyond, the same array
object (6.5.6).

— Addition or subtraction of a pointer into, or just beyond, an array object and an

integer type produces a result that points just beyond the array object and is used as
the operand of a unary

operator that is evaluated (6.5.6).

— Pointers that do not point into, or just beyond, the same array object are subtracted

(6.5.6).

494 Portability issues §J.2

Programming languages — C (INTERNATIONAL STANDARD ISO/IEC 9899:TC3) - page 17