xml/manual/using.xml

<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
	 xml:id="manual.intro.using" xreflabel="Using">
  <info><title>Using</title></info>
  <?dbhtml filename="using.html"?>

  <section xml:id="manual.intro.using.flags" xreflabel="Flags"><info><title>Command Options</title></info>

    <para>
      The set of features available in the GNU C++ library is shaped by
      several <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc-4.3.2/gcc/Invoking-GCC.html">GCC
      Command Options</link>. Options that impact libstdc++ are
      enumerated and detailed in the table below.
    </para>

    <para>
      The standard library conforms to the dialect of C++ specified by the
      <option>-std</option> option passed to the compiler.
      By default, <command>g++</command> is equivalent to
      <command>g++ -std=gnu++98</command> for GCC 5 and older releases.
    </para>

 <table frame="all" xml:id="table.cmd_options">
<title>C++ Command Options</title>

<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>

  <thead>
    <row>
      <entry>Option Flags</entry>
      <entry>Description</entry>
    </row>
  </thead>

  <tbody>
    <row>
      <entry><literal>-std=c++98</literal> or <literal>-std=c++03</literal>
      </entry>
      <entry>Use the 1998 ISO C++ standard plus amendments.</entry>
    </row>

    <row>
      <entry><literal>-std=gnu++98</literal> or <literal>-std=gnu++03</literal>
      </entry>
      <entry>As directly above, with GNU extensions.</entry>
    </row>

    <row>
      <entry><literal>-std=c++11</literal></entry>
      <entry>Use the 2011 ISO C++ standard.</entry>
    </row>

    <row>
      <entry><literal>-std=gnu++11</literal></entry>
      <entry>As directly above, with GNU extensions.</entry>
    </row>

    <row>
      <entry><literal>-std=c++14</literal></entry>
      <entry>Use the 2014 ISO C++ standard.</entry>
    </row>

    <row>
      <entry><literal>-std=gnu++14</literal></entry>
      <entry>As directly above, with GNU extensions.</entry>
    </row>

    <row>
      <entry><literal>-fexceptions</literal></entry>
      <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry>
    </row>

    <row>
      <entry><literal>-frtti</literal></entry>
      <entry>As above, but RTTI-free dialect.</entry>
    </row>

    <row>
      <entry><literal>-pthread</literal> or <literal>-pthreads</literal></entry>
      <entry>For ISO C++11
        <filename class="headerfile">&lt;thread&gt;</filename>,
        <filename class="headerfile">&lt;future&gt;</filename>,
        <filename class="headerfile">&lt;mutex&gt;</filename>,
        or <filename class="headerfile">&lt;condition_variable&gt;</filename>.
      </entry>
    </row>

    <row>
      <entry><literal>-latomic</literal></entry>
      <entry>Linking to <filename class="libraryfile">libatomic</filename>
        is required for some uses of ISO C++11
        <filename class="headerfile">&lt;atomic&gt;</filename>.
      </entry>
    </row>

    <row>
      <entry><literal>-lstdc++fs</literal></entry>
      <entry>Linking to <filename class="libraryfile">libstdc++fs</filename>
        is required for use of the Filesystem library extensions in
        <filename class="headerfile">&lt;experimental/filesystem&gt;</filename>.
      </entry>
    </row>

    <row>
      <entry><literal>-fopenmp</literal></entry>
      <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
    </row>
  </tbody>

</tgroup>
</table>

  </section>

  <section xml:id="manual.intro.using.headers" xreflabel="Headers"><info><title>Headers</title></info>
    <?dbhtml filename="using_headers.html"?>


    <section xml:id="manual.intro.using.headers.all" xreflabel="Header Files"><info><title>Header Files</title></info>


   <para>
     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 <code>#include</code>'s a
     header, the contents of that header become available, no matter
     how.
   </para>

   <para>
   That said, in practice files are used.
   </para>

   <para>
     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).
   </para>

   <para>
     Two dialects of standard headers are supported, corresponding to
     the 1998 standard as updated for 2003, and the current 2011 standard.
   </para>

   <para>
     C++98/03 include files. These are available in the default compilation mode, i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>.
   </para>

<table frame="all" xml:id="table.cxx98_headers">
<title>C++ 1998 Library Headers</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>
<row>
<entry><filename class="headerfile">algorithm</filename></entry>
<entry><filename class="headerfile">bitset</filename></entry>
<entry><filename class="headerfile">complex</filename></entry>
<entry><filename class="headerfile">deque</filename></entry>
<entry><filename class="headerfile">exception</filename></entry>
</row>
<row>
<entry><filename class="headerfile">fstream</filename></entry>
<entry><filename class="headerfile">functional</filename></entry>
<entry><filename class="headerfile">iomanip</filename></entry>
<entry><filename class="headerfile">ios</filename></entry>
<entry><filename class="headerfile">iosfwd</filename></entry>
</row>
<row>
<entry><filename class="headerfile">iostream</filename></entry>
<entry><filename class="headerfile">istream</filename></entry>
<entry><filename class="headerfile">iterator</filename></entry>
<entry><filename class="headerfile">limits</filename></entry>
<entry><filename class="headerfile">list</filename></entry>
</row>
<row>
<entry><filename class="headerfile">locale</filename></entry>
<entry><filename class="headerfile">map</filename></entry>
<entry><filename class="headerfile">memory</filename></entry>
<entry><filename class="headerfile">new</filename></entry>
<entry><filename class="headerfile">numeric</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ostream</filename></entry>
<entry><filename class="headerfile">queue</filename></entry>
<entry><filename class="headerfile">set</filename></entry>
<entry><filename class="headerfile">sstream</filename></entry>
<entry><filename class="headerfile">stack</filename></entry>
</row>
<row>
<entry><filename class="headerfile">stdexcept</filename></entry>
<entry><filename class="headerfile">streambuf</filename></entry>
<entry><filename class="headerfile">string</filename></entry>
<entry><filename class="headerfile">utility</filename></entry>
<entry><filename class="headerfile">typeinfo</filename></entry>
</row>
<row>
<entry><filename class="headerfile">valarray</filename></entry>
<entry><filename class="headerfile">vector</filename></entry>
</row>
</tbody>
</tgroup>
</table>

