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

7.19 Input/output

<stdio.h>

7.19.1 Introduction

The header

<stdio.h>

declares three types, several macros, and many functions for

performing input and output.

The types declared are

size_t

(described in 7.17);

FILE

which is an object type capable of recording all the information needed to control a
stream, including its file position indicator, a pointer to its associated buffer (if any), an
error indicator that records whether a read/write error has occurred, and an end-of-file
indicator that records whether the end of the file has been reached; and

fpos_t

which is an object type other than an array type capable of recording all the information
needed to specify uniquely every position within a file.

The macros are

NULL

(described in 7.17);

_IOFBF

_IOLBF

_IONBF

which expand to integer constant expressions with distinct values, suitable for use as the
third argument to the

setvbuf

function;

BUFSIZ

which expands to an integer constant expression that is the size of the buffer used by the

setbuf

function;

EOF

which expands to an integer constant expression, with type

int

and a negative value, that

is returned by several functions to indicate end-of-file, that is, no more input from a
stream;

FOPEN_MAX

which expands to an integer constant expression that is the minimum number of files that
the implementation guarantees can be open simultaneously;

FILENAME_MAX

which expands to an integer constant expression that is the size needed for an array of

char

large enough to hold the longest file name string that the implementation

262 Library

§7.19.1

guarantees can be opened;

231)

L_tmpnam

which expands to an integer constant expression that is the size needed for an array of

char

large enough to hold a temporary file name string generated by the

tmpnam

function;

SEEK_CUR

SEEK_END

SEEK_SET

which expand to integer constant expressions with distinct values, suitable for use as the
third argument to the

fseek

function;

TMP_MAX

which expands to an integer constant expression that is the maximum number of unique
file names that can be generated by the

tmpnam

function;

stderr

stdin

stdout

which are expressions of type ‘‘pointer to

FILE

’’ that point to the

FILE

objects

associated, respectively, with the standard error, input, and output streams.

The header

<wchar.h>

declares a number of functions useful for wide character input

and output. The wide character input/output functions described in that subclause
provide operations analogous to most of those described here, except that the
fundamental units internal to the program are wide characters.

The external

representation (in the file) is a sequence of ‘‘generalized’’ multibyte characters, as
described further in 7.19.3.

The input/output functions are given the following collective terms:

— The wide character input functions — those functions described in 7.24 that perform

input into wide characters and wide strings:

fgetwc

fgetws

getwc

getwchar

fwscanf

wscanf

vfwscanf

, and

vwscanf

— The wide character output functions — those functions described in 7.24 that perform

output from wide characters and wide strings:

fputwc

fputws

putwc

putwchar

fwprintf

wprintf

vfwprintf

, and

vwprintf

231) If the implementation imposes no practical limit on the length of file name strings, the value of

FILENAME_MAX

should instead be the recommended size of an array intended to hold a file name

string. Of course, file name string contents are subject to other system-specific constraints; therefore
all possible strings of length

FILENAME_MAX

cannot be expected to be opened successfully.

§7.19.1 Library

263

— The wide character input/output functions — the union of the

ungetwc

function, the

wide character input functions, and the wide character output functions.

— The byte input/output functions — those functions described in this subclause that

perform input/output:

fgetc

fgets

fprintf

fputc

fputs

fread

fscanf

fwrite

getc

getchar

gets

printf

putc

putchar

puts

scanf

ungetc

vfprintf

vfscanf

vprintf

, and

vscanf

Forward references: files (7.19.3), the

fseek

function (7.19.9.2), streams (7.19.2), the

tmpnam

function (7.19.4.4),

<wchar.h>

(7.24).

7.19.2 Streams

Input and output, whether to or from physical devices such as terminals and tape drives,
or whether to or from files supported on structured storage devices, are mapped into
logical data streams, whose properties are more uniform than their various inputs and
outputs. Two forms of mapping are supported, for text streams and for binary
streams.

232)

A text stream is an ordered sequence of characters composed into lines, each line
consisting of zero or more characters plus a terminating new-line character. Whether the
last line requires a terminating new-line character is implementation-defined. Characters
may have to be added, altered, or deleted on input and output to conform to differing
conventions for representing text in the host environment. Thus, there need not be a one-
to-one correspondence between the characters in a stream and those in the external
representation. Data read in from a text stream will necessarily compare equal to the data
that were earlier written out to that stream only if: the data consist only of printing
characters and the control characters horizontal tab and new-line; no new-line character is
immediately preceded by space characters; and the last character is a new-line character.
Whether space characters that are written out immediately before a new-line character
appear when read in is implementation-defined.

A binary stream is an ordered sequence of characters that can transparently record
internal data. Data read in from a binary stream shall compare equal to the data that were
earlier written out to that stream, under the same implementation. Such a stream may,
however, hav e an implementation-defined number of null characters appended to the end
of the stream.

Each stream has an orientation. After a stream is associated with an external file, but
before any operations are performed on it, the stream is without orientation. Once a wide
character input/output function has been applied to a stream without orientation, the

232) An implementation need not distinguish between text streams and binary streams. In such an

implementation, there need be no new-line characters in a text stream nor any limit to the length of a
line.

264 Library

§7.19.2

stream becomes a wide-oriented stream. Similarly, once a byte input/output function has
been applied to a stream without orientation, the stream becomes a byte-oriented stream.
Only a call to the

freopen

function or the

fwide

function can otherwise alter the

orientation of a stream. (A successful call to

freopen

removes any orientation.)

233)

Byte input/output functions shall not be applied to a wide-oriented stream and wide
character input/output functions shall not be applied to a byte-oriented stream. The
remaining stream operations do not affect, and are not affected by, a stream’s orientation,
except for the following additional restrictions:

— Binary wide-oriented streams have the file-positioning restrictions ascribed to both

text and binary streams.

— For wide-oriented streams, after a successful call to a file-positioning function that

