Headers
Prev | Chapter 3. Using | Next

## Headers

### Header Files

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 (TS, TR1, C++ ABI, and Extensions).

Multiple dialects of standard headers are supported, corresponding to the 1998 standard as updated for 2003, the 2011 standard, the 2014 standard, and so on.

Table 3.2, “C++ 1998 Library Headers” and Table 3.3, “C++ 1998 Library Headers for C Library Facilities” and Table 3.4, “C++ 1998 Deprecated Library Header” show the C++98/03 include files. These are available in the C++98 compilation mode, i.e. `-std=c++98` or `-std=gnu++98`. Unless specified otherwise below, they are also available in later modes (C++11, C++14 etc).

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` |

The following header is deprecated and might be removed from a future C++ standard.

Table 3.4. C++ 1998 Deprecated Library Header

`strstream`

Table 3.5, “C++ 2011 Library Headers” and Table 3.6, “C++ 2011 Library Headers for C Library Facilities” show the C++11 include files. These are available in C++11 compilation mode, i.e. `-std=c++11` or `-std=gnu++11`. Including these headers in C++98/03 mode may result in compilation errors. Unless specified otherwise below, they are also available in later modes (C++14 etc).

Table 3.5. C++ 2011 Library Headers

`array` | `atomic` | `chrono` | `codecvt` | `condition_variable`
`forward_list` | `future` | `initalizer_list` | `mutex` | `random`
`ratio` | `regex` | `scoped_allocator` | `system_error` | `thread`
`tuple` | `typeindex` | `type_traits` | `unordered_map` | `unordered_set`

Table 3.6. C++ 2011 Library Headers for C Library Facilities

`ccomplex` | `cfenv` | `cinttypes` | `cstdalign` | `cstdbool`
`cstdint` | `ctgmath` | `cuchar` |

Table 3.7, “C++ 2014 Library Header” shows the C++14 include file. This is available in C++14 compilation mode, i.e. `-std=c++14` or `-std=gnu++14`. Including this header in C++98/03 mode or C++11 will not result in compilation errors, but will not define anything. Unless specified otherwise below, it is also available in later modes (C++17 etc).

Table 3.7. C++ 2014 Library Header

`shared_mutex`

Table 3.8, “C++ 2017 Library Headers” shows the C++17 include files. These are available in C++17 compilation mode, i.e. `-std=c++17` or `-std=gnu++17`. Including these headers in earlier modes will not result in compilation errors, but will not define anything. Unless specified otherwise below, they are also available in later modes (C++20 etc).

Table 3.8. C++ 2017 Library Headers

`any` | `charconv` | `execution` | `filesystem` | `memory_resource`
`optional` | `string_view` | `variant` |

Table 3.9, “C++ 2020 Library Headers” shows the C++2a include files. These are available in C++2a compilation mode, i.e. `-std=c++2a` or `-std=gnu++2a`. Including these headers in earlier modes will not result in compilation errors, but will not define anything.

Table 3.9. C++ 2020 Library Headers

`bit` | `version`

The following headers have been removed in the C++2a working draft. They are still available when using this implementation, but in future they might start to produce warnings or errors when included in C++2a mode. Programs that intend to be portable should not include them.

Table 3.10. C++ 2020 Obsolete Headers

`ccomplex` | `ciso646` | `cstdalign` | `cstdbool` | `ctgmath`

Table 3.11, “File System TS Header”, shows the additional include file define by the File System Technical Specification, ISO/IEC TS 18822. This is available in C++11 and later compilation modes. Including this header in earlier modes will not result in compilation errors, but will not define anything.

Table 3.11. File System TS Header

`experimental/filesystem`

Table 3.12, “Library Fundamentals TS Headers”, shows the additional include files define by the C++ Extensions for Library Fundamentals Technical Specification, ISO/IEC TS 19568. These are available in C++14 and later compilation modes. Including these headers in earlier modes will not result in compilation errors, but will not define anything.

Table 3.12. Library Fundamentals TS Headers

`experimental/algorithm` | `experimental/any` | `experimental/array` | `experimental/chrono` | `experimental/deque`
`experimental/forward_list` | `experimental/functional` | `experimental/iterator` | `experimental/list` | `experimental/map`
`experimental/memory` | `experimental/memory_resource` | `experimental/numeric` | `experimental/optional` | `experimental/propagate_const`
`experimental/random` | `experimental/ratio` | `experimental/regex` | `experimental/set` | `experimental/source_location`
`experimental/string` | `experimental/string_view` | `experimental/system_error` | `experimental/tuple` | `experimental/type_traits`
`experimental/unordered_map` | `experimental/unordered_set` | `experimental/utility` | `experimental/vector` |

In addition, TR1 includes as:

Table 3.13. 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.14. 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)))`.

Table 3.15. C++ TR 24733 Decimal Floating-Point Header

`decimal/decimal`

Also included are files for the C++ ABI interface:

Table 3.16. C++ ABI Headers

`cxxabi.h` | `cxxabi_forced.h`

And a large variety of extensions.

Table 3.17. Extension Headers

`ext/algorithm` | `ext/atomicity.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.18. Extension Debug Headers

`debug/array` | `debug/bitset` | `debug/deque` | `debug/forward_list` | `debug/list`
`debug/map` | `debug/set` | `debug/string` | `debug/unordered_map` | `debug/unordered_set`
`debug/vector` |

Table 3.19. Extension Parallel Headers

`parallel/algorithm` | `parallel/numeric`

### Mixing Headers

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 C Headers and `namespace std`

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

### Precompiled Headers

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 then be used to speed up compilations 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 <stdc++.h>, and adds all the Extension headers (and in C++98 mode also adds all the TR1 headers by including all of <stdtr1c++.h>).

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.

Prev | Up | Next
Chapter 3. Using | Home | Macros