<para/>
<table frame="all" xml:id="table.cxx98_cheaders">
<title>C++ 1998 Library Headers for C Library Facilities</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>
<row>
<entry><filename class="headerfile">cassert</filename></entry>
<entry><filename class="headerfile">cerrno</filename></entry>
<entry><filename class="headerfile">cctype</filename></entry>
<entry><filename class="headerfile">cfloat</filename></entry>
<entry><filename class="headerfile">ciso646</filename></entry>
</row>
<row>
<entry><filename class="headerfile">climits</filename></entry>
<entry><filename class="headerfile">clocale</filename></entry>
<entry><filename class="headerfile">cmath</filename></entry>
<entry><filename class="headerfile">csetjmp</filename></entry>
<entry><filename class="headerfile">csignal</filename></entry>
</row>
<row>
<entry><filename class="headerfile">cstdarg</filename></entry>
<entry><filename class="headerfile">cstddef</filename></entry>
<entry><filename class="headerfile">cstdio</filename></entry>
<entry><filename class="headerfile">cstdlib</filename></entry>
<entry><filename class="headerfile">cstring</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ctime</filename></entry>
<entry><filename class="headerfile">cwchar</filename></entry>
<entry><filename class="headerfile">cwctype</filename></entry>
</row>
</tbody>
</tgroup>
</table>

<para>
C++11 include files. These are only available in C++11 compilation
mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
</para>

<para/>
<table frame="all" xml:id="table.cxx11_headers">
<title>C++ 2011 Library Headers</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>

<row>
<entry><filename class="headerfile">algorithm</filename></entry>
<entry><filename class="headerfile">array</filename></entry>
<entry><filename class="headerfile">bitset</filename></entry>
<entry><filename class="headerfile">chrono</filename></entry>
<entry><filename class="headerfile">complex</filename></entry>
</row>
<row>
<entry><filename class="headerfile">condition_variable</filename></entry>
<entry><filename class="headerfile">deque</filename></entry>
<entry><filename class="headerfile">exception</filename></entry>
<entry><filename class="headerfile">forward_list</filename></entry>
<entry><filename class="headerfile">fstream</filename></entry>
</row>
<row>
<entry><filename class="headerfile">functional</filename></entry>
<entry><filename class="headerfile">future</filename></entry>
<entry><filename class="headerfile">initalizer_list</filename></entry>
<entry><filename class="headerfile">iomanip</filename></entry>
<entry><filename class="headerfile">ios</filename></entry>
</row>
<row>
<entry><filename class="headerfile">iosfwd</filename></entry>
<entry><filename class="headerfile">iostream</filename></entry>
<entry><filename class="headerfile">istream</filename></entry>
<entry><filename class="headerfile">iterator</filename></entry>
<entry><filename class="headerfile">limits</filename></entry>
</row>
<row>
<entry><filename class="headerfile">list</filename></entry>
<entry><filename class="headerfile">locale</filename></entry>
<entry><filename class="headerfile">map</filename></entry>
<entry><filename class="headerfile">memory</filename></entry>
<entry><filename class="headerfile">mutex</filename></entry>
</row>
<row>
<entry><filename class="headerfile">new</filename></entry>
<entry><filename class="headerfile">numeric</filename></entry>
<entry><filename class="headerfile">ostream</filename></entry>
<entry><filename class="headerfile">queue</filename></entry>
<entry><filename class="headerfile">random</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ratio</filename></entry>
<entry><filename class="headerfile">regex</filename></entry>
<entry><filename class="headerfile">set</filename></entry>
<entry><filename class="headerfile">sstream</filename></entry>
<entry><filename class="headerfile">stack</filename></entry>
</row>
<row>
<entry><filename class="headerfile">stdexcept</filename></entry>
<entry><filename class="headerfile">streambuf</filename></entry>
<entry><filename class="headerfile">string</filename></entry>
<entry><filename class="headerfile">system_error</filename></entry>
<entry><filename class="headerfile">thread</filename></entry>
</row>
<row>
<entry><filename class="headerfile">tuple</filename></entry>
<entry><filename class="headerfile">type_traits</filename></entry>
<entry><filename class="headerfile">typeinfo</filename></entry>
<entry><filename class="headerfile">unordered_map</filename></entry>
<entry><filename class="headerfile">unordered_set</filename></entry>
</row>
<row>
<entry><filename class="headerfile">utility</filename></entry>
<entry><filename class="headerfile">valarray</filename></entry>
<entry><filename class="headerfile">vector</filename></entry>
</row>

</tbody>
</tgroup>
</table>

<para/>

<table frame="all" xml:id="table.cxx11_cheaders">
<title>C++ 2011 Library Headers for C Library Facilities</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>
<row>
<entry><filename class="headerfile">cassert</filename></entry>
<entry><filename class="headerfile">ccomplex</filename></entry>
<entry><filename class="headerfile">cctype</filename></entry>
<entry><filename class="headerfile">cerrno</filename></entry>
<entry><filename class="headerfile">cfenv</filename></entry>
</row>
<row>
<entry><filename class="headerfile">cfloat</filename></entry>
<entry><filename class="headerfile">cinttypes</filename></entry>
<entry><filename class="headerfile">ciso646</filename></entry>
<entry><filename class="headerfile">climits</filename></entry>
<entry><filename class="headerfile">clocale</filename></entry>
</row>
<row>
<entry><filename class="headerfile">cmath</filename></entry>
<entry><filename class="headerfile">csetjmp</filename></entry>
<entry><filename class="headerfile">csignal</filename></entry>
<entry><filename class="headerfile">cstdarg</filename></entry>
<entry><filename class="headerfile">cstdbool</filename></entry>
</row>
<row>
<entry><filename class="headerfile">cstddef</filename></entry>
<entry><filename class="headerfile">cstdint</filename></entry>
<entry><filename class="headerfile">cstdlib</filename></entry>
<entry><filename class="headerfile">cstdio</filename></entry>
<entry><filename class="headerfile">cstring</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ctgmath</filename></entry>
<entry><filename class="headerfile">ctime</filename></entry>
<entry><filename class="headerfile">cuchar</filename></entry>
<entry><filename class="headerfile">cwchar</filename></entry>
<entry><filename class="headerfile">cwctype</filename></entry>
</row>
</tbody>
</tgroup>
</table>


