ISO/IEC TR 24731-1:2007

Information technology - Programming languages, their environments and system software interfaces - Extensions to the C library - Part 1: Bounds-checking interfaces

ISO/IEC TR 24731-1:2007 provides alternative functions for the C Library (as defined in ISO/IEC 9899:1999) that promote safer, more secure programming. The functions verify that output buffers are large enough for the intended result, and return a failure indicator if they are not. Optionally, failing functions call a "runtime-constraint handler" to report the error. Data is never written past the end of an array. All string results are null terminated. In addition, the functions in ISO/IEC TR 24731-1:2007 are re-entrant: they never return pointers to static objects owned by the function. ISO/IEC TR 24731-1:2007 also contains functions that address insecurities with the C input-output facilities.

Technologies de l'information — Langages de programmation, leurs environnements et leurs systèmes d'interface de logiciel — Extensions à la bibliothèque C — Partie 1: Interfaces des contrôles des bornes

General Information

• Status: Published
• Publication Date: 28-Aug-2007
• ICS: 35.060 - Languages used in information technology
• Technical Committee: ISO/IEC JTC 1/SC 22 - Programming languages, their environments and system software interfaces
• Drafting Committee: ISO/IEC JTC 1/SC 22/WG 14 - C
• Current Stage: 9093 - International Standard confirmed
• Start Date: 30-Oct-2013
• Completion Date: 30-Oct-2025

Overview

ISO/IEC TR 24731-1:2007 specifies bounds‑checking interfaces - a set of extensions to the C standard library (ISO/IEC 9899:1999) that promote safer, more secure C programming. The Technical Report defines alternative library functions, macros and types (available via existing headers when enabled) that verify output buffers are large enough, guarantee null‑terminated string results, avoid writing past array bounds, and are re‑entrant (they do not return pointers to static internal objects). The report also introduces a runtime‑constraint handler mechanism to report or respond to detected violations.

Key topics and requirements

• Bounds‑checking functions: Alternative C library functions that check destination buffer sizes before writing and return a failure indicator if insufficient space is detected. Data is never written past the end of an array and string results are null terminated.
• Runtime‑constraint handling: Implementations must verify runtime‑constraints and call the currently registered handler (set_constraint_handler_s) when violations occur. The handler may not return; if it does, the function must indicate failure.
• Re‑entrancy: Functions defined by the Technical Report avoid returning pointers to static objects, improving thread safety and re‑entrant use.
• Conditional availability: The extensions are exposed only when the user defines the macro STDC_WANT_LIB_EXT1 appropriately; implementations may define STDC_LIB_EXT1 to indicate conformance.
• Headers and scope: Extensions are provided via existing standard headers (examples include <stdio.h>, <string.h>, <stdlib.h>, <wchar.h>, <time.h>, <stdint.h>, <stddef.h>) and cover I/O, string handling, conversion utilities, and more as listed in Clause 6.
• Error reporting: Implementations may set errno for these functions but are not required to; the runtime‑constraint handler is the prescribed error reporting mechanism for violations.

Practical applications

• Secure coding: Reduces common buffer‑overflow vulnerabilities by adding checks in library calls - useful in security‑critical systems.
• Robust libraries and APIs: Library and framework authors can adopt these interfaces to enforce safer buffer usage and predictable failure modes.
• Embedded and safety‑critical software: Systems where undefined behavior is unacceptable benefit from explicit bounds checking and controlled error handling.
• Tooling and compliance: Compiler vendors, static analyzers, and auditors use the standard to guide secure‑coding checks and conformance tests.

Who should use it

• C application developers concerned with security and reliability
• Library implementers and runtime maintainers
• Compiler and toolchain vendors
• Security engineers and code auditors

Related standards

• ISO/IEC 9899:1999 (the C language standard) - normative context for these extensions
• Associated corrigenda (ISO/IEC 9899:1999/Cor.1, Cor.2) and the wider ISO/IEC 24731 family

Keywords: ISO/IEC TR 24731-1:2007, C library bounds checking, runtime-constraint handler, secure C programming, buffer overflow mitigation, STDC_WANT_LIB_EXT1.

Standards Content (Sample)