leaves the file position indicator prior to the end-of-file, a wide character output
function can overwrite a partial multibyte character; any file contents beyond the
byte(s) written are henceforth indeterminate.

Each wide-oriented stream has an associated

mbstate_t

object that stores the current

parse state of the stream. A successful call to

fgetpos

stores a representation of the

value of this

mbstate_t

object as part of the value of the

fpos_t

object. A later

successful call to

fsetpos

using the same stored

fpos_t

value restores the value of

the associated

mbstate_t

object as well as the position within the controlled stream.

Environmental limits

An implementation shall support text files with lines containing at least 254 characters,
including the terminating new-line character. The value of the macro

BUFSIZ

shall be at

least 256.

Forward references: the

freopen

function (7.19.5.4), the

fwide

function (7.24.3.5),

mbstate_t

(7.25.1), the

fgetpos

function (7.19.9.1), the

fsetpos

function

(7.19.9.3).

233) The three predefined streams

stdin

stdout

, and

stderr

are unoriented at program startup.

§7.19.2 Library

265

7.19.3 Files

A stream is associated with an external file (which may be a physical device) by opening
a file, which may involve creating a new file. Creating an existing file causes its former
contents to be discarded, if necessary. If a file can support positioning requests (such as a
disk file, as opposed to a terminal), then a file position indicator associated with the
stream is positioned at the start (character number zero) of the file, unless the file is
opened with append mode in which case it is implementation-defined whether the file
position indicator is initially positioned at the beginning or the end of the file. The file
position indicator is maintained by subsequent reads, writes, and positioning requests, to
facilitate an orderly progression through the file.

Binary files are not truncated, except as defined in 7.19.5.3. Whether a write on a text
stream causes the associated file to be truncated beyond that point is implementation-
defined.

When a stream is unbuffered, characters are intended to appear from the source or at the
destination as soon as possible.

Otherwise characters may be accumulated and

transmitted to or from the host environment as a block. When a stream is fully buffered,
characters are intended to be transmitted to or from the host environment as a block when
a buffer is filled. When a stream is line buffered, characters are intended to be
transmitted to or from the host environment as a block when a new-line character is
encountered. Furthermore, characters are intended to be transmitted as a block to the host
environment when a buffer is filled, when input is requested on an unbuffered stream, or
when input is requested on a line buffered stream that requires the transmission of
characters from the host environment. Support

for these characteristics is

implementation-defined, and may be affected via the

setbuf

and

setvbuf

functions.

A file may be disassociated from a controlling stream by closing the file. Output streams
are flushed (any unwritten buffer contents are transmitted to the host environment) before
the stream is disassociated from the file. The value of a pointer to a

FILE

object is

indeterminate after the associated file is closed (including the standard text streams).
Whether a file of zero length (on which no characters have been written by an output
stream) actually exists is implementation-defined.

The file may be subsequently reopened, by the same or another program execution, and
its contents reclaimed or modified (if it can be repositioned at its start). If the

main

function returns to its original caller, or if the

exit

function is called, all open files are

closed (hence all output streams are flushed) before program termination. Other paths to
program termination, such as calling the

abort

function, need not close all files

properly.

The address of the

FILE

object used to control a stream may be significant; a copy of a

FILE

object need not serve in place of the original.

266 Library

§7.19.3

At program startup, three text streams are predefined and need not be opened explicitly
— standard input (for reading conventional input), standard output (for writing
conventional output), and standard error (for writing diagnostic output). As initially
opened, the standard error stream is not fully buffered; the standard input and standard
output streams are fully buffered if and only if the stream can be determined not to refer
to an interactive device.

Functions that open additional (nontemporary) files require a file name, which is a string.
The rules for composing valid file names are implementation-defined. Whether the same
file can be simultaneously open multiple times is also implementation-defined.

Although both text and binary wide-oriented streams are conceptually sequences of wide
characters, the external file associated with a wide-oriented stream is a sequence of
multibyte characters, generalized as follows:

— Multibyte encodings within files may contain embedded null bytes (unlike multibyte

encodings valid for use internal to the program).

— A file need not begin nor end in the initial shift state.

234)

Moreover, the encodings used for multibyte characters may differ among files. Both the
nature and choice of such encodings are implementation-defined.

The wide character input functions read multibyte characters from the stream and convert
them to wide characters as if they were read by successive calls to the

fgetwc

function.

Each conversion occurs as if by a call to the

mbrtowc

function, with the conversion state

described by the stream’s own

mbstate_t

object. The byte input functions read

characters from the stream as if by successive calls to the

fgetc

function.

The wide character output functions convert wide characters to multibyte characters and
write them to the stream as if they were written by successive calls to the

fputwc

function. Each conversion occurs as if by a call to the

wcrtomb

function, with the

conversion state described by the stream’s own

mbstate_t

object. The byte output

functions write characters to the stream as if by successive calls to the

fputc

function.

In some cases, some of the byte input/output functions also perform conversions between
multibyte characters and wide characters. These conversions also occur as if by calls to
the

mbrtowc

and

wcrtomb

functions.

An encoding error occurs if the character sequence presented to the underlying

mbrtowc

function does not form a valid (generalized) multibyte character, or if the code

value passed to the underlying

wcrtomb

does not correspond to a valid (generalized)

234) Setting the file position indicator to end-of-file, as with

fseek(file, 0, SEEK_END)

, has

undefined behavior for a binary stream (because of possible trailing null characters) or for any stream
with state-dependent encoding that does not assuredly end in the initial shift state.

§7.19.3 Library

267

multibyte character. The wide character input/output functions and the byte input/output
functions store the value of the macro

EILSEQ

errno

if and only if an encoding error

occurs.

Environmental limits

The value of

FOPEN_MAX

shall be at least eight, including the three standard text

streams.

Forward references: the

exit

function (7.20.4.3), the

fgetc

function (7.19.7.1), the

fopen

function (7.19.5.3), the

