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

7.21.5.6 The

strspn

function

Synopsis

1

#include <string.h>

size_t strspn(const char *s1, const char *s2);

Description

2

The

strspn

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

pointed to by

s1

which consists entirely of characters from the string pointed to by

s2

.

Returns

3

The

strspn

function returns the length of the segment.

7.21.5.7 The

strstr

function

Synopsis

1

#include <string.h>

char *strstr(const char *s1, const char *s2);

Description

2

The

strstr

function locates the first occurrence in the string pointed to by

s1

of the

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

s2

.

Returns

3

The

strstr

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

is not found. If

s2

points to a string with zero length, the function returns

s1

.

7.21.5.8 The

strtok

function

Synopsis

1

#include <string.h>

char *strtok(char * restrict s1,

const char * restrict s2);

Description

2

A sequence of calls to the

strtok

function breaks the string pointed to by

s1

into a

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

s2

. The first call in the sequence has a non-null first argument; subsequent calls in the

sequence have a null first argument. The separator string pointed to by

s2

may be

different from call to call.

3

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

s1

for the first character

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

s2

. If no such character

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

s1

and the

strtok

function

332 Library

§7.21.5.8

returns a null pointer. If such a character is found, it is the start of the first token.

4

The

strtok

function then searches from there for a character that is contained in the

current separator string. If no such character is found, the current token extends to the
end of the string pointed to by

s1

, and subsequent searches for a token will return a null

pointer. If such a character is found, it is overwritten by a null character, which
terminates the current token. The

strtok

function saves a pointer to the following

character, from which the next search for a token will start.

5

Each subsequent call, with a null pointer as the value of the first argument, starts
searching from the saved pointer and behaves as described above.

6

The implementation shall behave as if no library function calls the

strtok

function.

Returns

7

The

strtok

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

if there is no token.

8

EXAMPLE

#include <string.h>

static char str[] = "?a???b,,,#c";

char *t;

t = strtok(str, "?");

// t

points to the token

"a"

t = strtok(NULL, ",");

// t

points to the token

"??b"

t = strtok(NULL, "#,"); // t

points to the token

"c"

t = strtok(NULL, "?");

// t

is a null pointer

7.21.6 Miscellaneous functions

7.21.6.1 The

memset

function

Synopsis

1

#include <string.h>

void *memset(void *s, int c, size_t n);

Description

2

The

memset

function copies the value of

c

(converted to an

unsigned char

) into

each of the first

n

characters of the object pointed to by

s

.

Returns

3

The

memset

function returns the value of

s

.

§7.21.6.1 Library

333

7.21.6.2 The

strerror

function

Synopsis

1

#include <string.h>

char *strerror(int errnum);

Description

2

The

strerror

function maps the number in

errnum

to a message string. Typically,

the values for

errnum

come from

errno

, but

strerror

shall map any value of type

int

to a message.

3

The implementation shall behave as if no library function calls the

strerror

function.

Returns

4

The

strerror

function returns a pointer to the string, the contents of which are locale-

specific. The array pointed to shall not be modified by the program, but may be
overwritten by a subsequent call to the

strerror

function.

7.21.6.3 The

strlen

function

Synopsis

1

#include <string.h>

size_t strlen(const char *s);

Description

2

The

strlen

function computes the length of the string pointed to by

s

.

Returns

3

The

strlen

function returns the number of characters that precede the terminating null

character.

334 Library

§7.21.6.3

7.22 Type-generic math

<tgmath.h>

1

The header

<tgmath.h>

includes the headers

<math.h>

and

<complex.h>

and

defines several type-generic macros.

2

Of the

<math.h>

and

<complex.h>

functions without an

f

(

float

) or

l

(

long

double

) suffix, several have one or more parameters whose corresponding real type is

double

. For each such function, except

modf

, there is a corresponding type-generic

macro.

272)

The parameters whose corresponding real type is

double

in the function

synopsis are generic parameters. Use of the macro invokes a function whose
corresponding real type and type domain are determined by the arguments for the generic
parameters.

273)

3

Use of the macro invokes a function whose generic parameters have the corresponding
real type determined as follows:

— First, if any argument for generic parameters has type

long double

, the type

determined is

long double

.

— Otherwise, if any argument for generic parameters has type

double

or is of integer

type, the type determined is

double

.

— Otherwise, the type determined is

float

.

4

For each unsuffixed function in

<math.h>

for which there is a function in

<complex.h>

with the same name except for a

c

prefix, the corresponding type-

generic macro (for both functions) has the same name as the function in

<math.h>

. The

corresponding type-generic macro for

fabs

and

cabs

is

fabs

.

272) Like other function-like macros in Standard libraries, each type-generic macro can be suppressed to

make available the corresponding ordinary function.

273) If the type of the argument is not compatible with the type of the parameter for the selected function,

the behavior is undefined.

§7.22 Library

335

<math.h> <complex.h>

type-generic

function function

macro

acos cacos acos

asin casin asin

atan catan atan

acosh cacosh acosh

asinh casinh asinh

atanh catanh atanh