<para>
  In addition, TR1 includes as:
</para>

<table frame="all" xml:id="table.tr1_headers">
<title>C++ TR 1 Library Headers</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>

<row>
<entry><filename class="headerfile">tr1/array</filename></entry>
<entry><filename class="headerfile">tr1/complex</filename></entry>
<entry><filename class="headerfile">tr1/memory</filename></entry>
<entry><filename class="headerfile">tr1/functional</filename></entry>
<entry><filename class="headerfile">tr1/random</filename></entry>
</row>
<row>
<entry><filename class="headerfile">tr1/regex</filename></entry>
<entry><filename class="headerfile">tr1/tuple</filename></entry>
<entry><filename class="headerfile">tr1/type_traits</filename></entry>
<entry><filename class="headerfile">tr1/unordered_map</filename></entry>
<entry><filename class="headerfile">tr1/unordered_set</filename></entry>
</row>
<row>
<entry><filename class="headerfile">tr1/utility</filename></entry>
</row>

</tbody>
</tgroup>
</table>

<para/>


<table frame="all" xml:id="table.tr1_cheaders">
<title>C++ TR 1 Library Headers for C Library Facilities</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>

<row>
<entry><filename class="headerfile">tr1/ccomplex</filename></entry>
<entry><filename class="headerfile">tr1/cfenv</filename></entry>
<entry><filename class="headerfile">tr1/cfloat</filename></entry>
<entry><filename class="headerfile">tr1/cmath</filename></entry>
<entry><filename class="headerfile">tr1/cinttypes</filename></entry>
</row>
<row>
<entry><filename class="headerfile">tr1/climits</filename></entry>
<entry><filename class="headerfile">tr1/cstdarg</filename></entry>
<entry><filename class="headerfile">tr1/cstdbool</filename></entry>
<entry><filename class="headerfile">tr1/cstdint</filename></entry>
<entry><filename class="headerfile">tr1/cstdio</filename></entry>
</row>
<row>
<entry><filename class="headerfile">tr1/cstdlib</filename></entry>
<entry><filename class="headerfile">tr1/ctgmath</filename></entry>
<entry><filename class="headerfile">tr1/ctime</filename></entry>
<entry><filename class="headerfile">tr1/cwchar</filename></entry>
<entry><filename class="headerfile">tr1/cwctype</filename></entry>
</row>

</tbody>
</tgroup>
</table>


<para>Decimal floating-point arithmetic is available if the C++
compiler supports scalar decimal floating-point types defined via
<code>__attribute__((mode(SD|DD|LD)))</code>.
</para>

<table frame="all" xml:id="table.decfp_headers">
<title>C++ TR 24733 Decimal Floating-Point Header</title>

<tgroup cols="1" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<tbody>
<row>
<entry><filename class="headerfile">decimal/decimal</filename></entry>
</row>
</tbody>
</tgroup>
</table>

<para>
  Also included are files for the C++ ABI interface:
</para>

<table frame="all" xml:id="table.abi_headers">
<title>C++ ABI Headers</title>

<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<tbody>
<row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row>
</tbody>
</tgroup>
</table>

<para>
  And a large variety of extensions.
</para>

<table frame="all" xml:id="table.ext_headers">
<title>Extension Headers</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>

<row>
<entry><filename class="headerfile">ext/algorithm</filename></entry>
<entry><filename class="headerfile">ext/atomicity.h</filename></entry>
<entry><filename class="headerfile">ext/array_allocator.h</filename></entry>
<entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry>
<entry><filename class="headerfile">ext/cast.h</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry>
<entry><filename class="headerfile">ext/concurrence.h</filename></entry>
<entry><filename class="headerfile">ext/debug_allocator.h</filename></entry>
<entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry>
<entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ext/functional</filename></entry>
<entry><filename class="headerfile">ext/iterator</filename></entry>
<entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry>
<entry><filename class="headerfile">ext/memory</filename></entry>
<entry><filename class="headerfile">ext/mt_allocator.h</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ext/new_allocator.h</filename></entry>
<entry><filename class="headerfile">ext/numeric</filename></entry>
<entry><filename class="headerfile">ext/numeric_traits.h</filename></entry>
<entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry>
<entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry>
<entry><filename class="headerfile">ext/pool_allocator.h</filename></entry>
<entry><filename class="headerfile">ext/rb_tree</filename></entry>
<entry><filename class="headerfile">ext/rope</filename></entry>
<entry><filename class="headerfile">ext/slist</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry>
<entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry>
<entry><filename class="headerfile">ext/throw_allocator.h</filename></entry>
<entry><filename class="headerfile">ext/typelist.h</filename></entry>
<entry><filename class="headerfile">ext/type_traits.h</filename></entry>
</row>
<row>
<entry><filename class="headerfile">ext/vstring.h</filename></entry>
</row>

</tbody>
</tgroup>
</table>

<para/>

<table frame="all" xml:id="table.debug_headers">
<title>Extension Debug Headers</title>

<tgroup cols="5" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<colspec colname="c5"/>
<tbody>

<row>
<entry><filename class="headerfile">debug/bitset</filename></entry>
<entry><filename class="headerfile">debug/deque</filename></entry>
<entry><filename class="headerfile">debug/list</filename></entry>
<entry><filename class="headerfile">debug/map</filename></entry>
<entry><filename class="headerfile">debug/set</filename></entry>
</row>