fputc

function (7.19.7.3), the

setbuf

function

(7.19.5.5), the

setvbuf

function (7.19.5.6), the

fgetwc

function (7.24.3.1), the

fputwc

function (7.24.3.3), conversion state (7.24.6), the

mbrtowc

function

(7.24.6.3.2), the

wcrtomb

function (7.24.6.3.3).

7.19.4 Operations on files

7.19.4.1 The

remove

function

Synopsis

#include <stdio.h>

int remove(const char *filename);

Description

The

remove

function causes the file whose name is the string pointed to by

filename

to be no longer accessible by that name. A subsequent attempt to open that file using that
name will fail, unless it is created anew. If the file is open, the behavior of the

remove

function is implementation-defined.

Returns

The

remove

function returns zero if the operation succeeds, nonzero if it fails.

7.19.4.2 The

rename

function

Synopsis

#include <stdio.h>

int rename(const char *old, const char *new);

Description

The

rename

function causes the file whose name is the string pointed to by

old

to be

henceforth known by the name given by the string pointed to by

new

. The file named

old

is no longer accessible by that name. If a file named by the string pointed to by

new

exists prior to the call to the

rename

function, the behavior is implementation-defined.

268 Library

§7.19.4.2

Returns

The

rename

function returns zero if the operation succeeds, nonzero if it fails,

235)

which case if the file existed previously it is still known by its original name.

7.19.4.3 The

tmpfile

function

Synopsis

#include <stdio.h>

FILE *tmpfile(void);

Description

The

tmpfile

function creates a temporary binary file that is different from any other

existing file and that will automatically be removed when it is closed or at program
termination. If the program terminates abnormally, whether an open temporary file is
removed is implementation-defined. The file is opened for update with

"wb+"

mode.

Recommended practice

It should be possible to open at least

TMP_MAX

temporary files during the lifetime of the

program (this limit may be shared with

tmpnam

) and there should be no limit on the

number simultaneously open other than this limit and any limit on the number of open
files (

FOPEN_MAX

Returns

The

tmpfile

function returns a pointer to the stream of the file that it created. If the file

cannot be created, the

tmpfile

function returns a null pointer.

Forward references: the

fopen

function (7.19.5.3).

7.19.4.4 The

tmpnam

function

Synopsis

#include <stdio.h>

char *tmpnam(char *s);

Description

The

tmpnam

function generates a string that is a valid file name and that is not the same

as the name of an existing file.

236)

The function is potentially capable of generating

235) Among the reasons the implementation may cause the

rename

function to fail are that the file is open

or that it is necessary to copy its contents to effectuate its renaming.

236) Files created using strings generated by the

tmpnam

function are temporary only in the sense that

their names should not collide with those generated by conventional naming rules for the
implementation. It is still necessary to use the

remove

function to remove such files when their use

is ended, and before program termination.

§7.19.4.4 Library

269

TMP_MAX

different strings, but any or all of them may already be in use by existing files

and thus not be suitable return values.

The

tmpnam

function generates a different string each time it is called.

The implementation shall behave as if no library function calls the

tmpnam

function.

Returns

If no suitable string can be generated, the

tmpnam

function returns a null pointer.

Otherwise, if the argument is a null pointer, the

tmpnam

function leaves its result in an

internal static object and returns a pointer to that object (subsequent calls to the

tmpnam

function may modify the same object). If the argument is not a null pointer, it is assumed
to point to an array of at least

L_tmpnam char

s; the

tmpnam

function writes its result

in that array and returns the argument as its value.

Environmental limits

The value of the macro

TMP_MAX

shall be at least 25.

7.19.5 File access functions

7.19.5.1 The

fclose

function

Synopsis

#include <stdio.h>

int fclose(FILE *stream);

Description

A successful call to the

fclose

function causes the stream pointed to by

stream

to be

flushed and the associated file to be closed. Any unwritten buffered data for the stream
are delivered to the host environment to be written to the file; any unread buffered data
are discarded. Whether or not the call succeeds, the stream is disassociated from the file
and any buffer set by the

setbuf

setvbuf

function is disassociated from the stream

(and deallocated if it was automatically allocated).

Returns

The

fclose

function returns zero if the stream was successfully closed, or

EOF

if any

errors were detected.

7.19.5.2 The

fflush

function

Synopsis

#include <stdio.h>

int fflush(FILE *stream);

270 Library

§7.19.5.2

Description

stream

points to an output stream or an update stream in which the most recent

operation was not input, the

fflush

function causes any unwritten data for that stream

to be delivered to the host environment to be written to the file; otherwise, the behavior is
undefined.

stream

is a null pointer, the

fflush

function performs this flushing action on all

streams for which the behavior is defined above.

Returns

The

fflush

function sets the error indicator for the stream and returns

EOF

if a write

error occurs, otherwise it returns zero.

Forward references: the

fopen

function (7.19.5.3).

7.19.5.3 The

fopen

function

Synopsis

#include <stdio.h>

FILE *fopen(const char * restrict filename,

const char * restrict mode);

Description

The

fopen

function opens the file whose name is the string pointed to by

filename

and associates a stream with it.

The argument

mode

points to a string. If the string is one of the following, the file is

open in the indicated mode. Otherwise, the behavior is undefined.

237)

open text file for reading

truncate to zero length or create text file for writing

append; open or create text file for writing at end-of-file

open binary file for reading

truncate to zero length or create binary file for writing

append; open or create binary file for writing at end-of-file

open text file for update (reading and writing)

truncate to zero length or create text file for update

append; open or create text file for update, writing at end-of-file

237) If the string begins with one of the above sequences, the implementation might choose to ignore the

remaining characters, or it might use them to select different kinds of a file (some of which might not
conform to the properties in 7.19.2).

§7.19.5.3 Library

271

r+b

rb+

open binary file for update (reading and writing)

w+b

wb+

truncate to zero length or create binary file for update