cos ccos cos

sin csin sin

tan ctan tan

cosh ccosh cosh

sinh csinh sinh

tanh ctanh tanh

exp cexp exp

log clog log

pow cpow pow

sqrt csqrt sqrt

fabs cabs

fabs

If at least one argument for a generic parameter is complex, then use of the macro invokes
a complex function; otherwise, use of the macro invokes a real function.

5

For each unsuffixed function in

<math.h>

without a

c

-prefixed counterpart in

<complex.h>

(except

modf

), the corresponding type-generic macro has the same

name as the function. These type-generic macros are:

atan2

cbrt

ceil

copysign

erf

erfc

exp2

expm1

fdim

floor

fma

fmax

fmin

fmod

frexp

hypot

ilogb

ldexp

lgamma

llrint

llround

log10

log1p

log2

logb

lrint

lround

nearbyint

nextafter

nexttoward

remainder

remquo

rint

round

scalbn

scalbln

tgamma

trunc

If all arguments for generic parameters are real, then use of the macro invokes a real
function; otherwise, use of the macro results in undefined behavior.

6

For each unsuffixed function in

<complex.h>

that is not a

c

-prefixed counterpart to a

function in

<math.h>

, the corresponding type-generic macro has the same name as the

function. These type-generic macros are:

336 Library

§7.22

carg

cimag

conj

cproj

creal

Use of the macro with any real or complex argument invokes a complex function.

7

EXAMPLE With the declarations

#include <tgmath.h>

int n;

float f;

double d;

long double ld;

float complex fc;

double complex dc;

long double complex ldc;

functions invoked by use of type-generic macros are shown in the following table:

macro use

invokes

exp(n) exp(n)

, the function

acosh(f) acoshf(f)

sin(d) sin(d)

, the function

atan(ld) atanl(ld)

log(fc) clogf(fc)

sqrt(dc) csqrt(dc)

pow(ldc, f)

cpowl(ldc, f)

remainder(n, n)

remainder(n, n)

, the function

nextafter(d, f)

nextafter(d, f)

, the function

nexttoward(f, ld)

nexttowardf(f, ld)

copysign(n, ld)

copysignl(n, ld)

ceil(fc)

undefined behavior

rint(dc)

undefined behavior

fmax(ldc, ld)

undefined behavior

carg(n) carg(n)

, the function

cproj(f) cprojf(f)

creal(d) creal(d)

, the function

cimag(ld) cimagl(ld)

fabs(fc) cabsf(fc)

carg(dc) carg(dc)

, the function

cproj(ldc) cprojl(ldc)

§7.22 Library

337

7.23 Date and time

<time.h>

7.23.1 Components of time

1

The header

<time.h>

defines two macros, and declares several types and functions for

manipulating time. Many functions deal with a calendar time that represents the current
date (according to the Gregorian calendar) and time. Some functions deal with local
time, which is the calendar time expressed for some specific time zone, and with Daylight
Saving Time, which is a temporary change in the algorithm for determining local time.
The local time zone and Daylight Saving Time are implementation-defined.

2

The macros defined are

NULL

(described in 7.17); and

CLOCKS_PER_SEC

which expands to an expression with type

clock_t

(described below) that is the

number per second of the value returned by the

clock

function.

3

The types declared are

size_t

(described in 7.17);

clock_t

and

time_t

which are arithmetic types capable of representing times; and

struct tm

which holds the components of a calendar time, called the broken-down time.

4

The range and precision of times representable in

clock_t

and

time_t

are

implementation-defined. The

tm

structure shall contain at least the following members,

in any order. The semantics of the members and their normal ranges are expressed in the
comments.

274)

int tm_sec;

//

seconds after the minute — [0, 60]

int tm_min;

//

minutes after the hour — [0, 59]

int tm_hour;

//

hours since midnight — [0, 23]

int tm_mday;

//

day of the month — [1, 31]

int tm_mon;

//

months since January — [0, 11]

int tm_year;

//

years since 1900

int tm_wday;

//

days since Sunday — [0, 6]

int tm_yday;

//

days since January 1 — [0, 365]

int tm_isdst; //

Daylight Saving Time flag

274) The range [0, 60] for

tm_sec

allows for a positive leap second.

338 Library

§7.23.1

The value of

tm_isdst

is positive if Daylight Saving Time is in effect, zero if Daylight

Saving Time is not in effect, and negative if the information is not available.

7.23.2 Time manipulation functions

7.23.2.1 The

clock

function

Synopsis

1

#include <time.h>

clock_t clock(void);

Description

2

The

clock

function determines the processor time used.

Returns

3

The

clock

function returns the implementation’s best approximation to the processor

time used by the program since the beginning of an implementation-defined era related
only to the program invocation. To determine the time in seconds, the value returned by
the

clock

function should be divided by the value of the macro

CLOCKS_PER_SEC

. If

the processor time used is not available or its value cannot be represented, the function
returns the value

(clock_t)(-1)

.

275)

7.23.2.2 The

difftime

function

Synopsis

1

#include <time.h>

double difftime(time_t time1, time_t time0);

