The set of features available in the GNU C++ library is shaped by several GCC Command Options. Options that impact libstdc++ are enumerated and detailed in the table below. By default, g++ is equivalent to g++ -std=gnu++98. The standard library also defaults to this dialect. Option Flags Description -std=c++98 Use the 1998 ISO C++ standard plus amendments. -std=gnu++98 As directly above, with GNU extensions. -std=c++0x Use the working draft of the upcoming ISO C++0x standard. -std=gnu++0x As directly above, with GNU extensions. -fexceptions See exception-free dialect -frtti As above, but RTTI-free dialect. -pthread or -pthreads For ISO C++0x <thread>, <future>, <mutex>, or <condition_variable>. -fopenmp For parallel mode.

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 draft of the upcoming 200x standard. C++98/03 include files. These are available in the default compilation mode, i.e. -std=c++98 or -std=gnu++98. 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 cassert cerrno cctype cfloat ciso646 climits clocale cmath csetjmp csignal cstdarg cstddef cstdio cstdlib cstring ctime cwchar cwctype C++0x include files. These are only available in C++0x compilation mode, i.e. -std=c++0x or -std=gnu++0x. 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 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: 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 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))). decimal/decimal Also included are files for the C++ ABI interface: cxxabi.hcxxabi_forced.h And a large variety of extensions. 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 debug/bitset debug/deque debug/list debug/map debug/set debug/string debug/unordered_map debug/unordered_set debug/vector profile/bitset profile/deque profile/list profile/map profile/set profile/unordered_map profile/unordered_set profile/vector parallel/algorithm parallel/numeric

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++0x mode. To use the entities in <array>, the C++0x compilation mode must be used, which implies the C++0x 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++0x are still only enabled when in C++0x 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++0x compiler flag. (Or std=c++0x, of course.) A special case of the second rule is the mixing of TR1 and C++0x facilities. It is possible (although not especially prudent) to include both the TR1 version and the C++0x version of header in the same translation unit: #include <tr1/type_traits> #include <type_traits> Several parts of C++0x 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, and thus the Detailed information about creating precompiled header files can be found in the GCC documentation.

All library macros begin with _GLIBCXX_. Furthermore, all pre-processor macros, switches, and configuration options are gathered in the file c++config.h, which is generated during the libstdc++ configuration and build process. This file is then included when needed by files part of the public libstdc++ API, like <ios>. Most of these macros should not be used by consumers of libstdc++, and are reserved for internal implementation use. These macros cannot be redefined. A select handful of macros control libstdc++ extensions and extra features, or provide versioning information for the API. Only those macros listed below are offered for consideration by the general public. Below is the macro which users may check for library version information. __GLIBCXX__ The current version of libstdc++ in compressed ISO date format, form of an unsigned long. For details on the value of this particular macro for a particular release, please consult this document. Below are the macros which users may change with #define/#undef or with -D/-U compiler flags. The default state of the symbol is listed. Configurable (or Not configurable) means that the symbol is initially chosen (or not) based on --enable/--disable options at library build and configure time (documented here), with the various --enable/--disable choices being translated to #define/#undef). ABI means that changing from the default value may mean changing the ABI of compiled code. In other words, these choices control code which has already been compiled (i.e., in a binary such as libstdc++.a/.so). If you explicitly #define or #undef these macros, the headers may see different code paths, but the libraries which you link against will not. Experimenting with different values with the expectation of consistent linkage requires changing the config headers before building/installing the library. _GLIBCXX_USE_DEPRECATED Defined by default. Not configurable. ABI-changing. Turning this off removes older ARM-style iostreams code, and other anachronisms from the API. This macro is dependent on the version of the standard being tracked, and as a result may give different results for -std=c++98 and -std=c++0x. This may be useful in updating old C++ code which no longer meet the requirements of the language, or for checking current code against new language standards. _GLIBCXX_FORCE_NEW Undefined by default. When defined, memory allocation and allocators controlled by libstdc++ call operator new/delete without caching and pooling. Configurable via --enable-libstdcxx-allocator. ABI-changing. _GLIBCXX_CONCEPT_CHECKS Undefined by default. Configurable via --enable-concept-checks. When defined, performs compile-time checking on certain template instantiations to detect violations of the requirements of the standard. This is described in more detail here. _GLIBCXX_DEBUG Undefined by default. When defined, compiles user code using the debug mode. _GLIBCXX_DEBUG_PEDANTIC Undefined by default. When defined while compiling with the debug mode, makes the debug mode extremely picky by making the use of libstdc++ extensions and libstdc++-specific behavior into errors. _GLIBCXX_PARALLEL Undefined by default. When defined, compiles user code using the parallel mode. _GLIBCXX_PROFILE Undefined by default. When defined, compiles user code using the profile mode.