a+b

ab+

append; open or create binary file for update, writing at end-of-file

Opening a file with read mode (

'r'

as the first character in the

mode

argument) fails if

the file does not exist or cannot be read.

Opening a file with append mode (

'a'

as the first character in the

mode

argument)

causes all subsequent writes to the file to be forced to the then current end-of-file,
regardless of intervening calls to the

fseek

function. In some implementations, opening

a binary file with append mode (

'b'

as the second or third character in the above list of

mode

argument values) may initially position the file position indicator for the stream

beyond the last data written, because of null character padding.

When a file is opened with update mode (

'+'

as the second or third character in the

above list of

mode

argument values), both input and output may be performed on the

associated stream. However, output shall not be directly followed by input without an
intervening call to the

fflush

function or to a file positioning function (

fseek

fsetpos

, or

rewind

), and input shall not be directly followed by output without an

intervening call to a file positioning function, unless the input operation encounters end-
of-file. Opening (or creating) a text file with update mode may instead open (or create) a
binary stream in some implementations.

When opened, a stream is fully buffered if and only if it can be determined not to refer to
an interactive device. The error and end-of-file indicators for the stream are cleared.

Returns

The

fopen

function returns a pointer to the object controlling the stream. If the open

operation fails,

fopen

returns a null pointer.

Forward references: file positioning functions (7.19.9).

7.19.5.4 The

freopen

function

Synopsis

#include <stdio.h>

FILE *freopen(const char * restrict filename,

const char * restrict mode,

FILE * restrict stream);

Description

The

freopen

function opens the file whose name is the string pointed to by

filename

and associates the stream pointed to by

stream

with it. The

mode

argument is used just

272 Library

§7.19.5.4

as in the

fopen

function.

238)

filename

is a null pointer, the

freopen

function attempts to change the mode of

the stream to that specified by

mode

, as if the name of the file currently associated with

the stream had been used. It is implementation-defined which changes of mode are
permitted (if any), and under what circumstances.

The

freopen

function first attempts to close any file that is associated with the specified

stream. Failure to close the file is ignored. The error and end-of-file indicators for the
stream are cleared.

Returns

The

freopen

function returns a null pointer if the open operation fails. Otherwise,

freopen

returns the value of

stream

7.19.5.5 The

setbuf

function

Synopsis

#include <stdio.h>

void setbuf(FILE * restrict stream,

char * restrict buf);

Description

Except that it returns no value, the

setbuf

function is equivalent to the

setvbuf

function invoked with the values

_IOFBF

for

mode

and

BUFSIZ

for

size

, or (if

buf

is a null pointer), with the value

_IONBF

for

mode

Returns

The

setbuf

function returns no value.

Forward references: the

setvbuf

function (7.19.5.6).

7.19.5.6 The

setvbuf

function

Synopsis

#include <stdio.h>

int setvbuf(FILE * restrict stream,

char * restrict buf,

int mode, size_t size);

238) The primary use of the

freopen

function is to change the file associated with a standard text stream

(

stderr

stdin

, or

stdout

), as those identifiers need not be modifiable lvalues to which the value

returned by the

fopen

function may be assigned.

§7.19.5.6 Library

273

Description

The

setvbuf

function may be used only after the stream pointed to by

stream

has

been associated with an open file and before any other operation (other than an
unsuccessful call to

setvbuf

) is performed on the stream. The argument

mode

determines how

stream

will be buffered, as follows:

_IOFBF

causes input/output to be

fully buffered;

_IOLBF

causes input/output to be line buffered;

_IONBF

causes

input/output to be unbuffered. If

buf

is not a null pointer, the array it points to may be

used instead of a buffer allocated by the

setvbuf

function

239)

and the argument

size

specifies the size of the array; otherwise,

size

may determine the size of a buffer

allocated by the

setvbuf

function. The contents of the array at any time are

indeterminate.

Returns

The

setvbuf

function returns zero on success, or nonzero if an invalid value is given

for

mode

or if the request cannot be honored.

7.19.6 Formatted input/output functions

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

240)

7.19.6.1 The

fprintf

function

Synopsis

#include <stdio.h>

int fprintf(FILE * restrict stream,

const char * restrict format, ...);

Description

The

fprintf

function writes output to the stream pointed to by

stream

, under control

of the 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

fprintf

function returns when

the end of the format string is encountered.

The format shall be a multibyte character sequence, beginning and ending in its initial
shift state. The format is composed of zero or more directives: ordinary multibyte
characters (not

), which are copied unchanged to the output stream; and conversion

239) The buffer has to have a lifetime at least as great as the open stream, so the stream should be closed

before a buffer that has automatic storage duration is deallocated upon block exit.

240) The

fprintf

functions perform writes to memory for the

specifier.

274 Library

§7.19.6.1

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.

Each conversion specification is introduced by the 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 characters than the

field width, it is padded with spaces (by default) on the left (or right, if the left
adjustment flag, described later, has been given) to the field width. The field width
takes the form of an asterisk

(described later) or a nonnegative decimal integer.

241)

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

, and

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

character for

, and

conversions, the maximum number of significant

digits for the

and

conversions, or the maximum number of bytes to be written for

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 character that specifies the type of conversion to be applied.

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.

The flag 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

241) Note that

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

§7.19.6.1 Library

275

specified.)

242)

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

results in no 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

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

(or

)

conversion, a nonzero result has

(or

) prefixed to it. For

and

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

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

and

conversions, trailing zeros are not removed from the

result. For other conversions, the behavior is undefined.

For

, and

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

and

flags both appear, the

flag is ignored. For

, and

conversions, if a precision is specified, the

flag is ignored.

For other

conversions, the behavior is undefined.

The length modifiers and their meanings are:

Specifies that a following

, or

conversion specifier applies to a

signed char

unsigned char

argument (the argument will have

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

signed char

unsigned char

before printing); or that

a following