TECHNICAL ISO/IEC
REPORT TR
24731-1
First edition
2007-09-01
Information technology — Programming
languages, their environments and
system software interfaces — Extensions
to the C library
Part 1:
Bounds-checking interfaces
Technologies de l'information — Langages de programmation, leurs
environnements et leurs systèmes d'interface de logiciel — Extensions
à la bibliothèque C —
Partie 1: Interfaces des contrôles des bornes

Reference number
©
ISO/IEC 2007
PDF disclaimer
This PDF file may contain embedded typefaces. In accordance with Adobe's licensing policy, this file may be printed or viewed but
shall not be edited unless the typefaces which are embedded are licensed to and installed on the computer performing the editing. In
downloading this file, parties accept therein the responsibility of not infringing Adobe's licensing policy. The ISO Central Secretariat
accepts no liability in this area.
Adobe is a trademark of Adobe Systems Incorporated.
Details of the software products used to create this PDF file can be found in the General Info relative to the file; the PDF-creation
parameters were optimized for printing. Every care has been taken to ensure that the file is suitable for use by ISO member bodies. In
the unlikely event that a problem relating to it is found, please inform the Central Secretariat at the address given below.

©  ISO/IEC 2007
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized in any form or by any means,
electronic or mechanical, including photocopying and microfilm, without permission in writing from either ISO at the address below or
ISO's member body in the country of the requester.
ISO copyright office
Case postale 56 • CH-1211 Geneva 20
Tel. + 41 22 749 01 11
Fax + 41 22 749 09 47
E-mail [e-mail]
Web www.iso.org
Published in Switzerland
ii © ISO/IEC 2007 – All rights reserved

Contents
Foreword . v
Introduction . vi
1. Scope . 1
2. Normative references . 1
3. Terms, definitions, and symbols . 2
4.Conformance . 2
5. Predefined macro names . 2
6. Library . 3
6.1Introduction . 3
6.1.1 Standard headers . 3
6.1.2 Reserved identifiers . 4
6.1.3 Use of errno . 4
6.1.4 Runtime-constraint violations . 4
6.2 Errors . 5
6.3 Common definitions . 6
6.4 Integer types . 7
6.5 Input/output . 8
6.5.1 Operations on files . 8
6.5.2 File access functions . 10
6.5.3 Formatted input/output functions . 13
6.5.4 Character input/output functions . 26
6.6 General utilities . 28
6.6.1 Runtime-constraint handling . 28
6.6.2 Communication with the environment . 30
6.6.3 Searching and sorting utilities . 31
6.6.4 Multibyte/wide character conversion functions . 34
6.6.5 Multibyte/wide string conversion functions . 35
6.7 String handling . 39
6.7.1 Copying functions . 39
6.7.2 Concatenation functions . 43
6.7.3 Search functions . 45
6.7.4 Miscellaneous functions . 47
6.8 Date and time . 49
6.8.1 Components of time . 49
6.8.2 Time conversion functions . 49
6.9 Extended multibyte and wide character utilities . 53
6.9.1 Formatted wide character input/output functions . 53
6.9.2 General wide string utilities . 64
© ISO/IEC 2007 – All rights reserved iii

6.9.3 Extended multibyte/wide character conversion utilities . 73
Bibliography . 78
Index . 79
iv © ISO/IEC 2007 – All rights reserved

Foreword
ISO (the International Organization for Standardization) and IEC (the International Electrotechnical
Commission) form the specialized system for worldwide standardization. National bodies that are members of
ISO or IEC participate in the development of International Standards through technical committees
established by the respective organization to deal with particular fields of technical activity. ISO and IEC
technical committees collaborate in fields of mutual interest. Other international organizations, governmental
and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information
technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.
International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.
The main task of the joint technical committee is to prepare International Standards. Draft International
Standards adopted by the joint technical committee are circulated to national bodies for voting. Publication as
an International Standard requires approval by at least 75 % of the national bodies casting a vote.
In exceptional circumstances, the joint technical committee may propose the publication of a Technical Report
of one of the following types:
— type 1, when the required support cannot be obtained for the publication of an International Standard,
despite repeated efforts;
— type 2, when the subject is still under technical development or where for any other reason there is the
future but not immediate possibility of an agreement on an International Standard;
— type 3, when the joint technical committee has collected data of a different kind from that which is normally
published as an International Standard (“state of the art”, for example).
Technical Reports of types 1 and 2 are subject to review within three years of publication, to decide whether
they can be transformed into International Standards. Technical Reports of type 3 do not necessarily have to
be reviewed until the data they provide are considered to be no longer valid or useful.
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent
rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights.
ISO/IEC TR 24731-1, which is a Technical Report of type 2, was prepared by Joint Technical Committee
ISO/IEC JTC 1, Information technology, Subcommittee SC 22, Programming languages, their environments
and system software interfaces.
ISO/IEC 24731 consists of the following part, under the general title Information technology —
Programming languages, their environments and system software interfaces — Extensions to the C library:
⎯ Part 1: Bounds-checking interfaces [Technical Report]