<row>
<entry><filename class="headerfile">debug/string</filename></entry>
<entry><filename class="headerfile">debug/unordered_map</filename></entry>
<entry><filename class="headerfile">debug/unordered_set</filename></entry>
<entry><filename class="headerfile">debug/vector</filename></entry>
</row>

</tbody>
</tgroup>
</table>

<para/>

<table frame="all" xml:id="table.profile_headers">
<title>Extension Profile Headers</title>

<tgroup cols="4" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<colspec colname="c4"/>
<tbody>

<row>
<entry><filename class="headerfile">profile/bitset</filename></entry>
<entry><filename class="headerfile">profile/deque</filename></entry>
<entry><filename class="headerfile">profile/list</filename></entry>
<entry><filename class="headerfile">profile/map</filename></entry>
</row>

<row>
<entry><filename class="headerfile">profile/set</filename></entry>
<entry><filename class="headerfile">profile/unordered_map</filename></entry>
<entry><filename class="headerfile">profile/unordered_set</filename></entry>
<entry><filename class="headerfile">profile/vector</filename></entry>
</row>

</tbody>
</tgroup>
</table>

<para/>

<table frame="all" xml:id="table.parallel_headers">
<title>Extension Parallel Headers</title>

<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<tbody>
<row>
<entry><filename class="headerfile">parallel/algorithm</filename></entry>
<entry><filename class="headerfile">parallel/numeric</filename></entry>
</row>
</tbody>
</tgroup>
</table>

    </section>

    <section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info>


<para> A few simple rules.
</para>

<para>First, mixing different dialects of the standard headers is not
possible. It's an all-or-nothing affair. Thus, code like
</para>

<programlisting>
#include &lt;array&gt;
#include &lt;functional&gt;
</programlisting>

<para>Implies C++11 mode. To use the entities in &lt;array&gt;, the C++11
compilation mode must be used, which implies the C++11 functionality
(and deprecations) in &lt;functional&gt; will be present.
</para>

<para>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 <code>__gnu_cxx::vstring</code>, or to use the
debug-mode versions of <code>std::unordered_map</code>, one must use
the <code>std=gnu++11</code> compiler flag. (Or <code>std=c++11</code>, of course.)
</para>

<para>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:
</para>

<programlisting>
#include &lt;tr1/type_traits&gt;
#include &lt;type_traits&gt;
</programlisting>

<para> Several parts of C++11 diverge quite substantially from TR1 predecessors.
</para>
    </section>

    <section xml:id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"><info><title>The C Headers and <code>namespace std</code></title></info>


<para>
	The standard specifies that if one includes the C-style header
	(&lt;math.h&gt; in this case), the symbols will be available
	in the global namespace and perhaps in
	namespace <code>std::</code> (but this is no longer a firm
	requirement.) On the other hand, including the C++-style
	header (&lt;cmath&gt;) guarantees that the entities will be
	found in namespace std and perhaps in the global namespace.
      </para>

<para>
Usage of C++-style headers is recommended, as then
C-linkage names can be disambiguated by explicit qualification, such
as by <code>std::abort</code>. In addition, the C++-style headers can
use function overloading to provide a simpler interface to certain
families of C-functions. For instance in &lt;cmath&gt;, the
function <code>std::sin</code> has overloads for all the builtin
floating-point types. This means that <code>std::sin</code> can be
used uniformly, instead of a combination
of <code>std::sinf</code>, <code>std::sin</code>,
and <code>std::sinl</code>.
</para>
    </section>

    <section xml:id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"><info><title>Precompiled Headers</title></info>


<para>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.
</para>


<itemizedlist>
<listitem>
  <para>stdc++.h</para>
<para>Includes all standard headers. Actual content varies depending on
<link linkend="manual.intro.using.flags">language dialect</link>.
</para>
</listitem>

<listitem>
  <para>stdtr1c++.h</para>
<para>Includes all of &lt;stdc++.h&gt;, and adds all the TR1 headers.
</para>
</listitem>

<listitem><para>extc++.h</para>
<para>Includes all of the Extension headers
(and in C++98 mode also adds all the TR1 headers by including all of
&lt;stdtr1c++.h&gt;).
</para></listitem>
</itemizedlist>

<para>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:</para>

<programlisting>
g++ -v hello.cc

#include &lt;...&gt; search starts here:
 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
...
End of search list.
</programlisting>


<para>Then, create a precompiled header file with the same flags that
will be used to compile other projects.</para>

<programlisting>
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
</programlisting>

<para>The resulting file will be quite large: the current size is around
thirty megabytes. </para>

<para>How to use the resulting file.</para>

<programlisting>
g++ -I. -include stdc++.h  -H -g -O2 hello.cc
</programlisting>

<para>Verification that the PCH file is being used is easy:</para>

<programlisting>
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
</programlisting>

<para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used.</para>
<para/>