Description

2

The

difftime

function computes the difference between two calendar times:

time1 -

time0

.

Returns

3

The

difftime

function returns the difference expressed in seconds as a

double

.

275) In order to measure the time spent in a program, the

clock

function should be called at the start of

the program and its return value subtracted from the value returned by subsequent calls.

§7.23.2.2 Library

339

7.23.2.3 The

mktime

function

Synopsis

1

#include <time.h>

time_t mktime(struct tm *timeptr);

Description

2

The

mktime

function converts the broken-down time, expressed as local time, in the

structure pointed to by

timeptr

into a calendar time value with the same encoding as

that of the values returned by the

time

function. The original values of the

tm_wday

and

tm_yday

components of the structure are ignored, and the original values of the

other components are not restricted to the ranges indicated above.

276)

On successful

completion, the values of the

tm_wday

and

tm_yday

components of the structure are

set appropriately, and the other components are set to represent the specified calendar
time, but with their values forced to the ranges indicated above; the final value of

tm_mday

is not set until

tm_mon

and

tm_year

are determined.

Returns

3

The

mktime

function returns the specified calendar time encoded as a value of type

time_t

. If the calendar time cannot be represented, the function returns the value

(time_t)(-1)

.

4

EXAMPLE What day of the week is July 4, 2001?

#include <stdio.h>

#include <time.h>

static const char *const wday[] = {

"Sunday", "Monday", "Tuesday", "Wednesday",

"Thursday", "Friday", "Saturday", "-unknown-"

};

struct tm time_str;

/*

...

*/

276) Thus, a positive or zero value for

tm_isdst

causes the

mktime

function to presume initially that

Daylight Saving Time, respectively, is or is not in effect for the specified time. A neg ative value
causes it to attempt to determine whether Daylight Saving Time is in effect for the specified time.

340 Library

§7.23.2.3

time_str.tm_year = 2001 - 1900;

time_str.tm_mon = 7 - 1;

time_str.tm_mday = 4;

time_str.tm_hour = 0;

time_str.tm_min = 0;

time_str.tm_sec = 1;

time_str.tm_isdst = -1;

if (mktime(&time_str) == (time_t)(-1))

time_str.tm_wday = 7;

printf("%s\n", wday[time_str.tm_wday]);

7.23.2.4 The

time

function

Synopsis

1

#include <time.h>

time_t time(time_t *timer);

Description

2

The

time

function determines the current calendar time. The encoding of the value is

unspecified.

Returns

3

The

time

function returns the implementation’s best approximation to the current

calendar time. The value

(time_t)(-1)

is returned if the calendar time is not

available. If

timer

is not a null pointer, the return value is also assigned to the object it

points to.

7.23.3 Time conversion functions

1

Except for the

strftime

function, these functions each return a pointer to one of two

types of static objects: a broken-down time structure or an array of

char

. Execution of

any of the functions that return a pointer to one of these object types may overwrite the
information in any object of the same type pointed to by the value returned from any
previous call to any of them. The implementation shall behave as if no other library
functions call these functions.

7.23.3.1 The

asctime

function

Synopsis

1

#include <time.h>

char *asctime(const struct tm *timeptr);

Description

2

The

asctime

function converts the broken-down time in the structure pointed to by

timeptr

into a string in the form

Sun Sep 16 01:03:52 1973\n\0

§7.23.3.1 Library

341

using the equivalent of the following algorithm.

char *asctime(const struct tm *timeptr)

{

static const char wday_name[7][3] = {

"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"

};

static const char mon_name[12][3] = {

"Jan", "Feb", "Mar", "Apr", "May", "Jun",

"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"

};

static char result[26];

sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n",

wday_name[timeptr->tm_wday],

mon_name[timeptr->tm_mon],

timeptr->tm_mday, timeptr->tm_hour,

timeptr->tm_min, timeptr->tm_sec,

1900 + timeptr->tm_year);

return result;

}

Returns

3

The

asctime

function returns a pointer to the string.

7.23.3.2 The

ctime

function

Synopsis

1

#include <time.h>

char *ctime(const time_t *timer);

Description

2

The

ctime

function converts the calendar time pointed to by

timer

to local time in the

form of a string. It is equivalent to

asctime(localtime(timer))

Returns

3

The

ctime

function returns the pointer returned by the

asctime

function with that

broken-down time as argument.

Forward references: the

localtime

function (7.23.3.4).

342 Library

§7.23.3.2

7.23.3.3 The

gmtime

function

Synopsis

1

#include <time.h>

struct tm *gmtime(const time_t *timer);

Description

2

The

gmtime

function converts the calendar time pointed to by

timer

into a broken-

down time, expressed as UTC.

Returns

3

The

gmtime

function returns a pointer to the broken-down time, or a null pointer if the

specified time cannot be converted to UTC.

7.23.3.4 The

localtime

function

Synopsis

1

#include <time.h>

struct tm *localtime(const time_t *timer);

Description

2

The

localtime

function converts the calendar time pointed to by

timer

into a

broken-down time, expressed as local time.

Returns

