— The name of a predefined macro, or the identifier defined, is the subject of a #define or
#undef preprocessing directive (6.10.9).
— An attempt is made to copy an object to an overlapping object by use of a library function,
other than as explicitly allowed (e.g., memmove) (Clause 7).
— A file with the same name as one of the standard headers, not provided as part of the implemen-
tation, is placed in any of the standard places that are searched for included source files (7.1.2).
— A header is included within an external declaration or definition (7.1.2).
— A function, object, type, or macro that is specified as being declared or defined by some
standard header is used before any header that declares or defines it is included (7.1.2).
— A standard header is included while a macro is defined with the same name as a keyword
(7.1.2).
— The program attempts to declare a library function itself, rather than via a standard header,
but the declaration does not have external linkage (7.1.2).
— The program declares or defines a reserved identifier, other than as allowed by 7.1.4 (7.1.3).
— The program removes the definition of a macro whose name begins with an underscore and
either an uppercase letter or another underscore (7.1.3).
— An argument to a library function has an invalid value or a type not expected by a function
with a variable number of arguments (7.1.4).
— The pointer passed to a library function array parameter does not have a value such that all
address computations and object accesses are valid (7.1.4).
— The macro definition of assert is suppressed in order to access an actual function (7.2).
— The argument to the assert macro does not have a scalar type (7.2).
— The CX_LIMITED_RANGE, FENV_ACCESS, or FP_CONTRACT pragma is used in any context other
than outside all external declarations or preceding all explicit declarations and statements
inside a compound statement (7.3.4, 7.6.1, 7.12.2).
— The value of an argument to a character handling function is neither equal to the value of EOF
nor representable as an unsigned char (7.4).
— A macro definition of errno is suppressed in order to access an actual object, or the program
defines an identifier with the name errno (7.5).
— Part of the program tests floating-point status flags, sets floating-point control modes, or
runs under non-default mode settings, but was translated with the state for the FENV_ACCESS
pragma "off" (7.6.1).
— The exception-mask argument for one of the functions that provide access to the floating-point
status flags has a nonzero value not obtained by bitwise OR of the floating-point exception
macros (7.6.4).
— The fesetexceptflag function is used to set floating-point status flags that were not specified
in the call to the fegetexceptflag function that provided the value of the corresponding
fexcept_t object (<IP_ADDRESS>).
— The argument to fesetenv or feupdateenv is neither an object set by a call to fegetenv or
feholdexcept, nor is it an environment macro (<IP_ADDRESS>, <IP_ADDRESS>).
— The value of the result of an integer arithmetic or conversion function cannot be represented
(<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, 7.24.1).
— The program modifies the string pointed to by the value returned by the setlocale function
(<IP_ADDRESS>).
— A pointer returned by the setlocale function is used after a subsequent call to the function,
or after the calling thread has exited (<IP_ADDRESS>).
— The program modifies the structure pointed to by the value returned by the localeconv
function (<IP_ADDRESS>).
— A macro definition of math_errhandling is suppressed or the program defines an identifier
with the name math_errhandling (7.12).
— An argument to a floating-point classification or comparison macro is not of real floating type
(7.12.3, 7.12.17).
— A macro definition of setjmp is suppressed in order to access an actual function, or the
program defines an external identifier with the name setjmp (7.13).
— An invocation of the setjmp macro occurs other than in an allowed context (<IP_ADDRESS>).
— The longjmp function is invoked to restore a nonexistent environment (<IP_ADDRESS>).
— After a longjmp, there is an attempt to access the value of an object of automatic storage dura-
tion that does not have volatile-qualified type, local to the function containing the invocation
of the corresponding setjmp macro, that was changed between the setjmp invocation and
longjmp call (<IP_ADDRESS>).
— The program specifies an invalid pointer to a signal handler function (<IP_ADDRESS>).
— A signal handler returns when the signal corresponded to a computational exception (<IP_ADDRESS>).
— A signal handler called in response to SIGFPE, SIGILL, SIGSEGV, or any other implementation-
defined value corresponding to a computational exception returns (<IP_ADDRESS>).
— A signal occurs as the result of calling the abort or raise function, and the signal handler
calls the raise function (<IP_ADDRESS>).
— A signal occurs other than as the result of calling the abort or raise function, and the signal
handler refers to an object with static or thread storage duration that is not a lock-free atomic
object other than by assigning a value to an object declared as volatile sig_atomic_t, or
calls any function in the standard library other than the abort function, the _Exit function,
the quick_exit function, the functions in <stdatomic.h> (except where explicitly stated
otherwise) when the atomic arguments are lock-free, the atomic_is_lock_free function with
any atomic argument, or the signal function (for the same signal number) (<IP_ADDRESS>).
— The value of errno is referred to after a signal occurred other than as the result of calling the
abort or raise function and the corresponding signal handler obtained a SIG_ERR return
from a call to the signal function (<IP_ADDRESS>).
— A signal is generated by an asynchronous signal handler (<IP_ADDRESS>).
— The signal function is used in a multi-threaded program (<IP_ADDRESS>).
— A function with a variable number of arguments attempts to access its varying arguments
other than through a properly declared and initialized va_list object, or before the va_start
macro is invoked (7.16, <IP_ADDRESS>, <IP_ADDRESS>).
— The macro va_arg is invoked using the parameter ap that was passed to a function that
invoked the macro va_arg with the same parameter (7.16).
— A macro definition of va_start, va_arg, va_copy, or va_end is suppressed in order to access
an actual function, or the program defines an external identifier with the name va_copy or
va_end (7.16.1).
— The va_start or va_copy macro is invoked without a corresponding invocation of the va_end
macro in the same function, or vice versa (7.16.1, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>).
— The type parameter to the va_arg macro is not such that a pointer to an object of that type can
be obtained simply by postfixing a * (<IP_ADDRESS>).
— The va_arg macro is invoked when there is no actual next argument, or with a specified
type that is not compatible with the promoted type of the actual next argument, with certain
exceptions (<IP_ADDRESS>).
— Using a null pointer constant in form of an integer expression as an argument to a ... function
and then interpreting it as a void* or char* (<IP_ADDRESS>).
— The va_copy or va_start macro is called to initialize a va_list that was previously initialized
by either macro without an intervening invocation of the va_end macro for the same va_list
(<IP_ADDRESS>, <IP_ADDRESS>).
— The macro definition of a generic function is suppressed in order to access an actual function
(7.17.1, 7.18).
— The type parameter of an offsetof macro defines a new type (7.21).
— When program execution reaches an unreachable() macro call (7.21.1).
— Arbitrarily copying or changing the bytes of or copying from a non-null pointer into a
nullptr_t object and then reading that object (7.21.2).
— The member-designator parameter of an offsetof macro is an invalid right operand of the .
operator for the type parameter, or designates a bit-field (7.21).
— The argument in an instance of one of the integer-constant macros is not a decimal, octal, or
hexadecimal constant, or it has a value that exceeds the limits for the corresponding type
(7.22.4).
— A byte input/output function is applied to a wide-oriented stream, or a wide character
input/output function is applied to a byte-oriented stream (7.23.2).
— Use is made of any portion of a file beyond the most recent wide character written to a
wide-oriented stream (7.23.2).
— The value of a pointer to a FILE object is used after the associated file is closed (7.23.3).
— The stream for the fflush function points to an input stream or to an update stream in which
the most recent operation was input (<IP_ADDRESS>).
— The string pointed to by the mode argument in a call to the fopen function does not exactly
match one of the specified character sequences (<IP_ADDRESS>).
— An output operation on an update stream is followed by an input operation without an
intervening call to the fflush function or a file positioning function, or an input operation
on an update stream is followed by an output operation with an intervening call to a file
positioning function (<IP_ADDRESS>).
— An attempt is made to use the contents of the array that was supplied in a call to the setvbuf
function (<IP_ADDRESS>).
— There are insufficient arguments for the format in a call to one of the formatted input/output
functions, or an argument does not have an appropriate type (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>,
and <IP_ADDRESS>).
— The format in a call to one of the formatted input/output functions or to the strftime or
wcsftime function is not a valid multibyte character sequence that begins and ends in its
initial shift state (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>).
— In a call to one of the formatted output functions, a precision appears with a conversion
specifier other than those described (<IP_ADDRESS>, <IP_ADDRESS>).
— A conversion specification for a formatted output function uses an asterisk to denote an
argument-supplied field width or precision, but the corresponding argument is not provided
(<IP_ADDRESS>, <IP_ADDRESS>).
— A conversion specification for a formatted output function uses a # or 0 flag with a conversion
specifier other than those described (<IP_ADDRESS>, <IP_ADDRESS>).
— A conversion specification for one of the formatted input/output functions uses a length
modifier with a conversion specifier other than those described (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>,
and <IP_ADDRESS>).
— An s conversion specifier is encountered by one of the formatted output functions, and the
argument is missing the null terminator (unless a precision is specified that does not require
null termination) (<IP_ADDRESS>, <IP_ADDRESS>).
— An n conversion specification for one of the formatted input/output functions includes any
flags, an assignment-suppressing character, a field width, or a precision (<IP_ADDRESS>, <IP_ADDRESS>,
and <IP_ADDRESS>, <IP_ADDRESS>).
— A % conversion specifier is encountered by one of the formatted input/output functions, but
the complete conversion specification is not exactly %% (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>).
— An invalid conversion specification is found in the format for one of the formatted input/out-
put functions, or the strftime or wcsftime function (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>,
and <IP_ADDRESS>, <IP_ADDRESS>).
— The number of characters or wide characters transmitted by a formatted output function (or
written to an array, or that would have been written to an array) is greater than INT_MAX
(<IP_ADDRESS>, <IP_ADDRESS>).
— The number of input items assigned by a formatted input function is greater than INT_MAX
(<IP_ADDRESS>, <IP_ADDRESS>).
— The result of a conversion by one of the formatted input functions cannot be represented in
the corresponding object, or the receiving object does not have an appropriate type (<IP_ADDRESS>,
and <IP_ADDRESS>).
— A c, s, or [ conversion specifier is encountered by one of the formatted input functions, and
the array pointed to by the corresponding argument is not large enough to accept the input
sequence (and a null terminator if the conversion specifier is s or [) (<IP_ADDRESS>, <IP_ADDRESS>).
— A c, s, or [ conversion specifier with an l qualifier is encountered by one of the formatted
input functions, but the input is not a valid multibyte character sequence that begins in the
initial shift state (<IP_ADDRESS>, <IP_ADDRESS>).
— The input item for a %p conversion by one of the formatted input functions is not a value
converted earlier during the same program execution (<IP_ADDRESS>, <IP_ADDRESS>).
— The vfprintf, vfscanf, vprintf, vscanf, vsnprintf, vsprintf, vsscanf, vfwprintf,
vfwscanf , vswprintf , vswscanf , vwprintf , or vwscanf function is called with an improperly
initialized va_list argument, or the argument is used (other than in an invocation of va_end)
after the function returns (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>,
and <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>).
— The contents of the array supplied in a call to the fgets or fgetws function are used after a
read error occurred (<IP_ADDRESS>, <IP_ADDRESS>).
— The file position indicator for a binary stream is used after a call to the ungetc function where
its value was zero before the call (<IP_ADDRESS>).
— The file position indicator for a stream is used after an error occurred during a call to the
fread or fwrite function (<IP_ADDRESS>, <IP_ADDRESS>).
— A partial element read by a call to the fread function is used (<IP_ADDRESS>).
— The fseek function is called for a text stream with a nonzero offset and either the offset was
not returned by a previous successful call to the ftell function on a stream associated with
the same file or whence is not SEEK_SET (<IP_ADDRESS>).
— The fsetpos function is called to set a position that was not returned by a previous successful
call to the fgetpos function on a stream associated with the same file (<IP_ADDRESS>).
— A non-null pointer returned by a call to the calloc, malloc, realloc, or aligned_alloc
function with a zero requested size is used to access an object (7.24.3).
— The value of a pointer that refers to space deallocated by a call to the free or realloc function
is used (7.24.3).
— The pointer argument to the free or realloc function does not match a pointer earlier
returned by a memory management function, or the space has been deallocated by a call to
free or realloc (<IP_ADDRESS>, <IP_ADDRESS>).
— The value of the object allocated by the malloc function is used (<IP_ADDRESS>).
— The values of any bytes in a new object allocated by the realloc function beyond the size of
the old object are used (<IP_ADDRESS>).
— The program calls the exit or quick_exit function more than once, or calls both functions
(<IP_ADDRESS>, <IP_ADDRESS>).
— During the call to a function registered with the atexit or at_quick_exit function, a call is
made to the longjmp function that would terminate the call to the registered function (<IP_ADDRESS>,
and <IP_ADDRESS>).
— The string set up by the getenv or strerror function is modified by the program (<IP_ADDRESS>,
and <IP_ADDRESS>).
— A signal is raised while the quick_exit function is executing (<IP_ADDRESS>).
— A command is executed through the system function in a way that is documented as causing
termination or some other form of undefined behavior (<IP_ADDRESS>).
— A searching or sorting utility function is called with an invalid pointer argument, even if the
number of elements is zero (7.24.5).
— The comparison function called by a searching or sorting utility function alters the contents of
the array being searched or sorted, or returns ordering values inconsistently (7.24.5).
— The array being searched by the bsearch function does not have its elements in proper order
(<IP_ADDRESS>).
— The current conversion state is used by a multibyte/wide character conversion function after
changing the LC_CTYPE category (7.24.7).
— A string or wide string utility function is instructed to access an array beyond the end of an
object (7.26.1, 7.31.4).
— A string or wide string utility function is called with an invalid pointer argument, even if the
length is zero (7.26.1, 7.31.4).
— The contents of the destination array are used after a call to the strxfrm, strftime, wcsxfrm,
or wcsftime function in which the specified length was too small to hold the entire null-
terminated result (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>.4, <IP_ADDRESS>).
— A sequence of calls of the strtok function is made from different threads (<IP_ADDRESS>).
— The first argument in the very first call to the strtok or wcstok is a null pointer (<IP_ADDRESS>,
and <IP_ADDRESS>.7).
— A pointer returned by the strerror function is used after a subsequent call to the function, or
after the calling thread has exited (<IP_ADDRESS>).
— The type of an argument to a type-generic macro is not compatible with the type of the
corresponding parameter of the selected function (7.27).
— Arguments for generic parameters of a type-generic macro are such that some argument has a
corresponding real type that is of standard floating type and another argument is of decimal
floating type (7.27).
— Arguments for generic parameters of a type-generic macro are such that neither <math.h> and
<complex.h> define a function whose generic parameters have the determined corresponding
real type (7.27).
— A complex argument is supplied for a generic parameter of a type-generic macro that has no
corresponding complex function (7.27).
— A decimal floating argument is supplied for a generic parameter of a type-generic macro that
expects a complex argument (7.27).
— A standard floating or complex argument is supplied for a generic parameter of a type-generic
macro that expects a decimal floating type argument (7.27).
— A non-recursive mutex passed to mtx_lock is locked by the calling thread (<IP_ADDRESS>).
— The mutex passed to mtx_timedlock does not support timeout (<IP_ADDRESS>).
— The mutex passed to mtx_unlock is not locked by the calling thread (<IP_ADDRESS>).
— The thread passed to thrd_detach or thrd_join was previously detached or joined with
another thread (<IP_ADDRESS>, <IP_ADDRESS>).
— The tss_create function is called from within a destructor (<IP_ADDRESS>).
— The key passed to tss_delete, tss_get, or tss_set was not returned by a call to tss_create
before the thread commenced executing destructors (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>).
— An attempt is made to access the pointer returned by the time conversion functions after the
thread that originally called the function to obtain it has exited (7.29.3).
— At least one member of the broken-down time passed to asctime contains a value outside its
normal range, or the calculated year exceeds four digits or is less than the year 1000 (<IP_ADDRESS>).
— The argument corresponding to an s specifier without an l qualifier in a call to the fwprintf
function does not point to a valid multibyte character sequence that begins in the initial shift
state (<IP_ADDRESS>).
— In a call to the wcstok function, the object pointed to by ptr does not have the value stored by
the previous call for the same wide string (<IP_ADDRESS>.7).
— An mbstate_t object is used inappropriately (7.31.6).
— The value of an argument of type wint_t to a wide character classification or case mapping
function is neither equal to the value of WEOF nor representable as a wchar_t (7.32.1).
— The iswctype function is called using a different LC_CTYPE category from the one in effect for
the call to the wctype function that returned the description (<IP_ADDRESS>.1).
— The towctrans function is called using a different LC_CTYPE category from the one in effect
for the call to the wctrans function that returned the description (<IP_ADDRESS>.1).
J.3 [Implementation-defined behavior]
1 A conforming implementation is required to document its choice of behavior in each of the areas
listed in this subclause. The following are implementation-defined:
J.3.1 [Translation]
1 — How a diagnostic is identified (3.10, <IP_ADDRESS>).
— Whether each nonempty sequence of white-space characters other than new-line is retained or
replaced by one space character in translation phase 3 (<IP_ADDRESS>).
J.3.2 [Environment]
1 — The mapping between physical source file multibyte characters and the source character set in
translation phase 1 (<IP_ADDRESS>).
— The name and type of the function called at program startup in a freestanding environment
(<IP_ADDRESS>).
— The effect of program termination in a freestanding environment (<IP_ADDRESS>).
— An alternative manner in which the main function may be defined (<IP_ADDRESS>.1).
— The values given to the strings pointed to by the argv argument to main (<IP_ADDRESS>.1).
— What constitutes an interactive device (<IP_ADDRESS>).
— Whether a program can have more than one thread of execution in a freestanding environment
(<IP_ADDRESS>).
— The set of signals, their semantics, and their default handling (7.14).
— Signal values other than SIGFPE, SIGILL, and SIGSEGV that correspond to a computational
exception (<IP_ADDRESS>).
— Signals for which the equivalent of signal(sig, SIG_IGN); is executed at program startup
(<IP_ADDRESS>).
— The set of environment names and the method for altering the environment list used by the
getenv function (<IP_ADDRESS>).
— The manner of execution of the string by the system function (<IP_ADDRESS>).
J.3.3 [Identifiers]
1 — Which additional multibyte characters may appear in identifiers and their correspondence to
universal character names (6.4.2).
— The number of significant initial characters in an identifier (<IP_ADDRESS>, 6.4.2).
J.3.4 [Characters]
1 — The number of bits in a byte (3.6).
— The values of the members of the execution character set (5.2.1).
— The unique value of the member of the execution character set produced for each of the
standard alphabetic escape sequences (5.2.2).
— The value of a char object into which has been stored any character other than a member of
the basic execution character set (6.2.5).
— Which of signed char or unsigned char has the same range, representation, and behavior
as "plain" char (6.2.5, <IP_ADDRESS>).
— The literal encoding, which maps of the characters of the execution character set to the values
in a character constant or string literal (6.2.9, <IP_ADDRESS>).
— The wide literal encoding, of the characters of the execution character set to the values in a
wchar_t character constant or wchar_t string literal (6.2.9, <IP_ADDRESS>).
— The mapping of members of the source character set (in character constants and string literals)
to members of the execution character set (<IP_ADDRESS>, <IP_ADDRESS>).
— The value of an integer character constant containing more than one character or containing a
character or escape sequence that does not map to a single-byte execution character (<IP_ADDRESS>).
— The value of a wide character constant containing more than one multibyte character or a
single multibyte character that maps to multiple members of the extended execution character
set, or containing a multibyte character or escape sequence not represented in the extended
execution character set (<IP_ADDRESS>).
— The current locale used to convert a wide character constant consisting of a single multibyte
character that maps to a member of the extended execution character set into a corresponding
wide character code (<IP_ADDRESS>).
— The current locale used to convert a wide string literal into corresponding wide character
codes (6.4.5).
— The value of a string literal containing a multibyte character or escape sequence not represented
in the execution character set (6.4.5).
— The encoding of any of wchar_t, char16_t, and char32_t where the corresponding stan-
dard encoding macro (__STDC_ISO_10646__ , __STDC_UTF_16__ , or __STDC_UTF_32__ ) is not
defined (<IP_ADDRESS>).
J.3.5 [Integers]
1 — Any extended integer types that exist in the implementation (6.2.5).
— The rank of any extended integer type relative to another extended integer type with the same
precision (<IP_ADDRESS>).
— The result of, or the signal raised by, converting an integer to a signed integer type when the
value cannot be represented in an object of that type (<IP_ADDRESS>).
— The results of some bitwise operations on signed integers (6.5).
J.3.6 [Floating-point]
1 — The accuracy of the floating-point operations and of the library functions in <math.h> and
<complex.h> that return floating-point results (<IP_ADDRESS>.2).
— The accuracy of the conversions between floating-point internal representations and string
representations performed by the library functions in <stdio.h>, <stdlib.h>, and <wchar.h>
(<IP_ADDRESS>.2).
— The rounding behaviors characterized by non-standard values of FLT_ROUNDS (<IP_ADDRESS>.2).
— The evaluation methods characterized by non-standard negative values of FLT_EVAL_METHOD
(<IP_ADDRESS>.2).
— The evaluation methods characterized by non-standard negative values of DEC_EVAL_METHOD
(<IP_ADDRESS>.3).
— If decimal floating types are supported (6.2.5).
— The direction of rounding when an integer is converted to a floating-point number that cannot
exactly represent the original value (<IP_ADDRESS>).
— The direction of rounding when a floating-point number is converted to a narrower floating-
point number (<IP_ADDRESS>).
— How the nearest representable value or the larger or smaller representable value immediately
adjacent to the nearest representable value is chosen for certain floating constants (<IP_ADDRESS>).
— Whether and how floating expressions are contracted when not disallowed by the
FP_CONTRACT pragma (6.5).
— The default state for the FENV_ACCESS pragma (7.6.1).
— Additional floating-point exceptions, rounding modes, environments, and classifications, and
their macro names (7.6, 7.12).
— The default state for the FP_CONTRACT pragma (7.12.2).
J.3.7 [Arrays and pointers]
1 — The result of converting a pointer to an integer or vice versa (<IP_ADDRESS>).
— The size of the result of subtracting two pointers to elements of the same array (6.5.6).
J.3.8 [Hints]
1 — The extent to which suggestions made by using the register storage-class specifier are
effective (6.7.1).
— The extent to which suggestions made by using the inline function specifier are effective
(6.7.4).
J.3.9 [Structures, unions, enumerations, and bit-fields]
1 — Whether a "plain" int bit-field is treated as a signed int bit-field or as an unsigned int
bit-field (6.7.2, <IP_ADDRESS>).
— Allowable bit-field types other than bool, signed int, unsigned int, and bit-precise integer
types (<IP_ADDRESS>).
— Whether atomic types are permitted for bit-fields (<IP_ADDRESS>).
— Whether a bit-field can straddle a storage-unit boundary (<IP_ADDRESS>).
— The order of allocation of bit-fields within a unit (<IP_ADDRESS>).
— The alignment of non-bit-field members of structures (<IP_ADDRESS>). This should present no problem
unless binary data written by one implementation is read by another.
— The integer type compatible with each enumerated type (<IP_ADDRESS>).
J.3.10 [Qualifiers]
1 — What constitutes an access to an object that has volatile-qualified type (6.7.3).
J.3.11 [Preprocessing directives]
1 — The locations within #pragma directives where header name preprocessing tokens are recog-
nized (6.4, 6.4.7).
— How sequences in both forms of header names are mapped to headers or external source file
names (6.4.7).
— Whether the value of a character constant in a constant expression that controls conditional
inclusion matches the value of the same character constant in the execution character set
(6.10.1).
— Whether the value of a single-character character constant in a constant expression that controls
conditional inclusion may have a negative value (6.10.1).
— The places that are searched for an included < > delimited header, and how the places are
specified or the header is identified (6.10.2).
— How the named source file is searched for in an included " " delimited header (6.10.2).
— The method by which preprocessing tokens (possibly resulting from macro expansion) in a
#include directive are combined into a header name (6.10.2).
— The nesting limit for #include processing (6.10.2).
— Whether the # operator inserts a \ character before the \ character that begins a universal
character name in a character constant or string literal (<IP_ADDRESS>).
— The behavior on each recognized non-STDC #pragma directive (6.10.7).
— The definitions for __DATE__ and __TIME__ when respectively, the date and time of translation
are not available (<IP_ADDRESS>).
J.3.12 [Library functions]
1 — Any library facilities available to a freestanding program, other than the minimal set required
by Clause 4 (<IP_ADDRESS>).
— The format of the diagnostic printed by the assert macro (<IP_ADDRESS>).
— The representation of the floating-point status flags stored by the fegetexceptflag function
(<IP_ADDRESS>).
— Whether the feraiseexcept function raises the "inexact" floating-point exception in addition
to the "overflow" or "underflow" floating-point exception (<IP_ADDRESS>).
— Strings other than "C" and "" that may be passed as the second argument to the setlocale
function (<IP_ADDRESS>).
— The types defined for float_t and double_t when the value of the FLT_EVAL_METHOD macro
is less than 0 (7.12).
— The types defined for _Decimal32_t and _Decimal64_t when the value of the
DEC_EVAL_METHOD macro is less than 0 (7.12).
— Domain errors for the mathematics functions, other than those required by this document
(7.12.1).
— The values returned by the mathematics functions on domain errors or pole errors (7.12.1).
— The values returned by the mathematics functions on underflow range errors, whether errno
is set to the value of the macro ERANGE when the integer expression math_errhandling &
MATH_ERRNO is nonzero, and whether the "underflow" floating-point exception is raised when
the integer expression math_errhandling & MATH_ERREXCEPT is nonzero. (7.12.1).
— Whether a domain error occurs or zero is returned when an fmod function has a second
argument of zero (<IP_ADDRESS>).
— Whether a domain error occurs or zero is returned when a remainder function has a second
argument of zero (<IP_ADDRESS>).
— The base-2 logarithm of the modulus used by the remquo functions in reducing the quotient
(<IP_ADDRESS>).
— The byte order of decimal floating type encodings (7.12.16).
— Whether a domain error occurs or zero is returned when a remquo function has a second
argument of zero (<IP_ADDRESS>).
— Whether the equivalent of signal(sig, SIG_DFL); is executed prior to the call of a signal
handler, and, if not, the blocking of signals that is performed (<IP_ADDRESS>).
— The value of __STDC_ENDIAN_NATIVE__ if the execution environment is not big-endian or
little-endian (7.18.2)
— The null pointer constant to which the macro NULL expands (7.21).
— Whether the last line of a text stream requires a terminating new-line character (7.23.2).
— Whether space characters that are written out to a text stream immediately before a new-line
character appear when read in (7.23.2).
— The number of null characters that may be appended to data written to a binary stream (7.23.2).
— Whether the file position indicator of an append-mode stream is initially positioned at the
beginning or end of the file (7.23.3).
— Whether a write on a text stream causes the associated file to be truncated beyond that point
(7.23.3).
— The characteristics of file buffering (7.23.3).
— Whether a zero-length file actually exists (7.23.3).
— The rules for composing valid file names (7.23.3).
— Whether the same file can be simultaneously open multiple times (7.23.3).
— The nature and choice of encodings used for multibyte characters in files (7.23.3).
— The effect of the remove function on an open file (<IP_ADDRESS>).
— The effect if a file with the new name exists prior to a call to the rename function (<IP_ADDRESS>).
— Whether an open temporary file is removed upon abnormal program termination (<IP_ADDRESS>).
— Which changes of mode are permitted (if any), and under what circumstances (<IP_ADDRESS>).
— The style used to print an infinity or NaN, and the meaning of any n-char or n-wchar sequence
printed for a NaN (<IP_ADDRESS>, <IP_ADDRESS>).
— The output for %p conversion in the fprintf or fwprintf function (<IP_ADDRESS>, <IP_ADDRESS>).
— The interpretation of a- character that is neither the first nor the last character, nor the second
where a ^ character is the first, in the scanlist for %[ conversion in the fscanf or fwscanf
function (<IP_ADDRESS>, <IP_ADDRESS>).
— The set of sequences matched by a %p conversion and the interpretation of the corresponding
input item in the fscanf or fwscanf function (<IP_ADDRESS>, <IP_ADDRESS>).
— The value to which the macro errno is set by the fgetpos, fsetpos, or ftell functions on
failure (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>).
— The meaning of any n-char or n-wchar sequence in a string representing a NaN that is
converted by the strtod, strtof, strtold, wcstod, wcstof, or wcstold function (<IP_ADDRESS>,
and <IP_ADDRESS>.2).
— Whether or not the strtod, strtof, strtold, wcstod, wcstof, or wcstold function sets
errno to ERANGE when underflow occurs (<IP_ADDRESS>, <IP_ADDRESS>.2).
— The meaning of any d-char or d-wchar sequence in a string representing a NaN that is con-
verted by the strtod32, strtod64, strtod128, wcstod32, wcstod64, or wcstod128 function
(<IP_ADDRESS>, <IP_ADDRESS>.3).
— Whether or not the strtod32, strtod64, strtod128, wcstod32, wcstod64, or wcstod128
function sets errno to ERANGE when underflow occurs (<IP_ADDRESS>, <IP_ADDRESS>.3).
— Whether the calloc, malloc, realloc, and aligned_alloc functions return a null pointer or
a pointer to an allocated object when the size requested is zero (7.24.3).
— Whether open streams with unwritten buffered data are flushed, )open streams are closed, or
temporary files are removed when the abort or _Exit function is called (<IP_ADDRESS>, <IP_ADDRESS>).
— The termination status returned to the host environment by the abort, exit, _Exit , or
quick_exit function (<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>).
— The value returned by the system function when its argument is not a null pointer (<IP_ADDRESS>).
— Whether the internal state of multibyte/wide character conversion functions has thread-storage
duration, and its initial value in newly created threads (7.24.7).
— The range and precision of times representable in clock_t and time_t (7.29).
— The local time zone and Daylight Saving Time (7.29.1).
— Whether TIME_MONOTONIC or TIME_ACTIVE are supported time bases (7.29.1).
— Whether TIME_THREAD_ACTIVE is a supported time bases (7.29.1, 7.28.1).
— The local time zone and Daylight Saving Time (7.29.1).
— The era for the clock function (<IP_ADDRESS>).
— The TIME_UTC epoch (<IP_ADDRESS>).
— The replacement string for the %Z specifier to the strftime, and wcsftime functions in the
"C" locale (<IP_ADDRESS>, <IP_ADDRESS>).
— Whether internal mbstate_t objects have thread storage duration (7.30.1, <IP_ADDRESS>, <IP_ADDRESS>).
— Whether the functions in <math.h> honor the rounding direction mode in an IEC 60559
conformant implementation, unless explicitly specified otherwise (F.10).
J.3.13 [Architecture]
1 — The values or expressions assigned to the macros specified in the headers <float.h>,
<limits.h>, and <stdint.h> (<IP_ADDRESS>, 7.22).
— The result of attempting to indirectly access an object with automatic or thread storage duration
from a thread other than the one with which it is associated (6.2.4).
— The number, order, and encoding of bytes in any object (when not explicitly specified in this
document) (<IP_ADDRESS>).
— Whether any extended alignments are supported and the contexts in which they are supported
(6.2.8).
— Valid alignment values other than those returned by an alignof expression for fundamental
types, if any (6.2.8).
— The value of the result of the sizeof and alignof operators (<IP_ADDRESS>).
J.4 [Locale-specific behavior]
1 The following characteristics of a hosted environment are locale-specific and are required to be
documented by the implementation:
— Additional members of the source and execution character sets beyond the basic character set
(5.2.1).
— The presence, meaning, and representation of additional multibyte characters in the execution
character set beyond the basic character set (<IP_ADDRESS>).
— The shift states used for the encoding of multibyte characters (<IP_ADDRESS>).
— The direction of writing of successive printing characters (5.2.2).
— The decimal-point character (7.1.1).
— The set of printing characters (7.4, 7.32.2).
— The set of control characters (7.4, 7.32.2).
— The sets of characters tested for by the isalpha, isblank, islower, ispunct, isspace,
isupper, iswalpha, iswblank, iswlower, iswpunct, iswspace, or iswupper functions
(<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>.2, <IP_ADDRESS>.3, <IP_ADDRESS>.7, <IP_ADDRESS>.9,
<IP_ADDRESS>.10, <IP_ADDRESS>.11).
— The native environment (<IP_ADDRESS>).
— Additional subject sequences accepted by the numeric conversion functions (7.24.1, <IP_ADDRESS>).
— The collation sequence of the execution character set (<IP_ADDRESS>, <IP_ADDRESS>.2).
— The contents of the error message strings set up by the strerror function (<IP_ADDRESS>).
— The formats for time and date (<IP_ADDRESS>, <IP_ADDRESS>).
— Character mappings that are supported by the towctrans function (7.32.1).
— Character classifications that are supported by the iswctype function (7.32.1).
J.5 [Common extensions]
1 The following extensions are widely used in many systems, but are not portable to all implemen-
tations. The inclusion of any extension that may cause a strictly conforming program to become
invalid renders an implementation nonconforming. Examples of such extensions are new keywords,
extra library functions declared in standard headers, or predefined macros with names that do not
begin with an underscore.
J.5.1 [Environment arguments]
1 In a hosted environment, the main function receives a third argument, char *envp[], that points to
a null-terminated array of pointers to char, each of which points to a string that provides information
about the environment for this execution of the program (<IP_ADDRESS>.1).
J.5.2 [Specialized identifiers]
1 Characters other than the underscore _ , letters, and digits, that are not part of the basic source
character set (such as the dollar sign $, or characters in national character sets) may appear in an
identifier (6.4.2).
J.5.3 [Lengths and cases of identifiers]
1 All characters in identifiers (with or without external linkage) are significant (6.4.2).
J.5.4 [Scopes of identifiers]
1 A function identifier, or the identifier of an object the declaration of which contains the keyword
extern, has file scope (6.2.1).
J.5.5 [Writable string literals]
1 String literals are modifiable (in which case, identical string literals should denote distinct objects)
(6.4.5).
J.5.6 [Other arithmetic types]
1 Additional arithmetic types, such as __int128 or double double, and their appropriate conver-
sions are defined (6.2.5, 6.3.1). Additional floating types may have more range or precision than
long double, may be used for evaluating expressions of other floating types, and may be used to
define float_t or double_t. Additional floating types may also have less range or precision than
float.
J.5.7 [Function pointer casts]
1 A pointer to an object or to void may be cast to a pointer to a function, allowing data to be invoked
as a function (6.5.4).
2 A pointer to a function may be cast to a pointer to an object or to void, allowing a function to be
inspected or modified (for example, by a debugger) (6.5.4).
J.5.8 [Extended bit-field types]
1 A bit-field may be declared with a type other than bool, unsigned int, signed int, or a bit-precise
integer type, with an appropriate maximum width (<IP_ADDRESS>).
J.5.9 [The fortran keyword]
1 The fortran function specifier may be used in a function declaration to indicate that calls suitable
for FORTRAN should be generated, or that a different representation for the external name is to be
generated (6.7.4).
J.5.10 [The asm keyword]
1 The asm keyword may be used to insert assembly language directly into the translator output (6.8).
The most common implementation is via a statement of the form:
asm (character-string-literal);
J.5.11 [Multiple external definitions]
1 There may be more than one external definition for the identifier of an object, with or without the
explicit use of the keyword extern; if the definitions disagree, or more than one is initialized, the
behavior is undefined (6.9.2).
J.5.12 [Predefined macro names]
1 Macro names that do not begin with an underscore, describing the translation and execution
environments, are defined by the implementation before translation begins (6.10.9).
J.5.13 [Floating-point status flags]
1 If any floating-point status flags are set on normal termination after all calls to functions registered
by the atexit function have been made (see <IP_ADDRESS>), the implementation writes some diagnostics
indicating the fact to the stderr stream, if it is still open,
J.5.14 [Extra arguments for signal handlers]
1 Handlers for specific signals are called with extra arguments in addition to the signal number
(<IP_ADDRESS>).
J.5.15 [Additional stream types and file-opening modes]
1 Additional mappings from files to streams are supported (7.23.2).
2 Additional file-opening modes may be specified by characters appended to the mode argument of
the fopen function (<IP_ADDRESS>).
J.5.16 [Defined file position indicator]
1 The file position indicator is decremented by each successful call to the ungetc or ungetwc function
for a text stream, except if its value was zero before a call (<IP_ADDRESS>, <IP_ADDRESS>).
J.5.17 [Math error reporting]
1 Functions declared in <complex.h> and <math.h> raise SIGFPE to report errors instead of, or in
addition to, setting errno or raising floating-point exceptions (7.3, 7.12).
J.6 [Reserved identifiers and keywords]
1 A lot of identifier preprocessing tokens are used for specific purposes in regular clauses or appendices
from translation phase 3 onwards. Using any of these for a purpose different from their description
in this document, even if the use is in a context where they are normatively permitted, may have an
impact on the portability of code and should thus be avoided.
J.6.1 [Rule based identifiers]
1 The following 40 regular expressions characterize identifiers that are systematically reserved by
some clause this document.

K. [Annex K (normative) Bounds-checking interfaces]
K.1 [Background]
1 Traditionally, the C Library has contained many functions that trust the programmer to provide
output character arrays big enough to hold the result being produced. Not only do these functions
not check that the arrays are big enough, they frequently lack the information needed to perform
such checks. While it is possible to write safe, robust, and error-free code using the existing library,
the library tends to promote programming styles that lead to mysterious failures if a result is too big
for the provided array.
2 A common programming style is to declare character arrays large enough to handle most practical
cases. However, if these arrays are not large enough to handle the resulting strings, data can be
written past the end of the array overwriting other data and program structures. The program never
gets any indication that a problem exists, and so never has a chance to recover or to fail gracefully.
3 Worse, this style of programming has compromised the security of computers and networks. Buffer
overflows can often be exploited to run arbitrary code with the permissions of the vulnerable
(defective) program.
4 If the programmer writes runtime checks to verify lengths before calling library functions, then
those runtime checks frequently duplicate work done inside the library functions, which discover
string lengths as a side effect of doing their job.
5 This annex provides alternative library functions that promote safer, more secure programming. The
alternative functions verify that output buffers are large enough for the intended result and return a
failure indicator if they are not. Data is never written past the end of an array. All string results are
null terminated.
6 This annex also addresses another problem that complicates writing robust code: functions that are
not reentrant because they return pointers to static objects owned by the function. Such functions
can be troublesome since a previously returned result can change if the function is called again,
perhaps by another thread.
K.2 [Scope]
1 This annex specifies a series of optional extensions that can be useful in the mitigation of security
vulnerabilities in programs, and comprise new functions, macros, and types declared or defined in
existing standard headers.
2 An implementation that defines __STDC_LIB_EXT1__ shall conform to the specifications in this
annex.[465]
Footnote 465) Implementations that do not define __STDC_LIB_EXT1__ are not required to conform to these specifications.
3 Subclause K.3 should be read as if it were merged into the parallel structure of named subclauses of
Clause 7.
K.3 [Library]
K.3.1 [Introduction]
K.3.1.1 [Standard headers]
1 The functions, macros, and types declared or defined in K.3 and its subclauses are not declared
or defined by their respective headers if __STDC_WANT_LIB_EXT1__ is defined as a macro which
expands to the integer constant 0 at the point in the source file where the appropriate header is first
included.
2 The functions, macros, and types declared or defined in K.3 and its subclauses are declared and
defined by their respective headers if __STDC_WANT_LIB_EXT1__ is defined as a macro which ex-
pands to the integer constant 1 at the point in the source file where the appropriate header is first
included.[466]
Footnote 466) Future revisions of this document might define meanings for other values of __STDC_WANT_LIB_EXT1__ .
3 It is implementation-defined whether the functions, macros, and types declared or defined in K.3 and
its subclauses are declared or defined by their respective headers if __STDC_WANT_LIB_EXT1__ is not
defined as a macro at the point in the source file where the appropriate header is first included.[467]
Footnote 467) Subclause 7.1.3 reserves certain names and patterns of names that an implementation can use in headers. All other names
are not reserved, and a conforming implementation is not permitted to use them. While some of the names defined in K.3 and
its subclauses are reserved, others are not. If an unreserved name is defined in a header when __STDC_WANT_LIB_EXT1__ is
defined as 0, the implementation is not conforming.
4 Within a preprocessing translation unit, __STDC_WANT_LIB_EXT1__ shall be defined identically for
all inclusions of any headers from Subclause K.3. If __STDC_WANT_LIB_EXT1__ is defined differently
for any such inclusion, the implementation shall issue a diagnostic as if a preprocessor error directive
were used.
K.3.1.2 [Reserved identifiers]
1 Each macro name in any of the following subclauses is reserved for use as specified if it is defined
by any of its associated headers when included; unless explicitly stated otherwise (see 7.1.4).
2 All identifiers with external linkage in any of the following subclauses are reserved for use as
identifiers with external linkage if any of them are used by the program. None of them are reserved
if none of them are used.
3 Each identifier with file scope listed in any of the following subclauses is reserved for use as a
macro name and as an identifier with file scope in the same name space if it is defined by any of its
associated headers when included.
K.3.1.3 [Use of errno]
1 An implementation may set errno for the functions defined in this annex, but is not required to.
K.3.1.4 [Runtime-constraint violations]
1 Most functions in this annex include as part of their specification a list of runtime-constraints. These
runtime-constraints are requirements on the program using the library.[468]
Footnote 468) Although runtime-constraints replace many cases of undefined behavior, undefined behavior still exists in this annex.
Implementations are free to detect any case of undefined behavior and treat it as a runtime-constraint violation by calling the
runtime-constraint handler. This license comes directly from the definition of undefined behavior.
2 Implementations shall verify that the runtime-constraints for a function are not violated by the
program. If a runtime-constraint is violated, the implementation shall call the currently registered
runtime-constraint handler (see set_constraint_handler_s in <stdlib.h>). Multiple runtime-
constraint violations in the same call to a library function result in only one call to the runtime-
constraint handler. It is unspecified which one of the multiple runtime-constraint violations cause
the handler to be called.
3 If the runtime-constraints section for a function states an action to be performed when a runtime-
constraint violation occurs, the function shall perform the action before calling the runtime-constraint
handler. If the runtime-constraints section lists actions that are prohibited when a runtime-constraint
violation occurs, then such actions are prohibited to the function both before calling the handler and
after the handler returns.
4 The runtime-constraint handler might not return. If the handler does return, the library function
whose runtime-constraint was violated shall return some indication of failure as given by the returns
section in the function’s specification.
K.3.2 [Errors <errno.h>]
1 The header <errno.h> defines a type.
2 The type is
errno_t
which is type int.[469]
Footnote 469) As a matter of programming style, errno_t can be used as the type of something that deals only with the values that
might be found in errno. For example, a function which returns the value of errno could be declared as having the return
type errno_t.
K.3.3 [Common definitions <stddef.h>]
1 The header <stddef.h> defines a type.
2 The type is
rsize_t
which is the type size_t.[470]
Footnote 470) See the description of the RSIZE_MAX macro in <stdint.h>.
K.3.4 [Integer types <stdint.h>]
1 The header <stdint.h> defines a macro.
2 The macro is
RSIZE_MAX
which expands to a value[471] of type size_t. Functions that have parameters of type rsize_t con-
sider it a runtime-constraint violation if the values of those parameters are greater than RSIZE_MAX.
Recommended practice
Footnote 471) The macro RSIZE_MAX need not expand to a constant expression.
3 Extremely large object sizes are frequently a sign that an object’s size was calculated incorrectly. For
example, negative numbers appear as very large positive numbers when converted to an unsigned
type like size_t. Also, some implementations do not support objects as large as the maximum
value that can be represented by type size_t.
4 For those reasons, it is sometimes beneficial to restrict the range of object sizes to detect programming
errors. For implementations targeting machines with large address spaces, it is recommended that
RSIZE_MAX be defined as the smaller of the size of the largest object supported or (SIZE_MAX >> 1) ,
even if this limit is smaller than the size of some legitimate, but very large, objects. Implementations
targeting machines with small address spaces may wish to define RSIZE_MAX as SIZE_MAX, which
means that there is no object size that is considered a runtime-constraint violation.
K.3.5 [Input/output <stdio.h>]
1 The header <stdio.h> defines several macros and two types.
2 The macros are
L_tmpnam_s
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_s function;
TMP_MAX_S
which expands to an integer constant expression that is the maximum number of unique file names
that can be generated by the tmpnam_s function.
3 The types are
errno_t
which is type int; and
rsize_t
which is the type size_t.
K.3.5.1 [Operations on files]
K.<IP_ADDRESS> [The tmpfile_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
errno_t tmpfile_s(FILE * restrict * restrict streamptr);
Runtime-constraints
2 streamptr shall not be a null pointer.
3 If there is a runtime-constraint violation, tmpfile_s does not attempt to create a file.
Description
4 The tmpfile_s 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 with the meaning that mode has in the fopen_s function
(including the mode’s effect on exclusive access and file permissions).
5 If the file was created successfully, then the pointer to FILE pointed to by streamptr will be set to
the pointer to the object controlling the opened file. Otherwise, the pointer to FILE pointed to by
streamptr will be set to a null pointer.
Recommended practice
It should be possible to open at least TMP_MAX_S temporary files during the lifetime of the program
(this limit may be shared with tmpnam_s) 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
6 The tmpfile_s function returns zero if it created the file. If it did not create the file or there was a
runtime-constraint violation, tmpfile_s returns a nonzero value.
K.<IP_ADDRESS> [The tmpnam_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
errno_t tmpnam_s(char *s, rsize_t maxsize);
Runtime-constraints
2 s shall not be a null pointer. maxsize shall be less than or equal to RSIZE_MAX. maxsize shall be
greater than the length of the generated file name string.
Description
3 The tmpnam_s function generates a string that is a valid file name and that is not the same as the
name of an existing file.[472] The function is potentially capable of generating TMP_MAX_S different
strings, but any or all of them may already be in use by existing files and thus not be suitable return
values. The lengths of these strings shall be less than the value of the L_tmpnam_s macro.
Footnote 472) Files created using strings generated by the tmpnam_s 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.
4 The tmpnam_s function generates a different string each time it is called.
5 It is assumed that s points to an array of at least maxsize characters. This array will be set to
generated string, as specified below.
6 The implementation shall behave as if no library function except tmpnam calls the tmpnam_s func-
tion.[473]
Recommended practice
Footnote 473) An implementation can have tmpnam call tmpnam_s (perhaps so there is only one naming convention for temporary files),
but this is not required.
7 After a program obtains a file name using the tmpnam_s function and before the program creates a
file with that name, the possibility exists that someone else may create a file with that same name.
To avoid this race condition, the tmpfile_s function should be used instead of tmpnam_s when
possible. One situation that requires the use of the tmpnam_s function is when the program needs to
create a temporary directory rather than a temporary file.
8 Implementations should take care in choosing the patterns used for names returned by tmpnam_s.
For example, making a thread ID part of the names avoids the race condition and possible conflict
when multiple programs run simultaneously by the same user generate the same temporary file
names.
Returns
9 If no suitable string can be generated, or if there is a runtime-constraint violation, the tmpnam_s
function:
— if s is not null and maxsize is both greater than zero and not greater than RSIZE_MAX, writes a
null character to s[0]
— returns a nonzero value.
10 Otherwise, the tmpnam_s function writes the string in the array pointed to by s and returns zero.
Environmental limits
11 The value of the macro TMP_MAX_S shall be at least 25.
K.3.5.2 [File access functions]
K.<IP_ADDRESS> [The fopen_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
errno_t fopen_s(FILE * restrict * restrict streamptr,
const char * restrict filename, const char * restrict mode);
Runtime-constraints
2 None of streamptr, filename, or mode shall be a null pointer.
3 If there is a runtime-constraint violation, fopen_s does not attempt to open a file. Furthermore, if
streamptr is not a null pointer, fopen_s sets *streamptr to the null pointer.
Description
4 The fopen_s function opens the file whose name is the string pointed to by filename, and associates
a stream with it.
5 The mode string shall be as described for fopen, with the addition that modes starting with the
character ’w’ or ’a’ may be preceded by the character ’u’ , see below:
uw truncate to zero length or create text file for writing, default permissions
uwx create text file for writing, default permissions
ua append; open or create text file for writing at end-of-file, default permissions
uwb truncate to zero length or create binary file for writing, default permissions
uwbx create binary file for writing, default permissions
uab append; open or create binary file for writing at end-of-file, default permissions
uw+ truncate to zero length or create text file for update, default permissions
uw+x create text file for update, default permissions
ua+ append; open or create text file for update, writing at end-of-file, default permis-
sions
uw+b or uwb+ truncate to zero length or create binary file for update, default permissions
uw+bx or uwb+x create binary file for update, default permissions
ua+b or uab+ append; open or create binary file for update, writing at end-of-file, default permis-
sions
6 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.
7 To the extent that the underlying system supports the concepts, files opened for writing shall be
opened with exclusive (also known as non-shared) access. If the file is being created, and the first
character of the mode string is not ’u’ , to the extent that the underlying system supports it, the file
shall have a file permission that prevents other users on the system from accessing the file. If the
file is being created and first character of the mode string is ’u’ , then by the time the file has been
closed, it shall have the system default file access permissions.[474]
Footnote 474) These are the same permissions that the file would have been created with by fopen.
8 If the file was opened successfully, then the pointer to FILE pointed to by streamptr will be set to
the pointer to the object controlling the opened file. Otherwise, the pointer to FILE pointed to by
streamptr will be set to a null pointer.
Returns
9 The fopen_s function returns zero if it opened the file. If it did not open the file or if there was a
runtime-constraint violation, fopen_s returns a nonzero value.
K.<IP_ADDRESS> [The freopen_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
errno_t freopen_s(FILE * restrict * restrict newstreamptr,
const char * restrict filename, const char * restrict mode,
FILE * restrict stream);
Runtime-constraints
2 None of newstreamptr, mode, and stream shall be a null pointer.
3 If there is a runtime-constraint violation, freopen_s neither attempts to close any file associated with
stream nor attempts to open a file. Furthermore, if newstreamptr is not a null pointer, fopen_s
sets *newstreamptr to the null pointer.
Description
4 The freopen_s 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 has the same meaning as in
the fopen_s function (including the mode’s effect on exclusive access and file permissions).
5 If filename is a null pointer, the freopen_s 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.
6 The freopen_s function first attempts to close any file that is associated with stream. Failure to
close the file is ignored. The error and end-of-file indicators for the stream are cleared.
7 If the file was opened successfully, then the pointer to FILE pointed to by newstreamptr will be set
to the value of stream. Otherwise, the pointer to FILE pointed to by newstreamptr will be set to a
null pointer.
Returns
8 The freopen_s function returns zero if it opened the file. If it did not open the file or there was a
runtime-constraint violation, freopen_s returns a nonzero value.
K.3.5.3 [Formatted input/output functions]
1 Unless explicitly stated otherwise, if the execution of a function described in this subclause causes
copying to take place between objects that overlap, the objects take on unspecified values.
K.<IP_ADDRESS> [The fprintf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int fprintf_s(FILE * restrict stream, const char * restrict format, ...);
Runtime-constraints
2 Neither stream nor format shall be a null pointer. The %n specifier[475] (modified or not by flags,
field width, or precision) shall not appear in the string pointed to by format. Any argument to
fprintf_s corresponding to a %s specifier shall not be a null pointer.
Footnote 475) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, the[476] fprintf_s function does not attempt to produce
further output, and it is unspecified to what extent fprintf_s produced output before discovering
the runtime-constraint violation.
Description
Footnote 476) Because an implementation can treat any undefined behavior as a runtime-constraint violation, an implementation can
treat any unsupported specifiers in the string pointed to by format as a runtime-constraint violation.
4 The fprintf_s function is equivalent to the fprintf function except for the explicit runtime-
constraints listed above.
Returns
5 The fprintf_s function returns the number of characters transmitted, or a negative value if an
output error, encoding error, or runtime-constraint violation occurred.
K.<IP_ADDRESS> [The fscanf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int fscanf_s(FILE * restrict stream, const char * restrict format, ...);
Runtime-constraints
2 Neither stream nor format shall be a null pointer. Any argument indirected though in order to
store converted input shall not be a null pointer.
3 If there is a runtime-constraint violation, the[477] fscanf_s function does not attempt to perform
further input, and it is unspecified to what extent fscanf_s performed input before discovering the
runtime-constraint violation.
Description
Footnote 477) Because an implementation can treat any undefined behavior as a runtime-constraint violation, an implementation can
treat any unsupported specifiers in the string pointed to by format as a runtime-constraint violation.
4 The fscanf_s function is equivalent to fscanf except that the c, s, and [ conversion specifiers
apply to a pair of arguments (unless assignment suppression is indicated by a *). The first of these
arguments is the same as for fscanf. That argument is immediately followed in the argument list
by the second argument, which has type rsize_t and gives the number of elements in the array
pointed to by the first argument of the pair. If the first argument points to a scalar object, it is
considered to be an array of one element.[478]
Footnote 478) If the format is known at translation time, an implementation can issue a diagnostic for any argument used to store
the result from a c, s, or [ conversion specifier if that argument is not followed by an argument of a type compatible with
rsize_t. A limited amount of checking can be done if even if the format is not known at translation time. For example, an
implementation could issue a diagnostic for each argument after format that has of type pointer to one of char, signed char,
unsigned char, or void that is not followed by an argument of a type compatible with rsize_t. The diagnostic could warn
that unless the pointer is being used with a conversion specifier using the hh length modifier, a length argument is expected
to follow the pointer argument. Another useful diagnostic could flag any non-pointer argument following format that did
not have a type compatible with rsize_t.
5 A matching failure occurs if the number of elements in a receiving object is insufficient to hold the
converted input (including any trailing null character).
Returns
6 The fscanf_s function returns the value of the macro EOF if an input failure occurs before any
conversion or if there is a runtime-constraint violation. Otherwise, the fscanf_s 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 EXAMPLE 1 The call:
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
/* ... */
int n, i; float x; char name[50];
n = fscanf_s(stdin, "%d%f%s", &i, &x, name, (rsize_t) 50);
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.
8 EXAMPLE 2 The call:
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
/* ... */
int n; char s[5];
n = fscanf_s(stdin, "%s", s, sizeof s);
with the input line:
hello
will assign to n the value 0 since a matching failure occurred because the sequence hello\0 requires an array of six characters
to store it.
K.<IP_ADDRESS> [The printf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int printf_s(const char * restrict format, ...);
Runtime-constraints
2 format shall not be a null pointer. The %n specifier[479] (modified or not by flags, field width,
or precision) shall not appear in the string pointed to by format. Any argument to printf_s
corresponding to a %s specifier shall not be a null pointer.
Footnote 479) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, the printf_s function does not attempt to produce further
output, and it is unspecified to what extent printf_s produced output before discovering the
runtime-constraint violation.
Description
4 The printf_s function is equivalent to the printf function except for the explicit runtime-
constraints listed above.
Returns
5 The printf_s function returns the number of characters transmitted, or a negative value if an
output error, encoding error, or runtime-constraint violation occurred.
K.<IP_ADDRESS> [The scanf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int scanf_s(const char * restrict format, ...);
Runtime-constraints
2 format shall not be a null pointer. Any argument indirected though in order to store converted
input shall not be a null pointer.
3 If there is a runtime-constraint violation, the scanf_s function does not attempt to perform further
input, and it is unspecified to what extent scanf_s performed input before discovering the runtime-
constraint violation.
Description
4 The scanf_s function is equivalent to fscanf_s with the argument stdin interposed before the
arguments to scanf_s.
Returns
5 The scanf_s function returns the value of the macro EOF if an input failure occurs before any
conversion or if there is a runtime-constraint violation. Otherwise, the scanf_s 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.
K.<IP_ADDRESS> [The snprintf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int snprintf_s(char * restrict s, rsize_t n, const char * restrict format, ...);
Runtime-constraints
2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater than RSIZE_MAX.
The %n specifier[480] (modified or not by flags, field width, or precision) shall not appear in the string
pointed to by format. Any argument to snprintf_s corresponding to a %s specifier shall not be a
null pointer. No encoding error shall occur.
Footnote 480) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater than zero and
not greater than RSIZE_MAX, then the snprintf_s function sets s[0] to the null character.
Description
4 The snprintf_s function is equivalent to the snprintf function except for the explicit runtime-
constraints listed above.
5 The snprintf_s function, unlike sprintf_s, will truncate the result to fit within the array pointed
to by s.
Returns
6 The snprintf_s 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 a runtime-
constraint violation occurred. Thus, the null-terminated output has been completely written if and
only if the returned value is both nonnegative and less than n.
K.<IP_ADDRESS> [The sprintf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int sprintf_s(char * restrict s, rsize_t n, const char * restrict format, ...);
Runtime-constraints
2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater than RSIZE_MAX.
The number of characters (including the trailing null) required for the result to be written to the
array pointed to by s shall not be greater than n. The %n specifier[481] (modified or not by flags,
field width, or precision) shall not appear in the string pointed to by format. Any argument to
sprintf_s corresponding to a %s specifier shall not be a null pointer. No encoding error shall occur.
Footnote 481) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater than zero and
not greater than RSIZE_MAX, then the sprintf_s function sets s[0] to the null character.
Description
4 The sprintf_s function is equivalent to the sprintf function except for the parameter n and the
explicit runtime-constraints listed above.
5 The sprintf_s function, unlike snprintf_s, treats a result too big for the array pointed to by s as a
runtime-constraint violation.
Returns
6 If no runtime-constraint violation occurred, the sprintf_s function returns the number of characters
written in the array, not counting the terminating null character. If an encoding error occurred,
sprintf_s returns a negative value. If any other runtime-constraint violation occurred, sprintf_s
returns zero.
K.<IP_ADDRESS> [The sscanf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int sscanf_s(const char * restrict s, const char * restrict format, ...);
Runtime-constraints
2 Neither s nor format shall be a null pointer. Any argument indirected though in order to store
converted input shall not be a null pointer.
3 If there is a runtime-constraint violation, the sscanf_s function does not attempt to perform further
input, and it is unspecified to what extent sscanf_s performed input before discovering the runtime-
constraint violation.
Description
4 The sscanf_s function is equivalent to fscanf_s, 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_s function. If copying takes place between objects that
overlap, the objects take on unspecified values.
Returns
5 The sscanf_s function returns the value of the macro EOF if an input failure occurs before any
conversion or if there is a runtime-constraint violation. Otherwise, the sscanf_s 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.
K.<IP_ADDRESS> [The vfprintf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdarg.h>
#include <stdio.h>
int vfprintf_s(FILE *restrict stream, const char *restrict format, va_list arg);
Runtime-constraints
2 Neither stream nor format shall be a null pointer. The %n specifier[482] (modified or not by flags,
field width, or precision) shall not appear in the string pointed to by format. Any argument to
vfprintf_s corresponding to a %s specifier shall not be a null pointer.
Footnote 482) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, the vfprintf_s function does not attempt to produce
further output, and it is unspecified to what extent vfprintf_s produced output before discovering
the runtime-constraint violation.
Description
4 The vfprintf_s function is equivalent to the vfprintf function except for the explicit runtime-
constraints listed above.
Returns
5 The vfprintf_s function returns the number of characters transmitted, or a negative value if an
output error, encoding error, or runtime-constraint violation occurred.
K.<IP_ADDRESS> [The vfscanf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdarg.h>
#include <stdio.h>
int vfscanf_s(FILE *restrict stream, const char *restrict format, va_list arg);
Runtime-constraints
2 Neither stream nor format shall be a null pointer. Any argument indirected though in order to
store converted input shall not be a null pointer.
3 If there is a runtime-constraint violation, the vfscanf_s function does not attempt to perform
further input, and it is unspecified to what extent vfscanf_s performed input before discovering
the runtime-constraint violation.
Description
4 The vfscanf_s function is equivalent to fscanf_s, 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_s function does not invoke the va_end macro.[483]
Returns
Footnote 483) As the functions vfprintf_s , vfscanf_s , vprintf_s , vscanf_s , vsnprintf_s , vsprintf_s , and vsscanf_s invoke
the va_arg macro, the representation of arg after the return is indeterminate.
5 The vfscanf_s function returns the value of the macro EOF if an input failure occurs before any
conversion or if there is a runtime-constraint violation. Otherwise, the vfscanf_s 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.
K.<IP_ADDRESS> [The vprintf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdarg.h>
#include <stdio.h>
int vprintf_s(const char * restrict format, va_list arg);
Runtime-constraints
2 format shall not be a null pointer. The %n specifier[484] (modified or not by flags, field width,
or precision) shall not appear in the string pointed to by format. Any argument to vprintf_s
corresponding to a %s specifier shall not be a null pointer.
Footnote 484) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, the vprintf_s function does not attempt to produce
further output, and it is unspecified to what extent vprintf_s produced output before discovering
the runtime-constraint violation.
Description
4 The vprintf_s function is equivalent to the vprintf function except for the explicit runtime-
constraints listed above.
Returns
5 The vprintf_s function returns the number of characters transmitted, or a negative value if an
output error, encoding error, or runtime-constraint violation occurred.
K.<IP_ADDRESS> [The vscanf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdarg.h>
#include <stdio.h>
int vscanf_s(const char * restrict format, va_list arg);
Runtime-constraints
2 format shall not be a null pointer. Any argument indirected though in order to store converted
input shall not be a null pointer.
3 If there is a runtime-constraint violation, the vscanf_s function does not attempt to perform further
input, and it is unspecified to what extent vscanf_s performed input before discovering the runtime-
constraint violation.
Description
4 The vscanf_s function is equivalent to scanf_s, 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_s function does not invoke the va_end macro[485] .
Returns
Footnote 485) As the functions vfprintf_s , vfscanf_s , vprintf_s , vscanf_s , vsnprintf_s , vsprintf_s , and vsscanf_s invoke
the va_arg macro, the representation of arg after the return is indeterminate.
5 The vscanf_s function returns the value of the macro EOF if an input failure occurs before any
conversion or if there is a runtime-constraint violation. Otherwise, the vscanf_s 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.
K.<IP_ADDRESS> [The vsnprintf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdarg.h>
#include <stdio.h>
int vsnprintf_s(char *restrict s, rsize_t n, const char *restrict format,
va_list arg);
Runtime-constraints
2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater than RSIZE_MAX.
The %n specifier[486] (modified or not by flags, field width, or precision) shall not appear in the string
pointed to by format. Any argument to vsnprintf_s corresponding to a %s specifier shall not be a
null pointer. No encoding error shall occur.
Footnote 486) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater than zero and
not greater than RSIZE_MAX, then the vsnprintf_s function sets s[0] to the null character.
Description
4 The vsnprintf_s function is equivalent to the vsnprintf function except for the explicit runtime-
constraints listed above.
5 The vsnprintf_s function, unlike vsprintf_s, will truncate the result to fit within the array pointed
to by s.
Returns
6 The vsnprintf_s 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 a runtime-
constraint violation occurred. Thus, the null-terminated output has been completely written if and
only if the returned value is both nonnegative and less than n.
K.<IP_ADDRESS> [The vsprintf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdarg.h>
#include <stdio.h>
int vsprintf_s(char * restrict s, rsize_t n, const char * restrict format,
va_list arg);
Runtime-constraints
2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater than RSIZE_MAX.
The number of characters (including the trailing null) required for the result to be written to the array
pointed to by s shall not be greater than n. The %n specifier[487] (modified or not by flags, field width,
or precision) shall not appear in the string pointed to by format. Any argument to vsprintf_s
corresponding to a %s specifier shall not be a null pointer. No encoding error shall occur.
Footnote 487) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed at by format
when those characters are not a interpreted as a %n specifier. For example, if the entire format string was %%n.
3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater than zero and
not greater than RSIZE_MAX, then the vsprintf_s function sets s[0] to the null character.
Description
4 The vsprintf_s function is equivalent to the vsprintf function except for the parameter n and the
explicit runtime-constraints listed above.
5 The vsprintf_s function, unlike vsnprintf_s, treats a result too big for the array pointed to by s
as a runtime-constraint violation.
Returns
6 If no runtime-constraint violation occurred, the vsprintf_s function returns the number of char-
acters written in the array, not counting the terminating null character. If an encoding error oc-
curred, vsprintf_s returns a negative value. If any other runtime-constraint violation occurred,
vsprintf_s returns zero.
K.<IP_ADDRESS> [The vsscanf_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdarg.h>
#include <stdio.h>
int vsscanf_s(const char *restrict s, const char *restrict format, va_list arg);
Runtime-constraints
2 Neither s nor format shall be a null pointer. Any argument indirected though in order to store
converted input shall not be a null pointer.
3 If there is a runtime-constraint violation, the vsscanf_s function does not attempt to perform
further input, and it is unspecified to what extent vsscanf_s performed input before discovering
the runtime-constraint violation.
Description
4 The vsscanf_s function is equivalent to sscanf_s, 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_s function does not invoke the va_end macro.[488]
Returns
Footnote 488) As the functions vfprintf_s , vfscanf_s , vprintf_s , vscanf_s , vsnprintf_s , vsprintf_s , and vsscanf_s invoke
the va_arg macro, the value of arg after the return is indeterminate.
5 The vsscanf_s function returns the value of the macro EOF if an input failure occurs before any
conversion or if there is a runtime-constraint violation. Otherwise, the vscanf_s 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.
K.3.5.4 [Character input/output functions]
K.<IP_ADDRESS> [The gets_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
char *gets_s(char *s, rsize_t n);
Runtime-constraints
2 s shall not be a null pointer. n shall neither be equal to zero nor be greater than RSIZE_MAX. A new-
line character, end-of-file, or read error shall occur within reading n-1 characters from stdin.[489]
Footnote 489) The gets_s function, unlike the historical gets function, makes it a runtime-constraint violation for a line of input to
overflow the buffer to store it. Unlike the fgets function, gets_s maintains a one-to-one relationship between input lines
and successful calls to gets_s. Programs that use gets expect such a relationship.
3 If there is a runtime-constraint violation, characters are read and discarded from stdin until a
new-line character is read, or end-of-file or a read error occurs, and if s is not a null pointer, s[0] is
set to the null character.
Description
4 The gets_s function reads at most one less than the number of characters specified by n from the
stream pointed to by stdin, into the array pointed to by s. No additional characters are read after a
new-line character (which is discarded) or after end-of-file. The discarded new-line character does
not count towards number of characters read. A null character is written immediately after the last
character read into the array.
5 If end-of-file is encountered and no characters have been read into the array, or if a read error
occurs during the operation, then s[0] is set to the null character, and the other elements of s take
unspecified values.
Recommended practice
6 The fgets function allows properly-written programs to safely process input lines too long to store
in the result array. In general this requires that callers of fgets pay attention to the presence or
absence of a new-line character in the result array. Consider using fgets (along with any needed
processing based on new-line characters) instead of gets_s.
Returns
7 The gets_s function returns s if successful. If there was a runtime-constraint violation, or if end-of-
file is encountered and no characters have been read into the array, or if a read error occurs during
the operation, then a null pointer is returned.
K.3.6 [General utilities <stdlib.h>]
1 The header <stdlib.h> defines three types.
2 The types are
errno_t
which is type int; and
rsize_t
which is the type size_t; and
constraint_handler_t
which has the following definition
typedef void (*constraint_handler_t)(
const char * restrict msg,
void * restrict ptr,
errno_t error);
K.3.6.1 [Runtime-constraint handling]
K.<IP_ADDRESS> [The set_constraint_handler_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
constraint_handler_t set_constraint_handler_s(constraint_handler_t handler);
Description
2 The set_constraint_handler_s function sets the runtime-constraint handler to be handler. The
runtime-constraint handler is the function to be called when a library function detects a runtime-
constraint violation. Only the most recent handler registered with set_constraint_handler_s is
called when a runtime-constraint violation occurs.
3 When the handler is called, it is passed the following arguments in the following order:
1. A pointer to a character string describing the runtime-constraint violation.
2. A null pointer or a pointer to an implementation-defined object.
3. If the function calling the handler has a return type declared as errno_t, the return value of
the function is passed. Otherwise, a positive value of type errno_t is passed.
4 The implementation has a default constraint handler that is used if no calls to the
set_constraint_handler_s function have been made. The behavior of the default handler is
implementation-defined, and it may cause the program to exit or abort.
5 If the handler argument to set_constraint_handler_s is a null pointer, the implementation
default handler becomes the current constraint handler.
Returns
6 The set_constraint_handler_s function returns a pointer to the previously registered handler.[490]
Footnote 490) If the previous handler was registered by calling set_constraint_handler_s with a null pointer argument, a pointer to
the implementation default handler is returned (not NULL).
K.<IP_ADDRESS> [The abort_handler_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
void abort_handler_s(const char * restrict msg, void * restrict ptr,
errno_t error);
Description
2 A pointer to the abort_handler_s function shall be a suitable argument to the
set_constraint_handler_s function.
3 The abort_handler_s function writes a message on the standard error stream in an implementation-
defined format. The message shall include the string pointed to by msg. The abort_handler_s
function then calls the abort function.[491]
Returns
Footnote 491) Many implementations invoke a debugger when the abort function is called.
4 The abort_handler_s function does not return to its caller.
K.<IP_ADDRESS> [The ignore_handler_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
void ignore_handler_s(const char * restrict msg, void * restrict ptr,
errno_t error);
Description
2 A pointer to the ignore_handler_s function shall be a suitable argument to the
set_constraint_handler_s function.
3 The ignore_handler_s function simply returns to its caller.[492]
Returns
Footnote 492) If the runtime-constraint handler is set to the ignore_handler_s function, any library function in which a runtime-
constraint violation occurs will return to its caller. The caller can determine whether a runtime-constraint violation occurred
based on the library function’s specification (usually, the library function returns a nonzero errno_t).
4 The ignore_handler_s function returns no value.
K.3.6.2 [Communication with the environment]
K.<IP_ADDRESS> [The getenv_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
errno_t getenv_s(size_t * restrict len, char * restrict value, rsize_t maxsize,
const char * restrict name);
Runtime-constraints
2 name shall not be a null pointer. maxsize shall not be greater than RSIZE_MAX. If maxsize is not
equal to zero, then value shall not be a null pointer.
3 If there is a runtime-constraint violation, the integer pointed to by len is set to 0 (if len is not null),
and the environment list is not searched.
Description
4 The getenv_s function searches an environment list, provided by the host environment, for a string
that matches the string pointed to by name.
5 If that name is found then getenv_s performs the following actions. If len is not a null pointer, the
length of the string associated with the matched list member is stored in the integer pointed to by
len. If the length of the associated string is less than maxsize, then the associated string is copied to
the array pointed to by value.
6 If that name is not found then getenv_s performs the following actions. If len is not a null pointer,
zero is stored in the integer pointed to by len. If maxsize is greater than zero, then value[0] is set
to the null character.
7 The set of environment names and the method for altering the environment list are implementation-
defined. The getenv_s function need not avoid data races with other threads of execution that
modify the environment list.[493]
Returns
Footnote 493) Many implementations provide non-standard functions that modify the environment list.
8 The getenv_s function returns zero if the specified name is found and the associated string was
successfully stored in value. Otherwise, a nonzero value is returned.
K.3.6.3 [Searching and sorting utilities]
1 These utilities make use of a comparison function to search or sort arrays of unspecified type. Where
an argument declared as size_t nmemb specifies the length of the array for a function, if nmemb has
the value zero on a call to that function, then the comparison function is not called, a search finds no
matching element, sorting performs no rearrangement, and the pointer to the array may be null.
2 The implementation shall ensure that the second argument of the comparison function (when called
from bsearch_s), or both arguments (when called from qsort_s), are pointers to elements of the
array.[494] The first argument when called from bsearch_s shall equal key.
Footnote 494) That is, if the value passed is p, then the following expressions are always valid and nonzero:
((char *)p - (char *)base) % size == 0
(char *)p >= (char *)base
(char *)p < (char *)base + nmemb * size
3 The comparison function shall not alter the contents of either the array or search key. The implemen-
tation may reorder elements of the array between calls to the comparison function, but shall not
otherwise alter the contents of any individual element.
4 When the same objects (consisting of size bytes, irrespective of their current positions in the array)
are passed more than once to the comparison function, the results shall be consistent with one
another. That is, for qsort_s they shall define a total ordering on the array, and for bsearch_s the
same object shall always compare the same way with the key.
5 A sequence point occurs immediately before and immediately after each call to the comparison
function, and also between any call to the comparison function and any movement of the objects
passed as arguments to that call.
K.<IP_ADDRESS> [The bsearch_s generic function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
void *bsearch_s(const void *key, QVoid *base, rsize_t nmemb, rsize_t size,
int (*compar)(const void *k, const void *y, void *context),
void *context);
Runtime-constraints
2 Neither nmemb nor size shall be greater than RSIZE_MAX. If nmemb is not equal to zero, then none of
key, base, or compar shall be a null pointer.
3 If there is a runtime-constraint violation, the bsearch_s function does not search the array.
Description
4 The bsearch_s function searches an array of nmemb objects, the initial element of which is pointed
to by base, for an element that matches the object pointed to by key. The size of each element of the
array is specified by size.
5 The comparison function pointed to by compar is called with three arguments. The first two point
to the key object and to an array element, in that order. The function shall return an integer less
than, equal to, or greater than zero if the key object is considered, respectively, to be less than,
to match, or to be greater than the array element. The array shall consist of: all the elements
that compare less than, all the elements that compare equal to, and all the elements that compare
greater than the key object, in that order.[495] The third argument to the comparison function is the
context argument passed to bsearch_s. The sole use of context by bsearch_s is to pass it to the
comparison function.[496]
Returns
Footnote 495) In practice, this means that the entire array has been sorted according to the comparison function.
Footnote 496) The context argument is for the use of the comparison function in performing its duties. For example, it might specify a
collating sequence used by the comparison function.
6 The bsearch_s function returns a pointer to a matching element of the array, or a null pointer if no
match is found or there is a runtime-constraint violation. If two elements compare as equal, which
element is matched is unspecified.
7 The bsearch_s function is generic in the qualification of the type pointed to by the argument to
base. If this argument is a pointer to a const-qualified object type, the returned pointer will be a
pointer to const-qualified void. Otherwise, the argument shall be a pointer to an unqualified object
type or a null pointer constant[497] , and the returned pointer will be a pointer to unqualified void.
Footnote 497) If the argument is a null pointer and the call is executed, the behavior is undefined.
8 The external declaration of bsearch_s has the concrete type:
void * (const void *, const void *, rsize_t, rsize_t, int (*) (const void *,
const void *), void *)
, which supports all correct uses. If a macro definition of the generic function is suppressed in order
to access an actual function, the external declaration with this concrete type is visible[498] .
Footnote 498) This is an obsolescent feature.
K.<IP_ADDRESS> [The qsort_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
errno_t qsort_s(void *base, rsize_t nmemb, rsize_t size,
int (*compar)(const void *x, const void *y, void *context),
void *context);
Runtime-constraints
2 Neither nmemb nor size shall be greater than RSIZE_MAX. If nmemb is not equal to zero, then neither
base nor compar shall be a null pointer.
3 If there is a runtime-constraint violation, the qsort_s function does not sort the array.
Description
4 The qsort_s function sorts an array of nmemb objects, the initial element of which is pointed to by
base. The size of each object is specified by size.
5 The contents of the array are sorted into ascending order according to a comparison function pointed
to by compar, which is called with three arguments. The first two point to the objects being compared.
The function shall return an integer less than, equal to, or greater than zero if the first argument is
considered to be respectively less than, equal to, or greater than the second. The third argument to
the comparison function is the context argument passed to qsort_s. The sole use of context by
qsort_s is to pass it to the comparison function[499] .
Footnote 499) The context argument is for the use of the comparison function in performing its duties. For example, it might specify a
collating sequence used by the comparison function.
6 If two elements compare as equal, their relative order in the resulting sorted array is unspecified.
Returns
7 The qsort_s function returns zero if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
K.3.6.4 [Multibyte/wide character conversion functions]
1 The behavior of the multibyte character functions is affected by the LC_CTYPE category of the current
locale. For a state-dependent encoding, each function is placed into its initial conversion state by a
call for which its character pointer argument, s, is a null pointer. Subsequent calls with s as other
than a null pointer cause the internal conversion state of the function to be altered as necessary. A
call with s as a null pointer causes these functions to set the int pointed to by their status argument
to a nonzero value if encodings have state dependency, and zero otherwise. [500]
Changing the LC_CTYPE category causes the internal object describing the conversion state of these
functions to have an indeterminate representation.
Footnote 500) If the locale employs special bytes to change the shift state, these bytes do not produce separate wide character codes, but
are grouped with an adjacent multibyte character.
K.<IP_ADDRESS> [The wctomb_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
errno_t wctomb_s(int *restrict status, char *restrict s, rsize_t smax,
wchar_t wc);
Runtime-constraints
2 Let n denote the number of bytes needed to represent the multibyte character corresponding to the
wide character given by wc (including any shift sequences).
3 If s is not a null pointer, then smax shall not be less than n, and smax shall not be greater than
RSIZE_MAX. If s is a null pointer, then smax shall equal zero.
4 If there is a runtime-constraint violation, wctomb_s does not modify the int pointed to by status,
and if s is not a null pointer, no more than smax elements in the array pointed to by s will be
accessed.
Description
5 The wctomb_s function determines n and stores the multibyte character representation of wc in the
array whose first element is pointed to by s (if s is not a null pointer). The number of characters
stored never exceeds MB_CUR_MAX or smax. If wc is a null wide character, a null byte is stored,
preceded by any shift sequence needed to restore the initial shift state, and the function is left in the
initial conversion state.
6 The implementation shall behave as if no library function calls the wctomb_s function.
7 If s is a null pointer, the wctomb_s function stores into the int pointed to by status a nonzero or zero
value, if multibyte character encodings, respectively, do or do not have state-dependent encodings.
8 If s is not a null pointer, the wctomb_s function stores into the int pointed to by status either n or
−1 if wc, respectively, does or does not correspond to a valid multibyte character.
9 In no case will the int pointed to by status be set to a value greater than the MB_CUR_MAX macro.
Returns
10 The wctomb_s function returns zero if successful, and a nonzero value if there was a runtime-
constraint violation or wc did not correspond to a valid multibyte character.
K.3.6.5 [Multibyte/wide string conversion functions]
1 The behavior of the multibyte string functions is affected by the LC_CTYPE category of the current
locale.
K.<IP_ADDRESS> [The mbstowcs_s function]
1 Synopsis
#include <stdlib.h>
errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst,
rsize_t dstmax, const char * restrict src, rsize_t len);
Runtime-constraints
2 Neither retval nor src shall be a null pointer. If dst is not a null pointer, then neither len nor
dstmax shall be greater than RSIZE_MAX/sizeof(wchar_t). If dst is a null pointer, then dstmax
shall equal zero. If dst is not a null pointer, then dstmax shall not equal zero. If dst is not a null
pointer and len is not less than dstmax, then a null character shall occur within the first dstmax
multibyte characters of the array pointed to by src.
3 If there is a runtime-constraint violation, then mbstowcs_s does the following. If retval is not
a null pointer, then mbstowcs_s sets *retval to (size_t)(-1) . If dst is not a null pointer and
dstmax is greater than zero and not greater than RSIZE_MAX/sizeof(wchar_t), then mbstowcs_s
sets dst[0] to the null wide character.
Description
4 The mbstowcs_s function converts a sequence of multibyte characters that begins in the initial shift
state from the array pointed to by src into a sequence of corresponding wide characters. If dst is
not a null pointer, the converted characters are stored into the array pointed to by dst. Conversion
continues up to and including a terminating null character, which is also stored. Conversion stops
earlier in two cases: when a sequence of bytes is encountered that does not form a valid multibyte
character, or (if dst is not a null pointer) when len wide characters have been stored into the array
pointed to by dst.[501] If dst is not a null pointer and no null wide character was stored into the
array pointed to by dst, then dst[len] is set to the null wide character. Each conversion takes place
as if by a call to the mbrtowc function.
Footnote 501) Thus, the value of len is ignored if dst is a null pointer.
5 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a sequence of
bytes that do not form a valid multibyte character, an encoding error occurs: the mbstowcs_s func-
tion stores the value (size_t)(-1) into *retval . Otherwise, the mbstowcs_s function stores into
*retval the number of multibyte characters successfully converted, not including the terminating
null character (if any).
6 All elements following the terminating null wide character (if any) written by mbstowcs_s in the
array of dstmax wide characters pointed to by dst take unspecified values when mbstowcs_s
returns.[502]
Footnote 502) This allows an implementation to attempt converting the multibyte string before discovering a terminating null character
did not occur where required.
7 If copying takes place between objects that overlap, the objects take on unspecified values.
Returns
8 The mbstowcs_s function returns zero if no runtime-constraint violation and no encoding error
occurred. Otherwise, a nonzero value is returned.
K.<IP_ADDRESS> [The wcstombs_s function]
1 Synopsis
#include <stdlib.h>
errno_t wcstombs_s(size_t * restrict retval, char * restrict dst, rsize_t dstmax,
const wchar_t * restrict src, rsize_t len);
Runtime-constraints
2 Neither retval nor src shall be a null pointer. If dst is not a null pointer, then len shall not
be greater than RSIZE_MAX/sizeof(wchar_t) and dstmax shall be nonzero and not greater than
RSIZE_MAX. If dst is a null pointer, then dstmax shall equal zero. If dst is not a null pointer and
len is not less than dstmax, then the conversion shall have been stopped (see below) because a
terminating null wide character was reached or because an encoding error occurred.
3 If there is a runtime-constraint violation, then wcstombs_s does the following. If retval is not
a null pointer, then wcstombs_s sets *retval to (size_t)(-1) . If dst is not a null pointer and
dstmax is greater than zero and not greater than RSIZE_MAX, then wcstombs_s sets dst[0] to the
null character.
Description
4 The wcstombs_s function converts a sequence of wide characters from the array pointed to by
src into a sequence of corresponding multibyte characters that begins in the initial shift state. If
dst is not a null pointer, the converted characters are then stored into the array pointed to by dst.
Conversion continues up to and including a terminating null wide character, which is also stored.
Conversion stops earlier in two cases:
— when a wide character is reached that does not correspond to a valid multibyte character;
— (if dst is not a null pointer) when the next multibyte character would exceed the limit of n
total bytes to be stored into the array pointed to by dst. If the wide character being converted
is the null wide character, then n is the lesser of len or dstmax. Otherwise, n is the lesser of
len or dstmax-1.
If the conversion stops without converting a null wide character and dst is not a null pointer, then
a null character is stored into the array pointed to by dst immediately following any multibyte
characters already stored. Each conversion takes place as if by a call to the wcrtomb function.[503]
Footnote 503) If conversion stops because a terminating null wide character has been reached, the bytes stored include those necessary
to reach the initial shift state immediately before the null byte. However, if the conversion stops before a terminating null
wide character has been reached, the result will be null terminated, but might not end in the initial shift state.
5 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a wide
character that does not correspond to a valid multibyte character, an encoding error occurs: the
wcstombs_s function stores the value (size_t)(-1) into *retval . Otherwise, the wcstombs_s
function stores into *retval the number of bytes in the resulting multibyte character sequence, not
including the terminating null character (if any).
6 All elements following the terminating null character (if any) written by wcstombs_s in the array of
dstmax elements pointed to by dst take unspecified values when wcstombs_s returns.[504]
Footnote 504) When len is not less than dstmax, the implementation might fill the array before discovering a runtime-constraint
violation.
7 If copying takes place between objects that overlap, the objects take on unspecified values.
Returns
8 The wcstombs_s function returns zero if no runtime-constraint violation and no encoding error
occurred. Otherwise, a nonzero value is returned.
K.3.7 [String handling <string.h>]
1 The header <string.h> defines two types.
2 The types are
errno_t
which is type int; and
rsize_t
which is the type size_t.
K.3.7.1 [Copying functions]
K.<IP_ADDRESS> [The memcpy_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t memcpy_s(void * restrict s1, rsize_t s1max, const void * restrict s2,
rsize_t n);
Runtime-constraints
2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than RSIZE_MAX. n
shall not be greater than s1max. Copying shall not take place between objects that overlap.
3 If there is a runtime-constraint violation, the memcpy_s function stores zeros in the first s1max
characters of the object pointed to by s1 if s1 is not a null pointer and s1max is not greater than
RSIZE_MAX.
Description
4 The memcpy_s function copies n characters from the object pointed to by s2 into the object pointed
to by s1.
Returns
5 The memcpy_s function returns zero if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
K.<IP_ADDRESS> [The memmove_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t memmove_s(void *s1, rsize_t s1max, const void *s2, rsize_t n);
Runtime-constraints
2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than RSIZE_MAX. n
shall not be greater than s1max.
3 If there is a runtime-constraint violation, the memmove_s function stores zeros in the first s1max
characters of the object pointed to by s1 if s1 is not a null pointer and s1max is not greater than
RSIZE_MAX.
Description
4 The memmove_s function copies n characters from the object pointed to by s2 into the object pointed
to by s1. This copying takes place as if the n characters from the object pointed to by s2 are first
copied into a temporary array of n characters that does not overlap the objects pointed to by s1 or
s2, and then the n characters from the temporary array are copied into the object pointed to by s1.
Returns
5 The memmove_s function returns zero if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
K.<IP_ADDRESS> [The strcpy_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t strcpy_s(char * restrict s1, rsize_t s1max, const char * restrict s2);
Runtime-constraints
2 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX. s1max shall
not equal zero. s1max shall be greater than strnlen_s(s2, s1max). Copying shall not take place
between objects that overlap.
3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is greater than
zero and not greater than RSIZE_MAX, then strcpy_s sets s1[0] to the null character.
Description
4 The strcpy_s function copies the string pointed to by s2 (including the terminating null character)
into the array pointed to by s1.
5 All elements following the terminating null character (if any) written by strcpy_s in the array of
s1max characters pointed to by s1 take unspecified values when strcpy_s returns.[505]
Returns
Footnote 505) This allows an implementation to copy characters from s2 to s1 while simultaneously checking if any of those characters
are null. Such an approach might write a character to every element of s1 before discovering that the first element was set to
the null character.
6 The strcpy_s function returns zero[506] if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
Footnote 506) A zero return value implies that all of the requested characters from the string pointed to by s2 fit within the array
pointed to by s1 and that the result in s1 is null terminated.
K.<IP_ADDRESS> [The strncpy_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t strncpy_s(char * restrict s1, rsize_t s1max, const char * restrict s2,
rsize_t n);
Runtime-constraints
2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than RSIZE_MAX.
s1max shall not equal zero. If n is not less than s1max, then s1max shall be greater than
strnlen_s(s2, s1max). Copying shall not take place between objects that overlap.
3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is greater than
zero and not greater than RSIZE_MAX, then strncpy_s sets s1[0] to the null character.
Description
4 The strncpy_s function copies not more than n successive characters (characters that follow a null
character are not copied) from the array pointed to by s2 to the array pointed to by s1. If no null
character was copied from s2, then s1[n] is set to a null character.
5 All elements following the terminating null character (if any) written by strncpy_s in the array
of s1max characters pointed to by s1 take unspecified values when strncpy_s returns a nonzero
value.[507]
Returns
Footnote 507) This allows an implementation to copy characters from s2 to s1 while simultaneously checking if any of those characters
are null. Such an approach might write a character to every element of s1 before discovering that the first element was set to
the null character.
6 The strncpy_s function returns zero[508] if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
Footnote 508) A zero return value implies that all of the requested characters from the string pointed to by s2 fit within the array
pointed to by s1 and that the result in s1 is null terminated.
7 EXAMPLE 1 The strncpy_s function can be used to copy a string without the danger that the result will not be null
terminated or that characters will be written past the end of the destination array.
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
/* ... */
char src1[100] = "hello";
char src2[7] = {’g’, ’o’, ’o’, ’d’, ’b’, ’y’, ’e’};
char dst1[6], dst2[5], dst3[5];
int r1, r2, r3;
r1 = strncpy_s(dst1, 6, src1, 100);
r2 = strncpy_s(dst2, 5, src2, 7);
r3 = strncpy_s(dst3, 5, src2, 4);
The first call will assign to r1 the value zero and to dst1 the sequence hello\0.
The second call will assign to r2 a nonzero value and to dst2 the sequence \0.
The third call will assign to r3 the value zero and to dst3 the sequence good\0.
K.3.7.2 [Concatenation functions]
K.<IP_ADDRESS> [The strcat_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t strcat_s(char * restrict s1, rsize_t s1max, const char * restrict s2);
Runtime-constraints
2 Let m denote the value s1max - strnlen_s(s1, s1max) upon entry to strcat_s.
3 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX. s1max shall
not equal zero. m shall not equal zero.[509] m shall be greater than strnlen_s(s2, m). Copying shall
not take place between objects that overlap.
Footnote 509) Zero means that s1 was not null terminated upon entry to strcat_s.
4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is greater than
zero and not greater than RSIZE_MAX, then strcat_s sets s1[0] to the null character.
Description
5 The strcat_s function appends a copy of the string pointed to by s2 (including the terminating
null character) to the end of the string pointed to by s1. The initial character from s2 overwrites the
null character at the end of s1.
6 All elements following the terminating null character (if any) written by strcat_s in the array of
s1max characters pointed to by s1 take unspecified values when strcat_s returns.[510]
Returns
Footnote 510) This allows an implementation to append characters from s2 to s1 while simultaneously checking if any of those
characters are null. Such an approach might write a character to every element of s1 before discovering that the first element
was set to the null character.
7 The strcat_s function returns zero[511] if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
Footnote 511) A zero return value implies that all of the requested characters from the string pointed to by s2 were appended to the
string pointed to by s1 and that the result in s1 is null terminated.
K.<IP_ADDRESS> [The strncat_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t strncat_s(char * restrict s1, rsize_t s1max, const char * restrict s2,
rsize_t n);
Runtime-constraints
2 Let m denote the value s1max - strnlen_s(s1, s1max) upon entry to strncat_s.
3 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than RSIZE_MAX.
s1max shall not equal zero. m shall not equal zero.[512] If n is not less than m, then m shall be greater
than strnlen_s(s2, m). Copying shall not take place between objects that overlap.
Footnote 512) Zero means that s1 was not null terminated upon entry to strncat_s.
4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is greater than
zero and not greater than RSIZE_MAX, then strncat_s sets s1[0] to the null character.
Description
5 The strncat_s function appends not more than n successive characters (characters that follow a
null character are not copied) from the array pointed to by s2 to the end of the string pointed to by
s1. The initial character from s2 overwrites the null character at the end of s1. If no null character
was copied from s2, then s1[s1max- m +n] is set to a null character.
6 All elements following the terminating null character (if any) written by strncat_s in the array of
s1max characters pointed to by s1 take unspecified values when strncat_s returns.[513]
Returns
Footnote 513) This allows an implementation to append characters from s2 to s1 while simultaneously checking if any of those
characters are null. Such an approach might write a character to every element of s1 before discovering that the first element
was set to the null character.
7 The strncat_s function returns zero[514] if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
Footnote 514) A zero return value implies that all of the requested characters from the string pointed to by s2 were appended to the
string pointed to by s1 and that the result in s1 is null terminated.
8 EXAMPLE 1 The strncat_s function can be used to copy a string without the danger that the result will not be null
terminated or that characters will be written past the end of the destination array.
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
/* ... */
char s1[100] = "good";
char s2[6] = "hello";
char s3[6] = "hello";
char s4[7] = "abc";
char s5[1000] = "bye";
int r1, r2, r3, r4;
r1 = strncat_s(s1, 100, s5, 1000);
r2 = strncat_s(s2, 6, "", 1);
r3 = strncat_s(s3, 6, "X", 2);
r4 = strncat_s(s4, 7, "defghijklmn", 3);
After the first call r1 will have the value zero and s1 will contain the sequence goodbye\0.
After the second call r2 will have the value zero and s2 will contain the sequence hello\0.
After the third call r3 will have a nonzero value and s3 will contain the sequence \0.
After the fourth call r4 will have the value zero and s4 will contain the sequence abcdef\0.
K.3.7.3 [Search functions]
K.<IP_ADDRESS> [The strtok_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
char *strtok_s(char * restrict s1, rsize_t * restrict s1max,
const char * restrict s2, char ** restrict ptr);
Runtime-constraints
2 None of s1max, s2, or ptr shall be a null pointer. If s1 is a null pointer, then *ptr shall not be a
null pointer. The value of *s1max shall not be greater than RSIZE_MAX. The end of the token found
shall occur within the first *s1max characters of s1 for the first call, and shall occur within the first
*s1max characters of where searching resumes on subsequent calls.
3 If there is a runtime-constraint violation, the strtok_s function does not indirect through the s1 or
s2 pointers, and does not store a value in the object pointed to by ptr.
Description
4 A sequence of calls to the strtok_s function breaks the string pointed to by s1 into a sequence of
tokens, each of which is delimited by a character from the string pointed to by s2. The fourth argu-
ment points to a caller-provided char pointer into which the strtok_s function stores information
necessary for it to continue scanning the same string.
5 The first call in a sequence has a non-null first argument and s1max points to an object whose value
is the number of elements in the character array pointed to by the first argument. The first call stores
an initial value in the object pointed to by ptr and updates the value pointed to by s1max to reflect
the number of elements that remain in relation to ptr. Subsequent calls in the sequence have a null
first argument and the objects pointed to by s1max and ptr are required to have the values stored
by the previous call in the sequence, which are then updated. The separator string pointed to by s2
may be different from call to call.
6 The first call in the sequence searches the string pointed to by s1 for the first character that is not
contained in the current separator string pointed to by s2. If no such character is found, then there
are no tokens in the string pointed to by s1 and the strtok_s function returns a null pointer. If such
a character is found, it is the start of the first token.
7 The strtok_s function then searches from there for the first character in s1 that is contained in the
current separator string. If no such character is found, the current token extends to the end of the
string pointed to by s1, and subsequent searches in the same string for a token return a null pointer.
If such a character is found, it is overwritten by a null character, which terminates the current token.
8 In all cases, the strtok_s function stores sufficient information in the pointer pointed to by ptr so
that subsequent calls, with a null pointer for s1 and the unmodified pointer value for ptr, shall start
searching just past the element overwritten by a null character (if any).
Returns
9 The strtok_s function returns a pointer to the first character of a token, or a null pointer if there is
no token or there is a runtime-constraint violation.
10 EXAMPLE
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
static char str1[] = "?a???b,,,#c";
static char str2[] = "\t \t";
char *t, *ptr1, *ptr2;
rsize_t max1 = sizeof (str1);
rsize_t max2 = sizeof (str2);
t = strtok_s(str1, &max1, "?", &ptr1); // t points to the token "a"
t = strtok_s(NULL, &max1, ",", &ptr1); // t points to the token "??b"
t = strtok_s(str2, &max2, " \t", &ptr2); // t is a null pointer
t = strtok_s(NULL, &max1, "#,", &ptr1); // t points to the token "c"
t = strtok_s(NULL, &max1, "?", &ptr1); // t is a null pointer
K.3.7.4 [Miscellaneous functions]
K.<IP_ADDRESS> [The memset_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t memset_s(void *s, rsize_t smax, int c, rsize_t n)
Runtime-constraints
2 s shall not be a null pointer. Neither smax nor n shall be greater than RSIZE_MAX. n shall not be
greater than smax.
3 If there is a runtime-constraint violation, then if s is not a null pointer and smax is not greater than
RSIZE_MAX, the memset_s function stores the value of c (converted to an unsigned char) into each
of the first smax characters of the object pointed to by s.
Description
4 The memset_s function copies the value of c (converted to an unsigned char) into each of the first
n characters of the object pointed to by s. Unlike memset, any call to the memset_s function shall be
evaluated strictly according to the rules of the abstract machine as described in (<IP_ADDRESS>). That is, any
call to the memset_s function shall assume that the memory indicated by s and n may be accessible
in the future and thus contains the values indicated by c.
Returns
5 The memset_s function returns zero if there was no runtime-constraint violation. Otherwise, a
nonzero value is returned.
K.<IP_ADDRESS> [The strerror_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
errno_t strerror_s(char *s, rsize_t maxsize, errno_t errnum);
Runtime-constraints
2 s shall not be a null pointer. maxsize shall not be greater than RSIZE_MAX. maxsize shall not equal
zero.
3 If there is a runtime-constraint violation, then the array (if any) pointed to by s is not modified.
Description
4 The strerror_s function maps the number in errnum to a locale-specific message string. Typically,
the values for errnum come from errno, but strerror_s shall map any value of type int to a
message.
5 If the length of the desired string is less than maxsize, then the string is copied to the array pointed
to by s.
6 Otherwise, if maxsize is greater than zero, then maxsize-1 characters are copied from the string
to the array pointed to by s and then s[maxsize-1] is set to the null character. Then, if maxsize
is greater than 3, then s[maxsize-2], s[maxsize-3], and s[maxsize-4] are set to the character
period (.).
Returns
7 The strerror_s function returns zero if the length of the desired string was less than maxsize and
there was no runtime-constraint violation. Otherwise, the strerror_s function returns a nonzero
value.
K.<IP_ADDRESS> [The strerrorlen_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
size_t strerrorlen_s(errno_t errnum);
Description
2 The strerrorlen_s function calculates the length of the (untruncated) locale-specific message
string that the strerror_s function maps to errnum.
Returns
3 The strerrorlen_s function returns the number of characters (not including the null character) in
the full message string.
K.<IP_ADDRESS> [The strnlen_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
size_t strnlen_s(const char *s, size_t maxsize);
Description
2 The strnlen_s function computes the length of the string pointed to by s.
Returns
3 If s is a null pointer,[515] then the strnlen_s function returns zero.
Footnote 515) Note that the strnlen_s function has no runtime-constraints. This lack of runtime-constraints along with the values
returned for a null pointer or an unterminated string argument make strnlen_s useful in algorithms that gracefully handle
such exceptional data.
4 Otherwise, the strnlen_s function returns the number of characters that precede the terminating
null character. If there is no null character in the first maxsize characters of s then strnlen_s
returns maxsize. At most the first maxsize characters of s shall be accessed by strnlen_s.
K.3.8 [Date and time <time.h>]
1 The header <time.h> defines two types.
2 The types are
errno_t
which is type int; and
rsize_t
which is the type size_t.
K.3.8.1 [Components of time]
1 A broken-down time is normalized if the values of the members of the tm structure are in their normal
rages.[516]
Footnote 516) The normal ranges are defined in 7.29.1.
K.3.8.2 [Time conversion functions]
1 Like the strftime function, the asctime_s and ctime_s functions do not return a pointer to a static
object, and other library functions are permitted to call them.
K.<IP_ADDRESS> [The asctime_s function]
1 Synopsis
#define __STDC_WANT_LIB_EXT1__ 1
#include <time.h>
errno_t asctime_s(char *s, rsize_t maxsize, const struct tm *timeptr);
Runtime-constraints
2 Neither s nor timeptr shall be a null pointer. maxsize shall not be less than 26 and shall not be
greater than RSIZE_MAX. The broken-down time pointed to by timeptr shall be normalized. The
calendar year represented by the broken-down time pointed to by timeptr shall not be less than
calendar year 0 and shall not be greater than calendar year 9999.
3 If there is a runtime-constraint violation, there is no attempt to convert the time, and s[0] is set to a
null character if s is not a null pointer and maxsize is not zero and is not greater than RSIZE_MAX.
Description
4 The asctime_s function converts the normalized broken-down time in the structure pointed to by
timeptr into a 26 character (including the null character) string in the form
Sun Sep 16 01:03:52 1973\n\0
The fields making up this string are (in order):
1. The name of the day of the week represented by timeptr->tm_wday using the following three
character weekday names: Sun, Mon, Tue, Wed, Thu, Fri, and Sat.
2. The character space.
3. The name of the month represented by timeptr->tm_mon using the following three character
month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec.
4. The character space.
5. The value of timeptr->tm_mday as if printed using the fprintf format "%2d".
6. The character space.
7. The value of timeptr->tm_hour as if printed using the fprintf format "%.2d".
8. The character colon.