<para> Detailed information about creating precompiled header files can be found in the GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</link>.
</para>

    </section>
  </section>


  <section xml:id="manual.intro.using.macros" xreflabel="Macros"><info><title>Macros</title></info>
    <?dbhtml filename="using_macros.html"?>


   <para>
     All library macros begin with <code>_GLIBCXX_</code>.
   </para>

   <para>
     Furthermore, all pre-processor macros, switches, and
      configuration options are gathered in the
      file <filename class="headerfile">c++config.h</filename>, 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
      <filename class="headerfile">&lt;ios&gt;</filename>. Most of these
      macros should not be used by consumers of libstdc++, and are reserved
      for internal implementation use. <emphasis>These macros cannot
      be redefined</emphasis>.
   </para>

   <para>
     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.
   </para>

   <para>Below is the macro which users may check for library version
      information. </para>

    <variablelist>
    <varlistentry>
      <term><code>__GLIBCXX__</code></term>
      <listitem>
	<para>The current version of
    libstdc++ in compressed ISO date format, as an unsigned
    long. For details on the value of this particular macro for a
    particular release, please consult the <link linkend="appendix.porting.abi">
    ABI Policy and Guidelines</link> appendix.
    </para>
    </listitem>
    </varlistentry>
    </variablelist>

   <para>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.</para>

   <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
      that the symbol is initially chosen (or not) based on
      --enable/--disable options at library build and configure time
      (documented in
      <link linkend="manual.intro.setup.configure">Configure</link>),
      with the various --enable/--disable choices being translated to
      #define/#undef).
   </para>

   <para> <acronym>ABI</acronym> means that changing from the default value may
  mean changing the <acronym>ABI</acronym> 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 <emphasis>headers</emphasis> may see different code
  paths, but the <emphasis>libraries</emphasis> 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.
   </para>

    <variablelist>
    <varlistentry><term><code>_GLIBCXX_USE_DEPRECATED</code></term>
    <listitem>
      <para>
	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
	<code>-std=c++98</code> and <code>-std=c++11</code>. 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.
    </para>
    </listitem></varlistentry>

    <varlistentry><term><code>_GLIBCXX_USE_CXX11_ABI</code></term>
    <listitem>
      <para>
        Defined to the value <literal>1</literal> by default.
        Configurable via  <code>--disable-libstdcxx-dual-abi</code>
        and/or <code>--with-default-libstdcxx-abi</code>.
        ABI-changing.
        When defined to a non-zero value the library headers will use the
        new C++11-conforming ABI introduced in GCC 5, rather than the older
        ABI introduced in GCC 3.4. This changes the definition of several
        class templates, including <classname>std:string</classname>,
        <classname>std::list</classname> and some locale facets.
        For more details see <xref linkend="manual.intro.using.abi"/>.
    </para>
    </listitem></varlistentry>

    <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
    <listitem>
      <para>
	Undefined by default.  Configurable via
	<code>--enable-concept-checks</code>.  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 in
	<link linkend="manual.ext.compile_checks">Compile Time Checks</link>.
      </para>
    </listitem></varlistentry>

    <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
    <listitem>
      <para>
	Undefined by default. When defined, compiles user code using
	the <link linkend="manual.ext.debug_mode">debug mode</link>.
      </para>
    </listitem></varlistentry>
    <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
    <listitem>
      <para>
	Undefined by default. When defined while compiling with
	the <link linkend="manual.ext.debug_mode">debug mode</link>, makes
	the debug mode extremely picky by making the use of libstdc++
	extensions and libstdc++-specific behavior into errors.
      </para>
    </listitem></varlistentry>
    <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
    <listitem>
      <para>Undefined by default. When defined, compiles user code
	using the <link linkend="manual.ext.parallel_mode">parallel
	mode</link>.
      </para>
    </listitem></varlistentry>

    <varlistentry><term><code>_GLIBCXX_PROFILE</code></term>
    <listitem>
      <para>Undefined by default. When defined, compiles user code
	using the <link linkend="manual.ext.profile_mode">profile
	mode</link>.
      </para>
    </listitem></varlistentry>
    </variablelist>

  </section>

<section xml:id="manual.intro.using.abi" xreflabel="Dual ABI">
  <info><title>Dual ABI</title></info>
  <?dbhtml filename="using_dual_abi.html"?>

<para> In the GCC 5.1 release libstdc++ introduced a new library ABI that
  includes new implementations of <classname>std::string</classname> and
  <classname>std::list</classname>. These changes were necessary to conform
  to the 2011 C++ standard which forbids Copy-On-Write strings and requires
  lists to keep track of their size.
</para>

<para> In order to maintain backwards compatibility for existing code linked
  to libstdc++ the library's soname has not changed and the old
  implementations are still supported in parallel with the new ones.
  This is achieved by defining the new implementations in an inline namespace
  so they have different names for linkage purposes, e.g. the new version of
  <classname>std::list&lt;int&gt;</classname> is actually defined as
  <classname>std::__cxx11::list&lt;int&gt;</classname>. Because the symbols
  for the new implementations have different names the definitions for both
  versions can be present in the same library.
</para>

<para> The <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro (see
<xref linkend="manual.intro.using.macros"/>) controls whether
  the declarations in the library headers use the old or new ABI.
  So the decision of which ABI to use can be made separately for each
  source file being compiled.
  Using the default configuration options for GCC the default value
  of the macro is <literal>1</literal> which causes the new ABI to be active,
  so to use the old ABI you must explicitly define the macro to
  <literal>0</literal> before including any library headers.
  (Be aware that some GNU/Linux distributions configure GCC 5 differently so
  that the default value of the macro is <literal>0</literal> and users must
  define it to <literal>1</literal> to enable the new ABI.)
</para>

<para> Although the changes were made for C++11 conformance, the choice of ABI
  to use is independent of the <option>-std</option> option used to compile
  your code, i.e. for a given GCC build the default value of the
  <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro is the same for all dialects.
  This ensures that the <option>-std</option> does not change the ABI, so
  that it is straightforward to link C++03 and C++11 code together.
</para>

<para> Because <classname>std::string</classname> is used extensively
  throughout the library a number of other types are also defined twice,
  including the stringstream classes and several facets used by
  <classname>std::locale</classname>. The standard facets which are always
  installed in a locale may be present twice, with both ABIs, to ensure that
  code like
  <code>std::use_facet&lt;std::time_get&lt;char&gt;&gt;(locale);</code>
  will work correctly for both <classname>std::time_get</classname> and
  <classname>std::__cxx11::time_get</classname> (even if a user-defined
  facet that derives from one or other version of
  <classname>time_get</classname> is installed in the locale).
</para>

<para> Although the standard exception types defined in
  <filename class="headerfile">&lt;stdexcept&gt;</filename> use strings, they
  are not defined twice, so that a <classname>std::out_of_range</classname>
  exception thrown in one file can always be caught by a suitable handler in
  another file, even if the two files are compiled with different ABIs.
</para>

<section xml:id="manual.intro.using.abi.trouble" xreflabel="Dual ABI Troubleshooting"><info><title>Troubleshooting</title></info>