3

The

localtime

function returns a pointer to the broken-down time, or a null pointer if

the specified time cannot be converted to local time.

7.23.3.5 The

strftime

function

Synopsis

1

#include <time.h>

size_t strftime(char * restrict s,

size_t maxsize,

const char * restrict format,

const struct tm * restrict timeptr);

Description

2

The

strftime

function places characters into the array pointed to by

s

as controlled by

the string pointed to by

format

. The format shall be a multibyte character sequence,

beginning and ending in its initial shift state. The

format

string consists of zero or

more conversion specifiers and ordinary multibyte characters. A conversion specifier
consists of a

%

character, possibly followed by an

E

or

O

modifier character (described

below), followed by a character that determines the behavior of the conversion specifier.
All ordinary multibyte characters (including the terminating null character) are copied

§7.23.3.5 Library

343

unchanged into the array. If copying takes place between objects that overlap, the
behavior is undefined. No more than

maxsize

characters are placed into the array.

3

Each conversion specifier is replaced by appropriate characters as described in the
following list. The appropriate characters are determined using the

LC_TIME

category

of the current locale and by the values of zero or more members of the broken-down time
structure pointed to by

timeptr

, as specified in brackets in the description. If any of

the specified values is outside the normal range, the characters stored are unspecified.

%a

is replaced by the locale’s abbreviated weekday name. [

tm_wday

]

%A

is replaced by the locale’s full weekday name. [

tm_wday

]

%b

is replaced by the locale’s abbreviated month name. [

tm_mon

]

%B

is replaced by the locale’s full month name. [

tm_mon

]

%c

is replaced by the locale’s appropriate date and time representation. [all specified
in 7.23.1]

%C

is replaced by the year divided by 100 and truncated to an integer, as a decimal
number (

00

−

99

). [

tm_year

]

%d

is replaced by the day of the month as a decimal number (

01

−

31

). [

tm_mday

]

%D

is equivalent to ‘‘

%m/%d/%y

’’. [

tm_mon

,

tm_mday

,

tm_year

]

%e

is replaced by the day of the month as a decimal number (

1

−

31

); a single digit is

preceded by a space. [

tm_mday

]

%F

is equivalent to ‘‘

%Y−%m−%d

’’ (the ISO 8601 date format). [

tm_year

,

tm_mon

,

tm_mday

]

%g

is replaced by the last 2 digits of the week-based year (see below) as a decimal
number (

00

−

99

). [

tm_year

,

tm_wday

,

tm_yday

]

%G

is replaced by the week-based year (see below) as a decimal number (e.g., 1997).
[

tm_year

,

tm_wday

,

tm_yday

]

%h

is equivalent to ‘‘

%b

’’. [

tm_mon

]

%H

is replaced by the hour (24-hour clock) as a decimal number (

00

−

23

). [

tm_hour

]

%I

is replaced by the hour (12-hour clock) as a decimal number (

01

−

12

). [

tm_hour

]

%j

is replaced by the day of the year as a decimal number (

001

−

366

). [

tm_yday

]

%m

is replaced by the month as a decimal number (

01

−

12

). [

tm_mon

]

%M

is replaced by the minute as a decimal number (

00

−

59

). [

tm_min

]

%n

is replaced by a new-line character.

%p

is replaced by the locale’s equivalent of the AM/PM designations associated with a
12-hour clock. [

tm_hour

]

%r

is replaced by the locale’s 12-hour clock time. [

tm_hour

,

tm_min

,

tm_sec

]

%R

is equivalent to ‘‘

%H:%M

’’. [

tm_hour

,

tm_min

]

%S

is replaced by the second as a decimal number (

00

−

60

). [

tm_sec

]

%t

is replaced by a horizontal-tab character.

%T

is equivalent to ‘‘

%H:%M:%S

’’ (the ISO 8601 time format). [

tm_hour

,

tm_min

,

tm_sec

]

344

Library

§7.23.3.5

%u

is replaced by the ISO 8601 weekday as a decimal number (

1

−

7

)

,

where Monday

is 1. [

tm_wday

]

%U

is replaced by the week number of the year (the first Sunday as the first day of week
1) as a decimal number (

00

−

53

). [

tm_year

,

tm_wday

,

tm_yday

]

%V

is replaced by the ISO 8601 week number (see below) as a decimal number
(

01

−

53

). [

tm_year

,

tm_wday

,

tm_yday

]

%w

is replaced by the weekday as a decimal number (

0

−

6

), where Sunday is 0.

[

tm_wday

]

%W

is replaced by the week number of the year (the first Monday as the first day of
week 1) as a decimal number (

00

−

53

). [

tm_year

,

tm_wday

,

tm_yday

]

%x

is replaced by the locale’s appropriate date representation. [all specified in 7.23.1]

%X

is replaced by the locale’s appropriate time representation. [all specified in 7.23.1]

%y

is replaced by the last 2 digits of the year as a decimal number (

00

−

99

).

[

tm_year

]

%Y

is replaced by the year as a decimal number (e.g.,

1997

). [

tm_year

]

%z