conversion specifier applies to a pointer to a

signed char

argument.

Specifies that a following

, or

conversion specifier applies to a

short int

unsigned short int

argument (the argument will

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

short int

unsigned short int

before printing);

or that a following

conversion specifier applies to a pointer to a

short

int

argument.

(ell) Specifies that a following

, or

conversion specifier applies to a

long int

unsigned long int

argument; that a following

conversion specifier applies to a pointer to a

long int

argument; that a

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

include a minus sign.

276 Library

§7.19.6.1

following

conversion specifier applies to a

wint_t

argument; that a

following

conversion specifier applies to a pointer to a

wchar_t

argument; or has no effect on a following

, or

conversion

specifier.

(ell-ell) Specifies that a following

, or

conversion specifier applies to a

long long int

unsigned long long int

argument; or that a

following

conversion specifier applies to a pointer to a

long long int

argument.

Specifies that a following

, or

conversion specifier applies to

intmax_t

uintmax_t

argument; or that a following

conversion

specifier applies to a pointer to an

intmax_t

argument.

Specifies that a following

, or

conversion specifier applies to a

size_t

or the corresponding signed integer type argument; or that a

following

conversion specifier applies to a pointer to a signed integer type

corresponding to

size_t

argument.

Specifies that a following

, or

conversion specifier applies to a

ptrdiff_t

or the corresponding unsigned integer type argument; or that a

following

conversion specifier applies to a pointer to a

ptrdiff_t

argument.

Specifies that a following

, or

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.

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

o,u,x,X

The

unsigned int

argument is converted to unsigned octal (

), unsigned

decimal (

), or unsigned hexadecimal notation (

) in the style dddd; the

letters

abcdef

are used for

conversion and the letters

ABCDEF

for

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

§7.19.6.1 Library

277

f,F

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

If a decimal-point

character appears, at least one digit appears before it. The value is rounded to
the appropriate number of digits.

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-char-sequence

)

— which style, and the meaning of

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

conversion specifier

produces

INF

INFINITY

, or

NAN

instead of

inf

infinity

, or

nan

respectively.

243)

e,E

double

argument representing a floating-point number is converted in the

style [

−

ddd

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

argument is nonzero) before the decimal-point 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

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

conversion specifier produces a number with

instead of

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.

double

argument representing an infinity or NaN is converted in the style

of an

conversion specifier.

g,G

double

argument representing a floating-point number is converted in

style

(or in style

in the case of a

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

would have an exponent of X :

— if P > X

≥ −

4, the conversion is with style

(or

) and precision

−

1).

— otherwise, the conversion is with style

(or

) and precision P

−

Finally, unless the

flag is used, any trailing zeros are removed from the

243) When applied to infinite and NaN values, the

, and space flag characters have their usual meaning;

the

and

flag characters have no effect.

278 Library

§7.19.6.1

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

double

argument representing an infinity or NaN is converted in the style

of an

conversion specifier.

a,A

double

argument representing a floating-point number is converted in the

style [

−

]

hhhh

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 character

244)

and the number

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

FLT_RADIX

is a power of 2, then the precision is sufficient for

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

FLT_RADIX

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

distinguish

245)

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 character appears. The letters

abcdef

are used for

conversion and

the letters

ABCDEF

for

conversion. The

conversion specifier produces a

number with

and

instead of

and

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

double

argument representing an infinity or NaN is converted in the style

of an

conversion specifier.

If no

length modifier is present, the

int

argument is converted to an

unsigned char

, and the resulting character is written.

If an

length modifier is present, the

wint_t

argument is converted as if by

conversion specification with no precision and an argument that points

to the initial element of a two-element array of

wchar_t

, the first element

containing the

wint_t

argument to the

conversion specification and the

second a null wide character.

If no

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

element of an array of character type.

246)

Characters from the array are

244) Binary implementations can choose the hexadecimal digit to the left of the decimal-point character so

that subsequent digits align to nibble (4-bit) boundaries.

245) The precision p is sufficient to distinguish values of the source type if

−

> b

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

246) No special provisions are made for multibyte characters.

§7.19.6.1 Library

279

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

If an

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

converted to multibyte characters (each as if by a call to the

wcrtomb

function, with the conversion state described by an

mbstate_t

object

initialized to zero before the first wide character is converted) up to and
including a terminating null wide character.

The resulting multibyte

characters are written up to (but not including) the terminating null character
(byte). If no precision is specified, the array shall contain a null wide
character. If a precision is specified, no more than that many bytes are
written (including shift sequences, if any), and the array shall contain a null
wide character if, to equal the multibyte character sequence length given by
the precision, the function would need to access a wide character one past the
end of the array. In no case is a partial multibyte character written.

247)

The argument shall be a pointer to

void

. The value of the pointer is

converted to a sequence of printing characters, in an implementation-defined
manner.

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

fprintf

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

character is written.

No argument is converted. The complete

conversion specification shall be

If a conversion specification is invalid, the behavior is undefined.

248)

If any argument is

not the correct type for the corresponding conversion specification, the behavior is
undefined.

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.

247) Redundant shift sequences may result if multibyte characters have a state-dependent encoding.

248) See ‘‘future library directions’’ (7.26.9).

280 Library

§7.19.6.1

For

and

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

For

and

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.

For

, and

conversions, if the number of significant decimal digits is at most

DECIMAL_DIG

, then the result should be correctly rounded.

249)

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

≤

U , with the extra stipulation that

the error should have a correct sign for the current rounding direction.

Returns

The

fprintf

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

if an output or encoding error occurred.

Environmental limits

The number of characters that can be produced by any single conversion shall be at least
4095.

EXAMPLE 1

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>

...

char *weekday, *month;

pointers to strings

int day, hour, min;

fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",

weekday, month, day, hour, min);

fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

EXAMPLE 2

In this example, multibyte characters do not have a state-dependent encoding, and the

