16 Library introduction [library]

16.4 Library-wide requirements [requirements]

16.4.2 Library contents and organization [organization]

16.4.2.3 Headers [headers]

Each element of the C++ standard library is declared or defined (as appropriate) in a header.148
The C++ standard library provides the C++ library headers, shown in Table 24.
Table 24: C++ library headers [tab:headers.cpp]
<algorithm>
<forward_list>
<mutex>
<stacktrace>
<any>
<fstream>
<new>
<stdexcept>
<array>
<functional>
<numbers>
<stdfloat>
<atomic>
<future>
<numeric>
<stop_token>
<barrier>
<generator>
<optional>
<streambuf>
<bit>
<hazard_pointer>
<ostream>
<string>
<bitset>
<initializer_list>
<print>
<string_view>
<charconv>
<inplace_vector>
<queue>
<syncstream>
<chrono>
<iomanip>
<random>
<system_error>
<compare>
<ios>
<ranges>
<text_encoding>
<complex>
<iosfwd>
<ratio>
<thread>
<concepts>
<iostream>
<rcu>
<tuple>
<condition_variable>
<istream>
<regex>
<type_traits>
<coroutine>
<iterator>
<scoped_allocator>
<typeindex>
<debugging>
<latch>
<semaphore>
<typeinfo>
<deque>
<limits>
<set>
<unordered_map>
<exception>
<linalg>
<shared_mutex>
<unordered_set>
<execution>
<list>
<source_location>
<utility>
<expected>
<locale>
<span>
<valarray>
<filesystem>
<map>
<spanstream>
<variant>
<flat_map>
<mdspan>
<sstream>
<vector>
<flat_set>
<memory>
<stack>
<version>
<format>
<memory_resource>
The facilities of the C standard library are provided in the additional headers shown in Table 25.149
Table 25: 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>
The headers listed in Table 24, 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 ([module.import]).
β€” end note]
[Example 1: import <vector>; // imports the <vector> header unit std::vector<int> vi; // OK β€” end example]
Except as noted in [library] through [exec] 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 [exec] and [depr]) are first declared within the global namespace scope and are then injected into namespace std by explicit using-declarations ([namespace.udecl]).
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]
Names that are defined as functions in C shall be defined as functions in the C++ standard library.150
Identifiers that are keywords or operators in C++ shall not be defined as macros in C++ standard library headers.151
Subclause [support.c.headers] describes the effects of using the name.h (C header) form in a C++ program.152
ISO/IEC 9899:2018, Annex K 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.)
Table 26 lists the Annex K names that may be declared in some header.
These names are also subject to the restrictions of [macro.names].
Table 26: Names from ISO/IEC 9899:2018, Annex K [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
148)148)
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]).
149)149)
It is intentional that there is no C++ header for any of these C headers: <stdnoreturn.h>, <threads.h>.
150)150)
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.
151)151)
In particular, including the standard header <iso646.h> has no effect.
152)152)
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.