The C++ standard specifies the entire set of header files that
must be available to all hosted implementations. Actually, the
word "files" is a misnomer, since the contents of the
headers don't necessarily have to be in any kind of external
file. The only rule is that when one #include's a
header, the contents of that header become available, no matter
how.
That said, in practice files are used.
There are two main types of include files: header files related to a specific version of the ISO C++ standard (called Standard Headers), and all others (TR1, C++ ABI, and Extensions).
Two dialects of standard headers are supported, corresponding to the 1998 standard as updated for 2003, and the current 2011 standard.
C++98/03 include files. These are available in the default compilation mode, i.e. -std=c++98 or -std=gnu++98.
Table 3.2. C++ 1998 Library Headers
algorithm | bitset | complex | deque | exception |
fstream | functional | iomanip | ios | iosfwd |
iostream | istream | iterator | limits | list |
locale | map | memory | new | numeric |
ostream | queue | set | sstream | stack |
stdexcept | streambuf | string | utility | typeinfo |
valarray | vector |
Table 3.3. C++ 1998 Library Headers for C Library Facilities
cassert | cerrno | cctype | cfloat | ciso646 |
climits | clocale | cmath | csetjmp | csignal |
cstdarg | cstddef | cstdio | cstdlib | cstring |
ctime | cwchar | cwctype |
C++11 include files. These are only available in C++11 compilation
mode, i.e. -std=c++11 or -std=gnu++11.
Table 3.4. C++ 2011 Library Headers
algorithm | array | bitset | chrono | complex |
condition_variable | deque | exception | forward_list | fstream |
functional | future | initalizer_list | iomanip | ios |
iosfwd | iostream | istream | iterator | limits |
list | locale | map | memory | mutex |
new | numeric | ostream | queue | random |
ratio | regex | set | sstream | stack |
stdexcept | streambuf | string | system_error | thread |
tuple | type_traits | typeinfo | unordered_map | unordered_set |
utility | valarray | vector |
Table 3.5. C++ 2011 Library Headers for C Library Facilities
cassert | ccomplex | cctype | cerrno | cfenv |
cfloat | cinttypes | ciso646 | climits | clocale |
cmath | csetjmp | csignal | cstdarg | cstdbool |
cstddef | cstdint | cstdlib | cstdio | cstring |
ctgmath | ctime | cuchar | cwchar | cwctype |
In addition, TR1 includes as:
Table 3.6. C++ TR 1 Library Headers
tr1/array | tr1/complex | tr1/memory | tr1/functional | tr1/random |
tr1/regex | tr1/tuple | tr1/type_traits | tr1/unordered_map | tr1/unordered_set |
tr1/utility |
Table 3.7. C++ TR 1 Library Headers for C Library Facilities
tr1/ccomplex | tr1/cfenv | tr1/cfloat | tr1/cmath | tr1/cinttypes |
tr1/climits | tr1/cstdarg | tr1/cstdbool | tr1/cstdint | tr1/cstdio |
tr1/cstdlib | tr1/ctgmath | tr1/ctime | tr1/cwchar | tr1/cwctype |
Decimal floating-point arithmetic is available if the C++
compiler supports scalar decimal floating-point types defined via
__attribute__((mode(SD|DD|LD))).
Also included are files for the C++ ABI interface:
And a large variety of extensions.
Table 3.10. Extension Headers
ext/algorithm | ext/atomicity.h | ext/array_allocator.h | ext/bitmap_allocator.h | ext/cast.h |
ext/codecvt_specializations.h | ext/concurrence.h | ext/debug_allocator.h | ext/enc_filebuf.h | ext/extptr_allocator.h |
ext/functional | ext/iterator | ext/malloc_allocator.h | ext/memory | ext/mt_allocator.h |
ext/new_allocator.h | ext/numeric | ext/numeric_traits.h | ext/pb_ds/assoc_container.h | ext/pb_ds/priority_queue.h |
ext/pod_char_traits.h | ext/pool_allocator.h | ext/rb_tree | ext/rope | ext/slist |
ext/stdio_filebuf.h | ext/stdio_sync_filebuf.h | ext/throw_allocator.h | ext/typelist.h | ext/type_traits.h |
ext/vstring.h |
Table 3.11. Extension Debug Headers
debug/bitset | debug/deque | debug/list | debug/map | debug/set |
debug/string | debug/unordered_map | debug/unordered_set | debug/vector |
Table 3.12. Extension Profile Headers
profile/bitset | profile/deque | profile/list | profile/map |
profile/set | profile/unordered_map | profile/unordered_set | profile/vector |
A few simple rules.
First, mixing different dialects of the standard headers is not possible. It's an all-or-nothing affair. Thus, code like
#include <array> #include <functional>
Implies C++11 mode. To use the entities in <array>, the C++11 compilation mode must be used, which implies the C++11 functionality (and deprecations) in <functional> will be present.
Second, the other headers can be included with either dialect of
the standard headers, although features and types specific to C++11
are still only enabled when in C++11 compilation mode. So, to use
rvalue references with __gnu_cxx::vstring, or to use the
debug-mode versions of std::unordered_map, one must use
the std=gnu++11 compiler flag. (Or std=c++11, of course.)
A special case of the second rule is the mixing of TR1 and C++11 facilities. It is possible (although not especially prudent) to include both the TR1 version and the C++11 version of header in the same translation unit:
#include <tr1/type_traits> #include <type_traits>
Several parts of C++11 diverge quite substantially from TR1 predecessors.
The standard specifies that if one includes the C-style header
(<math.h> in this case), the symbols will be available
in the global namespace and perhaps in
namespace std:: (but this is no longer a firm
requirement.) On the other hand, including the C++-style
header (<cmath>) guarantees that the entities will be
found in namespace std and perhaps in the global namespace.
Usage of C++-style headers is recommended, as then
C-linkage names can be disambiguated by explicit qualification, such
as by std::abort. In addition, the C++-style headers can
use function overloading to provide a simpler interface to certain
families of C-functions. For instance in <cmath>, the
function std::sin has overloads for all the builtin
floating-point types. This means that std::sin can be
used uniformly, instead of a combination
of std::sinf, std::sin,
and std::sinl.
There are three base header files that are provided. They can be used to precompile the standard headers and extensions into binary files that may the be used to speed compiles that use these headers.
stdc++.h
Includes all standard headers. Actual content varies depending on language dialect.
stdtr1c++.h
Includes all of <stdc++.h>, and adds all the TR1 headers.
extc++.h
Includes all of <stdtr1c++.h>, and adds all the Extension headers.
How to construct a .gch file from one of these base header files.
First, find the include directory for the compiler. One way to do this is:
g++ -v hello.cc #include <...> search starts here: /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0 ... End of search list.
Then, create a precompiled header file with the same flags that will be used to compile other projects.
g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h
The resulting file will be quite large: the current size is around thirty megabytes.
How to use the resulting file.
g++ -I. -include stdc++.h -H -g -O2 hello.cc
Verification that the PCH file is being used is easy:
g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe ! ./stdc++.h.gch . /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream . /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
The exclamation point to the left of the stdc++.h.gch listing means that the generated PCH file was used.
Detailed information about creating precompiled header files can be found in the GCC documentation.