members of the extended character set that consist of more than one byte each consist of exactly two bytes,
the first of which is denoted here by a

and the second by an uppercase letter.

249) 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.19.6.1 Library

281

Given the following wide string with length seven,

static wchar_t wstr[] = L" X Yabc Z W";

the seven calls

fprintf(stdout, "|1234567890123|\n");

fprintf(stdout, "|%13ls|\n", wstr);

fprintf(stdout, "|%-13.9ls|\n", wstr);

fprintf(stdout, "|%13.10ls|\n", wstr);

fprintf(stdout, "|%13.11ls|\n", wstr);

fprintf(stdout, "|%13.15ls|\n", &wstr[2]);

fprintf(stdout, "|%13lc|\n", (wint_t) wstr[5]);

will print the following seven lines:

|1234567890123|

X Yabc Z W|

| X Yabc Z

X Yabc Z|

X Yabc Z W|

abc Z W|

Forward references: conversion state (7.24.6), the

wcrtomb

function (7.24.6.3.3).

7.19.6.2 The

fscanf

function

Synopsis

#include <stdio.h>

int fscanf(FILE * restrict stream,

const char * restrict format, ...);

Description

The

fscanf

function reads input from the stream pointed to by

stream

, under control

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

The format shall be a multibyte character sequence, beginning and ending in its initial
shift state. The format is composed of zero or more directives: one or more white-space
characters, an ordinary multibyte character (neither

nor a white-space character), or a

conversion specification. Each conversion specification is introduced by the character

After the

, the following appear in sequence:

— An optional assignment-suppressing character

— An optional decimal integer greater than zero that specifies the maximum field width

(in characters).

282 Library

§7.19.6.2

— An optional length modifier that specifies the size of the receiving object.

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

The

fscanf

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

A directive composed of white-space character(s) is executed by reading input up to the
first non-white-space character (which remains unread), or until no more characters can
be read.

A directive that is an ordinary multibyte character is executed by reading the next
characters of the stream. If any of those characters differ from the ones composing the
directive, the directive fails and the differing and subsequent characters remain unread.
Similarly, if end-of-file, an encoding error, or a read error prevents a character from being
read, the directive fails.

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:

Input white-space characters (as specified by the

isspace

function) are skipped, unless

the specification includes a

[

, or

specifier.

250)

An input item is read from the stream, unless the specification includes an

specifier. An

input item is defined as the longest sequence of input characters which does not exceed
any specified field width and which is, or is a prefix of, a matching input sequence.

251)

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

Except in the case of a

specifier, the input item (or, in the case of a

directive, the

count of input characters) is converted to a type appropriate to the conversion specifier. If
the input item is not a matching sequence, the execution of the directive fails: this
condition is a matching failure. Unless assignment suppression was indicated by a

, the

result of the conversion is placed in the object pointed to by the first argument following
the

format

argument that has not already received a conversion result. If this object

does not have an appropriate type, or if the result of the conversion cannot be represented

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

251)

fscanf

pushes back at most one input character onto the input stream. Therefore, some sequences

that are acceptable to

strtod

strtol

, etc., are unacceptable to

fscanf

§7.19.6.2 Library

283

in the object, the behavior is undefined.

The length modifiers and their meanings are:

Specifies that a following

, or

conversion specifier applies

to an argument with type pointer to

signed char

unsigned char

Specifies that a following

, or

conversion specifier applies

to an argument with type pointer to

short int

unsigned short

int

(ell) Specifies that a following

, or

conversion specifier applies

to an argument with type pointer to

long int

unsigned long

int

; that a following

, or

conversion specifier applies to

an argument with type pointer to

double

; or that a following

, or

[

conversion specifier applies to an argument with type pointer to

wchar_t

(ell-ell) Specifies that a following

, or

conversion specifier applies

to an argument with type pointer to

long long int

unsigned

long long int

Specifies that a following

, or

conversion specifier applies

to an argument with type pointer to

intmax_t

uintmax_t

Specifies that a following

, or

conversion specifier applies

to an argument with type pointer to

size_t

or the corresponding signed

integer type.

Specifies that a following

, or

conversion specifier applies

to an argument with type pointer to

ptrdiff_t

or the corresponding

unsigned integer type.

Specifies that a following

, or

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.

The conversion specifiers and their meanings are:

Matches an optionally signed decimal integer, whose format is the same as
expected for the subject sequence of the

strtol

function with the value 10

for the

base

argument. The corresponding argument shall be a pointer to

signed integer.

Matches an optionally signed integer, whose format is the same as expected
for the subject sequence of the

strtol

function with the value 0 for the

base

argument. The corresponding argument shall be a pointer to signed

integer.

284 Library

§7.19.6.2

Matches an optionally signed octal integer, whose format is the same as
expected for the subject sequence of the

strtoul

function with the value 8

for the

base

argument. The corresponding argument shall be a pointer to

unsigned integer.

Matches an optionally signed decimal integer, whose format is the same as
expected for the subject sequence of the

strtoul

function with the value 10

for the

base

argument. The corresponding argument shall be a pointer to

unsigned integer.

Matches an optionally signed hexadecimal integer, whose format is the same
as expected for the subject sequence of the

strtoul

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

strtod

function. The corresponding argument shall be a pointer to floating.

Matches a sequence of characters of exactly the number specified by the field
width (1 if no field width is present in the directive).

252)

If no

length modifier is present, 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

length modifier is present, the input shall be a sequence of multibyte

characters that begins in the initial shift state. Each multibyte character in the
sequence is converted to a wide character as if by a call to the

mbrtowc

function, with the conversion state described by an

mbstate_t

object

initialized to zero before the first multibyte character is converted. The
corresponding argument shall be a pointer to the initial element of an array of

wchar_t

large enough to accept the resulting sequence of wide characters.

No null wide character is added.

Matches a sequence of non-white-space characters.

252)

If no

length modifier is present, 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

