1 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
2 xml:id="manual.intro.using" xreflabel="Using">
3 <info><title>Using</title></info>
4 <?dbhtml filename="using.html"?>
6 <section xml:id="manual.intro.using.flags" xreflabel="Flags"><info><title>Command Options</title></info>
9 The set of features available in the GNU C++ library is shaped by
10 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
11 Command Options</link>. Options that impact libstdc++ are
12 enumerated and detailed in the table below.
16 The standard library conforms to the dialect of C++ specified by the
17 <option>-std</option> option passed to the compiler.
18 By default, <command>g++</command> is equivalent to
19 <command>g++ -std=gnu++17</command> since GCC 11, and
20 <command>g++ -std=gnu++14</command> in GCC 6, 7, 8, 9, and 10, and
21 <command>g++ -std=gnu++98</command> for older releases.
24 <table frame="all" xml:id="table.cmd_options">
25 <title>C++ Command Options</title>
27 <tgroup cols="2" align="left" colsep="1" rowsep="1">
28 <colspec colname="c1"/>
29 <colspec colname="c2"/>
33 <entry>Option Flags</entry>
34 <entry>Description</entry>
40 <entry><literal>-std=c++98</literal> or <literal>-std=c++03</literal>
42 <entry>Use the 1998 ISO C++ standard plus amendments.</entry>
46 <entry><literal>-std=gnu++98</literal> or <literal>-std=gnu++03</literal>
48 <entry>As directly above, with GNU extensions.</entry>
52 <entry><literal>-std=c++11</literal></entry>
53 <entry>Use the 2011 ISO C++ standard.</entry>
57 <entry><literal>-std=gnu++11</literal></entry>
58 <entry>As directly above, with GNU extensions.</entry>
62 <entry><literal>-std=c++14</literal></entry>
63 <entry>Use the 2014 ISO C++ standard.</entry>
67 <entry><literal>-std=gnu++14</literal></entry>
68 <entry>As directly above, with GNU extensions.</entry>
73 <literal>-fno-exceptions</literal>
75 <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry>
80 <literal>-fno-rtti</literal>
82 <entry>As above, but RTTI-free dialect.</entry>
86 <entry><literal>-pthread</literal></entry>
88 <filename class="headerfile"><thread></filename>,
89 <filename class="headerfile"><future></filename>,
90 <filename class="headerfile"><mutex></filename>,
91 or <filename class="headerfile"><condition_variable></filename>.
96 <entry><literal>-latomic</literal></entry>
97 <entry>Linking to <filename class="libraryfile">libatomic</filename>
98 is required for some uses of ISO C++11
99 <filename class="headerfile"><atomic></filename>.
104 <entry><literal>-lstdc++exp</literal></entry>
105 <entry>Linking to <filename class="libraryfile">libstdc++exp.a</filename>
106 is required for use of experimental C++ library features.
107 This currently provides support for the C++23 types defined in the
108 <filename class="headerfile"><stacktrace></filename> header,
109 the Filesystem library extensions defined in the
110 <filename class="headerfile"><experimental/filesystem></filename>
112 and the Contracts extensions enabled by <literal>-fcontracts</literal>.
117 <entry><literal>-lstdc++fs</literal></entry>
118 <entry>Linking to <filename class="libraryfile">libstdc++fs.a</filename>
119 is another way to use the Filesystem library extensions defined in the
120 <filename class="headerfile"><experimental/filesystem></filename>
122 The <filename class="libraryfile">libstdc++exp.a</filename> library
123 also provides all the symbols contained in this library.
128 <entry><literal>-fopenmp</literal></entry>
129 <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
133 <entry><literal>-ltbb</literal></entry>
134 <entry>Linking to tbb (Thread Building Blocks) is required for use of the
135 Parallel Standard Algorithms and execution policies in
136 <filename class="headerfile"><execution></filename>.
141 <entry><literal>-ffreestanding</literal></entry>
143 Limits the library to its freestanding subset. Headers that are
144 not supported in freestanding will emit a "This header is not available
145 in freestanding mode" error.
146 Headers that are in the freestanding subset partially will not expose
147 functionality that is not part of the freestanding subset.
158 <section xml:id="manual.intro.using.headers" xreflabel="Headers"><info><title>Headers</title></info>
159 <?dbhtml filename="using_headers.html"?>
162 <section xml:id="manual.intro.using.headers.all" xreflabel="Header Files"><info><title>Header Files</title></info>
166 The C++ standard specifies the entire set of header files that
167 must be available to all hosted implementations. Actually, the
168 word "files" is a misnomer, since the contents of the
169 headers don't necessarily have to be in any kind of external
170 file. The only rule is that when one <code>#include</code>s a
171 header, the contents of that header become available, no matter
176 That said, in practice files are used.
180 There are two main types of include files: header files related
181 to a specific version of the ISO C++ standard (called Standard
182 Headers), and all others (TS, TR1, C++ ABI, and Extensions).
186 Multiple dialects of standard headers are supported, corresponding to
187 the 1998 standard as updated for 2003, the 2011 standard, the 2014
192 <xref linkend="table.cxx98_headers"/> and
193 <xref linkend="table.cxx98_cheaders"/> and
194 <xref linkend="table.cxx98_deprheaders"/>
195 show the C++98/03 include files.
196 These are available in the C++98 compilation mode,
197 i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>.
198 Unless specified otherwise below, they are also available in later modes
202 <table frame="all" xml:id="table.cxx98_headers">
203 <title>C++ 1998 Library Headers</title>
205 <tgroup cols="5" align="left" colsep="1" rowsep="1">
206 <colspec colname="c1"/>
207 <colspec colname="c2"/>
208 <colspec colname="c3"/>
209 <colspec colname="c4"/>
210 <colspec colname="c5"/>
213 <entry><filename class="headerfile">algorithm</filename></entry>
214 <entry><filename class="headerfile">bitset</filename></entry>
215 <entry><filename class="headerfile">complex</filename></entry>
216 <entry><filename class="headerfile">deque</filename></entry>
217 <entry><filename class="headerfile">exception</filename></entry>
220 <entry><filename class="headerfile">fstream</filename></entry>
221 <entry><filename class="headerfile">functional</filename></entry>
222 <entry><filename class="headerfile">iomanip</filename></entry>
223 <entry><filename class="headerfile">ios</filename></entry>
224 <entry><filename class="headerfile">iosfwd</filename></entry>
227 <entry><filename class="headerfile">iostream</filename></entry>
228 <entry><filename class="headerfile">istream</filename></entry>
229 <entry><filename class="headerfile">iterator</filename></entry>
230 <entry><filename class="headerfile">limits</filename></entry>
231 <entry><filename class="headerfile">list</filename></entry>
234 <entry><filename class="headerfile">locale</filename></entry>
235 <entry><filename class="headerfile">map</filename></entry>
236 <entry><filename class="headerfile">memory</filename></entry>
237 <entry><filename class="headerfile">new</filename></entry>
238 <entry><filename class="headerfile">numeric</filename></entry>
241 <entry><filename class="headerfile">ostream</filename></entry>
242 <entry><filename class="headerfile">queue</filename></entry>
243 <entry><filename class="headerfile">set</filename></entry>
244 <entry><filename class="headerfile">sstream</filename></entry>
245 <entry><filename class="headerfile">stack</filename></entry>
248 <entry><filename class="headerfile">stdexcept</filename></entry>
249 <entry><filename class="headerfile">streambuf</filename></entry>
250 <entry><filename class="headerfile">string</filename></entry>
251 <entry><filename class="headerfile">utility</filename></entry>
252 <entry><filename class="headerfile">typeinfo</filename></entry>
255 <entry><filename class="headerfile">valarray</filename></entry>
256 <entry><filename class="headerfile">vector</filename></entry>
257 <entry namest="c3" nameend="c5"/>
264 <table frame="all" xml:id="table.cxx98_cheaders">
265 <title>C++ 1998 Library Headers for C Library Facilities</title>
267 <tgroup cols="5" align="left" colsep="1" rowsep="1">
268 <colspec colname="c1"/>
269 <colspec colname="c2"/>
270 <colspec colname="c3"/>
271 <colspec colname="c4"/>
272 <colspec colname="c5"/>
275 <entry><filename class="headerfile">cassert</filename></entry>
276 <entry><filename class="headerfile">cerrno</filename></entry>
277 <entry><filename class="headerfile">cctype</filename></entry>
278 <entry><filename class="headerfile">cfloat</filename></entry>
279 <entry><filename class="headerfile">ciso646</filename></entry>
282 <entry><filename class="headerfile">climits</filename></entry>
283 <entry><filename class="headerfile">clocale</filename></entry>
284 <entry><filename class="headerfile">cmath</filename></entry>
285 <entry><filename class="headerfile">csetjmp</filename></entry>
286 <entry><filename class="headerfile">csignal</filename></entry>
289 <entry><filename class="headerfile">cstdarg</filename></entry>
290 <entry><filename class="headerfile">cstddef</filename></entry>
291 <entry><filename class="headerfile">cstdio</filename></entry>
292 <entry><filename class="headerfile">cstdlib</filename></entry>
293 <entry><filename class="headerfile">cstring</filename></entry>
296 <entry><filename class="headerfile">ctime</filename></entry>
297 <entry><filename class="headerfile">cwchar</filename></entry>
298 <entry><filename class="headerfile">cwctype</filename></entry>
299 <entry namest="c4" nameend="c5"/>
306 The following header is deprecated
307 and might be removed from a future C++ standard.
310 <table frame="all" xml:id="table.cxx98_deprheaders">
311 <title>C++ 1998 Deprecated Library Header</title>
313 <tgroup cols="1" align="left" colsep="1" rowsep="1">
314 <colspec colname="c1"/>
317 <entry><filename class="headerfile">strstream</filename></entry>
324 <xref linkend="table.cxx11_headers"/> and
325 <xref linkend="table.cxx11_cheaders"/> show the C++11 include files.
326 These are available in C++11 compilation
327 mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
328 Including these headers in C++98/03 mode may result in compilation errors.
329 Unless specified otherwise below, they are also available in later modes
334 <table frame="all" xml:id="table.cxx11_headers">
335 <title>C++ 2011 Library Headers</title>
337 <tgroup cols="5" align="left" colsep="1" rowsep="1">
338 <colspec colname="c1"/>
339 <colspec colname="c2"/>
340 <colspec colname="c3"/>
341 <colspec colname="c4"/>
342 <colspec colname="c5"/>
346 <entry><filename class="headerfile">array</filename></entry>
347 <entry><filename class="headerfile">atomic</filename></entry>
348 <entry><filename class="headerfile">chrono</filename></entry>
349 <entry><filename class="headerfile">codecvt</filename></entry>
350 <entry><filename class="headerfile">condition_variable</filename></entry>
353 <entry><filename class="headerfile">forward_list</filename></entry>
354 <entry><filename class="headerfile">future</filename></entry>
355 <entry><filename class="headerfile">initalizer_list</filename></entry>
356 <entry><filename class="headerfile">mutex</filename></entry>
357 <entry><filename class="headerfile">random</filename></entry>
360 <entry><filename class="headerfile">ratio</filename></entry>
361 <entry><filename class="headerfile">regex</filename></entry>
362 <entry><filename class="headerfile">scoped_allocator</filename></entry>
363 <entry><filename class="headerfile">system_error</filename></entry>
364 <entry><filename class="headerfile">thread</filename></entry>
367 <entry><filename class="headerfile">tuple</filename></entry>
368 <entry><filename class="headerfile">typeindex</filename></entry>
369 <entry><filename class="headerfile">type_traits</filename></entry>
370 <entry><filename class="headerfile">unordered_map</filename></entry>
371 <entry><filename class="headerfile">unordered_set</filename></entry>
380 <table frame="all" xml:id="table.cxx11_cheaders">
381 <title>C++ 2011 Library Headers for C Library Facilities</title>
383 <tgroup cols="5" align="left" colsep="1" rowsep="1">
384 <colspec colname="c1"/>
385 <colspec colname="c2"/>
386 <colspec colname="c3"/>
387 <colspec colname="c4"/>
388 <colspec colname="c5"/>
391 <entry><filename class="headerfile">ccomplex</filename></entry>
392 <entry><filename class="headerfile">cfenv</filename></entry>
393 <entry><filename class="headerfile">cinttypes</filename></entry>
394 <entry><filename class="headerfile">cstdalign</filename></entry>
395 <entry><filename class="headerfile">cstdbool</filename></entry>
398 <entry><filename class="headerfile">cstdint</filename></entry>
399 <entry><filename class="headerfile">ctgmath</filename></entry>
400 <entry><filename class="headerfile">cuchar</filename></entry>
401 <entry namest="c4" nameend="c5"/>
408 <xref linkend="table.cxx14_headers"/> shows the C++14 include file.
409 This is available in C++14 compilation
410 mode, i.e. <literal>-std=c++14</literal> or <literal>-std=gnu++14</literal>.
411 Including this header in C++98/03 mode or C++11 will not result in
412 compilation errors, but will not define anything.
413 Unless specified otherwise below, it is also available in later modes
418 <table frame="all" xml:id="table.cxx14_headers">
419 <title>C++ 2014 Library Header</title>
421 <tgroup cols="1" align="left" colsep="1" rowsep="1">
422 <colspec colname="c1"/>
425 <entry><filename class="headerfile">shared_mutex</filename></entry>
432 <xref linkend="table.cxx17_headers"/> shows the C++17 include files.
433 These are available in C++17 compilation
434 mode, i.e. <literal>-std=c++17</literal> or <literal>-std=gnu++17</literal>.
435 Including these headers in earlier modes will not result in
436 compilation errors, but will not define anything.
437 Unless specified otherwise below, they are also available in later modes
442 <table frame="all" xml:id="table.cxx17_headers">
443 <title>C++ 2017 Library Headers</title>
445 <tgroup cols="5" align="left" colsep="1" rowsep="1">
446 <colspec colname="c1"/>
447 <colspec colname="c2"/>
448 <colspec colname="c3"/>
449 <colspec colname="c4"/>
450 <colspec colname="c5"/>
453 <entry><filename class="headerfile">any</filename></entry>
454 <entry><filename class="headerfile">charconv</filename></entry>
455 <entry><filename class="headerfile">execution</filename></entry>
456 <entry><filename class="headerfile">filesystem</filename></entry>
457 <entry><filename class="headerfile">memory_resource</filename></entry>
460 <entry><filename class="headerfile">optional</filename></entry>
461 <entry><filename class="headerfile">string_view</filename></entry>
462 <entry><filename class="headerfile">variant</filename></entry>
463 <entry namest="c4" nameend="c5"/>
470 <xref linkend="table.cxx20_headers"/>
471 shows the C++20 include files.
472 These are available in C++20 compilation
473 mode, i.e. <literal>-std=c++20</literal> or <literal>-std=gnu++20</literal>.
474 Including these headers in earlier modes will not result in
475 compilation errors, but will not define anything.
477 Unless specified otherwise below, they are also available in later modes
483 <table frame="all" xml:id="table.cxx20_headers">
484 <title>C++ 2020 Library Headers</title>
486 <tgroup cols="5" align="left" colsep="1" rowsep="1">
487 <colspec colname="c1"/>
488 <colspec colname="c2"/>
489 <colspec colname="c3"/>
490 <colspec colname="c4"/>
491 <colspec colname="c5"/>
494 <entry><filename class="headerfile">barrier</filename></entry>
495 <entry><filename class="headerfile">bit</filename></entry>
496 <entry><filename class="headerfile">charconv</filename></entry>
497 <entry><filename class="headerfile">compare</filename></entry>
498 <entry><filename class="headerfile">concepts</filename></entry>
501 <entry><filename class="headerfile">coroutine</filename></entry>
502 <entry><filename class="headerfile">format</filename></entry>
503 <entry><filename class="headerfile">latch</filename></entry>
504 <entry><filename class="headerfile">numbers</filename></entry>
505 <entry><filename class="headerfile">ranges</filename></entry>
508 <entry><filename class="headerfile">semaphore</filename></entry>
509 <entry><filename class="headerfile">source_location</filename></entry>
510 <entry><filename class="headerfile">span</filename></entry>
511 <entry><filename class="headerfile">stop_token</filename></entry>
512 <entry><filename class="headerfile">syncstream</filename></entry>
515 <entry><filename class="headerfile">version</filename></entry>
516 <entry namest="c2" nameend="c5"/>
523 The following headers have been removed in the C++20 standard.
524 They are still available when using this implementation, but in future
525 they might start to produce warnings or errors when included in C++20 mode.
526 Programs that intend to be portable should not include them.
529 <table frame="all" xml:id="table.cxx20_deprheaders">
530 <title>C++ 2020 Obsolete Headers</title>
532 <tgroup cols="5" align="left" colsep="1" rowsep="1">
533 <colspec colname="c1"/>
534 <colspec colname="c2"/>
535 <colspec colname="c3"/>
536 <colspec colname="c4"/>
537 <colspec colname="c5"/>
540 <entry><filename class="headerfile">ccomplex</filename></entry>
541 <entry><filename class="headerfile">ciso646</filename></entry>
542 <entry><filename class="headerfile">cstdalign</filename></entry>
543 <entry><filename class="headerfile">cstdbool</filename></entry>
544 <entry><filename class="headerfile">ctgmath</filename></entry>
551 <xref linkend="table.cxx23_headers"/>
552 shows the C++23 include files.
553 These are available in C++23 compilation
554 mode, i.e. <literal>-std=c++23</literal> or <literal>-std=gnu++23</literal>.
555 Including these headers in earlier modes will not result in
556 compilation errors, but will not define anything.
558 Unless specified otherwise below, they are also available in later modes
564 <table frame="all" xml:id="table.cxx23_headers">
565 <title>C++ 2023 Library Headers</title>
567 <tgroup cols="5" align="left" colsep="1" rowsep="1">
568 <colspec colname="c1"/>
569 <colspec colname="c2"/>
570 <colspec colname="c3"/>
571 <colspec colname="c4"/>
572 <colspec colname="c5"/>
575 <entry><filename class="headerfile">expected</filename></entry>
576 <entry><filename class="headerfile">generator</filename></entry>
577 <entry><filename class="headerfile">print</filename></entry>
578 <entry><filename class="headerfile">spanstream</filename></entry>
579 <entry><filename class="headerfile">stacktrace</filename></entry>
582 <entry><filename class="headerfile">stdatomic.h</filename></entry>
583 <entry><filename class="headerfile">stdfloat</filename></entry>
584 <entry namest="c3" nameend="c5"/>
585 <!-- TODO flat_map, flat_set, mdspan -->
592 <xref linkend="table.cxx26_headers"/>
593 shows the C++26 include files.
594 These are available in C++26 compilation
595 mode, i.e. <literal>-std=c++26</literal> or <literal>-std=gnu++26</literal>.
596 Including these headers in earlier modes will not result in
597 compilation errors, but will not define anything.
599 Unless specified otherwise below, they are also available in later modes
605 <table frame="all" xml:id="table.cxx26_headers">
606 <title>C++ 2026 Library Headers</title>
608 <tgroup cols="1" align="left" colsep="1" rowsep="1">
609 <colspec colname="c1"/>
611 <colspec colname="c2"/>
612 <colspec colname="c3"/>
613 <colspec colname="c4"/>
614 <colspec colname="c5"/>
618 <entry><filename class="headerfile">text_encoding</filename></entry>
619 <!-- TODO debugging, hazard_pointer, linalg, rcu -->
627 <xref linkend="table.filesystemts_headers"/>,
628 shows the additional include file define by the
629 File System Technical Specification, ISO/IEC TS 18822:2015.
630 This is available in C++11 and later compilation modes.
631 Including this header in earlier modes will not result in
632 compilation errors, but will not define anything.
636 <table frame="all" xml:id="table.filesystemts_headers">
637 <title>File System TS Header</title>
639 <tgroup cols="1" align="left" colsep="1" rowsep="1">
640 <colspec colname="c1"/>
643 <entry><filename class="headerfile">experimental/filesystem</filename></entry>
651 <xref linkend="table.libfundts_headers"/>,
652 shows the additional include files define by the C++ Extensions for
653 Library Fundamentals Technical Specification, ISO/IEC TS 19568:2015,
654 ISO/IEC TS 19568:2017, and ISO/IEC TS 19568:2024.
655 These are available in C++14 and later compilation modes, except for
656 <filename class="headerfile"><experimental/scope></filename>
657 which is available in C++20 and later compilation modes.
658 Including these headers in earlier modes will not result in
659 compilation errors, but will not define anything.
663 <table frame="all" xml:id="table.libfundts_headers">
664 <title>Library Fundamentals TS Headers</title>
666 <tgroup cols="5" align="left" colsep="1" rowsep="1">
667 <colspec colname="c1"/>
668 <colspec colname="c2"/>
669 <colspec colname="c3"/>
670 <colspec colname="c4"/>
671 <colspec colname="c5"/>
674 <entry><filename class="headerfile">experimental/algorithm</filename></entry>
675 <entry><filename class="headerfile">experimental/any</filename></entry>
676 <entry><filename class="headerfile">experimental/array</filename></entry>
677 <entry><filename class="headerfile">experimental/chrono</filename></entry>
678 <entry><filename class="headerfile">experimental/deque</filename></entry>
681 <entry><filename class="headerfile">experimental/forward_list</filename></entry>
682 <entry><filename class="headerfile">experimental/functional</filename></entry>
683 <entry><filename class="headerfile">experimental/iterator</filename></entry>
684 <entry><filename class="headerfile">experimental/list</filename></entry>
685 <entry><filename class="headerfile">experimental/map</filename></entry>
688 <entry><filename class="headerfile">experimental/memory</filename></entry>
689 <entry><filename class="headerfile">experimental/memory_resource</filename></entry>
690 <entry><filename class="headerfile">experimental/numeric</filename></entry>
691 <entry><filename class="headerfile">experimental/optional</filename></entry>
692 <entry><filename class="headerfile">experimental/propagate_const</filename></entry>
695 <entry><filename class="headerfile">experimental/random</filename></entry>
696 <entry><filename class="headerfile">experimental/ratio</filename></entry>
697 <entry><filename class="headerfile">experimental/regex</filename></entry>
698 <entry><filename class="headerfile">experimental/scope</filename></entry>
699 <entry><filename class="headerfile">experimental/set</filename></entry>
702 <entry><filename class="headerfile">experimental/source_location</filename></entry>
703 <entry><filename class="headerfile">experimental/string</filename></entry>
704 <entry><filename class="headerfile">experimental/string_view</filename></entry>
705 <entry><filename class="headerfile">experimental/system_error</filename></entry>
706 <entry><filename class="headerfile">experimental/tuple</filename></entry>
709 <entry><filename class="headerfile">experimental/type_traits</filename></entry>
710 <entry><filename class="headerfile">experimental/unordered_map</filename></entry>
711 <entry><filename class="headerfile">experimental/unordered_set</filename></entry>
712 <entry><filename class="headerfile">experimental/utility</filename></entry>
713 <entry><filename class="headerfile">experimental/vector</filename></entry>
721 <xref linkend="table.networkingts_headers"/>,
722 shows the additional include files define by the
723 Networking Technical Specification, ISO/IEC TS 19216:2018.
724 These are available in C++14 and later compilation modes.
725 Including these headers in earlier modes will not result in
726 compilation errors, but will not define anything.
730 <table frame="all" xml:id="table.networkingts_headers">
731 <title>Networking TS Headers</title>
733 <tgroup cols="4" align="left" colsep="1" rowsep="1">
734 <colspec colname="c1"/>
735 <colspec colname="c2"/>
736 <colspec colname="c3"/>
737 <colspec colname="c4"/>
740 <entry><filename class="headerfile">experimental/buffer</filename></entry>
741 <entry><filename class="headerfile">experimental/executor</filename></entry>
742 <entry><filename class="headerfile">experimental/internet</filename></entry>
743 <entry><filename class="headerfile">experimental/io_context</filename></entry>
746 <entry><filename class="headerfile">experimental/net</filename></entry>
747 <entry><filename class="headerfile">experimental/netfwd</filename></entry>
748 <entry><filename class="headerfile">experimental/socket</filename></entry>
749 <entry><filename class="headerfile">experimental/timer</filename></entry>
757 In addition, TR1 includes as:
760 <table frame="all" xml:id="table.tr1_headers">
761 <title>C++ TR 1 Library Headers</title>
763 <tgroup cols="5" align="left" colsep="1" rowsep="1">
764 <colspec colname="c1"/>
765 <colspec colname="c2"/>
766 <colspec colname="c3"/>
767 <colspec colname="c4"/>
768 <colspec colname="c5"/>
772 <entry><filename class="headerfile">tr1/array</filename></entry>
773 <entry><filename class="headerfile">tr1/complex</filename></entry>
774 <entry><filename class="headerfile">tr1/memory</filename></entry>
775 <entry><filename class="headerfile">tr1/functional</filename></entry>
776 <entry><filename class="headerfile">tr1/random</filename></entry>
779 <entry><filename class="headerfile">tr1/regex</filename></entry>
780 <entry><filename class="headerfile">tr1/tuple</filename></entry>
781 <entry><filename class="headerfile">tr1/type_traits</filename></entry>
782 <entry><filename class="headerfile">tr1/unordered_map</filename></entry>
783 <entry><filename class="headerfile">tr1/unordered_set</filename></entry>
786 <entry><filename class="headerfile">tr1/utility</filename></entry>
787 <entry namest="c2" nameend="c5"/>
797 <table frame="all" xml:id="table.tr1_cheaders">
798 <title>C++ TR 1 Library Headers for C Library Facilities</title>
800 <tgroup cols="5" align="left" colsep="1" rowsep="1">
801 <colspec colname="c1"/>
802 <colspec colname="c2"/>
803 <colspec colname="c3"/>
804 <colspec colname="c4"/>
805 <colspec colname="c5"/>
809 <entry><filename class="headerfile">tr1/ccomplex</filename></entry>
810 <entry><filename class="headerfile">tr1/cfenv</filename></entry>
811 <entry><filename class="headerfile">tr1/cfloat</filename></entry>
812 <entry><filename class="headerfile">tr1/cmath</filename></entry>
813 <entry><filename class="headerfile">tr1/cinttypes</filename></entry>
816 <entry><filename class="headerfile">tr1/climits</filename></entry>
817 <entry><filename class="headerfile">tr1/cstdarg</filename></entry>
818 <entry><filename class="headerfile">tr1/cstdbool</filename></entry>
819 <entry><filename class="headerfile">tr1/cstdint</filename></entry>
820 <entry><filename class="headerfile">tr1/cstdio</filename></entry>
823 <entry><filename class="headerfile">tr1/cstdlib</filename></entry>
824 <entry><filename class="headerfile">tr1/ctgmath</filename></entry>
825 <entry><filename class="headerfile">tr1/ctime</filename></entry>
826 <entry><filename class="headerfile">tr1/cwchar</filename></entry>
827 <entry><filename class="headerfile">tr1/cwctype</filename></entry>
835 <para>Decimal floating-point arithmetic is available if the C++
836 compiler supports scalar decimal floating-point types defined via
837 <code>__attribute__((mode(SD|DD|LD)))</code>.
840 <table frame="all" xml:id="table.decfp_headers">
841 <title>C++ TR 24733 Decimal Floating-Point Header</title>
843 <tgroup cols="1" align="left" colsep="1" rowsep="1">
844 <colspec colname="c1"/>
847 <entry><filename class="headerfile">decimal/decimal</filename></entry>
854 Also included are files for the C++ ABI interface:
857 <table frame="all" xml:id="table.abi_headers">
858 <title>C++ ABI Headers</title>
860 <tgroup cols="2" align="left" colsep="1" rowsep="1">
861 <colspec colname="c1"/>
862 <colspec colname="c2"/>
864 <row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row>
870 And a large variety of extensions.
873 <table frame="all" xml:id="table.ext_headers">
874 <title>Extension Headers</title>
876 <tgroup cols="5" align="left" colsep="1" rowsep="1">
877 <colspec colname="c1"/>
878 <colspec colname="c2"/>
879 <colspec colname="c3"/>
880 <colspec colname="c4"/>
881 <colspec colname="c5"/>
885 <entry><filename class="headerfile">ext/algorithm</filename></entry>
886 <entry><filename class="headerfile">ext/atomicity.h</filename></entry>
887 <entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry>
888 <entry><filename class="headerfile">ext/cast.h</filename></entry>
891 <entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry>
892 <entry><filename class="headerfile">ext/concurrence.h</filename></entry>
893 <entry><filename class="headerfile">ext/debug_allocator.h</filename></entry>
894 <entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry>
895 <entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry>
898 <entry><filename class="headerfile">ext/functional</filename></entry>
899 <entry><filename class="headerfile">ext/iterator</filename></entry>
900 <entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry>
901 <entry><filename class="headerfile">ext/memory</filename></entry>
902 <entry><filename class="headerfile">ext/mt_allocator.h</filename></entry>
905 <entry><filename class="headerfile">ext/new_allocator.h</filename></entry>
906 <entry><filename class="headerfile">ext/numeric</filename></entry>
907 <entry><filename class="headerfile">ext/numeric_traits.h</filename></entry>
908 <entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry>
909 <entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry>
912 <entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry>
913 <entry><filename class="headerfile">ext/pool_allocator.h</filename></entry>
914 <entry><filename class="headerfile">ext/rb_tree</filename></entry>
915 <entry><filename class="headerfile">ext/rope</filename></entry>
916 <entry><filename class="headerfile">ext/slist</filename></entry>
919 <entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry>
920 <entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry>
921 <entry><filename class="headerfile">ext/throw_allocator.h</filename></entry>
922 <entry><filename class="headerfile">ext/typelist.h</filename></entry>
923 <entry><filename class="headerfile">ext/type_traits.h</filename></entry>
926 <entry><filename class="headerfile">ext/vstring.h</filename></entry>
927 <entry namest="c2" nameend="c5"/>
936 <table frame="all" xml:id="table.debug_headers">
937 <title>Extension Debug Headers</title>
939 <tgroup cols="5" align="left" colsep="1" rowsep="1">
940 <colspec colname="c1"/>
941 <colspec colname="c2"/>
942 <colspec colname="c3"/>
943 <colspec colname="c4"/>
944 <colspec colname="c5"/>
948 <entry><filename class="headerfile">debug/array</filename></entry>
949 <entry><filename class="headerfile">debug/bitset</filename></entry>
950 <entry><filename class="headerfile">debug/deque</filename></entry>
951 <entry><filename class="headerfile">debug/forward_list</filename></entry>
952 <entry><filename class="headerfile">debug/list</filename></entry>
955 <entry><filename class="headerfile">debug/map</filename></entry>
956 <entry><filename class="headerfile">debug/set</filename></entry>
957 <entry><filename class="headerfile">debug/string</filename></entry>
958 <entry><filename class="headerfile">debug/unordered_map</filename></entry>
959 <entry><filename class="headerfile">debug/unordered_set</filename></entry>
962 <entry><filename class="headerfile">debug/vector</filename></entry>
963 <entry namest="c2" nameend="c5"/>
972 <table frame="all" xml:id="table.parallel_headers">
973 <title>Extension Parallel Headers</title>
975 <tgroup cols="2" align="left" colsep="1" rowsep="1">
976 <colspec colname="c1"/>
977 <colspec colname="c2"/>
980 <entry><filename class="headerfile">parallel/algorithm</filename></entry>
981 <entry><filename class="headerfile">parallel/numeric</filename></entry>
989 <section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info>
992 <para> A few simple rules.
995 <para>First, mixing different dialects of the standard headers is not
996 possible. It's an all-or-nothing affair. Thus, code like
1000 #include <array>
1001 #include <functional>
1004 <para>Implies C++11 mode. To use the entities in <array>, the C++11
1005 compilation mode must be used, which implies the C++11 functionality
1006 (and deprecations) in <functional> will be present.
1009 <para>Second, the other headers can be included with either dialect of
1010 the standard headers, although features and types specific to C++11
1011 are still only enabled when in C++11 compilation mode. So, to use
1012 rvalue references with <code>__gnu_cxx::vstring</code>, or to use the
1013 debug-mode versions of <code>std::unordered_map</code>, one must use
1014 the <code>std=gnu++11</code> compiler flag. (Or <code>std=c++11</code>, of course.)
1017 <para>A special case of the second rule is the mixing of TR1 and C++11
1018 facilities. It is possible (although not especially prudent) to
1019 include both the TR1 version and the C++11 version of header in the
1020 same translation unit:
1024 #include <tr1/type_traits>
1025 #include <type_traits>
1028 <para> Several parts of C++11 diverge quite substantially from TR1 predecessors.
1032 <section xml:id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"><info><title>The C Headers and <code>namespace std</code></title></info>
1036 The standard specifies that if one includes the C-style header
1037 (<math.h> in this case), the symbols will be available
1038 in the global namespace and perhaps in
1039 namespace <code>std::</code> (but this is no longer a firm
1040 requirement.) On the other hand, including the C++-style
1041 header (<cmath>) guarantees that the entities will be
1042 found in namespace std and perhaps in the global namespace.
1046 Usage of C++-style headers is recommended, as then
1047 C-linkage names can be disambiguated by explicit qualification, such
1048 as by <code>std::abort</code>. In addition, the C++-style headers can
1049 use function overloading to provide a simpler interface to certain
1050 families of C-functions. For instance in <cmath>, the
1051 function <code>std::sin</code> has overloads for all the builtin
1052 floating-point types. This means that <code>std::sin</code> can be
1053 used uniformly, instead of a combination
1054 of <code>std::sinf</code>, <code>std::sin</code>,
1055 and <code>std::sinl</code>.
1059 <section xml:id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"><info><title>Precompiled Headers</title></info>
1063 <para>There are three base header files that are provided. They can be
1064 used to precompile the standard headers and extensions into binary
1065 files that may then be used to speed up compilations that use these headers.
1071 <para>stdc++.h</para>
1072 <para>Includes all standard headers. Actual content varies depending on
1073 <link linkend="manual.intro.using.flags">language dialect</link>.
1078 <para>stdtr1c++.h</para>
1079 <para>Includes all of <stdc++.h>, and adds all the TR1 headers.
1083 <listitem><para>extc++.h</para>
1084 <para>Includes all of <stdc++.h>, and adds all the Extension headers
1085 (and in C++98 mode also adds all the TR1 headers by including all of
1086 <stdtr1c++.h>).
1090 <para>To construct a .gch file from one of these base header files,
1091 first find the include directory for the compiler. One way to do
1097 #include <...> search starts here:
1098 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
1104 <para>Then, create a precompiled header file with the same flags that
1105 will be used to compile other projects.</para>
1108 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
1111 <para>The resulting file will be quite large: the current size is around
1112 thirty megabytes. </para>
1114 <para>How to use the resulting file.</para>
1117 g++ -I. -include stdc++.h -H -g -O2 hello.cc
1120 <para>Verification that the PCH file is being used is easy:</para>
1123 g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
1125 . /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
1126 . /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
1129 <para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used.</para>
1132 <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>.
1139 <section xml:id="manual.intro.using.macros" xreflabel="Macros"><info><title>Macros</title></info>
1140 <?dbhtml filename="using_macros.html"?>
1144 All library macros begin with <code>_GLIBCXX_</code>.
1148 Furthermore, all pre-processor macros, switches, and
1149 configuration options are gathered in the
1150 file <filename class="headerfile">c++config.h</filename>, which
1151 is generated during the libstdc++ configuration and build
1152 process. This file is then included when needed by files part of
1153 the public libstdc++ API, like
1154 <filename class="headerfile"><ios></filename>. Most of these
1155 macros should not be used by consumers of libstdc++, and are reserved
1156 for internal implementation use. <emphasis>These macros cannot
1157 be redefined</emphasis>.
1161 A select handful of macros control libstdc++ extensions and extra
1162 features, or provide versioning information for the API. Only
1163 those macros listed below are offered for consideration by the
1167 <para>Below are the macros which users may check for library version
1168 information. </para>
1172 <term><code>_GLIBCXX_RELEASE</code></term>
1174 <para>The major release number for libstdc++. This macro is defined
1175 to the GCC major version that the libstdc++ headers belong to,
1176 as an integer constant.
1177 When compiling with GCC it has the same value as GCC's pre-defined
1178 macro <symbol>__GNUC__</symbol>.
1179 This macro can be used when libstdc++ is used with a non-GNU
1180 compiler where <symbol>__GNUC__</symbol> is not defined, or has a
1181 different value that doesn't correspond to the libstdc++ version.
1182 This macro first appeared in the GCC 7.1 release and is not defined
1183 for GCC 6.x or older releases.
1188 <term><code>__GLIBCXX__</code></term>
1190 <para>The revision date of the libstdc++ source code,
1191 in compressed ISO date format, as an unsigned
1192 long. For notes about using this macro and details on the value of
1193 this macro for a particular release, please consult the
1194 <link linkend="abi.versioning.__GLIBCXX__">ABI History</link>
1201 <para>Below are the macros which users may change with #define/#undef or
1202 with -D/-U compiler flags. The default state of the symbol is
1205 <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
1206 that the symbol is initially chosen (or not) based on
1207 --enable/--disable options at library build and configure time
1209 <link linkend="manual.intro.setup.configure">Configure</link>),
1210 with the various --enable/--disable choices being translated to
1214 <para> <acronym>ABI</acronym>-changing means that changing from the default value may
1215 mean changing the <acronym>ABI</acronym> of compiled code. In other words,
1216 these choices control code which has already been compiled (i.e., in a
1217 binary such as libstdc++.a/.so). If you explicitly #define or
1218 #undef these macros, the <emphasis>headers</emphasis> may see different code
1219 paths, but the <emphasis>libraries</emphasis> which you link against will not.
1220 Experimenting with different values with the expectation of
1221 consistent linkage requires changing the config headers before
1222 building/installing the library.
1226 <varlistentry><term><code>_GLIBCXX_USE_DEPRECATED</code></term>
1229 Defined to the value <literal>1</literal> by default.
1230 Not configurable. ABI-changing. Turning this off
1231 removes older ARM-style iostreams code, and other anachronisms
1232 from the API. This macro is dependent on the version of the
1233 standard being tracked, and as a result may give different results for
1234 different <code>-std</code> options. This may
1235 be useful in updating old C++ code which no longer meet the
1236 requirements of the language, or for checking current code
1237 against new language standards.
1239 </listitem></varlistentry>
1241 <varlistentry><term><code>_GLIBCXX_USE_CXX11_ABI</code></term>
1244 Defined to the value <literal>1</literal> by default.
1245 Configurable via <code>--disable-libstdcxx-dual-abi</code>
1246 and/or <code>--with-default-libstdcxx-abi</code>.
1248 When defined to a non-zero value the library headers will use the
1249 new C++11-conforming ABI introduced in GCC 5, rather than the older
1250 ABI introduced in GCC 3.4. This changes the definition of several
1251 class templates, including <classname>std:string</classname>,
1252 <classname>std::list</classname> and some locale facets.
1253 For more details see <xref linkend="manual.intro.using.abi"/>.
1255 </listitem></varlistentry>
1257 <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
1260 Undefined by default. Configurable via
1261 <code>--enable-concept-checks</code>. When defined, performs
1262 compile-time checking on certain template instantiations to
1263 detect violations of the requirements of the standard. This
1264 macro has no effect for freestanding implementations.
1265 This is described in more detail in
1266 <link linkend="manual.ext.compile_checks">Compile Time Checks</link>.
1268 </listitem></varlistentry>
1270 <varlistentry><term><code>_GLIBCXX_ASSERTIONS</code></term>
1273 Undefined by default. When defined, enables extra error checking in
1274 the form of precondition assertions, such as bounds checking in
1275 strings and null pointer checks when dereferencing smart pointers.
1277 </listitem></varlistentry>
1278 <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
1281 Undefined by default. When defined, compiles user code using
1282 the <link linkend="manual.ext.debug_mode">debug mode</link>.
1283 When defined, <code>_GLIBCXX_ASSERTIONS</code> is defined
1284 automatically, so all the assertions enabled by that macro are also
1285 enabled in debug mode.
1287 </listitem></varlistentry>
1288 <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
1291 Undefined by default. When defined while compiling with
1292 the <link linkend="manual.ext.debug_mode">debug mode</link>, makes
1293 the debug mode extremely picky by making the use of libstdc++
1294 extensions and libstdc++-specific behavior into errors.
1296 </listitem></varlistentry>
1297 <varlistentry><term><code>_GLIBCXX_DEBUG_BACKTRACE</code></term>
1300 Undefined by default. Considered only if libstdc++ has been configured with
1301 <option>--enable-libstdcxx-backtrace=yes</option> and if <code>_GLIBCXX_DEBUG</code>
1302 is defined. When defined display backtraces on
1303 <link linkend="manual.ext.debug_mode">debug mode</link> assertions.
1305 </listitem></varlistentry>
1306 <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
1308 <para>Undefined by default. When defined, compiles user code
1309 using the <link linkend="manual.ext.parallel_mode">parallel
1312 </listitem></varlistentry>
1313 <varlistentry><term><code>_GLIBCXX_PARALLEL_ASSERTIONS</code></term>
1315 <para>Undefined by default, but when any parallel mode header is included
1316 this macro will be defined to a non-zero value if
1317 <code>_GLIBCXX_ASSERTIONS</code> has a non-zero value, otherwise to zero.
1318 When defined to a non-zero value, it enables extra error checking and
1319 assertions in the parallel mode.
1321 </listitem></varlistentry>
1323 <varlistentry><term><code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code></term>
1325 <para>Undefined by default. When defined to a non-zero integer constant,
1326 enables support for ISO/IEC 29124 Special Math Functions.
1328 </listitem></varlistentry>
1330 <varlistentry><term><code>_GLIBCXX_SANITIZE_VECTOR</code></term>
1333 Undefined by default. When defined, <classname>std::vector</classname>
1334 operations will be annotated so that AddressSanitizer can detect
1335 invalid accesses to the unused capacity of a
1336 <classname>std::vector</classname>. These annotations are only
1338 <classname>std::vector<T, std::allocator<T>></classname>
1339 and only when <classname>std::allocator</classname> is derived from
1340 <link linkend="allocator.ext"><classname>new_allocator</classname>
1341 or <classname>malloc_allocator</classname></link>. The annotations
1342 must be present on all vector operations or none, so this macro must
1343 be defined to the same value for all translation units that create,
1344 destroy, or modify vectors.
1346 </listitem></varlistentry>
1351 <section xml:id="manual.intro.using.abi" xreflabel="Dual ABI">
1352 <info><title>Dual ABI</title></info>
1353 <?dbhtml filename="using_dual_abi.html"?>
1355 <para> In the GCC 5.1 release libstdc++ introduced a new library ABI that
1356 includes new implementations of <classname>std::string</classname> and
1357 <classname>std::list</classname>. These changes were necessary to conform
1358 to the 2011 C++ standard which forbids Copy-On-Write strings and requires
1359 lists to keep track of their size.
1362 <para> In order to maintain backwards compatibility for existing code linked
1363 to libstdc++ the library's soname has not changed and the old
1364 implementations are still supported in parallel with the new ones.
1365 This is achieved by defining the new implementations in an inline namespace
1366 so they have different names for linkage purposes, e.g. the new version of
1367 <classname>std::list<int></classname> is actually defined as
1368 <classname>std::__cxx11::list<int></classname>. Because the symbols
1369 for the new implementations have different names the definitions for both
1370 versions can be present in the same library.
1373 <para> The <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro (see
1374 <xref linkend="manual.intro.using.macros"/>) controls whether
1375 the declarations in the library headers use the old or new ABI.
1376 So the decision of which ABI to use can be made separately for each
1377 source file being compiled.
1378 Using the default configuration options for GCC the default value
1379 of the macro is <literal>1</literal> which causes the new ABI to be active,
1380 so to use the old ABI you must explicitly define the macro to
1381 <literal>0</literal> before including any library headers.
1382 (Be aware that some GNU/Linux distributions configure GCC 5 differently so
1383 that the default value of the macro is <literal>0</literal> and users must
1384 define it to <literal>1</literal> to enable the new ABI.)
1387 <para> Although the changes were made for C++11 conformance, the choice of ABI
1388 to use is independent of the <option>-std</option> option used to compile
1389 your code, i.e. for a given GCC build the default value of the
1390 <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro is the same for all dialects.
1391 This ensures that the <option>-std</option> does not change the ABI, so
1392 that it is straightforward to link C++03 and C++11 code together.
1395 <para> Because <classname>std::string</classname> is used extensively
1396 throughout the library a number of other types are also defined twice,
1397 including the stringstream classes and several facets used by
1398 <classname>std::locale</classname>. The standard facets which are always
1399 installed in a locale may be present twice, with both ABIs, to ensure that
1401 <code>std::use_facet<std::time_get<char>>(locale);</code>
1402 will work correctly for both <classname>std::time_get</classname> and
1403 <classname>std::__cxx11::time_get</classname> (even if a user-defined
1404 facet that derives from one or other version of
1405 <classname>time_get</classname> is installed in the locale).
1408 <para> Although the standard exception types defined in
1409 <filename class="headerfile"><stdexcept></filename> use strings, most
1410 are not defined twice, so that a <classname>std::out_of_range</classname>
1411 exception thrown in one file can always be caught by a suitable handler in
1412 another file, even if the two files are compiled with different ABIs.
1415 <para> One exception type does change when using the new ABI, namely
1416 <classname>std::ios_base::failure</classname>.
1417 This is necessary because the 2011 standard changed its base class from
1418 <classname>std::exception</classname> to
1419 <classname>std::system_error</classname>, which causes its layout to change.
1420 Exceptions due to iostream errors are thrown by a function inside
1421 <filename class="libraryfile">libstdc++.so</filename>, so whether the thrown
1422 exception uses the old <classname>std::ios_base::failure</classname> type
1423 or the new one depends on the ABI that was active when
1424 <filename class="libraryfile">libstdc++.so</filename> was built,
1425 <emphasis>not</emphasis> the ABI active in the user code that is using
1427 This means that for a given build of GCC the type thrown is fixed.
1428 In current releases the library throws a special type that can be caught
1429 by handlers for either the old or new type,
1430 but for GCC 7.1, 7.2 and 7.3 the library throws the new
1431 <classname>std::ios_base::failure</classname> type,
1432 and for GCC 5.x and 6.x the library throws the old type.
1433 Catch handlers of type <classname>std::ios_base::failure</classname>
1434 will only catch the exceptions if using a newer release,
1435 or if the handler is compiled with the same ABI as the type thrown by
1437 Handlers for <classname>std::exception</classname> will always catch
1438 iostreams exceptions, because the old and new type both inherit from
1439 <classname>std::exception</classname>.
1442 <section xml:id="manual.intro.using.abi.trouble" xreflabel="Dual ABI Troubleshooting"><info><title>Troubleshooting</title></info>
1444 <para> If you get linker errors about undefined references to symbols
1445 that involve types in the <code>std::__cxx11</code> namespace or the tag
1446 <code>[abi:cxx11]</code> then it probably indicates that you are trying to
1447 link together object files that were compiled with different values for the
1448 <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro. This commonly happens when
1449 linking to a third-party library that was compiled with an older version
1450 of GCC. If the third-party library cannot be rebuilt with the new ABI then
1451 you will need to recompile your code with the old ABI.
1454 <para> Not all uses of the new ABI will cause changes in symbol names, for
1455 example a class with a <classname>std::string</classname> member variable
1456 will have the same mangled name whether compiled with the old or new ABI.
1457 In order to detect such problems the new types and functions are
1458 annotated with the <property>abi_tag</property> attribute, allowing the
1459 compiler to warn about potential ABI incompatibilities in code using them.
1460 Those warnings can be enabled with the <option>-Wabi-tag</option> option.
1466 <section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
1467 <?dbhtml filename="using_namespaces.html"?>
1470 <section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info>
1475 <para> There are three main namespaces.
1479 <listitem><para>std</para>
1480 <para>The ISO C++ standards specify that "all library entities are defined
1481 within namespace std." This includes namespaces nested
1482 within namespace <code>std</code>, such as namespace
1483 <code>std::chrono</code>.
1486 <listitem><para>abi</para>
1487 <para>Specified by the C++ ABI. This ABI specifies a number of type and
1488 function APIs supplemental to those required by the ISO C++ Standard,
1489 but necessary for interoperability.
1493 <listitem><para>__gnu_</para>
1494 <para>Indicating one of several GNU extensions. Choices
1495 include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
1496 and <code>__gnu_pbds</code>.
1500 <para> The library uses a number of inline namespaces as implementation
1501 details that are not intended for users to refer to directly, these include
1502 <code>std::__detail</code>, <code>std::__cxx11</code> and <code>std::_V2</code>.
1505 <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>.
1511 <section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info>
1516 One standard requirement is that the library components are defined
1517 in <code>namespace std::</code>. Thus, in order to use these types or
1518 functions, one must do one of two things:
1522 <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source
1523 (either <code>using namespace std;</code> or i.e. <code>using
1524 std::string;</code>) This approach works well for individual source files, but
1525 should not be used in a global context, like header files.
1526 </para></listitem> <listitem><para>use a <emphasis>fully
1527 qualified name</emphasis> for each library symbol
1528 (i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
1529 used, and usually enhanced, by strategic use of typedefs. (In the
1530 cases where the qualified verbiage becomes unwieldy.)
1537 <section xml:id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"><info><title>Using Namespace Composition</title></info>
1541 Best practice in programming suggests sequestering new data or
1542 functionality in a sanely-named, unique namespace whenever
1543 possible. This is considered an advantage over dumping everything in
1544 the global namespace, as then name look-up can be explicitly enabled or
1545 disabled as above, symbols are consistently mangled without repetitive
1546 naming prefixes or macros, etc.
1549 <para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
1550 adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
1551 <emphasis>namespace composition</emphasis>. This is what happens if
1552 a <emphasis>using</emphasis>-declaration is put into a
1553 namespace-definition: the imported symbol(s) gets imported into the
1554 currently active namespace(s). For example:
1560 using std::tr1::array;
1562 class Window { ... };
1566 In this example, <code>std::string</code> gets imported into
1567 <code>namespace gtk</code>. The result is that use of
1568 <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
1570 <code>std::string</code> does not get imported into
1571 the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
1572 <code>using</code>-declarations can wrapped in macros that
1573 are set based on autoconf-tests to either "" or i.e. <code>using
1574 std::string;</code> (depending on whether the system has
1575 libstdc++ in <code>std::</code> or not). (ideas from
1576 Llewelly and Karl Nelson)
1583 <section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info>
1584 <?dbhtml filename="using_dynamic_or_shared.html"?>
1587 <section xml:id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"><info><title>Almost Nothing</title></info>
1590 Or as close as it gets: freestanding. This is a minimal
1591 configuration, with only partial support for the standard
1592 library. Assume only the following header files can be used:
1598 <filename class="headerfile">cstdarg</filename>
1604 <filename class="headerfile">cstddef</filename>
1610 <filename class="headerfile">cstdlib</filename>
1616 <filename class="headerfile">exception</filename>
1622 <filename class="headerfile">limits</filename>
1628 <filename class="headerfile">new</filename>
1634 <filename class="headerfile">exception</filename>
1640 <filename class="headerfile">typeinfo</filename>
1646 In addition, throw in
1652 <filename class="headerfile">cxxabi.h</filename>.
1659 C++11 <link linkend="manual.intro.using.flags">dialect</link> add
1665 <filename class="headerfile">initializer_list</filename>
1670 <filename class="headerfile">type_traits</filename>
1676 As of GCC 13, libstdc++ implements P1642, which brings in many more
1677 headers, as well a quite a few ones not covered by the paper.
1679 In general, if a feature does not require traditionally libc-provided
1680 facilities, or dynamic memory allocation, it's enabled in the
1681 freestanding subset. In addition, if only a subset of a header
1682 requires such features, it is partially included. Some examples
1689 <filename class="headerfile">string_view</filename>
1694 <filename class="headerfile">tuple</filename>
1699 <filename class="headerfile">bitset</filename>
1705 Currently, this subset includes all of the iterator APIs (including the
1706 ranges APIs) that do not involve streams, the entire C++ algorithms
1707 library, excluding parallel algorithms, and a large part of the
1708 utilities library. This is on top of the headers included in the lists
1713 If you're using a libstdc++ configured for hosted environments, and
1714 would like to not involve the libraries libstdc++ would depend on in
1715 your programs, you will need to use <command>gcc</command> to link your
1716 application with only <filename class="libraryfile">libsupc++.a</filename>,
1721 <command>gcc -ffreestanding foo.cc -lsupc++</command>
1725 If you configured libstdc++ with
1726 <code>--disable-hosted-libstdcxx</code>, however, you can use the
1727 normal <command>g++</command> command to link, as this configuration
1728 provides a (nearly) empty <filename class="libraryfile">libstdc++.a</filename>.
1732 <section xml:id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"><info><title>Finding Dynamic or Shared Libraries</title></info>
1736 If the only library built is the static library
1737 (<filename class="libraryfile">libstdc++.a</filename>), or if
1738 specifying static linking, this section is can be skipped. But
1739 if building or using a shared library
1740 (<filename class="libraryfile">libstdc++.so</filename>), then
1741 additional location information will need to be provided.
1747 A quick read of the relevant part of the GCC
1748 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
1749 C++ Programs</link>, specifies linking against a C++
1750 library. More details from the
1751 GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/faq.html#rpath">FAQ</link>,
1752 which states <emphasis>GCC does not, by default, specify a
1753 location so that the dynamic linker can find dynamic libraries at
1757 Users will have to provide this information.
1760 Methods vary for different platforms and different styles, and
1761 are printed to the screen during installation. To summarize:
1766 At runtime set <literal>LD_LIBRARY_PATH</literal> in your
1767 environment correctly, so that the shared library for
1768 libstdc++ can be found and loaded. Be certain that you
1769 understand all of the other implications and behavior
1770 of <literal>LD_LIBRARY_PATH</literal> first.
1776 Compile the path to find the library at runtime into the
1777 program. This can be done by passing certain options to
1778 <command>g++</command>, which will in turn pass them on to
1779 the linker. The exact format of the options is dependent on
1780 which linker you use:
1785 GNU ld (default on GNU/Linux):
1786 <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename>
1792 <literal>-Wl,-R</literal><filename class="directory">destdir/lib</filename>
1799 Some linkers allow you to specify the path to the library by
1800 setting <literal>LD_RUN_PATH</literal> in your environment
1806 On some platforms the system administrator can configure the
1807 dynamic linker to always look for libraries in
1808 <filename class="directory">destdir/lib</filename>, for example
1809 by using the <command>ldconfig</command> utility on GNU/Linux
1810 or the <command>crle</command> utility on Solaris. This is a
1811 system-wide change which can make the system unusable so if you
1812 are unsure then use one of the other methods described above.
1817 Use the <command>ldd</command> utility on the linked executable
1819 which <filename class="libraryfile">libstdc++.so</filename>
1820 library the system will get at runtime.
1823 A <filename class="libraryfile">libstdc++.la</filename> file is
1824 also installed, for use with Libtool. If you use Libtool to
1825 create your executables, these details are taken care of for
1830 <section xml:id="manual.intro.using.linkage.experimental" xreflabel="Library Extensions"><info><title>Experimental Library Extensions</title></info>
1833 GCC 5.3 includes an implementation of the Filesystem library defined
1834 by the technical specification ISO/IEC TS 18822:2015. Because this is
1835 an experimental library extension, not part of the C++ standard, it
1836 is implemented in a separate library,
1837 <filename class="libraryfile">libstdc++fs.a</filename>, and there is
1838 no shared library for it. To use the library you should include
1839 <filename class="headerfile"><experimental/filesystem></filename>
1840 and link with <option>-lstdc++fs</option>. The library implementation
1841 is incomplete on non-POSIX platforms, specifically Windows is only
1842 partially supported.
1843 Since GCC 14, <filename class="libraryfile">libstdc++exp.a</filename>
1844 also contains the definitions for this library,
1845 so <option>-lstdc++exp</option> can be used instead of
1846 <option>-lstdc++fs</option>.
1850 GCC 13 includes an implementation of the C++ Contracts library defined by
1851 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1429r3.pdf">P1429R3</link>.
1852 Because this is an experimental extension, not part of the C++ standard,
1853 it is implemented in a separate library,
1854 <filename class="libraryfile">libstdc++exp.a</filename>, and there is
1855 no shared library for it. To use the library you should include
1856 <filename class="headerfile"><experimental/contract></filename>
1857 and link with <option>-lstdc++exp</option>.
1861 Due to the experimental nature of these libraries the usual
1862 guarantees about ABI stability and backwards compatibility do not apply
1863 to them. There is no guarantee that the components in any
1864 <filename class="headerfile"><experimental/xxx></filename>
1865 header will remain compatible between different GCC releases.
1871 <section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
1872 <?dbhtml filename="using_concurrency.html"?>
1875 <para>This section discusses issues surrounding the proper compilation
1876 of multithreaded applications which use the Standard C++
1877 library. This information is GCC-specific since the C++
1878 standard does not address matters of multithreaded applications.
1881 <section xml:id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"><info><title>Prerequisites</title></info>
1884 <para>All normal disclaimers aside, multithreaded C++ application are
1885 only supported when libstdc++ and all user code was built with
1886 compilers which report (via <code> gcc/g++ -v </code>) the same thread
1887 model and that model is not <emphasis>single</emphasis>. As long as your
1888 final application is actually single-threaded, then it should be
1889 safe to mix user code built with a thread model of
1890 <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built
1891 with another thread model useful on the platform. Other mixes
1892 may or may not work but are not considered supported. (Thus, if
1893 you distribute a shared C++ library in binary form only, it may
1894 be best to compile it with a GCC configured with
1895 --enable-threads for maximal interchangeability and usefulness
1896 with a user population that may have built GCC with either
1897 --enable-threads or --disable-threads.)
1899 <para>When you link a multithreaded application, you will probably
1900 need to add a library or flag to g++. This is a very
1901 non-standardized area of GCC across ports. Some ports support a
1902 special flag (the spelling isn't even standardized yet) to add
1903 all required macros to a compilation (if any such flags are
1904 required then you must provide the flag for all compilations not
1905 just linking) and link-library additions and/or replacements at
1906 link time. The documentation is weak. On several targets (including
1907 GNU/Linux, Solaris and various BSDs) -pthread is honored.
1908 Some other ports use other switches.
1909 This is not well documented anywhere other than
1910 in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries).
1914 Some uses of <classname>std::atomic</classname> also require linking
1915 to <filename class="libraryfile">libatomic</filename>.
1920 <section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info>
1924 In the terms of the 2011 C++ standard a thread-safe program is one which
1925 does not perform any conflicting non-atomic operations on memory locations
1926 and so does not contain any data races.
1927 The standard places requirements on the library to ensure that no data
1928 races are caused by the library itself or by programs which use the
1929 library correctly (as described below).
1930 The C++11 memory model and library requirements are a more formal version
1931 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
1932 prior to the 2011 standard.
1936 <para>The library strives to be thread-safe when all of the following
1941 <para>The system's libc is itself thread-safe,
1946 The compiler in use reports a thread model other than
1947 'single'. This can be tested via output from <code>gcc
1948 -v</code>. Multi-thread capable versions of gcc output
1949 something like this:
1953 Using built-in specs.
1956 gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
1959 <para>Look for "Thread model" lines that aren't equal to "single."</para>
1963 Requisite command-line flags are used for atomic operations
1964 and threading. Examples of this include <code>-pthread</code>
1965 and <code>-march=native</code>, although specifics vary
1966 depending on the host environment. See
1967 <link linkend="manual.intro.using.flags">Command Options</link> and
1968 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
1969 Dependent Options</link>.
1974 An implementation of the
1975 <filename class="headerfile">atomicity.h</filename> functions
1976 exists for the architecture in question. See the
1977 <link linkend="internals.thread_safety">internals
1978 documentation</link> for more details.
1984 <para>The user code must guard against concurrent function calls which
1985 access any particular library object's state when one or more of
1986 those accesses modifies the state. An object will be modified by
1987 invoking a non-const member function on it or passing it as a
1988 non-const argument to a library function. An object will not be
1989 modified by invoking a const member function on it or passing it to
1990 a function as a pointer- or reference-to-const.
1991 Typically, the application
1992 programmer may infer what object locks must be held based on the
1993 objects referenced in a function call and whether the objects are
1994 accessed as const or non-const. Without getting
1995 into great detail, here is an example which requires user-level
1999 library_class_a shared_object_a;
2001 void thread_main () {
2002 library_class_b *object_b = new library_class_b;
2003 shared_object_a.add_b (object_b); // must hold lock for shared_object_a
2004 shared_object_a.mutate (); // must hold lock for shared_object_a
2007 // Multiple copies of thread_main() are started in independent threads.</programlisting>
2008 <para>Under the assumption that object_a and object_b are never exposed to
2009 another thread, here is an example that does not require any
2013 void thread_main () {
2014 library_class_a object_a;
2015 library_class_b *object_b = new library_class_b;
2016 object_a.add_b (object_b);
2020 <para>All library types are safe to use in a multithreaded program
2021 if objects are not shared between threads or as
2022 long each thread carefully locks out access by any other
2023 thread while it modifies any object visible to another thread.
2024 Unless otherwise documented, the only exceptions to these rules
2025 are atomic operations on the types in
2026 <filename class="headerfile"><atomic></filename>
2027 and lock/unlock operations on the standard mutex types in
2028 <filename class="headerfile"><mutex></filename>. These
2029 atomic operations allow concurrent accesses to the same object
2030 without introducing data races.
2033 <para>The following member functions of standard containers can be
2034 considered to be const for the purposes of avoiding data races:
2035 <code>begin</code>, <code>end</code>, <code>rbegin</code>, <code>rend</code>,
2036 <code>front</code>, <code>back</code>, <code>data</code>,
2037 <code>find</code>, <code>lower_bound</code>, <code>upper_bound</code>,
2038 <code>equal_range</code>, <code>at</code>
2039 and, except in associative or unordered associative containers,
2040 <code>operator[]</code>. In other words, although they are non-const
2041 so that they can return mutable iterators, those member functions
2042 will not modify the container.
2043 Accessing an iterator might cause a non-modifying access to
2044 the container the iterator refers to (for example incrementing a
2045 list iterator must access the pointers between nodes, which are part
2046 of the container and so conflict with other accesses to the container).
2049 <para>Programs which follow the rules above will not encounter data
2050 races in library code, even when using library types which share
2051 state between distinct objects. In the example below the
2052 <code>shared_ptr</code> objects share a reference count, but
2053 because the code does not perform any non-const operations on the
2054 globally-visible object, the library ensures that the reference
2055 count updates are atomic and do not introduce data races:
2058 std::shared_ptr<int> global_sp;
2060 void thread_main() {
2061 auto local_sp = global_sp; // OK, copy constructor's parameter is reference-to-const
2063 int i = *global_sp; // OK, operator* is const
2064 int j = *local_sp; // OK, does not operate on global_sp
2066 // *global_sp = 2; // NOT OK, modifies int visible to other threads
2067 // *local_sp = 2; // NOT OK, modifies int visible to other threads
2069 // global_sp.reset(); // NOT OK, reset is non-const
2070 local_sp.reset(); // OK, does not operate on global_sp
2074 global_sp.reset(new int(1));
2075 std::thread t1(thread_main);
2076 std::thread t2(thread_main);
2082 <para>For further details of the C++11 memory model see Hans-J. Boehm's
2083 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/">Threads
2084 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>
2085 and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/user-faq.html">FAQ</link>.
2089 <section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info>
2095 <section xml:id="manual.intro.using.concurrency.io" xreflabel="IO"><info><title>IO</title></info>
2097 <para>This gets a bit tricky. Please read carefully, and bear with me.
2100 <section xml:id="concurrency.io.structure" xreflabel="Structure"><info><title>Structure</title></info>
2103 type called <code>__basic_file</code> provides our abstraction layer
2104 for the <code>std::filebuf</code> classes. Nearly all decisions dealing
2105 with actual input and output must be made in <code>__basic_file</code>.
2107 <para>A generic locking mechanism is somewhat in place at the filebuf layer,
2108 but is not used in the current code. Providing locking at any higher
2109 level is akin to providing locking within containers, and is not done
2110 for the same reasons (see the links above).
2114 <section xml:id="concurrency.io.defaults" xreflabel="Defaults"><info><title>Defaults</title></info>
2116 <para>The __basic_file type is simply a collection of small wrappers around
2117 the C stdio layer (again, see the link under Structure). We do no
2118 locking ourselves, but simply pass through to calls to <code>fopen</code>,
2119 <code>fwrite</code>, and so forth.
2121 <para>So, for 3.0, the question of "is multithreading safe for I/O"
2122 must be answered with, "is your platform's C library threadsafe
2123 for I/O?" Some are by default, some are not; many offer multiple
2124 implementations of the C library with varying tradeoffs of threadsafety
2125 and efficiency. You, the programmer, are always required to take care
2126 with multiple threads.
2128 <para>(As an example, the POSIX standard requires that C stdio
2129 <code>FILE*</code> operations are atomic. POSIX-conforming C libraries
2130 (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize
2131 operations on <code>FILE*</code>s.
2132 However, you still need to not do stupid things like calling
2133 <code>fclose(fs)</code> in one thread followed by an access of
2134 <code>fs</code> in another.)
2136 <para>So, if your platform's C library is threadsafe, then your
2137 <code>fstream</code> I/O operations will be threadsafe at the lowest
2138 level. For higher-level operations, such as manipulating the data
2139 contained in the stream formatting classes (e.g., setting up callbacks
2140 inside an <code>std::ofstream</code>), you need to guard such accesses
2141 like any other critical shared resource.
2145 <section xml:id="concurrency.io.future" xreflabel="Future"><info><title>Future</title></info>
2148 second choice may be available for I/O implementations: libio. This is
2149 disabled by default, and in fact will not currently work due to other
2150 issues. It will be revisited, however.
2152 <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O
2153 implementation. When libio is in use, the <code>__basic_file</code>
2154 type is basically derived from FILE. (The real situation is more
2155 complex than that... it's derived from an internal type used to
2156 implement FILE. See libio/libioP.h to see scary things done with
2157 vtbls.) The result is that there is no "layer" of C stdio
2158 to go through; the filebuf makes calls directly into the same
2159 functions used to implement <code>fread</code>, <code>fwrite</code>,
2160 and so forth, using internal data structures. (And when I say
2161 "makes calls directly," I mean the function is literally
2162 replaced by a jump into an internal function. Fast but frightening.
2165 <para>Also, the libio internal locks are used. This requires pulling in
2166 large chunks of glibc, such as a pthreads implementation, and is one
2167 of the issues preventing widespread use of libio as the libstdc++
2168 cstdio implementation.
2170 <para>But we plan to make this work, at least as an option if not a future
2171 default. Platforms running a copy of glibc with a recent-enough
2172 version will see calls from libstdc++ directly into the glibc already
2173 installed. For other platforms, a copy of the libio subsection will
2174 be built and included in libstdc++.
2178 <section xml:id="concurrency.io.alt" xreflabel="Alt"><info><title>Alternatives</title></info>
2180 <para>Don't forget that other cstdio implementations are possible. You could
2181 easily write one to perform your own forms of locking, to solve your
2182 "interesting" problems.
2188 <section xml:id="manual.intro.using.concurrency.containers" xreflabel="Containers"><info><title>Containers</title></info>
2191 <para>This section discusses issues surrounding the design of
2192 multithreaded applications which use Standard C++ containers.
2193 All information in this section is current as of the gcc 3.0
2194 release and all later point releases. Although earlier gcc
2195 releases had a different approach to threading configuration and
2196 proper compilation, the basic code design rules presented here
2197 were similar. For information on all other aspects of
2198 multithreading as it relates to libstdc++, including details on
2199 the proper compilation of threaded code (and compatibility between
2200 threaded and non-threaded code), see Chapter 17.
2202 <para>Two excellent pages to read when working with the Standard C++
2203 containers and threads are
2204 <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
2205 https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html</link> and
2206 <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
2207 https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/Allocators.html</link>.
2209 <para><emphasis>However, please ignore all discussions about the user-level
2210 configuration of the lock implementation inside the STL
2211 container-memory allocator on those pages. For the sake of this
2212 discussion, libstdc++ configures the SGI STL implementation,
2213 not you. This is quite different from how gcc pre-3.0 worked.
2214 In particular, past advice was for people using g++ to
2215 explicitly define _PTHREADS or other macros or port-specific
2216 compilation options on the command line to get a thread-safe
2217 STL. This is no longer required for any port and should no
2218 longer be done unless you really know what you are doing and
2219 assume all responsibility.</emphasis>
2221 <para>Since the container implementation of libstdc++ uses the SGI
2222 code, we use the same definition of thread safety as SGI when
2223 discussing design. A key point that beginners may miss is the
2224 fourth major paragraph of the first page mentioned above
2225 (<emphasis>For most clients...</emphasis>), which points out that
2226 locking must nearly always be done outside the container, by
2227 client code (that'd be you, not us). There is a notable
2228 exceptions to this rule. Allocators called while a container or
2229 element is constructed uses an internal lock obtained and
2230 released solely within libstdc++ code (in fact, this is the
2231 reason STL requires any knowledge of the thread configuration).
2233 <para>For implementing a container which does its own locking, it is
2234 trivial to provide a wrapper class which obtains the lock (as
2235 SGI suggests), performs the container operation, and then
2236 releases the lock. This could be templatized <emphasis>to a certain
2237 extent</emphasis>, on the underlying container and/or a locking
2238 mechanism. Trying to provide a catch-all general template
2239 solution would probably be more trouble than it's worth.
2241 <para>The library implementation may be configured to use the
2242 high-speed caching memory allocator, which complicates thread
2243 safety issues. For all details about how to globally override
2244 this at application run-time
2245 see <link linkend="manual.intro.using.macros">here</link>. Also
2247 on <link linkend="std.util.memory.allocator">allocator</link>
2248 options and capabilities.
2254 <!-- Section 0x : Exception policies, expectations, topics -->
2255 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="using_exceptions.xml">
2258 <!-- Section 0x : Debug -->
2259 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="debug.xml">