16 Library introduction [library]

16.4 Library-wide requirements [requirements]

16.4.2 Library contents and organization [organization]

16.4.2.1 General [organization.general]

1
#
[contents] describes the entities and macros defined in the C++ standard library.
[headers] lists the standard library headers and some constraints on those headers.
[compliance] lists requirements for a freestanding implementation of the C++ standard library.

16.4.2.2 Library contents [contents]

1
#
The C++ standard library provides definitions for the entities and macros described in the synopses of the C++ standard library headers ([headers]), unless otherwise specified.
2
#
All library entities except operator new and operator delete are defined within the namespace std or namespaces nested within namespace std.167
It is unspecified whether names declared in a specific namespace are declared directly in that namespace or in an inline namespace inside that namespace.168
3
#
Whenever a name x defined in the standard library is mentioned, the name x is assumed to be fully qualified as ​::​std​::​x, unless explicitly described otherwise.
For example, if the Effects: element for library function F is described as calling library function G, the function ​::​std​::​G is meant.
167)
The C standard library headers ([depr.c.headers]) also define names within the global namespace, while the C++ headers for C library facilities ([headers]) can also define names within the global namespace.
 ⮥
168)
This gives implementers freedom to use inline namespaces to support multiple configurations of the library.
 ⮥

16.4.2.3 Headers [headers]

1
#
Each element of the C++ standard library is declared or defined (as appropriate) in a header.169
2
#
The C++ standard library provides the C++ library headers, shown in Table 21.
Table 21: C++ library headers [tab:headers.cpp]
<algorithm>
<forward_­list>
<numbers>
<string>
<any>
<fstream>
<numeric>
<string_­view>
<array>
<functional>
<optional>
<strstream>
<atomic>
<future>
<ostream>
<syncstream>
<barrier>
<initializer_­list>
<queue>
<system_­error>
<bit>
<iomanip>
<random>
<thread>
<bitset>
<ios>
<ranges>
<tuple>
<charconv>
<iosfwd>
<ratio>
<typeindex>
<chrono>
<iostream>
<regex>
<typeinfo>
<codecvt>
<istream>
<scoped_­allocator>
<type_­traits>
<compare>
<iterator>
<semaphore>
<unordered_­map>
<complex>
<latch>
<set>
<unordered_­set>
<concepts>
<limits>
<shared_­mutex>
<utility>
<condition_­variable>
<list>
<source_­location>
<valarray>
<coroutine>
<locale>
<span>
<variant>
<deque>
<map>
<sstream>
<vector>
<exception>
<memory>
<stack>
<version>
<execution>
<memory_­resource>
<stdexcept>
<filesystem>
<mutex>
<stop_­token>
<format>
<new>
<streambuf>
3
#
The facilities of the C standard library are provided in the additional headers shown in Table 22.170
Table 22: C++ headers for C library facilities [tab:headers.cpp.c]
<cassert>
<cfenv>
<climits>
<csetjmp>
<cstddef>
<cstdlib>
<cuchar>
<cctype>
<cfloat>
<clocale>
<csignal>
<cstdint>
<cstring>
<cwchar>
<cerrno>
<cinttypes>
<cmath>
<cstdarg>
<cstdio>
<ctime>
<cwctype>
4
#
The headers listed in Table 21, or, for a freestanding implementation, the subset of such headers that are provided by the implementation, are collectively known as the importable C++ library headers.
[Note 1:
Importable C++ library headers can be imported as module units ([module.import]).
— end note]
[Example 1: import <vector>; // imports the <vector> header unit std::vector<int> vi; // OK — end example]
5
#
Except as noted in [library] through [thread] and [depr], the contents of each header cname is the same as that of the corresponding header name.h as specified in the C standard library.
In the C++ standard library, however, the declarations (except for names which are defined as macros in C) are within namespace scope of the namespace std.
It is unspecified whether these names (including any overloads added in [support] through [thread] and [depr]) are first declared within the global namespace scope and are then injected into namespace std by explicit using-declarations ([namespace.udecl]).
6
#
Names which are defined as macros in C shall be defined as macros in the C++ standard library, even if C grants license for implementation as functions.
[Note 2:
The names defined as macros in C include the following: assert, offsetof, setjmp, va_­arg, va_­end, and va_­start.
— end note]
7
#
Names that are defined as functions in C shall be defined as functions in the C++ standard library.171
8
#
Identifiers that are keywords or operators in C++ shall not be defined as macros in C++ standard library headers.172
9
#
[depr.c.headers], C standard library headers, describes the effects of using the name.h (C header) form in a C++ program.173
10
#
Annex K of the C standard describes a large number of functions, with associated types and macros, which “promote safer, more secure programming” than many of the traditional C library functions.
The names of the functions have a suffix of _­s; most of them provide the same service as the C library function with the unsuffixed name, but generally take an additional argument whose value is the size of the result array.
If any C++ header is included, it is implementation-defined whether any of these names is declared in the global namespace.
(None of them is declared in namespace std.)
11
#
Table 23 lists the Annex K names that may be declared in some header.
These names are also subject to the restrictions of [macro.names].
Table 23: C standard Annex K names [tab:c.annex.k.names]
abort_­handler_­s
mbstowcs_­s
strncat_­s
vswscanf_­s
asctime_­s
memcpy_­s
strncpy_­s
vwprintf_­s
bsearch_­s
memmove_­s
strtok_­s
vwscanf_­s
constraint_­handler_­t
memset_­s
swprintf_­s
wcrtomb_­s
ctime_­s
printf_­s
swscanf_­s
wcscat_­s
errno_­t
qsort_­s
tmpfile_­s
wcscpy_­s
fopen_­s
RSIZE_­MAX
TMP_­MAX_­S
wcsncat_­s
fprintf_­s
rsize_­t
tmpnam_­s
wcsncpy_­s
freopen_­s
scanf_­s
vfprintf_­s
wcsnlen_­s
fscanf_­s
set_­constraint_­handler_­s
vfscanf_­s
wcsrtombs_­s
fwprintf_­s
snprintf_­s
vfwprintf_­s
wcstok_­s
fwscanf_­s
snwprintf_­s
vfwscanf_­s
wcstombs_­s
getenv_­s
sprintf_­s
vprintf_­s
wctomb_­s
gets_­s
sscanf_­s
vscanf_­s
wmemcpy_­s
gmtime_­s
strcat_­s
vsnprintf_­s
wmemmove_­s
ignore_­handler_­s
strcpy_­s
vsnwprintf_­s
wprintf_­s
localtime_­s
strerrorlen_­s
vsprintf_­s
wscanf_­s
L_­tmpnam_­s
strerror_­s
vsscanf_­s
mbsrtowcs_­s
strlen_­s
vswprintf_­s
169)
A header is not necessarily a source file, nor are the sequences delimited by < and > in header names necessarily valid source file names ([cpp.include]).
 ⮥