There are three main namespaces. std The ISO C++ standards specify that "all library entities are defined within namespace std." This includes namespaces nested within namespace std, such as namespace std::tr1. abi Specified by the C++ ABI. This ABI specifies a number of type and function APIs supplemental to those required by the ISO C++ Standard, but necessary for interoperability. __gnu_ Indicating one of several GNU extensions. Choices include __gnu_cxx, __gnu_debug, __gnu_parallel, and __gnu_pbds. A complete list of implementation namespaces (including namespace contents) is available in the generated source documentation.

One standard requirement is that the library components are defined in namespace std::. Thus, in order to use these types or functions, one must do one of two things: put a kind of using-declaration in your source (either using namespace std; or i.e. using std::string;) This approach works well for individual source files, but should not be used in a global context, like header files. use a fully qualified name for each library symbol (i.e. std::string, std::cout) Always can be used, and usually enhanced, by strategic use of typedefs. (In the cases where the qualified verbiage becomes unwieldy.)

Best practice in programming suggests sequestering new data or functionality in a sanely-named, unique namespace whenever possible. This is considered an advantage over dumping everything in the global namespace, as then name look-up can be explicitly enabled or disabled as above, symbols are consistently mangled without repetitive naming prefixes or macros, etc. For instance, consider a project that defines most of its classes in namespace gtk. It is possible to adapt namespace gtk to namespace std by using a C++-feature called namespace composition. This is what happens if a using-declaration is put into a namespace-definition: the imported symbol(s) gets imported into the currently active namespace(s). For example: namespace gtk { using std::string; using std::tr1::array; class Window { ... }; } In this example, std::string gets imported into namespace gtk. The result is that use of std::string inside namespace gtk can just use string, without the explicit qualification. As an added bonus, std::string does not get imported into the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the using-declarations can wrapped in macros that are set based on autoconf-tests to either "" or i.e. using std::string; (depending on whether the system has libstdc++ in std:: or not). (ideas from Llewelly and Karl Nelson)

Or as close as it gets: freestanding. This is a minimal configuration, with only partial support for the standard library. Assume only the following header files can be used: cstdarg cstddef cstdlib exception limits new exception typeinfo In addition, throw in cxxabi.h. In the C++0x dialect add initializer_list type_traits There exists a library that offers runtime support for just these headers, and it is called libsupc++.a. To use it, compile with gcc instead of g++, like so: gcc foo.cc -lsupc++ No attempt is made to verify that only the minimal subset identified above is actually used at compile time. Violations are diagnosed as undefined symbols at link time.

If the only library built is the static library (libstdc++.a), or if specifying static linking, this section is can be skipped. But if building or using a shared library (libstdc++.so), then additional location information will need to be provided. But how? A quick read of the relevant part of the GCC manual, Compiling C++ Programs, specifies linking against a C++ library. More details from the GCC FAQ, which states GCC does not, by default, specify a location so that the dynamic linker can find dynamic libraries at runtime. Users will have to provide this information. Methods vary for different platforms and different styles, and are printed to the screen during installation. To summarize: At runtime set LD_LIBRARY_PATH in your environment correctly, so that the shared library for libstdc++ can be found and loaded. Be certain that you understand all of the other implications and behavior of LD_LIBRARY_PATH first. Compile the path to find the library at runtime into the program. This can be done by passing certain options to g++, which will in turn pass them on to the linker. The exact format of the options is dependent on which linker you use: GNU ld (default on Linux): -Wl,-rpath,destdir/lib IRIX ld: -Wl,-rpath,destdir/lib Solaris ld: -Wl,-Rdestdir/lib Some linkers allow you to specify the path to the library by setting LD_RUN_PATH in your environment when linking. On some platforms the system administrator can configure the dynamic linker to always look for libraries in destdir/lib, for example by using the ldconfig utility on Linux or the crle utility on Solaris. This is a system-wide change which can make the system unusable so if you are unsure then use one of the other methods described above. Use the ldd utility on the linked executable to show which libstdc++.so library the system will get at runtime. A libstdc++.la file is also installed, for use with Libtool. If you use Libtool to create your executables, these details are taken care of for you.