length modifier is present, the input shall be a sequence of multibyte

252) No special provisions are made for multibyte characters in the matching rules used by the

, and

[

conversion specifiers — the extent of the input field is determined on a byte-by-byte basis. The
resulting field is nevertheless a sequence of multibyte characters that begins in the initial shift state.

§7.19.6.2 Library

285

characters that begins in the initial shift state. Each multibyte character is
converted to a wide character as if by a call to the

mbrtowc

function, with

the conversion state described by an

mbstate_t

object initialized to zero

before the first multibyte character is converted. The corresponding argument
shall be a pointer to the initial element of an array of

wchar_t

large enough

to accept the sequence and the terminating null wide character, which will be
added automatically.

[

Matches a nonempty sequence of characters from a set of expected characters
(the scanset).

252)

If no

length modifier is present, 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

length modifier is present, the input shall be a sequence of multibyte

characters that begins in the initial shift state. Each multibyte character is
converted to a wide character as if by a call to the

mbrtowc

function, with

the conversion state described by an

mbstate_t

object initialized to zero

before the first multibyte character is converted. 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 characters in the

format

string, up to and including the matching right bracket (

]

). The characters

between the brackets (the scanlist) compose the scanset, unless the character
after the left bracket is a circumflex (

), in which case the scanset contains all

characters that do not appear in the scanlist between the circumflex and the
right bracket. If the conversion specifier begins with

[]

[^]

, the right

bracket character is in the scanlist and the next following right bracket
character is the matching right bracket that ends the specification; otherwise
the first following right bracket character is the one that ends the
specification. If a

character is in the scanlist and is not the first, nor the

second where the first character is a

, nor the last character, the behavior is

implementation-defined.

Matches an implementation-defined set of sequences, which should be the
same as the set of sequences that may be produced by the

conversion of

the

fprintf

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

conversion is undefined.

286 Library

§7.19.6.2

Description

The

iswgraph

function tests for any wide character for which

iswprint

is true and

iswspace

is false.

306)

7.25.2.1.7 The

iswlower

function

Synopsis

#include <wctype.h>

int iswlower(wint_t wc);

Description

The

iswlower

function tests for any wide character that corresponds to a lowercase

letter or is one of a locale-specific set of wide characters for which none of

iswcntrl

iswdigit

iswpunct

, or

iswspace

is true.

7.25.2.1.8 The

iswprint

function

Synopsis

#include <wctype.h>

int iswprint(wint_t wc);

Description

The

iswprint

function tests for any printing wide character.

7.25.2.1.9 The

iswpunct

function

Synopsis

#include <wctype.h>

int iswpunct(wint_t wc);

Description

The

iswpunct

function tests for any printing wide character that is one of a locale-

specific set of punctuation wide characters for which neither

iswspace

nor

iswalnum

is true.

306)

7.25.2.1.10 The

iswspace

function

Synopsis

#include <wctype.h>

int iswspace(wint_t wc);

306) Note that the behavior of the

iswgraph

and

iswpunct

functions may differ from their

corresponding functions in 7.4.1 with respect to printing, white-space, single-byte execution
characters other than

' '

396 Library

§7.25.2.1.10

Description

The

iswspace

function tests for any wide character that corresponds to a locale-specific

set of white-space wide characters for which none of

iswalnum

iswgraph

, or

iswpunct

is true.

7.25.2.1.11 The

iswupper

function

Synopsis

#include <wctype.h>

int iswupper(wint_t wc);

Description

The

iswupper

function tests for any wide character that corresponds to an uppercase

letter or is one of a locale-specific set of wide characters for which none of

iswcntrl

iswdigit

iswpunct

, or

iswspace

is true.

7.25.2.1.12 The

iswxdigit

function

Synopsis

#include <wctype.h>

int iswxdigit(wint_t wc);

Description

The

iswxdigit

function tests for any wide character that corresponds to a

hexadecimal-digit character (as defined in 6.4.4.1).

7.25.2.2 Extensible wide character classification functions

The functions

wctype

and

iswctype

provide extensible wide character classification

as well as testing equivalent to that performed by the functions described in the previous
subclause (7.25.2.1).

7.25.2.2.1 The

iswctype

function

Synopsis

#include <wctype.h>

int iswctype(wint_t wc, wctype_t desc);

Description

The

iswctype

function determines whether the wide character

has the property

described by

desc

. The current setting of the

LC_CTYPE

category shall be the same as

during the call to

wctype

that returned the value

desc

Each of the following expressions has a truth-value equivalent to the call to the wide
character classification function (7.25.2.1) in the comment that follows the expression:

§7.25.2.2.1 Library

397

iswctype(wc, wctype("alnum"))

// iswalnum(wc)

iswctype(wc, wctype("alpha"))

// iswalpha(wc)

iswctype(wc, wctype("blank"))

// iswblank(wc)

iswctype(wc, wctype("cntrl"))

// iswcntrl(wc)

iswctype(wc, wctype("digit"))

// iswdigit(wc)

iswctype(wc, wctype("graph"))

// iswgraph(wc)

iswctype(wc, wctype("lower"))

// iswlower(wc)

iswctype(wc, wctype("print"))

// iswprint(wc)

iswctype(wc, wctype("punct"))

// iswpunct(wc)

iswctype(wc, wctype("space"))

// iswspace(wc)

iswctype(wc, wctype("upper"))

// iswupper(wc)

iswctype(wc, wctype("xdigit"))

// iswxdigit(wc)

Returns

The

iswctype

function returns nonzero (true) if and only if the value of the wide

character

has the property described by

desc

Forward references: the

wctype

function (7.25.2.2.2).

7.25.2.2.2 The

wctype

function

Synopsis

#include <wctype.h>

wctype_t wctype(const char *property);

Description

The

wctype

function constructs a value with type

wctype_t

that describes a class of

wide characters identified by the string argument

property

The strings listed in the description of the

iswctype

