# C++ Library Overview

<head><title>C++ Library Overview</title></head>

# C++ Library Overview

* * *

**[Using C++ Library Headers](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#Using%20C++%20Library%20Headers)· [C++ Library Conventions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#C++%20Library%20Conventions)· [Iostreams Conventions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#iostreams)· [ProgramStartup and Termination](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#C++%20Program%20Startup%20and%20Termination)· [Exceptions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#Exceptions)**

All C++ library entities are declared or defined in one or more
[standard headers](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20headers).
To make use of a library entity in a program, write an
[*include* directive](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_preproc.html#include%20directive)
that names the relevant standard header.
The Standard C++ library consists of 51 required headers.
This [implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation) also includes
three additional headers, `<hash_map>`,
`<hash_set>`,
and `<slist>`, not required by the C++ Standard,
for a total of 54 headers.
These 54
**C++ library headers**
(along with the additional 18
[Standard C headers](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20headers))
constitute a
**hosted implementation**
of the C++ library:
`<algorithm>`,
`<bitset>`,
`<cassert>`,
`<cctype>`,
`<cerrno>`,
`<cfloat>`,
`<ciso646>`,
`<climits>`,
`<clocale>`,
`<cmath>`,
`<complex>`,
`<csetjmp>`,
`<csignal>`,
`<cstdarg>`,
`<cstddef>`,
`<cstdio>`,
`<cstdlib>`,
`<cstring>`,
`<ctime>`,
`<cwchar>`,
`<cwctype>`,
`<deque>`,
`<exception>`,
`<fstream>`,
`<functional>`,
`<hash_map>`,
`<hash_set>`,
`<iomanip>`,
`<ios>`,
`<iosfwd>`,
`<iostream>`,
`<istream>`,
`<iterator>`,
`<limits>`,
`<list>`,
`<locale>`,
`<map>`,
`<memory>`,
`<new>`,
`<numeric>`,
`<ostream>`,
`<queue>`,
`<set>`,
`<slist>`,
`<sstream>`,
`<stack>`,
`<stdexcept>`,
`<streambuf>`,
`<string>`,
`<strstream>`,
`<typeinfo>`,
`<utility>`,
`<valarray>`, and
`<vector>`.

A **freestanding implementation**
of the C++ library provides only a subset of these headers:
`<cstddef>`,
`<cstdlib>`
(declaring at least the functions
[`abort`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stdlib.html#abort),
[`atexit`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stdlib.html#atexit), and
[`exit`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stdlib.html#exit)),
`<exception>`,
`<limits>`,
`<new>`,
`<typeinfo>`, and
`<cstdarg>`.

The C++ library headers have two broader subdivisions,
[iostreams](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#iostreams) headers and
[STL](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#STL) headers.

## Using C++ Library Headers

You include the contents of a standard header by naming it in an
[*include* directive](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_preproc.html#include%20directive),
as in:

    #include <iostream>  /* include I/O facilities */Copy to clipboard

You can include the standard headers in any order, a standard
header more than once, or two or more standard headers that define
the same macro or the same type.
Do not include a standard header within a declaration. Do not
define macros that have the same names as keywords before you include
a standard header.

A C++ library header includes any other C++ library headers
it needs to define needed types. (Always include explicitly any
C++ library headers needed in a translation unit, however, lest
you guess wrong about its actual dependencies.) A Standard C header
never includes another standard header. A standard header declares
or defines only the entities described for it in this document.

Every function in the library is declared in a standard header.
Unlike in Standard C, the standard header never provides a
[masking macro](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#masking%20macro),
with the same name as the function, that masks the function
declaration and achieves the same effect.

All names other than `operator delete` and
`operator new` in the C++ library headers are defined in the
**`std`** namespace,
or in a namespace nested within the `std` namespace.
You refer to the name
`cin`, for example,
as `std::cin`. Note, however, that macro names are not subject to
namespace qualification, so you always write
`__STD_COMPLEX`
without a namespace qualifier.

In some translation environments, including a C++ library header
may hoist external names declared in the `std` namespace
into the global namespace as well, with individual *using*
declarations for each of the names. Otherwise, the header does
*not* introduce any library names into the current namespace.

The C++ Standard requires that the
[C Standard headers](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20headers) declare
all external names in namespace `std`, then hoist them into
the global namespace with individual *using* declarations
for each of the names.
But in some translation environments the C Standard headers
include no namespace declarations,
declaring all names directly in the global namespace.
Thus, the most portable way to deal with namespaces is to follow
two rules:

- To assuredly declare in namespace `std`
an external name that is traditionally declared
in `<stdlib.h>`, for example,
include the header `<cstdlib>`. Know that
the name might also be declared in the global namespace.
- To assuredly declare in the global namespace
an external name declared in `<stdlib.h>`,
include the header `<stdlib.h>` directly. Know that
the name might also be declared in namespace `std`.

Thus, if you want to call
`std::abort()`
to cause abnormal termination,
you should include `<cstdlib>`.
And if you want to call `abort()`,
you should include
`<stdlib.h>`.

Alternatively, you can write the declaration:

    using namespace std;Copy to clipboard

which assuredly hoists all library names into the current namespace.
If you write this declaration immediately after all *include*
directives, you hoist the names into the global namespace.
You can subsequently ignore namespace
considerations in the remainder of the translation unit.
You also avoid most dialect differences across different
translation environments.

Unless specifically indicated otherwise, you may not define names in
the `std` namespace, or in a namespace nested within the
`std` namespace.

## C++ Library Conventions

The C++ library obeys much the same
[conventions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20Library%20Conventions)
as the Standard C library, plus a few more outlined here.

An implementation has certain latitude in how it declares types
and functions in the C++ library:

- Names of functions in the Standard C library may have either
**`extern "C++"`** or
**`extern "C"`** linkage.
Include the appropriate
[Standard C header](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20headers)
rather than declare a library entity inline.
- A member function name in a library class may have additional
function signatures over those listed in this document. You can
be sure that a function call described here behaves as expected,
but you cannot reliably take the address of a library member function.
(The type may not be what you expect.)
- A library class may have undocumented (non-virtual) base classes.
A class documented as derived from another class may, in fact,
be derived from that class through other undocumented classes.
- A type defined as a synonym for some integer type may be the
same as one of several different integer types.
- A **bitmask type** can
be implemented as either an integer type or an enumeration.
In either case, you can perform bitwise operations (such as AND
and OR) on values of the same bitmask type. The *elements*
`A` and `B` of a bitmask type are nonzero
values such that `A & B` is zero.
- A library function that has no exception specification can
throw an arbitrary exception, unless its definition clearly
restricts such a possibility.

On the other hand, there are some restrictions you can count on:

- The Standard C library uses no
masking macros. Only specific function
signatures are reserved, not the names of the functions themselves.
- A library function name outside a class will *not* have
additional, undocumented, function signatures. You can reliably
take its address.
- Base classes and member functions described as virtual are
assuredly virtual, while those described as non-virtual are
assuredly non-virtual.
- Two types defined by the C++ library
are always different unless this document explicitly suggests
otherwise.
- Functions supplied by the library, including the default versions of
[replaceable functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions),
can throw *at most* those exceptions listed in any exception
specification.
No destructors supplied by the library throw exceptions.
Functions in the
[Standard C library](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Standard%20C%20Library)
may propagate an exception, as when
`qsort` calls a comparison
function that throws an exception, but they do not otherwise throw
exceptions.

## Iostreams Conventions

The **iostreams** headers support conversions
between text and encoded forms, and input and output to external
[files](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_file.html#files):
`<fstream>`,
`<iomanip>`,
`<ios>`,
`<iosfwd>`,
`<iostream>`,
`<istream>`,
`<ostream>`,
`<sstream>`,
`<streambuf>`, and
`<strstream>`.

The simplest use of iostreams requires only that you include
the header `<iostream>`. You can then extract values from
[`cin`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_iostream.html#cin), to read the
[standard input](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20input).
The rules for doing so are outlined in the description of the class
`basic_istream`.
You can also insert values to
[`cout`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_iostream.html#cout), to write the
[standard output](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20output).
The rules for doing so are outlined in the description of the class
`basic_ostream`.
Format control common to both extractors and insertors is managed
by the class `basic_ios`.
Manipulating this format information in the guise of extracting and
inserting objects is the province of several
[manipulators](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_iomanip.html).

You can perform the same iostreams operations on files that you
open by name, using the classes declared in
`<fstream>`.
To convert between iostreams and objects of class
`basic_string`,
use the classes declared in `<sstream>`.
And to do the same with [C strings](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string),
use the classes declared in `<strstream>`.

The remaining headers provide support services, typically of direct
interest to only the most advanced users of the iostreams classes.

## C++ Program Startup and Termination

A C++ program performs the same operations as does a C program
[program startup](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#program%20startup) and at
[program termination](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#program%20termination),
plus a few more outlined here.

Before the target environment calls the function
[`main`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#main), and after it stores
any constant initial values you specify in all objects that have
static duration, the program executes any remaining constructors
for such static objects. The order of execution is not specified
between translation units, but you can nevertheless assume that some
[iostreams](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#iostreams) objects are properly initialized
for use by these static constructors. These control
text streams:

- **[`cin`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_iostream.html#cin)** --
for [standard input](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20input)
- **[`cout`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_iostream.html#cout)** --
for [standard output](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20output)
- **[`cerr`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_iostream.html#cerr)** --
for unbuffered
[standard error](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20error) output
- **[`clog`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_iostream.html#clog)** --
for buffered
[standard error](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20error) output

You can also use these objects within the destructors called for
static objects, during
[program termination](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#program%20termination).

As with C, returning
from [`main`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#main) or calling
[`exit`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stdlib.html#exit)
calls all functions registered with
[`atexit`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stdlib.html#atexit)
in reverse order of registry.
An exception thrown from such a registered function calls
`terminate()`.

## Exceptions

In this [implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation),
exception handling can be either enabled or disabled.
This document describes all behavior as if exception handling is enabled.
If exception handling is disabled, however:

- Throw specifications in library function declarations
are not actually present.
- Catch clauses in library function definitions likewise are not
actually present. It is not possible for the program to catch an
exception, except in the limited sense outlined below. Hence, the
library has no occasion to rethrow an exception.
- Rather than throw an exception, as in `throw ex`, the library
actually calls `ex._Raise()`.

Here, `void _Raise()`
is a member function of class `exception`,
the base class for all exceptions thrown by the library. It performs the following
operations, in order:

1. If a **raise handler**
has been registered by an earlier call to the static member function
`exception::
_Set_raise_handler(void
(*)(const exception&)`, then `_Raise` calls the
raise handler.
2. `_Raise` then calls the protected virtual member function
`void _Doraise()`, which typically calls
`_Throw(*this)` in any class derived
from `exception`. (This ensures that the most derived version
of the virtual public member function `what` gets called
by `_Throw`, as outlined below.)
3. `_Raise` then calls `_Throw(*this)`.

The replaceable global function
`void _Throw(const exception& ex)`
never returns to its caller.
If the pointer returned by `ex.what()` is not a null pointer,
the function writes to the
[standard error](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#standard%20error) output stream
a diagnostic message that includes the
[null-terminated string](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_charset.html#null-terminated%20string)
designated by the pointer. In any event, the function then calls
`abort`.

The net effect of all this machinery is to supply several levels of control,
in lieu of the normal exception-handling machinery:

- You can dynamically specify a raise handler that is called whenever the
library would normally throw any exception
derived from class `exception`.
- You can override `_Doraise`, in a class you derive
from `exception`, to get control whenever an object of that
class would normally be thrown by the library (assuming that any raise handler
you register returns to its caller).
- You can define your own version of `_Throw`, to statically handle
termination on all thrown exceptions as you see fit.

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

[Previous Topic
Dinkum C++ Library](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/cpp_index.md) [Next Topic
C Library Overview](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/cpp_lib_over.md)