<para> If you get linker errors about undefined references to symbols
  that involve types in the <code>std::__cxx11</code> namespace or the tag
  <code>[abi:cxx11]</code> then it probably indicates that you are trying to
  link together object files that were compiled with different values for the
  <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro. This commonly happens when
  linking to a third-party library that was compiled with an older version
  of GCC. If the third-party library cannot be rebuilt with the new ABI then
  you will need to recompile your code with the old ABI.
</para>

<para> Not all uses of the new ABI will cause changes in symbol names, for
  example a class with a <classname>std::string</classname> member variable
  will have the same mangled name whether compiled with the old or new ABI.
  In order to detect such problems the new types and functions are
  annotated with the <property>abi_tag</property> attribute, allowing the
  compiler to warn about potential ABI incompatibilities in code using them.
  Those warnings can be enabled with the <option>-Wabi-tag</option> option.
</para>

</section>
</section>

  <section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
    <?dbhtml filename="using_namespaces.html"?>


    <section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info>


<para> There are three main namespaces.
</para>

<itemizedlist>
  <listitem><para>std</para>
<para>The ISO C++ standards specify that "all library entities are defined
within namespace std." This includes namespaces nested
within namespace <code>std</code>, such as namespace
<code>std::chrono</code>.
</para>
</listitem>
<listitem><para>abi</para>
<para>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.
</para>
</listitem>

<listitem><para>__gnu_</para>
<para>Indicating one of several GNU extensions. Choices
include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
and <code>__gnu_pbds</code>.
</para></listitem>
</itemizedlist>

<para> The library uses a number of inline namespaces as implementation
details that are not intended for users to refer to directly, these include
<code>std::__detail</code>, <code>std::__cxx11</code> and <code>std::_V2</code>.
</para>

<para> A complete list of implementation namespaces (including namespace contents) is available in the generated source <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</link>.
</para>


    </section>

    <section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info>


<para>
      One standard requirement is that the library components are defined
      in <code>namespace std::</code>. Thus, in order to use these types or
      functions, one must do one of two things:
</para>

<itemizedlist>
  <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source
(either <code>using namespace std;</code> or i.e. <code>using
std::string;</code>) This approach works well for individual source files, but
should not be used in a global context, like header files.
	  </para></listitem> <listitem><para>use a <emphasis>fully
