17 Library introduction [library]

17.5 Library-wide requirements [requirements]

17.5.1 Library contents and organization [organization]

17.5.1.2 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 61 C++ library headers, as shown in Table [tab:cpp.library.headers].

Table 16 — C++ library headers
<algorithm> <future> <numeric> <strstream>
<any> <initializer_list> <optional> <system_error>
<array> <iomanip> <ostream> <thread>
<atomic> <ios> <queue> <tuple>
<bitset> <iosfwd> <random> <type_traits>
<chrono> <iostream> <ratio> <typeindex>
<codecvt> <istream> <regex> <typeinfo>
<complex> <iterator> <scoped_allocator> <unordered_map>
<condition_variable> <limits> <set> <unordered_set>
<deque> <list> <shared_mutex> <utility>
<exception> <locale> <sstream> <valarray>
<execution> <map> <stack> <variant>
<filesystem> <memory> <stdexcept> <vector>
<forward_list> <memory_resource> <streambuf>
<fstream> <mutex> <string>
<functional> <new> <string_view>
3

The facilities of the C standard library are provided in 26 additional headers, as shown in Table [tab:cpp.c.headers].170

Table 17 — C++ headers for C library facilities
<cassert> <cinttypes> <csignal> <cstdio> <cwchar>
<ccomplex> <ciso646> <cstdalign> <cstdlib> <cwctype>
<cctype> <climits> <cstdarg> <cstring>
<cerrno> <clocale> <cstdbool> <ctgmath>
<cfenv> <cmath> <cstddef> <ctime>
<cfloat> <csetjmp> <cstdint> <cuchar>
4

Except as noted in Clauses [library] through [thread] and Annex [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 ([intro.refs]). In the C++ standard library, however, the declarations (except for names which are defined as macros in C) are within namespace scope ([basic.scope.namespace]) of the namespace std. It is unspecified whether these names (including any overloads added in Clauses [language.support] through [thread] and Annex [depr]) are first declared within the global namespace scope and are then injected into namespace std by explicit using-declarations ([namespace.udecl]).

5

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: The names defined as macros in C include the following: assert, offsetof, setjmp, va_arg, va_end, and va_start.  — end note ]

6

Names that are defined as functions in C shall be defined as functions in the C++ standard library.171

7

Identifiers that are keywords or operators in C++ shall not be defined as macros in C++ standard library headers.172

8

[depr.c.headers], C standard library headers, describes the effects of using the name.h (C header) form in a C++ program.173

9

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.)

10

Table [tab:c.annex.k.names] lists the Annex K names that may be declared in some header. These names are also subject to the restrictions of [macro.names].

Table 18 — C standard 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
L_tmpnam_s strerror_s vsprintf_s wscanf_s
localtime_s strerrorlen_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> or <ciso646> 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.