function shall be valid in all

locales as

property

arguments to the

wctype

function.

Returns

property

identifies a valid class of wide characters according to the

LC_CTYPE

category of the current locale, the

wctype

function returns a nonzero value that is valid

as the second argument to the

iswctype

function; otherwise, it returns zero.

∗

398 Library

§7.25.2.2.2

7.25.3 Wide character case mapping utilities

The header

<wctype.h>

declares several functions useful for mapping wide characters.

7.25.3.1 Wide character case mapping functions

7.25.3.1.1 The

towlower

function

Synopsis

#include <wctype.h>

wint_t towlower(wint_t wc);

Description

The

towlower

function converts an uppercase letter to a corresponding lowercase letter.

Returns

If the argument is a wide character for which

iswupper

is true and there are one or

more corresponding wide characters, as specified by the current locale, for which

iswlower

is true, the

towlower

function returns one of the corresponding wide

characters (always the same one for any giv en locale); otherwise, the argument is
returned unchanged.

7.25.3.1.2 The

towupper

function

Synopsis

#include <wctype.h>

wint_t towupper(wint_t wc);

Description

The

towupper

function converts a lowercase letter to a corresponding uppercase letter.

Returns

If the argument is a wide character for which

iswlower

is true and there are one or

more corresponding wide characters, as specified by the current locale, for which

iswupper

is true, the

towupper

function returns one of the corresponding wide

characters (always the same one for any giv en locale); otherwise, the argument is
returned unchanged.

7.25.3.2 Extensible wide character case mapping functions

The functions

wctrans

and

towctrans

provide extensible wide character mapping as

well as case mapping equivalent to that performed by the functions described in the
previous subclause (7.25.3.1).

§7.25.3.2 Library

399

7.25.3.2.1 The

towctrans

function

Synopsis

#include <wctype.h>

wint_t towctrans(wint_t wc, wctrans_t desc);

Description

The

towctrans

function maps the wide character

using the mapping described by

desc

. The current setting of the

LC_CTYPE

category shall be the same as during the call

wctrans

that returned the value

desc

Each of the following expressions behaves the same as the call to the wide character case
mapping function (7.25.3.1) in the comment that follows the expression:

towctrans(wc, wctrans("tolower"))

// towlower(wc)

towctrans(wc, wctrans("toupper"))

// towupper(wc)

Returns

The

towctrans

function returns the mapped value of

using the mapping described

desc

7.25.3.2.2 The

wctrans

function

Synopsis

#include <wctype.h>

wctrans_t wctrans(const char *property);

Description

The

wctrans

function constructs a value with type

wctrans_t

that describes a

mapping between wide characters identified by the string argument

property

The strings listed in the description of the

towctrans

function shall be valid in all

locales as

property

arguments to the

wctrans

function.

Returns

property

identifies a valid mapping of wide characters according to the

LC_CTYPE

category of the current locale, the

wctrans

function returns a nonzero value that is valid

as the second argument to the

towctrans

function; otherwise, it returns zero.

400 Library

§7.25.3.2.2

7.26 Future library directions

The following names are grouped under individual headers for convenience. All external
names described below are reserved no matter what headers are included by the program.

7.26.1 Complex arithmetic

<complex.h>

The function names

cerf

cerfc

cexp2

cexpm1

clog10

clog1p

clog2

clgamma

ctgamma

and the same names suffixed with

may be added to the declarations in the

<complex.h>

header.

7.26.2 Character handling

<ctype.h>

Function names that begin with either

, and a lowercase letter may be added to

the declarations in the

<ctype.h>

header.

7.26.3 Errors

<errno.h>

Macros that begin with

and a digit or

and an uppercase letter may be added to the

declarations in the

<errno.h>

header.

7.26.4 Format conversion of integer types

<inttypes.h>

Macro names beginning with

PRI

SCN

followed by any lowercase letter or

may be

added to the macros defined in the

<inttypes.h>

header.

7.26.5 Localization

<locale.h>

Macros that begin with

LC_

and an uppercase letter may be added to the definitions in

the

<locale.h>

header.

7.26.6 Signal handling

<signal.h>

Macros that begin with either

SIG

and an uppercase letter or

SIG_

and an uppercase

letter may be added to the definitions in the

<signal.h>

header.

7.26.7 Boolean type and values

<stdbool.h>

The ability to undefine and perhaps then redefine the macros

bool

true

, and

false

an obsolescent feature.

7.26.8 Integer types

<stdint.h>

Typedef names beginning with

int

uint

and ending with

may be added to the

types defined in the

<stdint.h>

header. Macro names beginning with

INT

UINT

and ending with

_MAX

_MIN

, or

may be added to the macros defined in the

<stdint.h>

header.

§7.26.8 Library

401

7.26.9 Input/output

<stdio.h>

Lowercase letters may be added to the conversion specifiers and length modifiers in

fprintf

and

fscanf

. Other characters may be used in extensions.

The

gets

function is obsolescent, and is deprecated.

The use of

ungetc

on a binary stream where the file position indicator is zero prior to

the call is an obsolescent feature.

7.26.10 General utilities

<stdlib.h>

Function names that begin with

str

and a lowercase letter may be added to the

declarations in the

<stdlib.h>

header.

7.26.11 String handling

<string.h>

Function names that begin with

str

mem

, or

wcs

and a lowercase letter may be added

to the declarations in the

<string.h>

header.

7.26.12 Extended multibyte and wide character utilities

<wchar.h>

Function names that begin with

wcs

and a lowercase letter may be added to the

declarations in the

<wchar.h>

header.

Lowercase letters may be added to the conversion specifiers and length modifiers in

fwprintf

and

fwscanf

. Other characters may be used in extensions.

7.26.13 Wide character classification and mapping utilities

<wctype.h>

Function names that begin with

and a lowercase letter may be added to the

declarations in the

<wctype.h>

header.

402 Library

§7.26.13

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