© ISO/IEC 2007 – All rights reserved v

Introduction
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.
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.
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.
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.
This Technical Report provides alternative functions for the C library that promote safer,
more secure programming. The 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.
This Technical Report also addresses another problem that complicates writing robust
code: functions that are not re-entrant 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.
vi © ISO/IEC 2007 – All rights reserved

TECHNICAL REPORT ISO/IEC TR 24731-1:2007(E)

Information technology — Programming languages, their
environments and system software interfaces —
Extensions to the C library —
Part 1:
Bounds-checking interfaces
1. Scope
This Technical Report specifies a series of extensions of the programming language C,
specified by International Standard ISO/IEC 9899:1999. These extensions can be useful
in the mitigation of security vulnerabilities in programs, and consist of a new predefined
macro, and new functions, macros, and types declared or defined in existing standard
headers.
International Standard ISO/IEC 9899:1999 provides important context and specification
for this Technical Report. Clauses 3 and 4 of this Technical Report are to be read as if
they were merged into Clauses 3 and 4 of ISO/IEC 9899:1999. Clause 5 of this Technical
Report is to be read as if it were merged into Subclause 6.10.8 of ISO/IEC 9899:1999.
Clause 6 of this Technical Report is to be read as if it were merged into the parallel
structure of named Subclauses of Clause 7 of ISO/IEC 9899:1999. Statements made in
ISO/IEC 9899:1999, whether about the language or library, apply to this Technical
Report unless a corresponding section of this Technical Report states otherwise. In
particular, Subclause 7.1.4 ("Use of library functions") of ISO/IEC 9899:1999 applies to
this Technical Report.
2. Normative references
The following referenced documents are indispensable for the application of this
document. For dated references, only the edition cited applies. For undated references,
the latest edition of the referenced document (including any amendments) applies.
ISO/IEC 9899:1999, Programming languages — C
ISO/IEC 9899:1999/Cor.1:2001, Programming languages — C — Technical Corrigendum 1
ISO/IEC 9899:1999/Cor.2:2004, Programming languages — C — Technical Corrigendum 2
ISO 31−11:1992, Quantities and units — Part 11: Mathematical signs and symbols for
use in the physical sciences and technology
ISO/IEC 2382−1:1993, Information technology — Vocabulary — Part 1: Fundamental
terms
©ISO/IEC 2007 — All rights reserved 1

3. Terms, definitions, and symbols
For the purposes of this document, the terms and definitions given in ISO/IEC 9899:1999,
ISO/IEC 2382−1, and the following apply. Other terms are defined where they appear in
italic type. Mathematical symbols not defined in this Technical Report are to be
interpreted according to ISO 31−11.
3.1
runtime-constraint
requirement on a program when calling a library function
NOTE 1 Despite the similar terms, a runtime-constraint is not a kind of constraint as defined by
ISO/IEC 9899:1999, Subclause 3.8, and need not be diagnosed at translation time.
NOTE 2 Implementations verify that the runtime-constraints for a library function are not violated by the
program. See Subclause 6.1.4.
4. Conformance
If a ‘‘shall’’ or ‘‘shall not’’ requirement that appears outside of a constraint or runtime-
constraint is violated, the behavior is undefined.
5. Predefined macronames
The following macro name is conditionally defined by the implementation:
__STDC_LIB_EXT1_ _The integer constant 200509L, intended to indicate
1)
conformance to this Technical Report.
1) The intention is that this will remain an integer constant of type long int that is increased with
each revision of this Technical Report.
2 ©ISO/IEC 2007 — All rights reserved