This section discusses issues surrounding the proper compilation of multithreaded applications which use the Standard C++ library. This information is GCC-specific since the C++ standard does not address matters of multithreaded applications.

All normal disclaimers aside, multithreaded C++ application are only supported when libstdc++ and all user code was built with compilers which report (via gcc/g++ -v ) the same thread model and that model is not single. As long as your final application is actually single-threaded, then it should be safe to mix user code built with a thread model of single with a libstdc++ and other C++ libraries built with another thread model useful on the platform. Other mixes may or may not work but are not considered supported. (Thus, if you distribute a shared C++ library in binary form only, it may be best to compile it with a GCC configured with --enable-threads for maximal interchangeability and usefulness with a user population that may have built GCC with either --enable-threads or --disable-threads.) When you link a multithreaded application, you will probably need to add a library or flag to g++. This is a very non-standardized area of GCC across ports. Some ports support a special flag (the spelling isn't even standardized yet) to add all required macros to a compilation (if any such flags are required then you must provide the flag for all compilations not just linking) and link-library additions and/or replacements at link time. The documentation is weak. Here is a quick summary to display how ad hoc this is: On Solaris, both -pthreads and -threads (with subtly different meanings) are honored. On OSF, -pthread and -threads (with subtly different meanings) are honored. On Linux/i386, -pthread is honored. On FreeBSD, -pthread is honored. Some other ports use other switches. AFAIK, none of this is properly documented anywhere other than in ``gcc -dumpspecs'' (look at lib and cpp entries).

We currently use the SGI STL definition of thread safety. The library strives to be thread-safe when all of the following conditions are met: The system's libc is itself thread-safe, The compiler in use reports a thread model other than 'single'. This can be tested via output from gcc -v. Multi-thread capable versions of gcc output something like this: %gcc -v Using built-in specs. ... Thread model: posix gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) Look for "Thread model" lines that aren't equal to "single." Requisite command-line flags are used for atomic operations and threading. Examples of this include -pthread and -march=native, although specifics vary depending on the host environment. See Machine Dependent Options. An implementation of atomicity.h functions exists for the architecture in question. See the internals documentation for more details. The user-code must guard against concurrent method calls which may access any particular library object's state. Typically, the application programmer may infer what object locks must be held based on the objects referenced in a method call. Without getting into great detail, here is an example which requires user-level locks: library_class_a shared_object_a; thread_main () { library_class_b *object_b = new library_class_b; shared_object_a.add_b (object_b); // must hold lock for shared_object_a shared_object_a.mutate (); // must hold lock for shared_object_a } // Multiple copies of thread_main() are started in independent threads. Under the assumption that object_a and object_b are never exposed to another thread, here is an example that should not require any user-level locks: thread_main () { library_class_a object_a; library_class_b *object_b = new library_class_b; object_a.add_b (object_b); object_a.mutate (); } All library objects are safe to use in a multithreaded program as long as each thread carefully locks out access by any other thread while it uses any object visible to another thread, i.e., treat library objects like any other shared resource. In general, this requirement includes both read and write access to objects; unless otherwise documented as safe, do not assume that two threads may access a shared standard library object at the same time.

This gets a bit tricky. Please read carefully, and bear with me.

A wrapper type called __basic_file provides our abstraction layer for the std::filebuf classes. Nearly all decisions dealing with actual input and output must be made in __basic_file. A generic locking mechanism is somewhat in place at the filebuf layer, but is not used in the current code. Providing locking at any higher level is akin to providing locking within containers, and is not done for the same reasons (see the links above).

The __basic_file type is simply a collection of small wrappers around the C stdio layer (again, see the link under Structure). We do no locking ourselves, but simply pass through to calls to fopen, fwrite, and so forth. So, for 3.0, the question of "is multithreading safe for I/O" must be answered with, "is your platform's C library threadsafe for I/O?" Some are by default, some are not; many offer multiple implementations of the C library with varying tradeoffs of threadsafety and efficiency. You, the programmer, are always required to take care with multiple threads. (As an example, the POSIX standard requires that C stdio FILE* operations are atomic. POSIX-conforming C libraries (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize operations on FILE*s. However, you still need to not do stupid things like calling fclose(fs) in one thread followed by an access of fs in another.) So, if your platform's C library is threadsafe, then your fstream I/O operations will be threadsafe at the lowest level. For higher-level operations, such as manipulating the data contained in the stream formatting classes (e.g., setting up callbacks inside an std::ofstream), you need to guard such accesses like any other critical shared resource.

A second choice may be available for I/O implementations: libio. This is disabled by default, and in fact will not currently work due to other issues. It will be revisited, however. The libio code is a subset of the guts of the GNU libc (glibc) I/O implementation. When libio is in use, the __basic_file type is basically derived from FILE. (The real situation is more complex than that... it's derived from an internal type used to implement FILE. See libio/libioP.h to see scary things done with vtbls.) The result is that there is no "layer" of C stdio to go through; the filebuf makes calls directly into the same functions used to implement fread, fwrite, and so forth, using internal data structures. (And when I say "makes calls directly," I mean the function is literally replaced by a jump into an internal function. Fast but frightening. *grin*) Also, the libio internal locks are used. This requires pulling in large chunks of glibc, such as a pthreads implementation, and is one of the issues preventing widespread use of libio as the libstdc++ cstdio implementation. But we plan to make this work, at least as an option if not a future default. Platforms running a copy of glibc with a recent-enough version will see calls from libstdc++ directly into the glibc already installed. For other platforms, a copy of the libio subsection will be built and included in libstdc++.

Don't forget that other cstdio implementations are possible. You could easily write one to perform your own forms of locking, to solve your "interesting" problems.

This section discusses issues surrounding the design of multithreaded applications which use Standard C++ containers. All information in this section is current as of the gcc 3.0 release and all later point releases. Although earlier gcc releases had a different approach to threading configuration and proper compilation, the basic code design rules presented here were similar. For information on all other aspects of multithreading as it relates to libstdc++, including details on the proper compilation of threaded code (and compatibility between threaded and non-threaded code), see Chapter 17. Two excellent pages to read when working with the Standard C++ containers and threads are SGI's http://www.sgi.com/tech/stl/thread_safety.html and SGI's http://www.sgi.com/tech/stl/Allocators.html. However, please ignore all discussions about the user-level configuration of the lock implementation inside the STL container-memory allocator on those pages. For the sake of this discussion, libstdc++ configures the SGI STL implementation, not you. This is quite different from how gcc pre-3.0 worked. In particular, past advice was for people using g++ to explicitly define _PTHREADS or other macros or port-specific compilation options on the command line to get a thread-safe STL. This is no longer required for any port and should no longer be done unless you really know what you are doing and assume all responsibility. Since the container implementation of libstdc++ uses the SGI code, we use the same definition of thread safety as SGI when discussing design. A key point that beginners may miss is the fourth major paragraph of the first page mentioned above (For most clients...), which points out that locking must nearly always be done outside the container, by client code (that'd be you, not us). There is a notable exceptions to this rule. Allocators called while a container or element is constructed uses an internal lock obtained and released solely within libstdc++ code (in fact, this is the reason STL requires any knowledge of the thread configuration). For implementing a container which does its own locking, it is trivial to provide a wrapper class which obtains the lock (as SGI suggests), performs the container operation, and then releases the lock. This could be templatized to a certain extent, on the underlying container and/or a locking mechanism. Trying to provide a catch-all general template solution would probably be more trouble than it's worth. The library implementation may be configured to use the high-speed caching memory allocator, which complicates thread safety issues. For all details about how to globally override this at application run-time see here. Also useful are details on allocator options and capabilities.