is replaced by the offset from UTC in the ISO 8601 format ‘‘

−0430

’’ (meaning 4

hours 30 minutes behind UTC, west of Greenwich), or by no characters if no time
zone is determinable. [

tm_isdst

]

%Z

is replaced by the locale’s time zone name or abbreviation, or by no characters if no
time zone is determinable. [

tm_isdst

]

%%

is replaced by

%

.

4

Some conversion specifiers can be modified by the inclusion of an

E

or

O

modifier

character to indicate an alternative format or specification. If the alternative format or
specification does not exist for the current locale, the modifier is ignored.

%Ec

is replaced by the locale’s alternative date and time representation.

%EC

is replaced by the name of the base year (period) in the locale’s alternative
representation.

%Ex

is replaced by the locale’s alternative date representation.

%EX

is replaced by the locale’s alternative time representation.

%Ey

is replaced by the offset from

%EC

(year only) in the locale’s alternative

representation.

%EY

is replaced by the locale’s full alternative year representation.

%Od

is replaced by the day of the month, using the locale’s alternative numeric symbols
(filled as needed with leading zeros, or with leading spaces if there is no alternative
symbol for zero).

%Oe

is replaced by the day of the month, using the locale’s alternative numeric symbols
(filled as needed with leading spaces).

%OH

is replaced by the hour (24-hour clock), using the locale’s alternative numeric
symbols.

§7.23.3.5 Library

345

%OI

is replaced by the hour (12-hour clock), using the locale’s alternative numeric
symbols.

%Om

is replaced by the month, using the locale’s alternative numeric symbols.

%OM

is replaced by the minutes, using the locale’s alternative numeric symbols.

%OS

is replaced by the seconds, using the locale’s alternative numeric symbols.

%Ou

is replaced by the ISO 8601 weekday as a number in the locale’s alternative
representation, where Monday is 1.

%OU

is replaced by the week number, using the locale’s alternative numeric symbols.

%OV

is replaced by the ISO 8601 week number, using the locale’s alternative numeric
symbols.

%Ow

is replaced by the weekday as a number, using the locale’s alternative numeric
symbols.

%OW

is replaced by the week number of the year, using the locale’s alternative numeric
symbols.

%Oy

is replaced by the last 2 digits of the year, using the locale’s alternative numeric
symbols.

5

%g

,

%G

, and

%V

give values according to the ISO 8601 week-based year. In this system,

weeks begin on a Monday and week 1 of the year is the week that includes January 4th,
which is also the week that includes the first Thursday of the year, and is also the first
week that contains at least four days in the year. If the first Monday of January is the
2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year; thus,
for Saturday 2nd January 1999,

%G

is replaced by

1998

and

%V

is replaced by

53

. If

December 29th, 30th, or 31st is a Monday, it and any following days are part of week 1 of
the following year. Thus, for Tuesday 30th December 1997,

%G

is replaced by

1998

and

%V

is replaced by

01

.

6

If a conversion specifier is not one of the above, the behavior is undefined.

7

In the

"C"

locale, the

E

and

O

modifiers are ignored and the replacement strings for the

following specifiers are:

%a

the first three characters of

%A

.

%A

one of ‘‘

Sunday

’’, ‘‘

Monday

’’, ... , ‘‘

Saturday

’’.

%b

the first three characters of

%B

.

%B

one of ‘‘

January

’’, ‘‘

February

’’, ... , ‘‘

December

’’.

%c

equivalent to ‘‘

%a %b %e %T %Y

’’.

%p

one of ‘‘

AM

’’ or ‘‘

PM

’’.

%r

equivalent to ‘‘

%I:%M:%S %p

’’.

%x

equivalent to ‘‘

%m/%d/%y

’’.

%X

equivalent to

%T

.

%Z

implementation-defined.

346 Library

§7.23.3.5

Returns

8

If the total number of resulting characters including the terminating null character is not
more than

maxsize

, the

strftime

function returns the number of characters placed

into the array pointed to by

s

not including the terminating null character. Otherwise,

zero is returned and the contents of the array are indeterminate.

§7.23.3.5 Library

347

7.24 Extended multibyte and wide character utilities

<wchar.h>

7.24.1 Introduction

1

The header

<wchar.h>

declares four data types, one tag, four macros, and many

functions.

277)

2

The types declared are

wchar_t

and

size_t

(both described in 7.17);

mbstate_t

which is an object type other than an array type that can hold the conversion state
information necessary to convert between sequences of multibyte characters and wide
characters;

wint_t

which is an integer type unchanged by default argument promotions that can hold any
value corresponding to members of the extended character set, as well as at least one
value that does not correspond to any member of the extended character set (see

WEOF

below);

278)

and

struct tm

which is declared as an incomplete structure type (the contents are described in 7.23.1).

3

The macros defined are

NULL

(described in 7.17);

WCHAR_MIN

and

WCHAR_MAX

(described in 7.18.3); and

WEOF

which expands to a constant expression of type

wint_t

whose value does not

correspond to any member of the extended character set.

279)

It is accepted (and returned)