6. Library
6.1 Introduction
6.1.1 Standardheaders
The functions, macros, and types declared or defined in Clause 6 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 constant0 at the point in the source file
where the appropriate header is included.
The functions, macros, and types declared or defined in Clause 6 and its subclauses are
declared and defined by their respective headers if __STDC_WANT_LIB_EXT1_ _ is
defined as a macro which expands to the integer constant1 at the point in the source file
2)
where the appropriate header is included.
It is implementation-defined whether the functions, macros, and types declared or defined
in Clause 6 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
3)
where the appropriate header is included.
Within a preprocessing translation unit, __STDC_WANT_LIB_EXT1_ _ shall be
defined identically for all inclusions of any headers from Clause 6. If
__STDC_WANT_LIB_EXT1_ _ is defined differently for any such inclusion, the
implementation shall issue a diagnostic as if a preprocessor error directive was used.
2) Future revisions of this Technical Report may define meanings for other values of
__STDC_WANT_LIB_EXT1_ _.
3) Subclause 7.1.3 of ISO/IEC 9899:1999 reserves certain names and patterns of names that an
implementation may use in headers. All other names are not reserved, and a conforming
implementation may not use them. While some of the names defined in Clause 6 and its subclauses
are reserved, others are not. If an unreserved name is defined in a header when
__STDC_WANT_LIB_EXT1_ _ is not defined, then the implementation is not conforming.
©ISO/IEC 2007 — All rights reserved 3

6.1.2 Reservedidentifiers
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 ISO/IEC 9899:1999 Subclause 7.1.4).
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.
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.
6.1.3 Use of errno
An implementation may seterrno for the functions defined in this Technical Report, but
is not required to.
6.1.4 Runtime-constraintviolations
Most functions in this Technical Report include as part of their specification a list of
runtime-constraints. These runtime-constraints are requirements on the program using
4)
the library.
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 ). 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.
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.
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.
4) Although runtime-constraints replace many cases of undefined behavior from International Standard
ISO/IEC 9899:1999, undefined behavior still exists in this Technical Report. 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.
4 ©ISO/IEC 2007 — All rights reserved

6.2 Errors
The header defines a type.
The type is
errno_t
5)
which is typeint.
5) As a matter of programming style, errno_t may 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 might be declared as having the return typeerrno_t.
©ISO/IEC 2007 — All rights reserved 5

6.3 Commondefinitions
The header defines a type.
The type is
rsize_t
6)
which is the typesize_t.
6) See the description of theRSIZE_MAX macro in.
6 ©ISO/IEC 2007 — All rights reserved

6.4 Integertypes
The header defines a macro.
The macro is
RSIZE_MAX
7)
which expands to a value of type size_t. Functions that have parameters of type
rsize_t consider it a runtime-constraint violation if the values of those parameters are
greater thanRSIZE_MAX.
Recommended practice
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 likesize_t. Also, some implementations do not support
objects as large as the maximum value that can be represented by typesize_t.
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.
7) The macroRSIZE_MAX need not expand to a constant expression.
©ISO/IEC 2007 — All rights reserved 7

6.5 Input/output
The header defines several macros and two types.
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 thetmpnam_s function.
The types are
errno_t
which is typeint; and
rsize_t
which is the typesize_t.
6.5.1 Operationson files
6.5.1.1 Thetmpfile_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
errno_t tmpfile_s(FILE * restrict * restrict streamptr);
Runtime-constraints
streamptr shall not be a null pointer.
If there is a runtime-constraint violation,tmpfile_s does not attempt to create a file.
Description
Thetmpfile_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).
8 ©ISO/IEC 2007 — All rights reserved

If the file was created successfully, then the pointer toFILE pointed to bystreamptr
will be set to the pointer to the object controlling the opened file. Otherwise, the pointer
toFILE pointed to bystreamptr 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
Thetmpfile_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 non-zero value.
6.5.1.2 Thetmpnam_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
errno_t tmpnam_s(char *s, rsize_t maxsize);
Runtime-constraints
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
The tmpnam_s function generates a string that is a valid file name and that is not the
8)
The function is potentially capable of generating
same as the name of an existing file.
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 theL_tmpnam_s macro.
Thetmpnam_s function generates a different string each time it is called.
8) Files created using strings generated by thetmpnam_s function are temporary only in the sense that
their names should not collide with those generated by conventional naming rules for the
implementation. It is still necessary to use theremove function to remove such files when their use
is ended, and before program termination. Implementations should take care in choosing the patterns
used for names returned bytmpnam_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.
©ISO/IEC 2007 — All rights reserved 9