170)
It is intentional that there is no C++ header for any of these C headers: <stdatomic.h>, <stdnoreturn.h>, <threads.h>.
 ⮥
171)
This disallows the practice, allowed in C, of providing a masking macro in addition to the function prototype.
The only way to achieve equivalent inline behavior in C++ is to provide a definition as an extern inline function.
 ⮥
172)
In particular, including the standard header <iso646.h> has no effect.
 ⮥
173)
The ".h" headers dump all their names into the global namespace, whereas the newer forms keep their names in namespace std.
Therefore, the newer forms are the preferred forms for all uses except for C++ programs which are intended to be strictly compatible with C.
 ⮥

16.4.2.4 Freestanding implementations [compliance]

1
#
Two kinds of implementations are defined: hosted and freestanding ([intro.compliance]); the kind of the implementation is implementation-defined.
For a hosted implementation, this document describes the set of available headers.
2
#
A freestanding implementation has an implementation-defined set of headers.
This set shall include at least the headers shown in Table 24.
Table 24: C++ headers for freestanding implementations [tab:headers.cpp.fs]
Subclause
Header
Types
<cstddef>
Implementation properties
<cfloat>, <climits>, <limits>, <version>
Integer types
<cstdint>
Start and termination
<cstdlib>
Dynamic memory management
<new>
Type identification
<typeinfo>
Source location
<source_­location>
Exception handling
<exception>
Initializer lists
<initializer_­list>
Comparisons
<compare>
Coroutines support
<coroutine>
Other runtime support
<cstdarg>
Concepts library
<concepts>
Type traits
<type_­traits>
Bit manipulation
<bit>
Atomics
<atomic>
3
#
The supplied version of the header <cstdlib> shall declare at least the functions abort, atexit, at_­quick_­exit, exit, and quick_­exit ([support.start.term]).
The supplied version of the header <atomic> shall meet the same requirements as for a hosted implementation except that support for always lock-free integral atomic types ([atomics.lockfree]) is implementation-defined, and whether or not the type aliases atomic_­signed_­lock_­free and atomic_­unsigned_­lock_­free are defined ([atomics.alias]) is implementation-defined.
The other headers listed in this table shall meet the same requirements as for a hosted implementation.