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
• Completion Date: 30-Oct-2013

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 TR 24731-1:2007(E)
©
ISO/IEC 2007

---------------------- Page: 1 ----------------------
ISO/IEC TR 24731-1:2007(E)
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.


COPYRIGHT PROTECTED DOCUMENT


©  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

---------------------- Page: 2 ----------------------
ISO/IEC TR 24731-1:2007(E)

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

---------------------- Page: 3 ----------------------
ISO/IEC TR 24731-1:2007(E)
6.9.3 Extended multibyte/wide character conversion utilities . 73
Bibliography . 78
Index . 79
iv © ISO/IEC 2007 – All rights reserved

---------------------- Page: 4 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 5 ----------------------
ISO/IEC TR 24731-1:2007(E)

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

---------------------- Page: 6 ----------------------
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

---------------------- Page: 7 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 8 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 9 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 10 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 11 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 12 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 13 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 14 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 15 ----------------------
ISO/IEC TR 24731-1:2007(E)
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

---------------------- Page: 16 ----------------------
ISO/IEC TR 24731-1:2007(E)
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
...