unsigned char stdc_bit_flooruc(unsigned char value);
unsigned short stdc_bit_floorus(unsigned short value);
unsigned int stdc_bit_floorui(unsigned int value);
unsigned long stdc_bit_floorul(unsigned long value);
unsigned long long stdc_bit_floorull(unsigned long long value);
generic_value_type stdc_bit_floor(generic_value_type value);
Description
The stdc_bit_floor functions compute the largest integral power of 2 that is not greater than
value.
Returns
The stdc_bit_floor functions return 0 if value is 0. Otherwise, they return the largest integral
power of 2 that is not greater than value.
The type-generic function (marked by its generic_value_type argument) returns the previously
described result for a given input value so long as the generic_value_type is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
7.18.16 [Bit Ceiling]
1 Synopsis
#include <stdbit.h>
unsigned char stdc_bit_ceiluc(unsigned char value);
unsigned short stdc_bit_ceilus(unsigned short value);
unsigned int stdc_bit_ceilui(unsigned int value);
unsigned long stdc_bit_ceilul(unsigned long value);
unsigned long long stdc_bit_ceilull(unsigned long long value);
generic_value_type stdc_bit_ceil(generic_value_type value);
Description
The stdc_bit_ceil functions compute the smallest integral power of 2 that is not less than value.
If the computation does not fit in the given return type, the behavior is undefined.
Returns
The stdc_bit_ceil functions return the smallest integral power of 2 that is not less than value.
The type-generic function (marked by its generic_value_type argument) returns the previously
described result for a given input value so long as the generic_value_type is an:
— standard unsigned integer type, excluding bool;
— extended unsigned integer type;
— or, bit-precise unsigned integer type whose width matches a standard or extended integer
type, excluding bool.
7.19 [Boolean type and values <stdbool.h>]
1 The header <stdbool.h> provides the obsolescent macro __bool_true_false_are_defined which
expands to the integer constant 1.
7.20 [Checked Integer Arithmetic <stdckdint.h>]
1 The header <stdckdint.h> defines several macros for performing checked integer arithmetic.
7.20.1 [The ckd_ Checked Integer Operation Macros]
1 Synopsis
#include <stdckdint.h>
bool ckd_add(type1 *result, type2 a, type3 b);
bool ckd_sub(type1 *result, type2 a, type3 b);
bool ckd_mul(type1 *result, type2 a, type3 b);
Description
2 These macros perform addition, subtraction, or multiplication of the mathematical values of a and b,
storing the result of the operation in *result , (that is, *result is assigned the result of computing
a + b, a - b, or a * b). Each operation is performed as if both operands were represented in a
signed integer type with infinite range, and the result was then converted from this integer type to
type1.
3 Both type2 and type3 shall be any integer type other than plain char, bool, a bit-precise integer
type, or an enumeration type, and they need not be the same. *result shall be a modifiable lvalue
of any integer type other than plain char, bool, a bit-precise integer type, or an enumeration type.
Recommended practice
4 It is recommended to produce a diagnostic message if type2 or type3 are not suitable integer types,
or if *result is not a modifiable lvalue of a suitable integer type.
Returns
5 If these macros return false, the value assigned to *result correctly represents the mathematical
result of the operation. Otherwise, these macros return true. In this case, the value assigned to
*result is the mathematical result of the operation wrapped around to the width of *result .
6 EXAMPLE 1 If a and b are values of type signed int, and result is a signed long, then
ckd_sub(&result, a, b);
will indicate if a - b can be expressed as a signed long. If signed long has a greater width than signed int, this will
always be possible and this macro will return false.
7.21 [Common definitions <stddef.h>]
1 The header <stddef.h> defines the following macros and declares the following types. Some are
also defined in other headers, as noted in their respective subclauses.
2 The types are
ptrdiff_t
which is the signed integer type of the result of subtracting two pointers;
size_t
which is the unsigned integer type of the result of the sizeof operator;
max_align_t
which is an object type whose alignment is the greatest fundamental alignment;
wchar_t
which is an integer type whose range of values can represent distinct codes for all members of the
largest extended character set specified among the supported locales; the null character shall have
the code value zero. Each member of the basic character set shall have a code value equal to its
value when used as the lone character in an integer character constant if an implementation does
not define __STDC_MB_MIGHT_NEQ_WC__ ; and,
nullptr_t
which is the type of the nullptr predefined constant, see below.
3 The macros are
NULL
which expands to an implementation-defined null pointer constant;
unreachable()
which expands to a void expression that invokes undefined behavior if it is reached during execution;
and
offsetof(type, member-designator)
which expands to an integer constant expression that has type size_t, the value of which is the
offset in bytes, to the subobject (designated by member-designator), from the beginning of any object
of type type. The type and member designator shall be such that given
static type t;
then the expression &(t. member-designator) evaluates to an address constant. If the specified type
defines a new type or if the specified member is a bit-field, the behavior is undefined.
Recommended practice
4 The types used for size_t and ptrdiff_t should not have an integer conversion rank greater than
that of signed long int unless the implementation supports objects large enough to make this
necessary.
7.21.1 [The unreachable macro]
1 Synopsis
#include <stddef.h>
void unreachable(void);
Description
2 A call to the function-like macro unreachable indicates that the particular flow control that leads to
the call will never be taken; it receives no arguments and expands to a void expression. The program
execution shall not reach such a call.
Returns
3 If a macro call unreachable() is reached during execution, the behavior is undefined.
4 EXAMPLE 1 The following program assumes that each execution is provided with at least one command line argument.
The behavior of an execution with no arguments is undefined.
#include <stddef.h>
#include <stdio.h>
int main (int argc, char* argv[static argc + 1]) {
if (argc <= 2)
unreachable();
else
return printf("%s: we see %s", argv[0], argv[1]);
return puts("this should never be reached");
}
Here, the static array size expression and the annotation of the control flow with unreachable indicates that the pointed-to
parameter array argv will hold at least three elements, regardless of the circumstances. A possible optimization is that the
resulting executable never performs the comparison and unconditionally executes a tail call to printf that never returns to
the main function. In particular, the entire call and reference to puts can be omitted from the executable. No diagnostic is
expected.
7.21.2 [The nullptr_t type]
1 Synopsis
#include <stddef.h>
typedef typeof_unqual(nullptr) nullptr_t;
Description
2 The nullptr_t type is the type of the nullptr predefined constant. It has only a very limited use
in contexts where this type is needed to distinguish nullptr from other expression types. It is an
unqualified complete scalar type that is different from all pointer or arithmetic types and is neither
an atomic or array type and has exactly one value, nullptr. Default initialization of an object of this
type is equivalent to an initialization by nullptr.
3 The size and alignment of nullptr_t is the same as for a pointer to character type. An object
representation of the value nullptr is the same as the object representation of a null pointer value of
type void*. An lvalue conversion of an object of type nullptr_t with such an object representation
has the value nullptr; if the object representation is different, the behavior is undefined[319] .
Footnote 319) Thus, during the whole program execution an object of type nullptr_t evaluates to the assumed value nullptr.
4 NOTE Because it is considered to be a scalar type, nullptr_t may appear in many context where (void*)0 would be valid,
for example,
— as the operand of alignas, sizeof or typeof operators,
— as the operand of an implicit or explicit conversion to a pointer type,
— as the assignment expression in an assignment or initialization of an object of type nullptr_t,
— as an argument to a parameter of type nullptr_t or in a variable argument list,
— as a void expression,
— as the operand of an implicit or explicit conversion to bool,
— as an operand of a _Generic primary expression,
— as an operand of the !, &&, || or conditional operators, or
— as the controlling expression of an if or iteration statement.
7.22 [Integer types <stdint.h>]
1 The header <stdint.h> declares sets of integer types having specified widths, and defines corre-
sponding sets of macros.[320] It also defines macros that specify limits of integer types corresponding
to types defined in other standard headers.
Footnote 320) See "future library directions" (7.33.14).
2 Types are defined in the following categories:
— integer types having certain exact widths;
— integer types having at least certain specified widths;
— fastest integer types having at least certain specified widths;
— integer types wide enough to hold pointers to objects;
— integer types having greatest width.
(Some of these types may denote the same type.)
3 Corresponding macros specify limits of the declared types and construct suitable constants.
4 For each type described herein that the implementation provides,[321] <stdint.h> shall declare that
typedef name and define the associated macros. Conversely, for each type described herein that
the implementation does not provide, <stdint.h> shall not declare that typedef name nor shall it
define the associated macros. An implementation shall provide those types described as "required",
but need not provide any of the others (described as "optional"). None of the types shall be defined
as a synonym for a bit-precise integer type.
Footnote 321) Some of these types might denote implementation-defined extended integer types.
5 The feature test macro __STDC_VERSION_STDINT_H__ expands to the token 202311L.
7.22.1 [Integer types]
1 When typedef names differing only in the absence or presence of the initial u are defined, they shall
denote corresponding signed and unsigned types as described in 6.2.5; an implementation providing
one of these corresponding types shall also provide the other.
2 In the following descriptions, the symbol N represents an unsigned decimal integer with no leading
zeros (e.g., 8 or 24, but not 04 or 048).
<IP_ADDRESS> [Exact-width integer types]
1 The typedef name intN_t designates a signed integer type with width N and no padding bits. Thus,
int8_t denotes such a signed integer type with a width of exactly 8 bits.
2 The typedef name uintN_t designates an unsigned integer type with width N and no padding bits.
Thus, uint24_t denotes such an unsigned integer type with a width of exactly 24 bits.
3 If an implementation provides standard or extended integer types with a particular width and no
padding bits, it shall define the corresponding typedef names.
<IP_ADDRESS> [Minimum-width integer types]
1 The typedef name int_leastN_t designates a signed integer type with a width of at least N, such
that no signed integer type with lesser size has at least the specified width. Thus, int_least32_t
denotes a signed integer type with a width of at least 32 bits.
2 The typedef name uint_leastN_t designates an unsigned integer type with a width of at least
N, such that no unsigned integer type with lesser size has at least the specified width. Thus,
uint_least16_t denotes an unsigned integer type with a width of at least 16 bits.
3 If the typedef name intN_t is defined, int_leastN_t designates the same type. If the typedef
name uintN_t is defined, uint_leastN_t designates the same type.
4 The following types are required:
int_least8_t uint_least8_t
int_least16_t uint_least16_t
int_least32_t uint_least32_t
int_least64_t uint_least64_t
All other types of this form are optional.
<IP_ADDRESS> [Fastest minimum-width integer types]
1 Each of the following types designates an integer type that is usually fastest[322] to operate with
among all integer types that have at least the specified width.
Footnote 322) The designated type is not guaranteed to be fastest for all purposes; if the implementation has no clear grounds for
choosing one type over another, it will simply pick some integer type satisfying the signedness and width requirements.
2 The typedef name int_fastN_t designates the fastest signed integer type with a width of at least N.
The typedef name uint_fastN_t designates the fastest unsigned integer type with a width of at
least N.
3 The following types are required:
int_fast8_t uint_fast8_t
int_fast16_t uint_fast16_t
int_fast32_t uint_fast32_t
int_fast64_t uint_fast64_t
All other types of this form are optional.
<IP_ADDRESS> [Integer types capable of holding object pointers]
1 The following type designates a signed integer type, other than a bit-precise integer type, with the
property that any valid pointer to void can be converted to this type, then converted back to pointer
to void, and the result will compare equal to the original pointer:
intptr_t
The following type designates an unsigned integer type, other than a bit-precise integer type, with
the property that any valid pointer to void can be converted to this type, then converted back to
pointer to void, and the result will compare equal to the original pointer:
uintptr_t
These types are optional.
<IP_ADDRESS> [Greatest-width integer types]
1 The following type designates a signed integer type, other than a bit-precise integer type, capable of
representing any value of any signed integer type with the possible exceptions of signed bit-precise
integer types and of signed extended integer types that are wider than long long and that are
referred by the type definition for an exact width integer type:
intmax_t
The following type designates the unsigned integer type that corresponds to intmax_t[323] :
uintmax_t
These types are required.
Footnote 323) Thus this type is capable of representing any value of any unsigned integer type with the possible exception of particular
extended integer types that are wider than unsigned long long.
7.22.2 [Widths of specified-width integer types]
1 The following object-like macros specify the width of the types declared in <stdint.h>. Each macro
name corresponds to a similar type name in 7.22.1.
2 Each instance of any defined macro shall be replaced by a constant expression suitable for use in
#if preprocessing directives. Its implementation-defined value shall be equal to or greater than
the value given below, except where stated to be exactly the given value. An implementation shall
define only the macros corresponding to those typedef names it actually provides.[324]
Footnote 324) The exact-width and pointer-holding integer types are optional.
<IP_ADDRESS> [Width of exact-width integer types]
1 INTN_WIDTH exactly N
UINTN_WIDTH exactly N
<IP_ADDRESS> [Width of minimum-width integer types]
1 INT_LEASTN_WIDTH exactly UINT_LEASTN_WIDTH
UINT_LEASTN_WIDTH N
<IP_ADDRESS> [Width of fastest minimum-width integer types]
1 INT_FASTN_WIDTH exactly UINT_FASTN_WIDTH
UINT_FASTN_WIDTH N
<IP_ADDRESS> [Width of integer types capable of holding object pointers]
1 INTPTR_WIDTH exactly UINTPTR_WIDTH
UINTPTR_WIDTH 16
<IP_ADDRESS> [Width of greatest-width integer types]
1 INTMAX_WIDTH exactly UINTMAX_WIDTH
UINTMAX_WIDTH 64
7.22.3 [Width of other integer types]
1 The following object-like macros specify the width of integer types corresponding to types defined
in other standard headers.
2 Each instance of these macros shall be replaced by a constant expression suitable for use in #if
preprocessing directives. Its implementation-defined value shall be equal to or greater than the
corresponding value given below. An implementation shall define only the macros corresponding
to those typedef names it actually provides.[325]
Footnote 325) A freestanding implementation need not provide all of these types.
<IP_ADDRESS> [Width of ptrdiff_t]
1 PTRDIFF_WIDTH 16
<IP_ADDRESS> [Width of sig_atomic_t]
1 SIG_ATOMIC_WIDTH 8
<IP_ADDRESS> [Width of size_t]
1 SIZE_WIDTH 16
<IP_ADDRESS> [Width of wchar_t]
1 WCHAR_WIDTH 8
<IP_ADDRESS> [Width of wint_t]
1 WINT_WIDTH 16
7.22.4 [Macros for integer constants]
1 The following function-like macros expand to integer constants suitable for initializing objects that
have integer types corresponding to types defined in <stdint.h>. Each macro name corresponds to
a similar type name in <IP_ADDRESS> or <IP_ADDRESS>.
2 The argument in any instance of these macros shall be an unsuffixed integer constant (as defined
in <IP_ADDRESS>) with a value that does not exceed the limits for the corresponding type.
3 Each invocation of one of these macros shall expand to an integer constant expression. The type of
the expression shall have the same type as would an expression of the corresponding type converted
according to the integer promotions. The value of the expression shall be that of the argument. If
the value is in the range of the type intmax_t (for a signed type) or the type uintmax_t (for an
unsigned type), see <IP_ADDRESS>, the expression is suitable for use in #if preprocessing directives.
<IP_ADDRESS> [Macros for minimum-width integer constants]
1 The macro INTN_C( value) expands to an integer constant expression corresponding to the type
int_leastN_t . The macro UINTN_C( value) expands to an integer constant expression corre-
sponding to the type uint_leastN_t . For example, if uint_least64_t is a name for the type
unsigned long long int, then UINT64_C(0x123) might expand to the integer constant 0x123ULL.
<IP_ADDRESS> [Macros for greatest-width integer constants]
1 The following macro expands to an integer constant expression having the value specified by its
argument and the type intmax_t:
INTMAX_C(value)
The following macro expands to an integer constant expression having the value specified by its
argument and the type uintmax_t:
UINTMAX_C(value)
7.22.5 [Maximal and minimal values of integer types]
1 For all integer types for which there is a macro with suffix _WIDTH holding the width, maximum
macros with suffix _MAX and, for all signed types, minimum macros with suffix _MIN are defined as
by <IP_ADDRESS>. If it is unspecified if a type is signed or unsigned and the implementation has it as an
unsigned type, a minimum macro with extension _MIN , and value 0 of the corresponding type is
defined.
7.23 [Input/output <stdio.h>]
7.23.1 [Introduction]
1 The header <stdio.h> defines several macros, and declares three types and many functions for
performing input and output.
2 The types declared are size_t (described in 7.21);
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 a complete object type other than an array type capable of recording all the information
needed to specify uniquely every position within a file.
3 The macros are NULL (described in 7.21);
_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 guarantees can be opened or, if
the implementation imposes no practical limit on the length of file name strings, the recommended
size of an array intended to hold a file name string[326] ;
_PRINTF_NAN_LEN_MAX
which expands to an integer constant expression (suitable for use in #if preprocessing directives)
that is the maximum number of characters output for any
[-]NAN(n-char-sequence)
sequence.[327] If an implementation has no support for NaNs, it shall be 0. _PRINTF_NAN_LEN_MAX
shall be less than 64;
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 minimum 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.
Footnote 326) 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.
Footnote 327) If the implementation only uses the [-]NAN style, then _PRINTF_NAN_LEN_MAX would have the value 4.
4 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.23.3.
5 The input/output functions are given the following collective terms:
— The wide character input functions — those functions described in 7.31 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.31 that perform output from
wide characters and wide strings: fputwc, fputws, putwc, putwchar, fwprintf, wprintf,
vfwprintf , and vwprintf.
— The wide character input/output functions — the union of the ungetwc function, the wide charac-
ter 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,
printf, putc, putchar, puts, scanf, ungetc, vfprintf , vfscanf , vprintf , and vscanf.
Forward references: files (7.23.3), the fseek function (<IP_ADDRESS>), streams (7.23.2), the tmpnam func-
tion (<IP_ADDRESS>), <wchar.h> (7.31).
7.23.2 [Streams]
1 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.[328]
Footnote 328) 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.
2 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.
3 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, have an implementation-
defined number of null characters appended to the end of the stream.
4 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/out-
put function has been applied to a stream without orientation, the stream becomes a wide-oriented
stream. Similarly, once a byte input/output function has been applied to a stream without orien-
tation, 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.)[329]
Footnote 329) The three predefined streams stdin, stdout, and stderr are unoriented at program startup.
5 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 may henceforth not
consist of valid multibyte characters.
6 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.
7 Each stream has an associated lock that is used to prevent data races when multiple threads of
execution access a stream, and to restrict the interleaving of stream operations performed by multiple
threads. Only one thread may hold this lock at a time. The lock is reentrant: a single thread may
hold the lock multiple times at a given time.
8 All functions that read, write, position, or query the position of a stream lock the stream before
accessing it. They release the lock associated with the stream when the access is complete.
Environmental limits
9 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 (<IP_ADDRESS>), the fwide function (<IP_ADDRESS>), mbstate_t
(7.31.1), the fgetpos function (<IP_ADDRESS>), the fsetpos function (<IP_ADDRESS>).
7.23.3 [Files]
1 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.
2 Binary files are not truncated, except as defined in <IP_ADDRESS>. Whether a write on a text stream causes
the associated file to be truncated beyond that point is implementation-defined.
3 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.
4 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 lifetime of a FILE object ends when 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.
5 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.
6 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.
7 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.
8 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.
9 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 encod-
ings valid for use internal to the program).
— A file need not begin nor end in the initial shift state.[330]
Footnote 330) 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.
10 Moreover, the encodings used for multibyte characters may differ among files. Both the nature and
choice of such encodings are implementation-defined.
11 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.
12 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.
13 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.
14 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) multibyte character. The wide character
input/output functions and the byte input/output functions store the value of the macro EILSEQ in
errno if and only if an encoding error occurs.
Environmental limits
15 The value of FOPEN_MAX shall be at least eight, including the three standard text streams.
Forward references: the exit function (<IP_ADDRESS>), the fgetc function (<IP_ADDRESS>), the fopen function
(<IP_ADDRESS>), the fputc function (<IP_ADDRESS>), the setbuf function (<IP_ADDRESS>), the setvbuf function (<IP_ADDRESS>),
the fgetwc function (<IP_ADDRESS>), the fputwc function (<IP_ADDRESS>), conversion state (7.31.6), the mbrtowc
function (<IP_ADDRESS>.2), the wcrtomb function (<IP_ADDRESS>.3).
7.23.4 [Operations on files]
<IP_ADDRESS> [The remove function]
1 Synopsis
#include <stdio.h>
int remove(const char *filename);
Description
2 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
3 The remove function returns zero if the operation succeeds, nonzero if it fails.
<IP_ADDRESS> [The rename function]
1 Synopsis
#include <stdio.h>
int rename(const char *old, const char *new);
Description
2 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.
Returns
3 The rename function returns zero if the operation succeeds, nonzero if it fails,[331] in which case if the
file existed previously it is still known by its original name.
Footnote 331) Among the reasons the implementation could 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.
<IP_ADDRESS> [The tmpfile function]
1 Synopsis
#include <stdio.h>
FILE *tmpfile(void);
Description
2 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
3 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
4 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 (<IP_ADDRESS>).
<IP_ADDRESS> [The tmpnam function]
1 Synopsis
#include <stdio.h>
char *tmpnam(char *s);
Description
2 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.[332] The function is potentially capable of generating at least 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.
Footnote 332) Files created using strings generated by the tmpnam function are temporary only in the sense that their names are not
expected to 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.
3 The tmpnam function generates a different string each time it is called.
4 Calls to the tmpnam function with a null pointer argument may introduce data races with each other.
The implementation shall behave as if no library function calls the tmpnam function.
Returns
5 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 chars;
the tmpnam function writes its result in that array and returns the argument as its value.
Environmental limits
6 The value of the macro TMP_MAX shall be at least 25.
7.23.5 [File access functions]
<IP_ADDRESS> [The fclose function]
1 Synopsis
#include <stdio.h>
int fclose(FILE *stream);
Description
2 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 or setvbuf
function is disassociated from the stream (and deallocated if it was automatically allocated).
Returns
3 The fclose function returns zero if the stream was successfully closed, or EOF if any errors were
detected.
<IP_ADDRESS> [The fflush function]
1 Synopsis
#include <stdio.h>
int fflush(FILE *stream);
Description
2 If 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.
3 If stream is a null pointer, the fflush function performs this flushing action on all streams for which
the behavior is defined above.
Returns
4 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 (<IP_ADDRESS>).
<IP_ADDRESS> [The fopen function]
1 Synopsis
#include <stdio.h>
FILE *fopen(const char * restrict filename, const char * restrict mode);
Description
2 The fopen function opens the file whose name is the string pointed to by filename, and associates
a stream with it.
3 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.[333]
r open text file for reading
w truncate to zero length or create text file for writing
wx create text file for writing
a append; open or create text file for writing at end-of-file
rb open binary file for reading
wb truncate to zero length or create binary file for writing
wbx create binary file for writing
ab append; open or create binary file for writing at end-of-file
r+ open text file for update (reading and writing)
w+ truncate to zero length or create text file for update
w+x create text file for update
a+ append; open or create text file for update, writing at end-of-file
r+b or rb+ open binary file for update (reading and writing)
w+b or wb+ truncate to zero length or create binary file for update
w+bx or wb+x create binary file for update
a+b or ab+ append; open or create binary file for update, writing at end-of-file
Footnote 333) If the string begins with one of the listed mode 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.23.2).
4 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.
5 Opening a file with exclusive mode (’x’ as the last character in the mode argument) fails if the file
already exists or cannot be created. Otherwise, the file is created with exclusive (also known as
non-shared) access to the extent that the underlying system supports exclusive access.
6 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.
7 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.
8 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
9 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.23.9).
<IP_ADDRESS> [The freopen function]
1 Synopsis
#include <stdio.h>
FILE *freopen(const char * restrict filename, const char * restrict mode,
FILE * restrict stream);
Description
2 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 as in the fopen function.[334]
Footnote 334) 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 could be
assigned.
3 If 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.
4 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
5 The freopen function returns a null pointer if the open operation fails. Otherwise, freopen returns
the value of stream.
<IP_ADDRESS> [The setbuf function]
1 Synopsis
#include <stdio.h>
void setbuf(FILE * restrict stream, char * restrict buf);
Description
2 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
3 The setbuf function returns no value.
Forward references: the setvbuf function (<IP_ADDRESS>).
<IP_ADDRESS> [The setvbuf function]
1 Synopsis
#include <stdio.h>
int setvbuf(FILE * restrict stream, char * restrict buf, int mode, size_t size);
Description
2 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[335] 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 members of the array at any
time have unspecified values.
Returns
Footnote 335) The buffer has to have a lifetime at least as great as the open stream, so not closing the stream before a buffer that has
automatic storage duration is deallocated upon block exit results in undefined behavior.
3 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.23.6 [Formatted input/output functions]
1 The formatted input/output functions shall behave as if there is a sequence point after the actions
associated with each specifier.[336]
Footnote 336) The fprintf functions perform writes to memory for the %n specifier.
<IP_ADDRESS> [The fprintf function]
1 Synopsis
#include <stdio.h>
int fprintf(FILE * restrict stream, const char * restrict format, ...);
Description
2 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.
3 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 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 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.[337]
— An optional precision that gives the minimum number of digits to appear for the b, d, i, o, u, x,
and X conversions, the number of digits to appear after the decimal-point 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 bytes to be written for s conversions. The precision takes the form
of a period (.) followed either by an asterisk * (described later) or by an optional nonnegative
decimal integer; if only the period is specified, the precision is taken as zero. If a precision
appears with any other conversion specifier, the behavior is undefined.
— An optional length modifier that specifies the size of the argument.
— A conversion specifier character that specifies the type of conversion to be applied.
Footnote 337) Note that 0 is taken as a flag, not as the beginning of a field width.
5 As noted above, a field width, or precision, or both, may be indicated by an asterisk. In this case,
an int argument supplies the field width or precision. The arguments specifying field width, or
precision, or both, shall appear (in that order) before the argument (if any) to be converted. A
negative field width argument is taken as a - flag followed by a positive field width. A negative
precision argument is taken as if the precision were omitted.
6 The flag characters and their meanings are:
- The result of the conversion is left-justified within the field. (It is right-justified if this flag is
not specified.)
+ The result of a signed conversion always begins with a plus or minus sign. (It begins with a
sign only when a value with a negative sign is converted if this flag is not specified.) [338]
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 o conversion, it increases the precision, if
and only if necessary, to force the first digit of the result to be a zero (if the value and precision
are both 0, a single 0 is printed). For b conversion, a nonzero result has 0b prefixed to it. For
x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g, and G
conversions, the result of converting a floating-point number always contains a decimal-point
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 g and G conversions, trailing zeros
are not removed from the result. For other conversions, the behavior is undefined.
0 For b, d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, leading zeros (following any
indication of sign or base) are used to pad to the field width rather than performing space
padding, except when converting an infinity or NaN. If the 0 and - flags both appear, the
0 flag is ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 0 flag is
ignored. For other conversions, the behavior is undefined.
Footnote 338) The results of all floating conversions of a negative zero, and of negative values that round to zero, include a minus sign.
7 The length modifiers and their meanings are:
hh Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a
signed char or unsigned char argument (the argument will have been promoted
according to the integer promotions, but its value shall be converted to signed char or
unsigned char before printing); or that a following n conversion specifier applies to a
pointer to a signed char argument.
h Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a short int
or unsigned short int argument (the argument will have been promoted accord-
ing to the integer promotions, but its value shall be converted to short int or
unsigned short int before printing); or that a following n conversion specifier applies
to a pointer to a short int argument.
l (ell) Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a long int
or unsigned long int argument; that a following n conversion specifier applies to
a pointer to a long int argument; that a following c conversion specifier applies to
a wint_t argument; that a following s conversion specifier applies to a pointer to a
wchar_t argument; or has no effect on a following a, A, e, E, f, F, g, or G conversion
specifier.
ll (ell-ell) Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a
long long int or unsigned long long int argument; or that a following n con-
version specifier applies to a pointer to a long long int argument.
j Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to an intmax_t
or uintmax_t argument; or that a following n conversion specifier applies to a pointer
to an intmax_t argument.
z Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a size_t
or the corresponding signed integer type argument; or that a following n conversion
specifier applies to a pointer to a signed integer type corresponding to size_t argument.
t Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a ptrdiff_t
or the corresponding unsigned integer type argument; or that a following n conversion
specifier applies to a pointer to a ptrdiff_t argument.
wN Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to an integer
argument with a specific width where N is a positive decimal integer with no leading
zeros (the argument will have been promoted according to the integer promotions, but
its value shall be converted to the unpromoted type); or that a following n conversion
specifier applies to a pointer to an integer type argument with a width of N bits. All
minimum-width integer types (<IP_ADDRESS>) and exact-width integer types (<IP_ADDRESS>) de-
fined in the header <stdint.h> shall be supported. Other supported values of N are
implementation-defined.
wfN Specifies that a following b, d, i, o, u, x, or X conversion specifier applies to a fastest
minimum-width integer argument with a specific width where N is a positive decimal
integer with no leading zeros (the argument will have been promoted according to
the integer promotions, but its value shall be converted to the unpromoted type); or
that a following n conversion specifier applies to a pointer to a fastest minimum-width
integer type argument with a width of N bits. All fastest minimum-width integer types
(<IP_ADDRESS>) defined in the header <stdint.h> shall be supported. Other supported values
of N are implementation-defined.
L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
long double argument.
H Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
_Decimal32 argument.
D Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
_Decimal64 argument.
DD Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to a
_Decimal128 argument.
If a length modifier appears with any conversion specifier other than as specified above, the behavior
is undefined.
8 The conversion specifiers and their meanings are:
d,i The int argument is converted to signed decimal in the style [-]dddd. The precision
specifies the minimum number of digits to appear; if the value being converted can be
represented in fewer digits, it is expanded with leading zeros. The default precision is 1.
The result of converting a zero value with a precision of zero is no characters.
b, o,u,x,X The unsigned int argument is converted to unsigned binary (b), unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (x or X) in the style dddd; the
letters abcdef are used for x conversion and the letters ABCDEF for X conversion. The
precision specifies the minimum number of digits to appear; if the value being converted
can be represented in fewer digits, it is expanded with leading zeros. The default precision
is 1. The result of converting a zero value with a precision of zero is no 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 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.
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-char-sequence) — which style, and
the meaning of any n-char-sequence, is implementation-defined. The F conversion specifier
produces INF, INFINITY, or NAN instead of inf, infinity, or nan, respectively.[339]
e,E A double argument representing a floating-point number is converted in the style
[-]d.ddde±dd, where there is one digit (which is nonzero if the argument is nonzero) before
the decimal-point 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 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 character is removed if there is no fractional portion
remaining.
A double argument representing an infinity or NaN is converted in the style of an f or F
conversion specifier.
a,A A double argument representing a floating-point number is converted in the style
[-]0xh.hhhhp±d, where there is one hexadecimal digit (which is nonzero if the argument is a
normalized floating-point number and is otherwise unspecified) before the decimal-point
character[340] 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[341] 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 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.
[339] When applied to infinite and NaN values, the -, +, and space flag characters have their usual meaning; the # and 0 flag
characters have no effect.
[340] 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. This implementation choice affects numerical values printed with a precision P
that is insufficient to represent all values exactly. Implementations with different conventions about the most significant
hexadecimal digit will round at different places, affecting the numerical value of the hexadecimal result. For example,
possible printed output for the code
#include <stdio.h>
/* ... */
double x = 123.0;
printf("%.1a", x);
include "0x1.fp+6 " and "0xf.6p+3 " whose numerical values are 124 and 123, respectively. Portable code seeking identical
numerical results on different platforms should avoid precisions P that require rounding.
[341] The formatting precision P is sufficient to distinguish values of the source type if 16P > bp where b (not a power of 2)
and p are the base and precision of the source type (<IP_ADDRESS>.2). A smaller P might suffice depending on the implementation’s
scheme for determining the digit to the left of the decimal-point character.
If an H, D, or DD modifier is present and the precision is missing, then for a decimal
floating type argument represented by a triple of integers (s, c, q), where n is the number
of significant digits in the coefficient c,
— if −(n + 5) ≤ q ≤ 0, use style f (or style F in the case of an A conversion specifier)
with formatting precision equal to −q,
— otherwise, use style e (or style E in the case of an A conversion specifier) with format-
ting precision equal to n − 1, with the exceptions that if c = 0 then the digit-sequence
in the exponent-part shall have the value q (rather than 0), and that the exponent is
always expressed with the minimum number of digits required to represent its value
(the exponent never contains a leading zero).
If the precision P is present (in the conversion specification) and is zero or at least as
large as the precision p (<IP_ADDRESS>.2) of the decimal floating type, the conversion is as if the
precision were missing. If the precision P is present (and nonzero) and less than the
precision p of the decimal floating type, the conversion first obtains an intermediate result
as follows, where n is the number of significant digits in the coefficient:
— If n ≤ P , set the intermediate result to the input.
— If n > P , round the input value, according to the current rounding direction for
decimal floating-point operations, to P decimal digits, with unbounded exponent
range, representing the result with a P -digit integer coefficient when in the form
(s, c, q).
Convert the intermediate result in the manner described above for the case where the
precision is missing.
c If no l length modifier is present, the int argument is converted to an unsigned char,
and the resulting character is written.
If an l length modifier is present, the wint_t argument is converted as if by an ls
conversion specification with no precision and an argument that points to storage suitably
sized for at least two wchar_t elements, the first element containing the wint_t argument
to the lc conversion specification and the second a null wide character.
s If no l length modifier is present, the argument shall be a pointer to storage of character
type.[342] Characters from the storage are 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 storage, the storage shall
contain a null character.
If an l length modifier is present, the argument shall be a pointer to storage of wchar_t
type. Wide characters from the storage are 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
storage 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 storage 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.[343]
p The argument shall be a pointer to void or a pointer to a character type. The value of the
pointer is converted to a sequence of printing characters, in an implementation-defined
manner.
n The argument shall be a pointer to signed integer whose type is specified by the length
modifiers, if any, for the conversion specification, or shall be int if no length modifiers are
specified for the conversion specification. The number of characters written to the output
stream so far by this call to fprintf is stored into the integer object pointed to by the
argument. No argument is converted, but one is consumed. If the conversion specification
includes any flags, a field width, or a precision, the behavior is undefined.
% A % character is written. No argument is converted. The complete conversion specification
shall be %%.
Footnote 339) When applied to infinite and NaN values, the -, +, and space flag characters have their usual meaning; the # and 0 flag
characters have no effect.
Footnote 340) 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. This implementation choice affects numerical values printed with a precision P
that is insufficient to represent all values exactly. Implementations with different conventions about the most significant
hexadecimal digit will round at different places, affecting the numerical value of the hexadecimal result. For example,
possible printed output for the code
#include <stdio.h>
/* ... */
double x = 123.0;
printf("%.1a", x);
include "0x1.fp+6 " and "0xf.6p+3 " whose numerical values are 124 and 123, respectively. Portable code seeking identical
numerical results on different platforms should avoid precisions P that require rounding.
Footnote 341) The formatting precision P is sufficient to distinguish values of the source type if 16P > bp where b (not a power of 2)
and p are the base and precision of the source type (<IP_ADDRESS>.2). A smaller P might suffice depending on the implementation’s
scheme for determining the digit to the left of the decimal-point character.
Footnote 339) When applied to infinite and NaN values, the -, +, and space flag characters have their usual meaning; the # and 0 flag
characters have no effect.
Footnote 340) 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. This implementation choice affects numerical values printed with a precision P
that is insufficient to represent all values exactly. Implementations with different conventions about the most significant
hexadecimal digit will round at different places, affecting the numerical value of the hexadecimal result. For example,
possible printed output for the code
#include <stdio.h>
/* ... */
double x = 123.0;
printf("%.1a", x);
include "0x1.fp+6 " and "0xf.6p+3 " whose numerical values are 124 and 123, respectively. Portable code seeking identical
numerical results on different platforms should avoid precisions P that require rounding.
Footnote 341) The formatting precision P is sufficient to distinguish values of the source type if 16P > bp where b (not a power of 2)
and p are the base and precision of the source type (<IP_ADDRESS>.2). A smaller P might suffice depending on the implementation’s
scheme for determining the digit to the left of the decimal-point character.
Footnote 342) No special provisions are made for multibyte characters.
Footnote 343) Redundant shift sequences can result if multibyte characters have a state-dependent encoding.
9 If a conversion specification is invalid, the behavior is undefined.[344] fprintf shall behave as if it
uses va_arg with a type argument naming the type resulting from applying the default argument
promotions to the type corresponding to the conversion specification and then converting the result
of the va_arg expansion to the type corresponding to the conversion specification.[345]
Footnote 344) See "future library directions" (7.33.15).
Footnote 345) The behavior is undefined when the types differ as specified for va_arg <IP_ADDRESS>.
10 In no case does a nonexistent or small field width cause truncation of a field; if the result of a
conversion is wider than the field width, the field is expanded to contain the conversion result.
11 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded to a hexadecimal
floating number with the given precision.
Recommended practice
12 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly representable
in the given precision, the result should be one of the two adjacent numbers in hexadecimal floating
style with the given precision, with the extra stipulation that the error should have a correct sign for
the current rounding direction.
13 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most the maximum
value M of the T_DECIMAL_DIG macros (defined in <float.h>), then the result should be correctly
rounded.[346] If the number of significant decimal digits is more than M but the source value is
exactly representable with M digits, then the result should be an exact representation with trailing
zeros. Otherwise, the source value is bounded by two adjacent decimal strings L < U, both having
M significant digits; the value of the resultant decimal string D should satisfy L ≤ D ≤ U, with the
extra stipulation that the error should have a correct sign for the current rounding direction.
Footnote 346) For binary-to-decimal conversion, the result format’s values are the numbers representable with the given format specifier.
The number of significant digits is determined by the format specifier, and in the case of fixed-point conversion by the source
value as well.
14 An uppercase B format specifier is not covered by the description above, because it used to be
available for extensions in previous versions of this standard.
Implementations that did not use an uppercase B as their own extension before are encouraged to
implement it similar to conversion specifier b as standardized above, with the alternative form (#B)
generating 0B as prefix for nonzero values.
Returns
15 The fprintf function returns the number of characters transmitted, or a negative value if an output
or encoding error occurred or if the implementation does not support a specified width length
modifier.
Environmental limits
16 The number of characters that can be produced by any single conversion shall be at least 4095.
17 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));
18 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.
19 Given the following wide string with length seven,
static wchar_t wstr[] = L"□X□Yabc□Z□W";
the seven calls
fprintf(stdout, "|1234567890123|\n");
fprintf(stdout, "|%13ls|\n", wstr);
fprintf(stdout, "|%-13.9ls|\n", wstr);
fprintf(stdout, "|%13.10ls|\n", wstr);
fprintf(stdout, "|%13.11ls|\n", wstr);
fprintf(stdout, "|%13.15ls|\n", &wstr[2]);
fprintf(stdout, "|%13lc|\n", (wint_t) wstr[5]);
will print the following seven lines:
|1234567890123|
| □X□Yabc□Z□W|
|□X□Yabc□Z |
| □X□Yabc□Z|
| □X□Yabc□Z□W|
| abc□Z□W|
| □Z|
20 EXAMPLE 3 Following are representations of _Decimal64 arguments as triples (s, c, q) and the corresponding character
sequences fprintf produces with "%Da":
(+1, 123, 0) 123
(−1, 123, 0) -123
(+1, 123, −2) 1.23
(+1, 123, 1) 1.23e+3
(−1, 123, 1) -1.23e+3
(+1, 123, −8) 0.00000123
(+1, 123, −9) 1.23e-7
(+1, 120, −8) 0.00000120
(+1, 120, −9) 1.20e-7
(+1,<PHONE_NUMBER>123456, 0)<PHONE_NUMBER>123456
(+1,<PHONE_NUMBER>123456, 1) 1.234567890123456e+16
(+1,<PHONE_NUMBER>123456, −1)<PHONE_NUMBER>12345.6
(+1,<PHONE_NUMBER>123456, −21) 0.000001234567890123456
(+1,<PHONE_NUMBER>123456, −22) 1.234567890123456e-7
(+1, 0, 0) 0
(−1, 0, 0) -0
(+1, 0, −6) 0.000000
(+1, 0, −7) 0e-7
(+1, 0, 2) 0e+2
(+1, 5, −6) 0.000005
(+1, 50, −7) 0.0000050
(+1, 5, −7) 5e-7
To illustrate the effects of a precision specification, the sequence:
_Decimal32 x = 6543.00DF; // (+1, 654300, -2)
fprintf(stdout, "%Ha\n", x);
fprintf(stdout, "%.6Ha\n", x);
fprintf(stdout, "%.5Ha\n", x);
fprintf(stdout, "%.4Ha\n", x);
fprintf(stdout, "%.3Ha\n", x);
fprintf(stdout, "%.2Ha\n", x);
fprintf(stdout, "%.1Ha\n", x);
fprintf(stdout, "%.0Ha\n", x);
assuming default rounding, results in:
6543.00
6543.00
6543.0
6543
6.54e+3
6.5e+3
7e+3
6543.00
To illustrate the effects of the exponent range, the sequence:
_Decimal32 x = 9543210e87DF; // (+1, 9543210, 87)
_Decimal32 y = 9500000e90DF; // (+1, 9500000, 90)
fprintf(stdout, "%.6Ha\n", x);
fprintf(stdout, "%.5Ha\n", x);
fprintf(stdout, "%.4Ha\n", x);
fprintf(stdout, "%.3Ha\n", x);
fprintf(stdout, "%.2Ha\n", x);
fprintf(stdout, "%.1Ha\n", x);
fprintf(stdout, "%.1Ha\n", y);
assuming default rounding, results in:
9.54321e+93
9.5432e+93
9.543e+93
9.54e+93
9.5e+93
1e+94
1e+97
To further illustrate the effects of the exponent range, the sequence:
_Decimal32 x = 9512345e90DF; // (+1, 9512345, 90)
_Decimal32 y = 9512345e86DF; // (+1, 9512345, 86)
fprintf(stdout, "%.3Ha\n", x);
fprintf(stdout, "%.2Ha\n", x);
fprintf(stdout, "%.1Ha\n", x);
fprintf(stdout, "%.2Ha\n", y);
assuming default rounding, results in:
9.51e+96
9.5e+96
1e+97
9.5e+92
Forward references: conversion state (7.31.6), the wcrtomb function (<IP_ADDRESS>.3).
<IP_ADDRESS> [The fscanf function]
1 Synopsis
#include <stdio.h>
int fscanf(FILE * restrict stream, const char * restrict format, ...);
Description
2 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.
3 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).
— 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.
4 The fscanf function executes each directive of the format in turn. When all directives have been
executed, or if a directive fails (as detailed below), the function returns. Failures are described as
input failures (due to the occurrence of an encoding error or the unavailability of input characters),
or matching failures (due to inappropriate input).
5 A directive composed of white-space 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. The directive
never fails.
6 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.
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 characters are skipped, unless the specification includes a [, c, or n specifier.[347]
Footnote 347) These white-space characters are not counted against a specified field width.
9 An input item is read from the stream, unless the specification includes an n specifier. An input
item is defined as the longest sequence of input characters which does not exceed any specified
field width and which is, or is a prefix of, a matching input sequence.[348] 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.
Footnote 348) 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.
10 Except in the case of a % specifier, the input item (or, in the case of a %n 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 in the object, the behavior is undefined.
11 The length modifiers and their meanings are:
hh Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to signed char or unsigned char.
h Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to short int or unsigned short int.
l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to long int or unsigned long int; that a following a, A, e, E, f, F,
g, or G conversion specifier applies to an argument with type pointer to double; or that
a following c, s, or [ conversion specifier applies to an argument with type pointer to
wchar_t .
ll (ell-ell) Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to long long int or unsigned long long int.
j Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to intmax_t or uintmax_t.
z Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to size_t or the corresponding signed integer type.
t Specifies that a following b, d, i, o, u, x, X, or n conversion specifier applies to an argument
with type pointer to ptrdiff_t or the corresponding unsigned integer type.
wN Specifies that a following b, d, i, o, u, x, or X, or n conversion specifier applies to an
argument which is a pointer to an integer with a specific width where N is a positive
decimal integer with no leading zeros. All minimum-width integer types (<IP_ADDRESS>) and
exact-width integer types (<IP_ADDRESS>) defined in the header <stdint.h> shall be supported.
Other supported values of N are implementation-defined.
wfN Specifies that a following b, d, i, o, u, x, or X, or n conversion specifier applies to an
argument which is a pointer to a fastest minimum-width integer with a specific width
where N is a positive decimal integer with no leading zeros. All fastest minimum-width
integer types (<IP_ADDRESS>) defined in the header <stdint.h> shall be supported. Other
supported values of N are implementation-defined.
L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to long double.
H Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to _Decimal32 .
D Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to _Decimal64 .
DD Specifies that a following a, A, e, E, f, F, g, or G conversion specifier applies to an argument
with type pointer to _Decimal128 .
If a length modifier appears with any conversion specifier other than as specified above, the behavior
is undefined.
12 In the following, the type of the corresponding argument for a conversion specifier shall be a pointer
to a type determined by the length modifiers, if any, or specified by the conversion specifier. The
conversion specifiers and their meanings are:
d Matches an optionally signed decimal integer, whose format is the same as expected for
the subject sequence of the strtol function with the value 10 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
int.
b Matches an optionally signed binary integer, whose format is the same as expected for the
subject sequence of the strtol function with the value 2 for the base argument. Unless a
length modifier is specified, the corresponding argument shall be a pointer to unsigned
int.
i Matches an optionally signed integer, whose format is the same as expected for the subject
sequence of the strtol function with the value 0 for the base argument. Unless a length
modifier is specified, the corresponding argument shall be a pointer to int.
o Matches an optionally signed octal integer, whose format is the same as expected for
the subject sequence of the strtoul function with the value 8 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
unsigned int.
u Matches an optionally signed decimal integer, whose format is the same as expected for
the subject sequence of the strtoul function with the value 10 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
unsigned int.
x Matches an optionally signed hexadecimal integer, whose format is the same as expected
for the subject sequence of the strtoul function with the value 16 for the base argument.
Unless a length modifier is specified, the corresponding argument shall be a pointer to
unsigned int.
a,e,f,g Matches an optionally signed floating-point number, infinity, or NaN, whose format is
the same as expected for the subject sequence of the strtod function. Unless a length
modifier is specified, the corresponding argument shall be a pointer to float.
c Matches a sequence of characters of exactly the number specified by the field width (1 if
no field width is present in the directive).[349]
If no l length modifier is present, the corresponding argument shall be a pointer to char,
signed char, unsigned char, or void that points to storage large enough to accept the
sequence. No null character is added.
If an l length modifier is present, the 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 storage of wchar_t large enough to
accept the resulting sequence of wide characters.No null wide character is added.
s Matches a sequence of non-white-space characters.[349]
If no l length modifier is present, the corresponding argument shall be a pointer to char,
signed char, unsigned char, or void that points to storage large enough to accept the
sequence and a terminating null character, which will be added automatically.
If an l length modifier is present, the 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 storage of wchar_t large enough to accept
the sequence and the terminating null wide character, which will be added automatically.
[ Matches a nonempty sequence of characters from a set of expected characters (the
scanset).[349]
If no l length modifier is present, the corresponding argument shall be a pointer to char,
signed char, unsigned char, or void that points to storage large enough to accept the
sequence and a terminating null character, which will be added automatically.
If an l length modifier is present, the 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 that points to storage of wchar_t large
[349] No special provisions are made for multibyte characters in the matching rules used by the c, s, 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.
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 [] or [^], 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.
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 fprintf function.
The corresponding argument shall be a pointer to a pointer of void. The input item is
converted to a pointer value in an implementation-defined manner. If the input item is a
value converted earlier during the same program execution, the pointer that results shall
compare equal to that value; otherwise the behavior of the %p conversion is undefined.
n No input is consumed. The corresponding argument shall be a pointer of a signed integer
type. The number of characters read from the input stream so far by this call to the fscanf
function is stored into the integer object pointed to by the argument. Execution of a %n
directive does not increment the assignment count returned at the completion of execution
of the fscanf function. No argument is converted, but one is consumed. If the conversion
specification includes an assignment-suppressing character or a field width, the behavior
is undefined.
% Matches a single % character; no conversion or assignment occurs. The complete conversion
specification shall be %%.
Footnote 349) No special provisions are made for multibyte characters in the matching rules used by the c, s, 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.
Footnote 349) No special provisions are made for multibyte characters in the matching rules used by the c, s, 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.
Footnote 349) No special provisions are made for multibyte characters in the matching rules used by the c, s, 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.
Footnote 349) No special provisions are made for multibyte characters in the matching rules used by the c, s, 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.
13 If a conversion specification is invalid, the behavior is undefined.[350]
Footnote 350) See "future library directions" (7.33.15).
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 characters(including new-line characters) are left unread unless matched by a
directive. The success of literal matches and suppressed assignments is not directly determinable
other than via the %n directive.
Returns
16 The fscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the function returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure or if the implementation does not support a specific width length modifier.
17 EXAMPLE 1 The call:
#include <stdio.h>
/* ... */
int n, i; float x; char name[50];
n = fscanf(stdin, "%d%f%s", &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>
/* ... */
int i; float x; char name[50];
fscanf(stdin, "%2d%f%*d %[0123456789]", &i, &x, name);
with input:
56789 0123 56a72
will assign to i the value 56 and to x the value 789.0, will skip 0123, and will assign to name the sequence 56\0. The next
character read from the input stream will be a.
19 EXAMPLE 3 To accept repeatedly from stdin a quantity, a unit of measure, and an item name:
#include <stdio.h>
/* ... */
int count; float quant; char units[21], item[21];
do {
count = fscanf(stdin, "%f%20s of %20s", &quant, units, item);
fscanf(stdin,"%*[^\n]");
} while (!feof(stdin) && !ferror(stdin));
20 If the stdin stream contains the following lines:
2 quarts of oil
-12.8degrees Celsius
lots of luck
10.0LBS of
dirt
100ergs of energy
the execution of the above example will be analogous to the following assignments:
quant = 2; strcpy(units, "quarts"); strcpy(item, "oil");
count = 3;
quant = -12.8; strcpy(units, "degrees");
count = 2; // "C" fails to match "o"
count = 0; // "l" fails to match "%f"
quant = 10.0; strcpy(units, "LBS"); strcpy(item, "dirt");
count = 3;
count = 0; // "100e" fails to match "%f"
count = EOF;
21 EXAMPLE 4 In:
#include <stdio.h>
/* ... */
int d1, d2, n1, n2, i;
i = sscanf("123", "%d%n%n%d", &d1, &n1, &n2, &d2);
the value 123 is assigned to d1 and the value 3 to n1. Because %n can never get an input failure, the value of 3 is also assigned
to n2. The value of d2 is not affected. The value 1 is assigned to i.
22 EXAMPLE 5 The call:
#include <stdio.h>
/* ... */
int n, i;
n = sscanf("foo %bar 42", "foo%%bar%d", &i);
will assign to n the value 1 and to i the value 42 because input white-space characters are skipped for both the % and d
conversion specifiers.
23 EXAMPLE 6 In these examples, multibyte characters do 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, but are only recognized as such when in the alternate shift state. The shift sequences
are denoted by ↑ and ↓, in which the first causes entry into the alternate shift state.
24 After the call:
#include <stdio.h>
/* ... */
char str[50];
fscanf(stdin, "a%s", str);
with the input line:
a↑□X□Y↓ bc
str will contain ↑□X□Y↓\\0 assuming that none of the bytes of the shift sequences (or of the multibyte characters, in the
more general case) appears to be a single-byte white-space character.
25 In contrast, after the call:
#include <stdio.h>
#include <stddef.h>
/* ... */
wchar_t wstr[50];
fscanf(stdin, "a%ls", wstr);
with the same input line, wstr will contain the two wide characters that correspond to □X and □Y and a terminating null
wide character.
26 However, the call:
#include <stdio.h>
#include <stddef.h>
/* ... */
wchar_t wstr[50];
fscanf(stdin, "a↑□X↓%ls", wstr);
with the same input line will return zero due to a matching failure against the ↓ sequence in the format string.
27 Assuming that the first byte of the multibyte character □X is the same as the first byte of the multibyte character □Y, after the
call:
#include <stdio.h>
#include <stddef.h>
/* ... */
wchar_t wstr[50];
fscanf(stdin, "a↑□Y↓%ls", wstr);
with the same input line, zero will again be returned, but stdin will be left with a partially consumed multibyte character.
Forward references: the strtod, strtof, and strtold functions (<IP_ADDRESS>), the strtol, strtoll,
strtoul, and strtoull functions (<IP_ADDRESS>), conversion state (7.31.6), the wcrtomb function
(<IP_ADDRESS>.3).
<IP_ADDRESS> [The printf function]
1 Synopsis
#include <stdio.h>
int printf(const char * restrict format, ...);
Description
2 The printf function is equivalent to fprintf with the argument stdout interposed before the
arguments to printf.
Returns
3 The printf function returns the number of characters transmitted, or a negative value if an output
or encoding error occurred.
<IP_ADDRESS> [The scanf function]
1 Synopsis
#include <stdio.h>
int scanf(const char * restrict format, ...);
Description
2 The scanf function is equivalent to fscanf with the argument stdin interposed before the argu-
ments to scanf.
Returns
3 The scanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the scanf function returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The snprintf function]
1 Synopsis
#include <stdio.h>
int snprintf(char * restrict s, size_t n, const char * restrict format, ...);
Description
2 The snprintf function is equivalent to fprintf, except that the output is written into an array
(specified by argument s) rather than to a stream. If n is zero, nothing is written, and s may be a
null pointer. Otherwise, output characters beyond the n-1st are discarded rather than being written
to the array, and a null character is written at the end of the characters actually written into the array.
If copying takes place between objects that overlap, the behavior is undefined.
Returns
3 The snprintf function returns the number of characters that would have been written had n been
sufficiently large, not counting the terminating null character, or a negative value if an encoding
error occurred. Thus, the null-terminated output has been completely written if and only if the
returned value is both nonnegative and less than n.
<IP_ADDRESS> [The sprintf function]
1 Synopsis
#include <stdio.h>
int sprintf(char * restrict s, const char * restrict format, ...);
Description
2 The sprintf function is equivalent to fprintf, except that the output is written into an array
(specified by the argument s) rather than to a stream. A null character is written at the end of the
characters written; it is not counted as part of the returned value. If copying takes place between
objects that overlap, the behavior is undefined.
Returns
3 The sprintf function returns the number of characters written in the array, not counting the
terminating null character, or a negative value if an encoding error occurred.
<IP_ADDRESS> [The sscanf function]
1 Synopsis
#include <stdio.h>
int sscanf(const char * restrict s, const char * restrict format, ...);
Description
2 The sscanf function is equivalent to fscanf, except that input is obtained from a string (specified
by the argument s) rather than from a stream. Reaching the end of the string is equivalent to
encountering end-of-file for the fscanf function. If copying takes place between objects that overlap,
the behavior is undefined.
Returns
3 The sscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the sscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The vfprintf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
int vfprintf(FILE * restrict stream, const char * restrict format, va_list arg);
Description
2 The vfprintf function is equivalent to fprintf, 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 vfprintf function does not invoke the va_end macro[351] .
Returns
Footnote 351) As the functions vfprintf , vfscanf , vprintf , vscanf , vsnprintf , vsprintf , and vsscanf invoke the va_arg macro,
arg after the return has an indeterminate representation.
3 The vfprintf function returns the number of characters transmitted, or a negative value if an
output or encoding error occurred.
4 EXAMPLE The following shows the use of the vfprintf function in a general error-reporting routine.
#include <stdarg.h>
#include <stdio.h>
void error(char *function_name, char *format, ...)
{
va_list args;
va_start(args, format);
// print out name of function causing error
fprintf(stderr, "ERROR in %s: ", function_name);
// print out remainder of message
vfprintf(stderr, format, args);
va_end(args);
}
<IP_ADDRESS> [The vfscanf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
int vfscanf(FILE * restrict stream, const char * restrict format, va_list arg);
Description
2 The vfscanf function is equivalent to fscanf, 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 vfscanf function does not invoke the va_end macro.[351]
Returns
Footnote 351) As the functions vfprintf , vfscanf , vprintf , vscanf , vsnprintf , vsprintf , and vsscanf invoke the va_arg macro,
arg after the return has an indeterminate representation.
3 The vfscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the vfscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The vprintf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
int vprintf(const char * restrict format, va_list arg);
Description
2 The vprintf function is equivalent to printf, 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 vprintf function does not invoke the va_end macro.[351]
Returns
Footnote 351) As the functions vfprintf , vfscanf , vprintf , vscanf , vsnprintf , vsprintf , and vsscanf invoke the va_arg macro,
arg after the return has an indeterminate representation.
3 The vprintf function returns the number of characters transmitted, or a negative value if an output
or encoding error occurred.
<IP_ADDRESS> [The vscanf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
int vscanf(const char * restrict format, va_list arg);
Description
2 The vscanf function is equivalent to scanf, 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
vscanf function does not invoke the va_end macro.[351]
Returns
Footnote 351) As the functions vfprintf , vfscanf , vprintf , vscanf , vsnprintf , vsprintf , and vsscanf invoke the va_arg macro,
arg after the return has an indeterminate representation.
3 The vscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the vscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
<IP_ADDRESS> [The vsnprintf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
int vsnprintf(char * restrict s, size_t n, const char * restrict format, va_list
arg);
Description
2 The vsnprintf function is equivalent to snprintf, 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 vsnprintf function does not invoke the va_end macro.[351] If copying takes place between
objects that overlap, the behavior is undefined.
Returns
Footnote 351) As the functions vfprintf , vfscanf , vprintf , vscanf , vsnprintf , vsprintf , and vsscanf invoke the va_arg macro,
arg after the return has an indeterminate representation.
3 The vsnprintf function returns the number of characters that would have been written had n been
sufficiently large, not counting the terminating null character, or a negative value if an encoding
error occurred. Thus, the null-terminated output has been completely written if and only if the
returned value is both nonnegative and less than n.
<IP_ADDRESS> [The vsprintf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
int vsprintf(char * restrict s, const char * restrict format, va_list arg);
Description
2 The vsprintf function is equivalent to sprintf, 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 vsprintf function does not invoke the va_end macro.[351] If copying takes place between objects
that overlap, the behavior is undefined.
Returns
Footnote 351) As the functions vfprintf , vfscanf , vprintf , vscanf , vsnprintf , vsprintf , and vsscanf invoke the va_arg macro,
arg after the return has an indeterminate representation.
3 The vsprintf function returns the number of characters written in the array, not counting the
terminating null character, or a negative value if an encoding error occurred.
<IP_ADDRESS> [The vsscanf function]
1 Synopsis
#include <stdarg.h>
#include <stdio.h>
int vsscanf(const char * restrict s, const char * restrict format, va_list arg);
Description
2 The vsscanf function is equivalent to sscanf, 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 vsscanf function does not invoke the va_end macro.[351]
Returns
Footnote 351) As the functions vfprintf , vfscanf , vprintf , vscanf , vsnprintf , vsprintf , and vsscanf invoke the va_arg macro,
arg after the return has an indeterminate representation.
3 The vsscanf function returns the value of the macro EOF if an input failure occurs before the first
conversion (if any) has completed. Otherwise, the vsscanf function returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the event of an early matching
failure.
7.23.7 [Character input/output functions]
<IP_ADDRESS> [The fgetc function]
1 Synopsis
#include <stdio.h>
int fgetc(FILE *stream);
Description
2 If the end-of-file indicator for the input stream pointed to by stream is not set and a next character
is present, the fgetc function obtains that character as an unsigned char converted to an int and
advances the associated file position indicator for the stream (if defined).
Returns
3 If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-of-file
indicator for the stream is set and the fgetc function returns EOF. Otherwise, the fgetc function
returns the next character from the input stream pointed to by stream. If a read error occurs, the
error indicator for the stream is set and the fgetc function returns EOF.[352]
Footnote 352) An end-of-file and a read error can be distinguished by use of the feof and ferror functions.
<IP_ADDRESS> [The fgets function]
1 Synopsis
#include <stdio.h>
char *fgets(char * restrict s, int n, FILE * restrict stream);
Description
2 The fgets function reads at most one less than the number of characters specified by n from the
stream pointed to by stream into the array pointed to by s. No additional characters are read after a
new-line character (which is retained) or after end-of-file. A null character is written immediately
after the last character read into the array.
Returns
3 The fgets function returns s if successful. If end-of-file is encountered and no characters have been
read into the array, the contents of the array remain unchanged and a null pointer is returned. If a
read error occurs during the operation, the members of the array have unspecified values and a null
pointer is returned.
<IP_ADDRESS> [The fputc function]
1 Synopsis
#include <stdio.h>
int fputc(int c, FILE *stream);
Description
2 The fputc function writes the character specified by c (converted to an unsigned char) to the
output stream pointed to by stream, at the position indicated by the associated file position indicator
for the stream (if defined), and advances the indicator appropriately. If the file cannot support
positioning requests, or if the stream was opened with append mode, the character is appended to
the output stream.
Returns
3 The fputc function returns the character written. If a write error occurs, the error indicator for the
stream is set and fputc returns EOF.
<IP_ADDRESS> [The fputs function]
1 Synopsis
#include <stdio.h>
int fputs(const char * restrict s, FILE * restrict stream);
Description
2 The fputs function writes the string pointed to by s to the stream pointed to by stream. The
terminating null character is not written.
Returns
3 The fputs function returns EOF if a write error occurs; otherwise it returns a nonnegative value.
<IP_ADDRESS> [The getc function]
1 Synopsis
#include <stdio.h>
int getc(FILE *stream);
Description
2 The getc function is equivalent to fgetc, except that if it is implemented as a macro, it may evaluate
stream more than once, so the argument should never be an expression with side effects.
Returns
3 The getc function returns the next character from the input stream pointed to by stream. If the
stream is at end-of-file, the end-of-file indicator for the stream is set and getc returns EOF. If a read
error occurs, the error indicator for the stream is set and getc returns EOF.
<IP_ADDRESS> [The getchar function]
1 Synopsis
#include <stdio.h>
int getchar(void);
Description
2 The getchar function is equivalent to getc with the argument stdin.
Returns
3 The getchar function returns the next character from the input stream pointed to by stdin. If the
stream is at end-of-file, the end-of-file indicator for the stream is set and getchar returns EOF. If a
read error occurs, the error indicator for the stream is set and getchar returns EOF.
<IP_ADDRESS> [The putc function]
1 Synopsis
#include <stdio.h>
int putc(int c, FILE *stream);
Description
2 The putc function is equivalent to fputc, except that if it is implemented as a macro, it may evaluate
stream more than once, so that argument should never be an expression with side effects.
Returns
3 The putc function returns the character written. If a write error occurs, the error indicator for the
stream is set and putc returns EOF.
<IP_ADDRESS> [The putchar function]
1 Synopsis
#include <stdio.h>
int putchar(int c);
Description
2 The putchar function is equivalent to putc with the second argument stdout.
Returns
3 The putchar function returns the character written. If a write error occurs, the error indicator for
the stream is set and putchar returns EOF.
<IP_ADDRESS> [The puts function]
1 Synopsis
#include <stdio.h>
int puts(const char *s);
Description
2 The puts function writes the string pointed to by s to the stream pointed to by stdout, and appends
a new-line character to the output. The terminating null character is not written.
Returns
3 The puts function returns EOF if a write error occurs; otherwise it returns a nonnegative value.
<IP_ADDRESS> [The ungetc function]
1 Synopsis
#include <stdio.h>
int ungetc(int c, FILE *stream);
Description
2 The ungetc function pushes the character specified by c (converted to an unsigned char) back
onto the input stream pointed to by stream. Pushed-back characters will be returned by subsequent
reads on that stream in the reverse order of their pushing. A successful intervening call (with the
stream pointed to by stream) to a file positioning function (fseek, fsetpos, or rewind) discards
any pushed-back characters for the stream. The external storage corresponding to the stream is
unchanged.
3 One character of pushback is guaranteed. If the ungetc function is called too many times on the
same stream without an intervening read or file positioning operation on that stream, the operation
may fail.
4 If the value of c equals that of the macro EOF, the operation fails and the input stream is unchanged.
5 A successful call to the ungetc function clears the end-of-file indicator for the stream. The value
of the file position indicator for the stream after reading or discarding all pushed-back characters
shall be the same as it was before the characters were pushed back.[353] For a text stream, the value
of its file position indicator after a successful call to the ungetc function is unspecified until all
pushed-back characters are read or discarded. For a binary stream, its file position indicator is
decremented by each successful call to the ungetc function; if its value was zero before a call, it has
an indeterminate representation after the call[354] .
Returns
Footnote 353) Note that a file positioning function could further modify the file position indicator after discarding any pushed-back
characters.
Footnote 354) See "future library directions" (7.33.15).
6 The ungetc function returns the character pushed back after conversion, or EOF if the operation
fails.
Forward references: file positioning functions (7.23.9).
7.23.8 [Direct input/output functions]
<IP_ADDRESS> [The fread function]
1 Synopsis
#include <stdio.h>
size_t fread(void * restrict ptr, size_t size, size_t nmemb,
FILE * restrict stream);
Description
2 The fread function reads, into the array pointed to by ptr, up to nmemb elements whose size is
specified by size, from the stream pointed to by stream. For each object, size calls are made to
the fgetc function and the results stored, in the order read, in an array of unsigned char exactly
overlaying the object. The file position indicator for the stream (if defined) is advanced by the
number of characters successfully read. If an error occurs, the resulting representation of the file
position indicator for the stream is indeterminate. If a partial element is read, its representation is
indeterminate.
Returns
3 The fread function returns the number of elements successfully read, which may be less than nmemb
if a read error or end-of-file is encountered. If size or nmemb is zero, fread returns zero and the
contents of the array and the state of the stream remain unchanged.
<IP_ADDRESS> [The fwrite function]
1 Synopsis
#include <stdio.h>
size_t fwrite(const void * restrict ptr, size_t size, size_t nmemb,
FILE * restrict stream);
Description
2 The fwrite function writes, from the array pointed to by ptr, up to nmemb elements whose size is
specified by size, to the stream pointed to by stream. For each object, size calls are made to the
fputc function, taking the values (in order) from an array of unsigned char exactly overlaying the
object. The file position indicator for the stream (if defined) is advanced by the number of characters
successfully written. If an error occurs, the resulting representation of the file position indicator for
the stream is indeterminate.
Returns
3 The fwrite function returns the number of elements successfully written, which will be less than
nmemb only if a write error is encountered. If size or nmemb is zero, fwrite returns zero and the
state of the stream remains unchanged.
7.23.9 [File positioning functions]
<IP_ADDRESS> [The fgetpos function]
1 Synopsis
#include <stdio.h>
int fgetpos(FILE * restrict stream, fpos_t * restrict pos);
Description
2 The fgetpos function stores the current values of the parse state (if any) and file position indicator
for the stream pointed to by stream in the object pointed to by pos. The values stored contain
unspecified information usable by the fsetpos function for repositioning the stream to its position
at the time of the call to the fgetpos function.
Returns
3 If successful, the fgetpos function returns zero; on failure, the fgetpos function returns nonzero
and stores an implementation-defined positive value in errno.
Forward references: the fsetpos function (<IP_ADDRESS>).
<IP_ADDRESS> [The fseek function]
1 Synopsis
#include <stdio.h>
int fseek(FILE *stream, long int offset, int whence);
Description
2 The fseek function sets the file position indicator for the stream pointed to by stream. If a read or
write error occurs, the error indicator for the stream is set and fseek fails.
3 For a binary stream, the new position, measured in characters from the beginning of the file, is
obtained by adding offset to the position specified by whence. The specified position is the
beginning of the file if whence is SEEK_SET, the current value of the file position indicator if
SEEK_CUR, or end-of-file if SEEK_END. A binary stream need not meaningfully support fseek calls
with a whence value of SEEK_END.
4 For a text stream, either offset shall be zero, or offset shall be a value returned by an earlier
successful call to the ftell function on a stream associated with the same file and whence shall be
SEEK_SET.
5 After determining the new position, a successful call to the fseek function undoes any effects of the
ungetc function on the stream, clears the end-of-file indicator for the stream, and then establishes
the new position. After a successful fseek call, the next operation on an update stream may be
either input or output.
Returns
6 The fseek function returns nonzero only for a request that cannot be satisfied.
Forward references: the ftell function (<IP_ADDRESS>).
<IP_ADDRESS> [The fsetpos function]
1 Synopsis
#include <stdio.h>
int fsetpos(FILE *stream, const fpos_t *pos);
Description
2 The fsetpos function sets the mbstate_t object (if any) and file position indicator for the stream
pointed to by stream according to the value of the object pointed to by pos, which shall be a value
obtained from an earlier successful call to the fgetpos function on a stream associated with the
same file. If a read or write error occurs, the error indicator for the stream is set and fsetpos fails.
3 A successful call to the fsetpos function undoes any effects of the ungetc function on the stream,
clears the end-of-file indicator for the stream, and then establishes the new parse state and position.
After a successful fsetpos call, the next operation on an update stream may be either input or
output.
Returns
4 If successful, the fsetpos function returns zero; on failure, the fsetpos function returns nonzero
and stores an implementation-defined positive value in errno.
<IP_ADDRESS> [The ftell function]
1 Synopsis
#include <stdio.h>
long int ftell(FILE *stream);
Description
2 The ftell function obtains the current value of the file position indicator for the stream pointed to
by stream. For a binary stream, the value is the number of characters from the beginning of the file.
For a text stream, its file position indicator contains unspecified information, usable by the fseek
function for returning the file position indicator for the stream to its position at the time of the ftell
call; the difference between two such return values is not necessarily a meaningful measure of the
number of characters written or read.
Returns
3 If successful, the ftell function returns the current value of the file position indicator for the stream.
On failure, the ftell function returns −1L and stores an implementation-defined positive value in
errno.
<IP_ADDRESS> [The rewind function]
1 Synopsis
#include <stdio.h>
void rewind(FILE *stream);
Description
2 The rewind function sets the file position indicator for the stream pointed to by stream to the
beginning of the file. It is equivalent to
(void)fseek(stream, 0L, SEEK_SET)
except that the error indicator for the stream is also cleared.
Returns
3 The rewind function returns no value.
7.23.10 [Error-handling functions]
<IP_ADDRESS> [The clearerr function]
1 Synopsis
#include <stdio.h>
void clearerr(FILE *stream);
Description
2 The clearerr function clears the end-of-file and error indicators for the stream pointed to by
stream.
Returns
3 The clearerr function returns no value.
<IP_ADDRESS> [The feof function]
1 Synopsis
#include <stdio.h>
int feof(FILE *stream);
Description
2 The feof function tests the end-of-file indicator for the stream pointed to by stream.
Returns
3 The feof function returns nonzero if and only if the end-of-file indicator is set for stream.
<IP_ADDRESS> [The ferror function]
1 Synopsis
#include <stdio.h>
int ferror(FILE *stream);
Description
2 The ferror function tests the error indicator for the stream pointed to by stream.
Returns
3 The ferror function returns nonzero if and only if the error indicator is set for stream.
<IP_ADDRESS> [The perror function]
1 Synopsis
#include <stdio.h>
void perror(const char *s);
Description
2 The perror function maps the error number in the integer expression errno to an error message.
It writes a sequence of characters to the standard error stream thus: first (if s is not a null pointer
and the character pointed to by s is not the null character), the string pointed to by s followed by a
colon (:) and a space; then an appropriate error message string followed by a new-line character.
The contents of the error message strings are the same as those returned by the strerror function
with argument errno.
Returns
3 The perror function returns no value.
Forward references: the strerror function (<IP_ADDRESS>).
7.24 [General utilities <stdlib.h>]
1 The header <stdlib.h> declares five types and several functions of general utility, and defines
several macros.[355]
Footnote 355) See "future library directions" (7.33.16).
2 The feature test macro __STDC_VERSION_STDLIB_H__ expands to the token 202311L.
3 The types declared are size_t and wchar_t (both described in 7.21), once_flag (described in 7.28),
div_t
which is a structure type that is the type of the value returned by the div function,
ldiv_t
which is a structure type that is the type of the value returned by the ldiv function, and
lldiv_t
which is a structure type that is the type of the value returned by the lldiv function.
4 The macros defined are NULL (described in 7.21); ONCE_FLAG_INIT (described in 7.28);
EXIT_FAILURE
and
EXIT_SUCCESS
which expand to integer constant expressions that can be used as the argument to the exit function
to return unsuccessful or successful termination status, respectively, to the host environment;
RAND_MAX
which expands to an integer constant expression that is the maximum value returned by the rand
function; and
MB_CUR_MAX
which expands to a positive integer expression with type size_t that is the maximum number of
bytes in a multibyte character for the extended character set specified by the current locale (category
LC_CTYPE), which is never greater than MB_LEN_MAX.
5 The function
#include <stdlib.h>
void call_once(once_flag *flag, void (*func)(void));
is described in 7.28.2.
7.24.1 [Numeric conversion functions]
1 The functions atof, atoi, atol, and atoll need not affect the value of the integer expression errno
on an error. If the value of the result cannot be represented, the behavior is undefined.
<IP_ADDRESS> [The atof function]
1 Synopsis
#include <stdlib.h>
double atof(const char *nptr);
Description
2 The atof function converts the initial portion of the string pointed to by nptr to double representa-
tion. Except for the behavior on error, it is equivalent to
strtod(nptr, nullptr)
Returns
3 The atof function returns the converted value.
Forward references: the strtod, strtof, and strtold functions (<IP_ADDRESS>).
<IP_ADDRESS> [The atoi, atol, and atoll functions]
1 Synopsis
#include <stdlib.h>
int atoi(const char *nptr);
long int atol(const char *nptr);
long long int atoll(const char *nptr);
Description
2 The atoi, atol, and atoll functions convert the initial portion of the string pointed to by nptr to
int, long int, and long long int representation, respectively. Except for the behavior on error,
they are equivalent to
atoi: (int)strtol(nptr, nullptr, 10)
atol: strtol(nptr, nullptr, 10)
atoll: strtoll(nptr, nullptr, 10)
Returns
3 The atoi, atol, and atoll functions return the converted value.
Forward references: the strtol, strtoll, strtoul, and strtoull functions (<IP_ADDRESS>).
<IP_ADDRESS> [The strfromd, strfromf, and strfroml functions]
1 Synopsis
#include <stdlib.h>
int strfromd(char *restrict s, size_t n, const char *restrict format, double fp);
int strfromf(char *restrict s, size_t n, const char *restrict format, float fp);
int strfroml(char *restrict s, size_t n, const char *restrict format, long double fp);
Description
2 The strfromd, strfromf, and strfroml functions are equivalent to snprintf(s, n, format, fp)
(<IP_ADDRESS>), except that the format string shall only contain the character %, an optional precision that
does not contain an asterisk *, and one of the conversion specifiers a, A, e, E, f, F, g, or G, which
applies to the type (double, float, or long double) indicated by the function suffix (rather than by
a length modifier).
Returns
3 The strfromd, strfromf, and strfroml functions return the number of characters that would
have been written had n been sufficiently large, not counting the terminating null character. Thus,
the null-terminated output has been completely written if and only if the returned value is both
nonnegative and less than n.
<IP_ADDRESS> [The strfromdN functions]
1 Synopsis
#include <stdlib.h>
#ifdef __STDC_IEC_60559_DFP__
int strfromd32(char*restrict s, size_t n, const char*restrict format, _Decimal32 fp);
int strfromd64(char*restrict s, size_t n, const char*restrict format, _Decimal64 fp);
int strfromd128(char*restrict s, size_t n, const char*restrict format, _Decimal128 fp);
#endif
Description
2 The strfromdN functions are equivalent to snprintf(s, n, format, fp) (<IP_ADDRESS>), except the
format string contains only the character %, an optional precision that does not contain an asterisk *,
and one of the conversion specifiers a, A, e, E, f, F, g, or G, which applies to the type (_Decimal32 ,
_Decimal64 , or _Decimal128 ) indicated by the function suffix (rather than by a length modifier).
Use of these functions with any other format string results in undefined behavior.
Returns
3 The strfromdN functions return the number of characters that would have been written had n been
sufficiently large, not counting the terminating null character. Thus, the null-terminated output has
been completely written if and only if the returned value is less than n.
<IP_ADDRESS> [The strtod, strtof, and strtold functions]
1 Synopsis
#include <stdlib.h>
double strtod(const char *restrict nptr, char **restrict endptr);
float strtof(const char *restrict nptr, char **restrict endptr);
long double strtold(const char *restrict nptr, char **restrict endptr);
Description
2 The strtod, strtof, and strtold functions convert the initial portion of the string pointed to by
nptr to double, float, and long double representation, respectively. First, they decompose the
input string into three parts: an initial, possibly empty, sequence of white-space characters, a subject
sequence resembling a floating constant or representing an infinity or NaN; and a final string of one
or more unrecognized characters, including the terminating null character of the input string. Then,
they attempt to convert the subject sequence to a floating-point number, and return the result.
3 The expected form of the subject sequence is an optional plus or minus sign, then one of the
following:
— a nonempty sequence of decimal digits optionally containing a decimal-point character, then
an optional exponent part as defined in <IP_ADDRESS>, excluding any digit separators (<IP_ADDRESS>);
— a 0x or 0X, then a nonempty sequence of hexadecimal digits optionally containing a decimal-
point character, then an optional binary exponent part as defined in <IP_ADDRESS>, excluding any digit
separators;
— INF or INFINITY, ignoring case
— NAN or NAN(n-char-sequenceopt ), ignoring case in the NAN part, where: n-char-sequence:
digit
nondigit
n-char-sequence digit
n-char-sequence nondigit
The subject sequence is defined as the longest initial subsequence of the input string, starting with
the first non-white-space character, that is of the expected form. The subject sequence contains no
characters if the input string is not of the expected form.
4 If the subject sequence has the expected form for a floating-point number, the sequence of characters