It is assumed thats points to an array of at leastmaxsize characters. This array will be
set to generated string, as specified below.
The implementation shall behave as if no library function except tmpnam calls the
9)
tmpnam_s function.
Recommended practice
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 oftmpnam_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.
Returns
If no suitable string can be generated, or if there is a runtime-constraint violation, the
tmpnam_s function writes a null character tos[0] (only ifs is not null andmaxsize
is greater than zero) and returns a non-zero value.
Otherwise, the tmpnam_s function writes the string in the array pointed to by s and
returns zero.
Environmental limits
The value of the macroTMP_MAX_S shall be at least 25.
6.5.2 Fileaccess functions
6.5.2.1 Thefopen_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
errno_t fopen_s(FILE * restrict * restrict streamptr,
const char * restrict filename,
const char * restrict mode);
Runtime-constraints
None ofstreamptr,filename,ormode shall be a null pointer.
9) An implementation may have tmpnam call tmpnam_s (perhaps so there is only one naming
convention for temporary files), but this is not required.
10 ©ISO/IEC 2007 — All rights reserved

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
The fopen_s function opens the file whose name is the string pointed to by
filename, and associates a stream with it.
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
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
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
ua+ append; open or create text file for update, writing at end-of-file, default
permissions
uw+b or uwb+ truncate to zero length or 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 permissions
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
10)
system default file access permissions.
If the file was opened successfully, then the pointer toFILE pointed to bystreamptr
will be set to the pointer to the object controlling the opened file. Otherwise, the pointer
toFILE pointed to bystreamptr will be set to a null pointer.
Returns
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 non-zero value.
10) These are the same permissions that the file would have been created with byfopen.
©ISO/IEC 2007 — All rights reserved 11

6.5.2.2 Thefreopen_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
errno_t freopen_s(FILE * restrict * restrict newstreamptr,
const char * restrict filename,
const char * restrict mode,
FILE * restrict stream);
Runtime-constraints
None ofnewstreamptr,mode, andstream shall be a null pointer.
If there is a runtime-constraint violation, freopen_s neither attempts to close any file
associated withstream nor attempts to open a file. Furthermore, ifnewstreamptr is
not a null pointer,fopen_s sets*newstreamptr to the null pointer.
Description
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 thefopen_s function (including the mode’s effect
on exclusive access and file permissions).
Iffilename is a null pointer, thefreopen_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.
Thefreopen_s function first attempts to close any file that is associated withstream.
Failure to close the file is ignored. The error and end-of-file indicators for the stream are
cleared.
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 bynewstreamptr will be set to a null pointer.
Returns
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 non-zero value.
12 ©ISO/IEC 2007 — All rights reserved

6.5.3 Formatted input/output functions
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.
6.5.3.1 Thefprintf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
int fprintf_s(FILE * restrict stream,
const char * restrict format, .);
Runtime-constraints
11)
(modified or
Neither stream nor format shall be a null pointer. The %n specifier
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.
12)
If there is a runtime-constraint violation, thefprintf_s function does not attempt to
produce further output, and it is unspecified to what extentfprintf_s produced output
before discovering the runtime-constraint violation.
Description
Thefprintf_s function is equivalent to thefprintf function except for the explicit
runtime-constraints listed above.
Returns
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.
11) It is not a runtime-constraint violation for the characters%n to appear in sequence in the string pointed
at byformat when those characters are not a interpreted as a%n specifier. For example, if the entire
format string was%%n.
12) Because an implementation may treat any undefined behavior as a runtime-constraint violation, an
implementation may treat any unsupported specifiers in the string pointed to byformat as a runtime-
constraint violation.
©ISO/IEC 2007 — All rights reserved 13

6.5.3.2 Thefscanf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
int fscanf_s(FILE * restrict stream,
const char * restrict format, .);
Runtime-constraints
Neitherstream norformat shall be a null pointer. Any argument indirected though in
order to store converted input shall not be a null pointer.
13)
the fscanf_s function does not attempt to
If there is a runtime-constraint violation,
perform further input, and it is unspecified to what extent fscanf_s performed input
before discovering the runtime-constraint violation.
Description
Thefscanf_s function is equivalent tofscanf except that thec,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
14)
one element.
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).
13) Because an implementation may treat any undefined behavior as a runtime-constraint violation, an
implementation may treat any unsupported specifiers in the string pointed to byformat as a runtime-
constraint violation.
14) If the format is known at translation time, an implementation may 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 withrsize_t. A limited amount of checking may be done if even if
the format is not known at translation time. For example, an implementation may 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 must follow the pointer argument. Another useful
diagnostic could flag any non-pointer argument following format that did not have a type
compatible withrsize_t.
14 ©ISO/IEC 2007 — All rights reserved