qualified name</emphasis> for each library symbol
(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
used, and usually enhanced, by strategic use of typedefs. (In the
cases where the qualified verbiage becomes unwieldy.)
	  </para>
	</listitem>
</itemizedlist>

    </section>

    <section xml:id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"><info><title>Using Namespace Composition</title></info>


<para>
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.
</para>

<para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
	adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
	<emphasis>namespace composition</emphasis>. This is what happens if
	a <emphasis>using</emphasis>-declaration is put into a
	namespace-definition: the imported symbol(s) gets imported into the
	currently active namespace(s). For example:
</para>
<programlisting>
namespace gtk
{
  using std::string;
  using std::tr1::array;

  class Window { ... };
}
</programlisting>
<para>
	In this example, <code>std::string</code> gets imported into
	<code>namespace gtk</code>.  The result is that use of
	<code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
	As an added bonus,
	<code>std::string</code> does not get imported into
	the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
	<code>using</code>-declarations can wrapped in macros that
	are set based on autoconf-tests to either "" or i.e. <code>using
	  std::string;</code> (depending on whether the system has
	libstdc++ in <code>std::</code> or not).  (ideas from
	Llewelly and Karl Nelson)
</para>


    </section>
  </section>

  <section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info>
    <?dbhtml filename="using_dynamic_or_shared.html"?>


    <section xml:id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"><info><title>Almost Nothing</title></info>

      <para>
	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:
      </para>

      <itemizedlist>
	<listitem>
	  <para>
	    <filename class="headerfile">cstdarg</filename>
	  </para>
	</listitem>

	<listitem>
	  <para>
	  <filename class="headerfile">cstddef</filename>
	  </para>
	</listitem>

	<listitem>
	  <para>
	  <filename class="headerfile">cstdlib</filename>
	  </para>
	</listitem>

	<listitem>
	  <para>
	  <filename class="headerfile">exception</filename>
	  </para>
	</listitem>

	<listitem>
	  <para>
	  <filename class="headerfile">limits</filename>
	  </para>
	</listitem>

	<listitem>
	  <para>
	  <filename class="headerfile">new</filename>
	  </para>
	</listitem>

	<listitem>
	  <para>
	  <filename class="headerfile">exception</filename>
	  </para>
	</listitem>

	<listitem>
	  <para>
	  <filename class="headerfile">typeinfo</filename>
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	In addition, throw in
      </para>

      <itemizedlist>
	<listitem>
	  <para>
	  <filename class="headerfile">cxxabi.h</filename>.
	  </para>
	</listitem>
      </itemizedlist>

      <para>
	In the
	C++11 <link linkend="manual.intro.using.flags">dialect</link> add
      </para>

      <itemizedlist>
	<listitem>
	  <para>
	  <filename class="headerfile">initializer_list</filename>
	  </para>
	</listitem>
	<listitem>
	  <para>
	  <filename class="headerfile">type_traits</filename>
	  </para>
	</listitem>
      </itemizedlist>

      <para> There exists a library that offers runtime support for
	just these headers, and it is called
	<filename class="libraryfile">libsupc++.a</filename>. To use it, compile with <command>gcc</command> instead of <command>g++</command>, like so:
      </para>

      <para>
	<command>gcc foo.cc -lsupc++</command>
      </para>

      <para>
	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.
      </para>
    </section>

    <section xml:id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"><info><title>Finding Dynamic or Shared Libraries</title></info>


    <para>
      If the only library built is the static library
      (<filename class="libraryfile">libstdc++.a</filename>), or if
      specifying static linking, this section is can be skipped.  But
      if building or using a shared library
      (<filename class="libraryfile">libstdc++.so</filename>), then
      additional location information will need to be provided.
    </para>
    <para>
      But how?
    </para>
    <para>
A quick read of the relevant part of the GCC
      manual, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b">Compiling
      C++ Programs</link>, specifies linking against a C++
      library. More details from the
      GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/faq.html#rpath">FAQ</link>,
      which states <emphasis>GCC does not, by default, specify a
      location so that the dynamic linker can find dynamic libraries at
      runtime.</emphasis>
    </para>
    <para>
      Users will have to provide this information.
    </para>
    <para>
      Methods vary for different platforms and different styles, and
      are printed to the screen during installation. To summarize:
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  At runtime set <literal>LD_LIBRARY_PATH</literal> 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 <literal>LD_LIBRARY_PATH</literal> first.
	</para>

      </listitem>
      <listitem>
	<para>
	  Compile the path to find the library at runtime into the
	  program.  This can be done by passing certain options to
	  <command>g++</command>, which will in turn pass them on to
	  the linker.  The exact format of the options is dependent on
	  which linker you use:
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      GNU ld (default on GNU/Linux):
              <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename>
	    </para>
	  </listitem>
	  <listitem>
	  <para>
	    Solaris ld:
            <literal>-Wl,-R</literal><filename class="directory">destdir/lib</filename>
	  </para>
	  </listitem>
	</itemizedlist>
      </listitem>
      <listitem>
	<para>
	  Some linkers allow you to specify the path to the library by
	  setting <literal>LD_RUN_PATH</literal> in your environment
	  when linking.
	</para>
      </listitem>
      <listitem>
	<para>
	  On some platforms the system administrator can configure the
	  dynamic linker to always look for libraries in
	  <filename class="directory">destdir/lib</filename>, for example
	  by using the <command>ldconfig</command> utility on GNU/Linux
	  or the <command>crle</command> 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.
	</para>
      </listitem>
    </itemizedlist>
    <para>
      Use the <command>ldd</command> utility on the linked executable
      to show
      which <filename class="libraryfile">libstdc++.so</filename>
      library the system will get at runtime.
    </para>
    <para>
      A <filename class="libraryfile">libstdc++.la</filename> file is
      also installed, for use with Libtool.  If you use Libtool to
      create your executables, these details are taken care of for
      you.
    </para>
    </section>

    <section xml:id="manual.intro.using.linkage.experimental" xreflabel="Library Extensions"><info><title>Experimental Library Extensions</title></info>

    <para>
      GCC 5.3 includes an implementation of the Filesystem library defined
      by the technical specification ISO/IEC TS 18822:2015. Because this is
      an experimental library extension, not part of the C++ standard, it
      is implemented in a separate library,
      <filename class="libraryfile">libstdc++fs.a</filename>, and there is
      no shared library for it. To use the library you should include
      <filename class="headerfile">&lt;experimental/filesystem&gt;</filename>
      and link with <option>-lstdc++fs</option>. The library implementation
      is incomplete on non-POSIX platforms, specifically Windows support is
      rudimentary.
    </para>

    <para>
      Due to the experimental nature of the Filesystem library the usual
      guarantees about ABI stability and backwards compatibility do not apply
      to it. There is no guarantee that the components in any
      <filename class="headerfile">&lt;experimental/xxx&gt;</filename>
      header will remain compatible between different GCC releases.
    </para>
    </section>
  </section>

  <section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
    <?dbhtml filename="using_concurrency.html"?>


   <para>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.
   </para>

    <section xml:id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"><info><title>Prerequisites</title></info>


   <para>All normal disclaimers aside, multithreaded C++ application are
      only supported when libstdc++ and all user code was built with
      compilers which report (via <code> gcc/g++ -v </code>) the same thread
      model and that model is not <emphasis>single</emphasis>.  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
      <emphasis>single</emphasis> 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.)
   </para>
   <para>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.  On several targets (including
      GNU/Linux, Solaris and various BSDs) -pthread is honored.
      Some other ports use other switches.
      This is not well documented anywhere other than
      in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries).
   </para>

   <para>
     Some uses of <classname>std::atomic</classname> also require linking
     to <filename class="libraryfile">libatomic</filename>.
   </para>

    </section>

    <section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info>


<para>
In the terms of the 2011 C++ standard a thread-safe program is one which
does not perform any conflicting non-atomic operations on memory locations
and so does not contain any data races.
The standard places requirements on the library to ensure that no data
races are caused by the library itself or by programs which use the
library correctly (as described below).
The C++11 memory model and library requirements are a more formal version
of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</link> definition of thread safety, which the library used
prior to the 2011 standard.
</para>


      <para>The library strives to be thread-safe when all of the following
	 conditions are met:
      </para>
      <itemizedlist>
       <listitem>
       <para>The system's libc is itself thread-safe,
       </para>
       </listitem>
       <listitem>
	 <para>
	   The compiler in use reports a thread model other than
	   'single'. This can be tested via output from <code>gcc
	   -v</code>. Multi-thread capable versions of gcc output
	   something like this:
	 </para>
<programlisting>
%gcc -v
Using built-in specs.
...
Thread model: posix
gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
</programlisting>