by several functions in this subclause to indicate end-of-file, that is, no more input from a
stream. It is also used as a wide character value that does not correspond to any member
of the extended character set.

4

The functions declared are grouped as follows:

— Functions that perform input and output of wide characters, or multibyte characters,

or both;

— Functions that provide wide string numeric conversion;

— Functions that perform general wide string manipulation;

277) See ‘‘future library directions’’ (7.26.12).

278)

wchar_t

and

wint_t

can be the same integer type.

279) The value of the macro

WEOF

may differ from that of

EOF

and need not be negative.

348 Library

§7.24.1

— Functions for wide string date and time conversion; and

— Functions that provide extended capabilities for conversion between multibyte and

wide character sequences.

5

Unless explicitly stated otherwise, if the execution of a function described in this
subclause causes copying to take place between objects that overlap, the behavior is
undefined.

7.24.2 Formatted wide character input/output functions

1

The formatted wide character input/output functions shall behave as if there is a sequence
point after the actions associated with each specifier.

280)

7.24.2.1 The

fwprintf

function

Synopsis

1

#include <stdio.h>

#include <wchar.h>

int fwprintf(FILE * restrict stream,

const wchar_t * restrict format, ...);

Description

2

The

fwprintf

function writes output to the stream pointed to by

stream

, under

control of the wide string pointed to by

format

that specifies how subsequent arguments

are converted for output. If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain, the excess arguments
are evaluated (as always) but are otherwise ignored. The

fwprintf

function returns

when the end of the format string is encountered.

3

The format is composed of zero or more directives: ordinary wide characters (not

%

),

which are copied unchanged to the output stream; and conversion specifications, each of
which results in fetching zero or more subsequent arguments, converting them, if
applicable, according to the corresponding conversion specifier, and then writing the
result to the output stream.

4

Each conversion specification is introduced by the wide character

%

. After the

%

, the

following appear in sequence:

— Zero or more flags (in any order) that modify the meaning of the conversion

specification.

— An optional minimum field width. If the converted value has fewer wide characters

than the field width, it is padded with spaces (by default) on the left (or right, if the

280) The

fwprintf

functions perform writes to memory for the

%n

specifier.

§7.24.2.1 Library

349

left adjustment flag, described later, has been given) to the field width. The field
width takes the form of an asterisk

*

(described later) or a nonnegative decimal

integer.

281)

— An optional precision that gives the minimum number of digits to appear for the

d

,

i

,

o

,

u

,

x

, and

X

conversions, the number of digits to appear after the decimal-point

wide character for

a

,

A

,

e

,

E

,

f

, and

F

conversions, the maximum number of

significant digits for the

g

and

G

conversions, or the maximum number of wide

characters to be written for

s

conversions. The precision takes the form of a period

(

.

) followed either by an asterisk

*

(described later) or by an optional decimal

integer; if only the period is specified, the precision is taken as zero. If a precision
appears with any other conversion specifier, the behavior is undefined.

— An optional length modifier that specifies the size of the argument.

— A conversion specifier wide character that specifies the type of conversion to be

applied.

5

As noted above, a field width, or precision, or both, may be indicated by an asterisk. In
this case, an

int

argument supplies the field width or precision. The arguments

specifying field width, or precision, or both, shall appear (in that order) before the
argument (if any) to be converted. A negative field width argument is taken as a

-

flag

followed by a positive field width. A neg ative precision argument is taken as if the
precision were omitted.

6

The flag wide characters and their meanings are:

-

The result of the conversion is left-justified within the field. (It is right-justified if
this flag is not specified.)

+

The result of a signed conversion always begins with a plus or minus sign. (It
begins with a sign only when a negative value is converted if this flag is not
specified.)

282)

space If the first wide character of a signed conversion is not a sign, or if a signed

conversion results in no wide characters, a space is prefixed to the result. If the
space and

+

flags both appear, the space flag is ignored.

#

The result is converted to an ‘‘alternative form’’. For

o

conversion, it increases

the precision, if and only if necessary, to force the first digit of the result to be a
zero (if the value and precision are both 0, a single 0 is printed). For

x

(or

X

)

conversion, a nonzero result has

0x

(or

0X

) prefixed to it. For

a

,

A

,

e

,

E

,

f

,

F

,

g

,

281) Note that

0

is taken as a flag, not as the beginning of a field width.

282) The results of all floating conversions of a negative zero, and of negative values that round to zero,

include a minus sign.

350 Library

§7.24.2.1

and

G

conversions, the result of converting a floating-point number always

contains a decimal-point wide character, even if no digits follow it. (Normally, a
decimal-point wide character appears in the result of these conversions only if a
digit follows it.) For

g

and

G

conversions, trailing zeros are not removed from the

result. For other conversions, the behavior is undefined.

0

For

d

,

i

,

o

,

u

,

x

,

X

,

a

,

A

,

e

,

E

,

f

,

F

,

g

, and

G

conversions, leading zeros

(following any indication of sign or base) are used to pad to the field width rather
than performing space padding, except when converting an infinity or NaN. If the

0

and

