cppdraft_translate/cppdraft/headers.md

[headers]

16 Library introduction [library]

16.4 Library-wide requirements [requirements]

16.4.2 Library contents and organization [organization]

16.4.2.3 Headers [headers]

1

#

Each element of the C++ standard library is declared or defined (as appropriate) in aheader.144

2

#

The C++ standard library provides theC++ library headers, shown in Table 24.

Table 24 — C++ library headers [tab:headers.cpp]

🔗	<forward_list>
🔗
🔗
🔗
🔗			<stop_token>
🔗	<hazard_pointer>
🔗
🔗	<initializer_list>		<string_view>
🔗	<inplace_vector>
🔗			<system_error>
🔗			<text_encoding>
🔗
🔗 <condition_variable>
🔗			<type_traits>
🔗		<scoped_allocator>
🔗
🔗			<unordered_map>
🔗		<shared_mutex>	<unordered_set>
🔗
🔗		<source_location>
🔗
🔗 <flat_map>
🔗 <flat_set>
🔗	<memory_resource>

3

#

The facilities of the C standard library are provided in theadditional headers shown in Table 25.145

Table 25 — C++ headers for C library facilities [tab:headers.cpp.c]

🔗
🔗
🔗

4

#

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 ; // imports the header unit std::vector vi; // OK — end example]

5

#

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 withinnamespace 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 explicitusing-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.146

8

#

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

9

#

Subclause [support.c.headers] describes the effects of using the name.h (C header) form in a C++ program.148

10

#

ISO/IEC 9899:2024, 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.)

11

#

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:2024, 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

144)144)

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

145)145)

It is intentional that there is no C++ header for any of these C headers:<stdnoreturn.h>,<threads.h>.

146)146)

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.

147)147)

In particular, including the standard header <iso646.h> has no effect.

148)148)

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.