<para>Look for "Thread model" lines that aren't equal to "single."</para>
       </listitem>
       <listitem>
       <para>
	 Requisite command-line flags are used for atomic operations
	 and threading. Examples of this include <code>-pthread</code>
	 and <code>-march=native</code>, although specifics vary
	 depending on the host environment. See
	 <link linkend="manual.intro.using.flags">Command Options</link> and
	 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
	 Dependent Options</link>.
       </para>
       </listitem>
       <listitem>
	 <para>
	   An implementation of the
	   <filename class="headerfile">atomicity.h</filename> functions
	   exists for the architecture in question. See the
	   <link linkend="internals.thread_safety">internals
	   documentation</link> for more details.
       </para>
       </listitem>

      </itemizedlist>

      <para>The user code must guard against concurrent function calls which
         access any particular library object's state when one or more of
         those accesses modifies the state. An object will be modified by
         invoking a non-const member function on it or passing it as a
         non-const argument to a library function. An object will not be
         modified by invoking a const member function on it or passing it to
         a function as a pointer- or reference-to-const.
         Typically, the application
         programmer may infer what object locks must be held based on the
         objects referenced in a function call and whether the objects are
         accessed as const or non-const.  Without getting
	 into great detail, here is an example which requires user-level
	 locks:
      </para>
      <programlisting>
     library_class_a shared_object_a;

     void 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.</programlisting>
      <para>Under the assumption that object_a and object_b are never exposed to
	 another thread, here is an example that does not require any
	 user-level locks:
      </para>
      <programlisting>
     void 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 ();
     } </programlisting>

      <para>All library types are safe to use in a multithreaded program
         if objects are not shared between threads or as
	 long each thread carefully locks out access by any other
	 thread while it modifies any object visible to another thread.
	 Unless otherwise documented, the only exceptions to these rules
         are atomic operations on the types in
         <filename class="headerfile">&lt;atomic&gt;</filename>
         and lock/unlock operations on the standard mutex types in
         <filename class="headerfile">&lt;mutex&gt;</filename>. These
         atomic operations allow concurrent accesses to the same object
         without introducing data races.
      </para>

      <para>The following member functions of standard containers can be
         considered to be const for the purposes of avoiding data races:
         <code>begin</code>, <code>end</code>, <code>rbegin</code>, <code>rend</code>,
         <code>front</code>, <code>back</code>, <code>data</code>,
         <code>find</code>, <code>lower_bound</code>, <code>upper_bound</code>,
         <code>equal_range</code>, <code>at</code>
         and, except in associative or unordered associative containers,
         <code>operator[]</code>. In other words, although they are non-const
         so that they can return mutable iterators, those member functions
         will not modify the container.
         Accessing an iterator might cause a non-modifying access to
         the container the iterator refers to (for example incrementing a
         list iterator must access the pointers between nodes, which are part
         of the container and so conflict with other accesses to the container).
      </para>

      <para>Programs which follow the rules above will not encounter data
         races in library code, even when using library types which share
         state between distinct objects.  In the example below the
         <code>shared_ptr</code> objects share a reference count, but
         because the code does not perform any non-const operations on the
         globally-visible object, the library ensures that the reference
         count updates are atomic and do not introduce data races:
      </para>
      <programlisting>
    std::shared_ptr&lt;int&gt; global_sp;

    void thread_main() {
      auto local_sp = global_sp;  // OK, copy constructor's parameter is reference-to-const

      int i = *global_sp;         // OK, operator* is const
      int j = *local_sp;          // OK, does not operate on global_sp

      // *global_sp = 2;          // NOT OK, modifies int visible to other threads
      // *local_sp = 2;           // NOT OK, modifies int visible to other threads

      // global_sp.reset();       // NOT OK, reset is non-const
      local_sp.reset();           // OK, does not operate on global_sp
    }

    int main() {
      global_sp.reset(new int(1));
      std::thread t1(thread_main);
      std::thread t2(thread_main);
      t1.join();
      t2.join();
    }
      </programlisting>

      <para>For further details of the C++11 memory model see Hans-J. Boehm's
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/user-faq.html">Threads
      and memory model for C++</link> pages, particularly the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/threadsintro.html">introduction</link>
      and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/c++mm/user-faq.html">FAQ</link>.
      </para>

  </section>
  <section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info>

    <para>
    </para>
  </section>

    <section xml:id="manual.intro.using.concurrency.io" xreflabel="IO"><info><title>IO</title></info>

     <para>This gets a bit tricky.  Please read carefully, and bear with me.
   </para>

    <section xml:id="concurrency.io.structure" xreflabel="Structure"><info><title>Structure</title></info>

   <para>A wrapper
      type called <code>__basic_file</code> provides our abstraction layer
      for the <code>std::filebuf</code> classes.  Nearly all decisions dealing
      with actual input and output must be made in <code>__basic_file</code>.
   </para>
   <para>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).
   </para>
    </section>

    <section xml:id="concurrency.io.defaults" xreflabel="Defaults"><info><title>Defaults</title></info>

   <para>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 <code>fopen</code>,
      <code>fwrite</code>, and so forth.
   </para>
   <para>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.
   </para>
   <para>(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
       <code>fclose(fs)</code> in one thread followed by an access of
       <code>fs</code> in another.)
   </para>
   <para>So, if your platform's C library is threadsafe, then your
      <code>fstream</code> 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 <code>std::ofstream</code>), you need to guard such accesses
      like any other critical shared resource.
   </para>
    </section>

    <section xml:id="concurrency.io.future" xreflabel="Future"><info><title>Future</title></info>

   <para> 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.
   </para>
   <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O
      implementation.  When libio is in use, the <code>__basic_file</code>
      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 <code>fread</code>, <code>fwrite</code>,
      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*)
   </para>
   <para>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.
   </para>
   <para>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++.
   </para>
    </section>

    <section xml:id="concurrency.io.alt" xreflabel="Alt"><info><title>Alternatives</title></info>

   <para>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.
   </para>
    </section>

    </section>

    <section xml:id="manual.intro.using.concurrency.containers" xreflabel="Containers"><info><title>Containers</title></info>


   <para>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.
   </para>
   <para>Two excellent pages to read when working with the Standard C++
      containers and threads are
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
      http://www.sgi.com/tech/stl/thread_safety.html</link> and
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/Allocators.html">SGI's
      http://www.sgi.com/tech/stl/Allocators.html</link>.
   </para>
   <para><emphasis>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.</emphasis>
   </para>
   <para>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
      (<emphasis>For most clients...</emphasis>), 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).
   </para>
   <para>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 <emphasis>to a certain
      extent</emphasis>, 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.
   </para>
   <para>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 <link linkend="manual.intro.using.macros">here</link>. Also
      useful are details
      on <link linkend="std.util.memory.allocator">allocator</link>
      options and capabilities.
   </para>

    </section>
</section>

<!-- Section 0x : Exception policies, expectations, topics -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="using_exceptions.xml">
</xi:include>

<!-- Section 0x : Debug -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="debug.xml">
</xi:include>

</chapter>