Returns
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.
EXAMPLE 1 The call:
#define __STDC_WANT_LIB_EXT1_ _1
#include
/* . */
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.
EXAMPLE 2 The call:
#define __STDC_WANT_LIB_EXT1_ _1
#include
/* . */
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.
6.5.3.3 Theprintf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
int printf_s(const char * restrict format, .);
Runtime-constraints
15)
format shall not be a null pointer. The %n specifier (modified or not by flags, field
width, or precision) shall not appear in the string pointed to by format. Any argument
toprintf_s corresponding to a%s specifier shall not be a null pointer.
15) It is not a runtime-constraint violation for the characters%n to appear in sequence in the string pointed
at byformat when those characters are not a interpreted as a%n specifier. For example, if the entire
format string was%%n.
©ISO/IEC 2007 — All rights reserved 15

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
The printf_s function is equivalent to the printf function except for the explicit
runtime-constraints listed above.
Returns
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.
6.5.3.4 Thescanf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
int scanf_s(const char * restrict format, .);
Runtime-constraints
format shall not be a null pointer. Any argument indirected though in order to store
converted input shall not be a null pointer.
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
The scanf_s function is equivalent to fscanf_s with the argument stdin
interposed before the arguments toscanf_s.
Returns
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.
16 ©ISO/IEC 2007 — All rights reserved

6.5.3.5 Thesnprintf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
int snprintf_s(char * restrict s, rsize_t n,
const char * restrict format, .);
Runtime-constraints
Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
16)
(modified or not by flags, field width, or
than RSIZE_MAX. The %n specifier
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.
If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
than zero and less than RSIZE_MAX, then the snprintf_s function sets s[0] to the
null character.
Description
The snprintf_s function is equivalent to the snprintf function except for the
explicit runtime-constraints listed above.
Thesnprintf_s function, unlikesprintf_s, will truncate the result to fit within the
array pointed to bys.
Returns
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 nonnegative and
less thann.
16) It is not a runtime-constraint violation for the characters%n to appear in sequence in the string pointed
at byformat when those characters are not a interpreted as a%n specifier. For example, if the entire
format string was%%n.
©ISO/IEC 2007 — All rights reserved 17

6.5.3.6 Thesprintf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
int sprintf_s(char * restrict s, rsize_t n,
const char * restrict format, .);
Runtime-constraints
Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
thanRSIZE_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
17)
(modified or not by flags, field width, or precision) shall not appear in the
specifier
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.
If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
than zero and less than RSIZE_MAX, then the sprintf_s function sets s[0] to the
null character.
Description
The sprintf_s function is equivalent to the sprintf function except for the
parametern and the explicit runtime-constraints listed above.
The sprintf_s function, unlike snprintf_s, treats a result too big for the array
pointed to bys as a runtime-constraint violation.
Returns
If no runtime-constraint violation occurred, thesprintf_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.
17) It is not a runtime-constraint violation for the characters%n to appear in sequence in the string pointed
at byformat when those characters are not a interpreted as a%n specifier. For example, if the entire
format string was%%n.
18 ©ISO/IEC 2007 — All rights reserved

6.5.3.7 Thesscanf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
int sscanf_s(const char * restrict s,
const char * restrict format, .);
Runtime-constraints
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.
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
Thesscanf_s function is equivalent tofscanf_s, except that input is obtained from
a string (specified by the arguments) 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
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.
6.5.3.8 Thevfprintf_s function
Synopsis
#define __STDC_WANT_LIB_EXT1_ _1
#include
#include
int vfprintf_s(FILE * restrict stream,
const char * restrict format,
va_list arg);
©ISO/IEC 2007 — All rights reserved 19

Runtime-constraints
18)
Neither stream nor format shall be a null pointer. The %n specifier (modified or
not by flags, field width, or precision) shall not appear in the string pointed to by
format. Any argument tovfprintf_s corresponding to a%s specifier shall not be a
null pointer.
If there is a runtime-constraint violation, thevfprintf_s function does not atte
...