-

flags both appear, the

0

flag is ignored. For

d

,

i

,

o

,

u

,

x

, and

X

conversions, if a precision is specified, the

0

flag is ignored.

For other

conversions, the behavior is undefined.

7

The length modifiers and their meanings are:

hh

Specifies that a following

d

,

i

,

o

,

u

,

x

, or

X

conversion specifier applies to a

signed char

or

unsigned char

argument (the argument will have

been promoted according to the integer promotions, but its value shall be
converted to

signed char

or

unsigned char

before printing); or that

a following

n

conversion specifier applies to a pointer to a

signed char

argument.

h

Specifies that a following

d

,

i

,

o

,

u

,

x

, or

X

conversion specifier applies to a

short int

or

unsigned short int

argument (the argument will

have been promoted according to the integer promotions, but its value shall
be converted to

short int

or

unsigned short int

before printing);

or that a following

n

conversion specifier applies to a pointer to a

short

int

argument.

l

(ell) Specifies that a following

d

,

i

,

o

,

u

,

x

, or

X

conversion specifier applies to a

long int

or

unsigned long int

argument; that a following

n

conversion specifier applies to a pointer to a

long int

argument; that a

following

c

conversion specifier applies to a

wint_t

argument; that a

following

s

conversion specifier applies to a pointer to a

wchar_t

argument; or has no effect on a following

a

,

A

,

e

,

E

,

f

,

F

,

g

, or

G

conversion

specifier.

ll

(ell-ell) Specifies that a following

d

,

i

,

o

,

u

,

x

, or

X

conversion specifier applies to a

long long int

or

unsigned long long int

argument; or that a

following

n

conversion specifier applies to a pointer to a

long long int

argument.

j

Specifies that a following

d

,

i

,

o

,

u

,

x

, or

X

conversion specifier applies to

an

intmax_t

or

uintmax_t

argument; or that a following

n

conversion

specifier applies to a pointer to an

intmax_t

argument.

§7.24.2.1 Library

351

z

Specifies that a following

d

,

i

,

o

,

u

,

x

, or

X

conversion specifier applies to a

size_t

or the corresponding signed integer type argument; or that a

following

n

conversion specifier applies to a pointer to a signed integer type

corresponding to

size_t

argument.

t

Specifies that a following

d

,

i

,

o

,

u

,

x

, or

X

conversion specifier applies to a

ptrdiff_t

or the corresponding unsigned integer type argument; or that a

following

n

conversion specifier applies to a pointer to a

ptrdiff_t

argument.

L

Specifies that a following

a

,

A

,

e

,

E

,

f

,

F

,

g

, or

G

conversion specifier

applies to a

long double

argument.

If a length modifier appears with any conversion specifier other than as specified above,
the behavior is undefined.

8

The conversion specifiers and their meanings are:

d,i

The

int

argument is converted to signed decimal in the style [

−

]dddd. The

precision specifies the minimum number of digits to appear; if the value
being converted can be represented in fewer digits, it is expanded with
leading zeros. The default precision is 1. The result of converting a zero
value with a precision of zero is no wide characters.

o,u,x,X

The

unsigned int

argument is converted to unsigned octal (

o

), unsigned

decimal (

u

), or unsigned hexadecimal notation (

x

or

X

) in the style dddd; the

letters

abcdef

are used for

x

conversion and the letters

ABCDEF

for

X

conversion. The precision specifies the minimum number of digits to appear;
if the value being converted can be represented in fewer digits, it is expanded
with leading zeros. The default precision is 1. The result of converting a
zero value with a precision of zero is no wide characters.

f,F

A

double

argument representing a floating-point number is converted to

decimal notation in the style [

−

]ddd

.

ddd, where the number of digits after

the decimal-point wide character is equal to the precision specification. If the
precision is missing, it is taken as 6; if the precision is zero and the

#

flag is

not specified, no decimal-point wide character appears. If a decimal-point
wide character appears, at least one digit appears before it. The value is
rounded to the appropriate number of digits.

A

double

argument representing an infinity is converted in one of the styles

[

-

]

inf

or [

-

]

infinity

— which style is implementation-defined. A

double

argument representing a NaN is converted in one of the styles

[

-

]

nan

or [

-

]

nan(

n-wchar-sequence

)

— which style, and the meaning of

any n-wchar-sequence, is implementation-defined. The

F

conversion

specifier produces

INF

,

INFINITY

, or

NAN

instead of

inf

,

infinity

, or

352 Library

§7.24.2.1

nan

, respectively.

283)

e,E

A

double

argument representing a floating-point number is converted in the

style [

−

]d

.

ddd

e

±

dd, where there is one digit (which is nonzero if the

argument is nonzero) before the decimal-point wide character and the number
of digits after it is equal to the precision; if the precision is missing, it is taken
as 6; if the precision is zero and the

#

flag is not specified, no decimal-point

wide character appears. The value is rounded to the appropriate number of
digits. The

E

conversion specifier produces a number with

E

instead of

e

introducing the exponent. The exponent always contains at least two digits,
and only as many more digits as necessary to represent the exponent. If the
value is zero, the exponent is zero.

