| <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++14</command> since GCC 6, and |
| <command>g++ -std=gnu++98</command> for 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></entry> |
| <entry>For ISO C++11 |
| <filename class="headerfile"><thread></filename>, |
| <filename class="headerfile"><future></filename>, |
| <filename class="headerfile"><mutex></filename>, |
| or <filename class="headerfile"><condition_variable></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"><atomic></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"><experimental/filesystem></filename>. |
| </entry> |
| </row> |
| |
| <row> |
| <entry><literal>-fopenmp</literal></entry> |
| <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry> |
| </row> |
| |
| <row> |
| <entry><literal>-ltbb</literal></entry> |
| <entry>Linking to tbb (Thread Building Blocks) is required for use of the |
| Parallel Standard Algorithms and execution policies in |
| <filename class="headerfile"><execution></filename>. |
| </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 (TS, TR1, C++ ABI, and Extensions). |
| </para> |
| |
| <para> |
| Multiple dialects of standard headers are supported, corresponding to |
| the 1998 standard as updated for 2003, the 2011 standard, the 2014 |
| standard, and so on. |
| </para> |
| |
| <para> |
| <xref linkend="table.cxx98_headers"/> and |
| <xref linkend="table.cxx98_cheaders"/> and |
| <xref linkend="table.cxx98_deprheaders"/> |
| show the C++98/03 include files. |
| These are available in the C++98 compilation mode, |
| i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>. |
| Unless specified otherwise below, they are also available in later modes |
| (C++11, C++14 etc). |
| </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> |
| <entry namest="c3" nameend="c5"/> |
| </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> |
| <entry namest="c4" nameend="c5"/> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para> |
| The following header is deprecated |
| and might be removed from a future C++ standard. |
| </para> |
| |
| <table frame="all" xml:id="table.cxx98_deprheaders"> |
| <title>C++ 1998 Deprecated Library Header</title> |
| |
| <tgroup cols="1" align="left" colsep="1" rowsep="1"> |
| <colspec colname="c1"/> |
| <tbody> |
| <row> |
| <entry><filename class="headerfile">strstream</filename></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para> |
| <xref linkend="table.cxx11_headers"/> and |
| <xref linkend="table.cxx11_cheaders"/> show the C++11 include files. |
| These are available in C++11 compilation |
| mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>. |
| Including these headers in C++98/03 mode may result in compilation errors. |
| Unless specified otherwise below, they are also available in later modes |
| (C++14 etc). |
| </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">array</filename></entry> |
| <entry><filename class="headerfile">atomic</filename></entry> |
| <entry><filename class="headerfile">chrono</filename></entry> |
| <entry><filename class="headerfile">codecvt</filename></entry> |
| <entry><filename class="headerfile">condition_variable</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">forward_list</filename></entry> |
| <entry><filename class="headerfile">future</filename></entry> |
| <entry><filename class="headerfile">initalizer_list</filename></entry> |
| <entry><filename class="headerfile">mutex</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">scoped_allocator</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">typeindex</filename></entry> |
| <entry><filename class="headerfile">type_traits</filename></entry> |
| <entry><filename class="headerfile">unordered_map</filename></entry> |
| <entry><filename class="headerfile">unordered_set</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">ccomplex</filename></entry> |
| <entry><filename class="headerfile">cfenv</filename></entry> |
| <entry><filename class="headerfile">cinttypes</filename></entry> |
| <entry><filename class="headerfile">cstdalign</filename></entry> |
| <entry><filename class="headerfile">cstdbool</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">cstdint</filename></entry> |
| <entry><filename class="headerfile">ctgmath</filename></entry> |
| <entry><filename class="headerfile">cuchar</filename></entry> |
| <entry namest="c4" nameend="c5"/> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para> |
| <xref linkend="table.cxx14_headers"/> shows the C++14 include file. |
| This is available in C++14 compilation |
| mode, i.e. <literal>-std=c++14</literal> or <literal>-std=gnu++14</literal>. |
| Including this header in C++98/03 mode or C++11 will not result in |
| compilation errors, but will not define anything. |
| Unless specified otherwise below, it is also available in later modes |
| (C++17 etc). |
| </para> |
| |
| <para/> |
| <table frame="all" xml:id="table.cxx14_headers"> |
| <title>C++ 2014 Library Header</title> |
| |
| <tgroup cols="1" align="left" colsep="1" rowsep="1"> |
| <colspec colname="c1"/> |
| <tbody> |
| <row> |
| <entry><filename class="headerfile">shared_mutex</filename></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para> |
| <xref linkend="table.cxx17_headers"/> shows the C++17 include files. |
| These are available in C++17 compilation |
| mode, i.e. <literal>-std=c++17</literal> or <literal>-std=gnu++17</literal>. |
| Including these headers in earlier modes will not result in |
| compilation errors, but will not define anything. |
| Unless specified otherwise below, they are also available in later modes |
| (C++20 etc). |
| </para> |
| |
| <para/> |
| <table frame="all" xml:id="table.cxx17_headers"> |
| <title>C++ 2017 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">any</filename></entry> |
| <entry><filename class="headerfile">charconv</filename></entry> |
| <entry><filename class="headerfile">execution</filename></entry> |
| <entry><filename class="headerfile">filesystem</filename></entry> |
| <entry><filename class="headerfile">memory_resource</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">optional</filename></entry> |
| <entry><filename class="headerfile">string_view</filename></entry> |
| <entry><filename class="headerfile">variant</filename></entry> |
| <entry namest="c4" nameend="c5"/> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para> |
| <xref linkend="table.cxx20_headers"/> |
| shows the C++2a include files. |
| These are available in C++2a compilation |
| mode, i.e. <literal>-std=c++2a</literal> or <literal>-std=gnu++2a</literal>. |
| Including these headers in earlier modes will not result in |
| compilation errors, but will not define anything. |
| <!-- |
| Unless specified otherwise below, they are also available in later modes |
| (C++23 etc). |
| --> |
| </para> |
| |
| <para/> |
| <table frame="all" xml:id="table.cxx20_headers"> |
| <title>C++ 2020 Library Headers</title> |
| |
| <tgroup cols="2" 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">bit</filename></entry> |
| <entry><filename class="headerfile">version</filename></entry> |
| </row> |
| <!-- TODO compare, concepts, contract, span, syncstream --> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para> |
| The following headers have been removed in the C++2a working draft. |
| They are still available when using this implementation, but in future |
| they might start to produce warnings or errors when included in C++2a mode. |
| Programs that intend to be portable should not include them. |
| </para> |
| |
| <table frame="all" xml:id="table.cxx20_deprheaders"> |
| <title>C++ 2020 Obsolete 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">ccomplex</filename></entry> |
| <entry><filename class="headerfile">ciso646</filename></entry> |
| <entry><filename class="headerfile">cstdalign</filename></entry> |
| <entry><filename class="headerfile">cstdbool</filename></entry> |
| <entry><filename class="headerfile">ctgmath</filename></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para> |
| <xref linkend="table.filesystemts_headers"/>, |
| shows the additional include file define by the |
| File System Technical Specification, ISO/IEC TS 18822. |
| This is available in C++11 and later compilation modes. |
| Including this header in earlier modes will not result in |
| compilation errors, but will not define anything. |
| </para> |
| |
| <para/> |
| <table frame="all" xml:id="table.filesystemts_headers"> |
| <title>File System TS Header</title> |
| |
| <tgroup cols="1" align="left" colsep="1" rowsep="1"> |
| <colspec colname="c1"/> |
| <tbody> |
| <row> |
| <entry><filename class="headerfile">experimental/filesystem</filename></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| |
| <para> |
| <xref linkend="table.libfundts_headers"/>, |
| shows the additional include files define by the C++ Extensions for |
| Library Fundamentals Technical Specification, ISO/IEC TS 19568. |
| These are available in C++14 and later compilation modes. |
| Including these headers in earlier modes will not result in |
| compilation errors, but will not define anything. |
| </para> |
| |
| <para/> |
| <table frame="all" xml:id="table.libfundts_headers"> |
| <title>Library Fundamentals TS 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">experimental/algorithm</filename></entry> |
| <entry><filename class="headerfile">experimental/any</filename></entry> |
| <entry><filename class="headerfile">experimental/array</filename></entry> |
| <entry><filename class="headerfile">experimental/chrono</filename></entry> |
| <entry><filename class="headerfile">experimental/deque</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">experimental/forward_list</filename></entry> |
| <entry><filename class="headerfile">experimental/functional</filename></entry> |
| <entry><filename class="headerfile">experimental/iterator</filename></entry> |
| <entry><filename class="headerfile">experimental/list</filename></entry> |
| <entry><filename class="headerfile">experimental/map</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">experimental/memory</filename></entry> |
| <entry><filename class="headerfile">experimental/memory_resource</filename></entry> |
| <entry><filename class="headerfile">experimental/numeric</filename></entry> |
| <entry><filename class="headerfile">experimental/optional</filename></entry> |
| <entry><filename class="headerfile">experimental/propagate_const</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">experimental/random</filename></entry> |
| <entry><filename class="headerfile">experimental/ratio</filename></entry> |
| <entry><filename class="headerfile">experimental/regex</filename></entry> |
| <entry><filename class="headerfile">experimental/set</filename></entry> |
| <entry><filename class="headerfile">experimental/source_location</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">experimental/string</filename></entry> |
| <entry><filename class="headerfile">experimental/string_view</filename></entry> |
| <entry><filename class="headerfile">experimental/system_error</filename></entry> |
| <entry><filename class="headerfile">experimental/tuple</filename></entry> |
| <entry><filename class="headerfile">experimental/type_traits</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">experimental/unordered_map</filename></entry> |
| <entry><filename class="headerfile">experimental/unordered_set</filename></entry> |
| <entry><filename class="headerfile">experimental/utility</filename></entry> |
| <entry><filename class="headerfile">experimental/vector</filename></entry> |
| <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> |
| <entry namest="c2" nameend="c5"/> |
| </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/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> |
| <entry namest="c2" nameend="c5"/> |
| </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/array</filename></entry> |
| <entry><filename class="headerfile">debug/bitset</filename></entry> |
| <entry><filename class="headerfile">debug/deque</filename></entry> |
| <entry><filename class="headerfile">debug/forward_list</filename></entry> |
| <entry><filename class="headerfile">debug/list</filename></entry> |
| </row> |
| <row> |
| <entry><filename class="headerfile">debug/map</filename></entry> |
| <entry><filename class="headerfile">debug/set</filename></entry> |
| <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> |
| </row> |
| <row> |
| <entry><filename class="headerfile">debug/vector</filename></entry> |
| <entry namest="c2" nameend="c5"/> |
| </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 <array> |
| #include <functional> |
| </programlisting> |
| |
| <para>Implies C++11 mode. To use the entities in <array>, the C++11 |
| compilation mode must be used, which implies the C++11 functionality |
| (and deprecations) in <functional> will be present. |
| </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 <tr1/type_traits> |
| #include <type_traits> |
| </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 |
| (<math.h> 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 (<cmath>) 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 <cmath>, 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 <stdc++.h>, and adds all the TR1 headers. |
| </para> |
| </listitem> |
| |
| <listitem><para>extc++.h</para> |
| <para>Includes all of <stdc++.h>, and adds all the Extension headers |
| (and in C++98 mode also adds all the TR1 headers by including all of |
| <stdtr1c++.h>). |
| </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 <...> 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"><ios></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 are the macros which users may check for library version |
| information. </para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><code>_GLIBCXX_RELEASE</code></term> |
| <listitem> |
| <para>The major release number for libstdc++. This macro is defined |
| to the GCC major version that the libstdc++ headers belong to, |
| as an integer constant. |
| When compiling with GCC it has the same value as GCC's pre-defined |
| macro <symbol>__GNUC__</symbol>. |
| This macro can be used when libstdc++ is used with a non-GNU |
| compiler where <symbol>__GNUC__</symbol> is not defined, or has a |
| different value that doesn't correspond to the libstdc++ version. |
| This macro first appeared in the GCC 7.1 release and is not defined |
| for GCC 6.x or older releases. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><code>__GLIBCXX__</code></term> |
| <listitem> |
| <para>The revision date of the libstdc++ source code, |
| in compressed ISO date format, as an unsigned |
| long. For notes about using this macro and details on the value of |
| this macro for a particular release, please consult the |
| <link linkend="abi.versioning.__GLIBCXX__">ABI History</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 |
| different <code>-std</code> options. 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 |
| macro has no effect for freestanding implementations. |
| This is described in more detail in |
| <link linkend="manual.ext.compile_checks">Compile Time Checks</link>. |
| </para> |
| </listitem></varlistentry> |
| |
| <varlistentry><term><code>_GLIBCXX_ASSERTIONS</code></term> |
| <listitem> |
| <para> |
| Undefined by default. When defined, enables extra error checking in |
| the form of precondition assertions, such as bounds checking in |
| strings and null pointer checks when dereferencing smart pointers. |
| </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>. |
| When defined, <code>_GLIBCXX_ASSERTIONS</code> is defined |
| automatically, so all the assertions enabled by that macro are also |
| enabled in debug mode. |
| </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_PARALLEL_ASSERTIONS</code></term> |
| <listitem> |
| <para>Undefined by default, but when any parallel mode header is included |
| this macro will be defined to a non-zero value if |
| <code>_GLIBCXX_ASSERTIONS</code> has a non-zero value, otherwise to zero. |
| When defined to a non-zero value, it enables extra error checking and |
| assertions in the parallel mode. |
| </para> |
| </listitem></varlistentry> |
| |
| <varlistentry><term><code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code></term> |
| <listitem> |
| <para>Undefined by default. When defined to a non-zero integer constant, |
| enables support for ISO/IEC 29124 Special Math Functions. |
| </para> |
| </listitem></varlistentry> |
| |
| <varlistentry><term><code>_GLIBCXX_SANITIZE_VECTOR</code></term> |
| <listitem> |
| <para> |
| Undefined by default. When defined, <classname>std::vector</classname> |
| operations will be annotated so that AddressSanitizer can detect |
| invalid accesses to the unused capacity of a |
| <classname>std::vector</classname>. These annotations are only |
| enabled for |
| <classname>std::vector<T, std::allocator<T>></classname> |
| and only when <classname>std::allocator</classname> is derived from |
| <link linkend="allocator.ext"><classname>new_allocator</classname> |
| or <classname>malloc_allocator</classname></link>. The annotations |
| must be present on all vector operations or none, so this macro must |
| be defined to the same value for all translation units that create, |
| destroy or modify vectors. |
| </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<int></classname> is actually defined as |
| <classname>std::__cxx11::list<int></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<std::time_get<char>>(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"><stdexcept></filename> use strings, most |
| 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> |
| |
| <para> One exception type does change when using the new ABI, namely |
| <classname>std::ios_base::failure</classname>. |
| This is necessary because the 2011 standard changed its base class from |
| <classname>std::exception</classname> to |
| <classname>std::system_error</classname>, which causes its layout to change. |
| Exceptions due to iostream errors are thrown by a function inside |
| <filename class="libraryfile">libstdc++.so</filename>, so whether the thrown |
| exception uses the old <classname>std::ios_base::failure</classname> type |
| or the new one depends on the ABI that was active when |
| <filename class="libraryfile">libstdc++.so</filename> was built, |
| <emphasis>not</emphasis> the ABI active in the user code that is using |
| iostreams. |
| This means that for a given build of GCC the type thrown is fixed. |
| In current releases the library throws a special type that can be caught |
| by handlers for either the old or new type, |
| but for GCC 7.1, 7.2 and 7.3 the library throws the new |
| <classname>std::ios_base::failure</classname> type, |
| and for GCC 5.x and 6.x the library throws the old type. |
| Catch handlers of type <classname>std::ios_base::failure</classname> |
| will only catch the exceptions if using a newer release, |
| or if the handler is compiled with the same ABI as the type thrown by |
| the library. |
| Handlers for <classname>std::exception</classname> will always catch |
| iostreams exceptions, because the old and new type both inherit from |
| <classname>std::exception</classname>. |
| </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"><experimental/filesystem></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"><experimental/xxx></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="https://web.archive.org/web/20171225062613/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"><atomic></filename> |
| and lock/unlock operations on the standard mutex types in |
| <filename class="headerfile"><mutex></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<int> 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="https://www.hboehm.info/c++mm/">Threads |
| and memory model for C++</link> pages, particularly the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/threadsintro.html">introduction</link> |
| and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/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 |
| <code>FILE*</code> operations are atomic. POSIX-conforming C libraries |
| (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize |
| operations on <code>FILE*</code>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="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html">SGI's |
| https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html</link> and |
| <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/Allocators.html">SGI's |
| https://web.archive.org/web/20171225062613/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> |