A

double

argument representing an infinity or NaN is converted in the style

of an

f

or

F

conversion specifier.

g,G

A

double

argument representing a floating-point number is converted in

style

f

or

e

(or in style

F

or

E

in the case of a

G

conversion specifier),

depending on the value converted and the precision. Let P equal the
precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero.
Then, if a conversion with style

E

would have an exponent of X :

— if P > X

≥ −

4, the conversion is with style

f

(or

F

) and precision

P

−

(X

+

1).

— otherwise, the conversion is with style

e

(or

E

) and precision P

−

1.

Finally, unless the

#

flag is used, any trailing zeros are removed from the

fractional portion of the result and the decimal-point wide character is
removed if there is no fractional portion remaining.

A

double

argument representing an infinity or NaN is converted in the style

of an

f

or

F

conversion specifier.

a,A

A

double

argument representing a floating-point number is converted in the

style [

−

]

0x

h

.

hhhh

p

±

d, where there is one hexadecimal digit (which is

nonzero if the argument is a normalized floating-point number and is
otherwise unspecified) before the decimal-point wide character

284)

and the

number of hexadecimal digits after it is equal to the precision; if the precision
is missing and

FLT_RADIX

is a power of 2, then the precision is sufficient

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.

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.

§7.24.2.1 Library

353

for an exact representation of the value; if the precision is missing and

FLT_RADIX

is not a power of 2, then the precision is sufficient to

distinguish

285)

values of type

double

, except that trailing zeros may be

omitted; if the precision is zero and the

#

flag is not specified, no decimal-

point wide character appears. The letters

abcdef

are used for

a

conversion

and the letters

ABCDEF

for

A

conversion. The

A

conversion specifier

produces a number with

X

and

P

instead of

x

and

p

. The exponent always

contains at least one digit, and only as many more digits as necessary to
represent the decimal exponent of 2. If the value is zero, the exponent is
zero.

A

double

argument representing an infinity or NaN is converted in the style

of an

f

or

F

conversion specifier.

c

If no

l

length modifier is present, the

int

argument is converted to a wide

character as if by calling

btowc

and the resulting wide character is written.

If an

l

length modifier is present, the

wint_t

argument is converted to

wchar_t

and written.

s

If no

l

length modifier is present, the argument shall be a pointer to the initial

element of a character array containing a multibyte character sequence
beginning in the initial shift state. Characters from the array are converted as
if by repeated calls to the

mbrtowc

function, with the conversion state

described by an

mbstate_t

object initialized to zero before the first

multibyte character is converted, and written up to (but not including) the
terminating null wide character. If the precision is specified, no more than
that many wide characters are written. If the precision is not specified or is
greater than the size of the converted array, the converted array shall contain a
null wide character.

If an

l

length modifier is present, the argument shall be a pointer to the initial

element of an array of

wchar_t

type. Wide characters from the array are

written up to (but not including) a terminating null wide character. If the
precision is specified, no more than that many wide characters are written. If
the precision is not specified or is greater than the size of the array, the array
shall contain a null wide character.

p

The argument shall be a pointer to

void

. The value of the pointer is

converted to a sequence of printing wide characters, in an implementation-

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.

354 Library

§7.24.2.1

defined manner.

n

The argument shall be a pointer to signed integer into which is written the
number of wide characters written to the output stream so far by this call to

fwprintf

. No argument is converted, but one is consumed.

If the

conversion specification includes any flags, a field width, or a precision, the
behavior is undefined.

%

A

%

wide character is written. No argument is converted. The complete

conversion specification shall be

%%

.

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.

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

14

The

fwprintf

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

value if an output or encoding error occurred.

286) See ‘‘future library directions’’ (7.26.12).

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.

§7.24.2.1 Library

355

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 (7.24.6.1.1), the

mbrtowc

function

(7.24.6.3.2).

7.24.2.2 The

fwscanf

function

Synopsis

1

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

356 Library

§7.24.2.2

— 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)

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.

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

288) These white-space wide characters are not counted against a specified field width.

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

.

§7.24.2.2 Library

357

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

358 Library

§7.24.2.2

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

§7.24.2.2 Library

359

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

completion of execution of the

fwscanf

function. No argument is

360 Library

§7.24.2.2

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)

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

.

290) See ‘‘future library directions’’ (7.26.12).

§7.24.2.2 Library

361

Forward references: the

wcstod

,

wcstof

, and

wcstold

functions (7.24.4.1.1), the

wcstol

,

wcstoll

,

wcstoul

, and

wcstoull

functions (7.24.4.1.2), the

wcrtomb

function (7.24.6.3.3).

7.24.2.3 The

swprintf

function

Synopsis

1

#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 neg ative value if an encoding error
occurred or if

n

or more wide characters were requested to be written.

7.24.2.4 The

swscanf

function

Synopsis

1

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

362 Library

§7.24.2.4

7.24.2.5 The

vfwprintf

function

Synopsis

1

#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

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

}

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.

§7.24.2.5 Library

363