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++14</command> since GCC 6, and
20 <command>g++ -std=gnu++98</command> for older releases.
23 <table frame="all" xml:id="table.cmd_options">
24 <title>C++ Command Options</title>
26 <tgroup cols="2" align="left" colsep="1" rowsep="1">
27 <colspec colname="c1"/>
28 <colspec colname="c2"/>
32 <entry>Option Flags</entry>
33 <entry>Description</entry>
39 <entry><literal>-std=c++98</literal> or <literal>-std=c++03</literal>
41 <entry>Use the 1998 ISO C++ standard plus amendments.</entry>
45 <entry><literal>-std=gnu++98</literal> or <literal>-std=gnu++03</literal>
47 <entry>As directly above, with GNU extensions.</entry>
51 <entry><literal>-std=c++11</literal></entry>
52 <entry>Use the 2011 ISO C++ standard.</entry>
56 <entry><literal>-std=gnu++11</literal></entry>
57 <entry>As directly above, with GNU extensions.</entry>
61 <entry><literal>-std=c++14</literal></entry>
62 <entry>Use the 2014 ISO C++ standard.</entry>
66 <entry><literal>-std=gnu++14</literal></entry>
67 <entry>As directly above, with GNU extensions.</entry>
71 <entry><literal>-fexceptions</literal></entry>
72 <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry>
76 <entry><literal>-frtti</literal></entry>
77 <entry>As above, but RTTI-free dialect.</entry>
81 <entry><literal>-pthread</literal></entry>
83 <filename class="headerfile"><thread></filename>,
84 <filename class="headerfile"><future></filename>,
85 <filename class="headerfile"><mutex></filename>,
86 or <filename class="headerfile"><condition_variable></filename>.
91 <entry><literal>-latomic</literal></entry>
92 <entry>Linking to <filename class="libraryfile">libatomic</filename>
93 is required for some uses of ISO C++11
94 <filename class="headerfile"><atomic></filename>.
99 <entry><literal>-lstdc++fs</literal></entry>
100 <entry>Linking to <filename class="libraryfile">libstdc++fs</filename>
101 is required for use of the Filesystem library extensions in
102 <filename class="headerfile"><experimental/filesystem></filename>
103 and the C++17 Filesystem library in
104 <filename class="headerfile"><filesystem></filename>.
109 <entry><literal>-fopenmp</literal></entry>
110 <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
119 <section xml:id="manual.intro.using.headers" xreflabel="Headers"><info><title>Headers</title></info>
120 <?dbhtml filename="using_headers.html"?>
123 <section xml:id="manual.intro.using.headers.all" xreflabel="Header Files"><info><title>Header Files</title></info>
127 The C++ standard specifies the entire set of header files that
128 must be available to all hosted implementations. Actually, the
129 word "files" is a misnomer, since the contents of the
130 headers don't necessarily have to be in any kind of external
131 file. The only rule is that when one <code>#include</code>s a
132 header, the contents of that header become available, no matter
137 That said, in practice files are used.
141 There are two main types of include files: header files related
142 to a specific version of the ISO C++ standard (called Standard
143 Headers), and all others (TS, TR1, C++ ABI, and Extensions).
147 Multiple dialects of standard headers are supported, corresponding to
148 the 1998 standard as updated for 2003, the 2011 standard, the 2014
153 <xref linkend="table.cxx98_headers"/> and
154 <xref linkend="table.cxx98_cheaders"/> and
155 <xref linkend="table.cxx98_deprheaders"/>
156 show the C++98/03 include files.
157 These are available in the C++98 compilation mode,
158 i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>.
159 Unless specified otherwise below, they are also available in later modes
163 <table frame="all" xml:id="table.cxx98_headers">
164 <title>C++ 1998 Library Headers</title>
166 <tgroup cols="5" align="left" colsep="1" rowsep="1">
167 <colspec colname="c1"/>
168 <colspec colname="c2"/>
169 <colspec colname="c3"/>
170 <colspec colname="c4"/>
171 <colspec colname="c5"/>
174 <entry><filename class="headerfile">algorithm</filename></entry>
175 <entry><filename class="headerfile">bitset</filename></entry>
176 <entry><filename class="headerfile">complex</filename></entry>
177 <entry><filename class="headerfile">deque</filename></entry>
178 <entry><filename class="headerfile">exception</filename></entry>
181 <entry><filename class="headerfile">fstream</filename></entry>
182 <entry><filename class="headerfile">functional</filename></entry>
183 <entry><filename class="headerfile">iomanip</filename></entry>
184 <entry><filename class="headerfile">ios</filename></entry>
185 <entry><filename class="headerfile">iosfwd</filename></entry>
188 <entry><filename class="headerfile">iostream</filename></entry>
189 <entry><filename class="headerfile">istream</filename></entry>
190 <entry><filename class="headerfile">iterator</filename></entry>
191 <entry><filename class="headerfile">limits</filename></entry>
192 <entry><filename class="headerfile">list</filename></entry>
195 <entry><filename class="headerfile">locale</filename></entry>
196 <entry><filename class="headerfile">map</filename></entry>
197 <entry><filename class="headerfile">memory</filename></entry>
198 <entry><filename class="headerfile">new</filename></entry>
199 <entry><filename class="headerfile">numeric</filename></entry>
202 <entry><filename class="headerfile">ostream</filename></entry>
203 <entry><filename class="headerfile">queue</filename></entry>
204 <entry><filename class="headerfile">set</filename></entry>
205 <entry><filename class="headerfile">sstream</filename></entry>
206 <entry><filename class="headerfile">stack</filename></entry>
209 <entry><filename class="headerfile">stdexcept</filename></entry>
210 <entry><filename class="headerfile">streambuf</filename></entry>
211 <entry><filename class="headerfile">string</filename></entry>
212 <entry><filename class="headerfile">utility</filename></entry>
213 <entry><filename class="headerfile">typeinfo</filename></entry>
216 <entry><filename class="headerfile">valarray</filename></entry>
217 <entry><filename class="headerfile">vector</filename></entry>
218 <entry namest="c3" nameend="c5"/>
225 <table frame="all" xml:id="table.cxx98_cheaders">
226 <title>C++ 1998 Library Headers for C Library Facilities</title>
228 <tgroup cols="5" align="left" colsep="1" rowsep="1">
229 <colspec colname="c1"/>
230 <colspec colname="c2"/>
231 <colspec colname="c3"/>
232 <colspec colname="c4"/>
233 <colspec colname="c5"/>
236 <entry><filename class="headerfile">cassert</filename></entry>
237 <entry><filename class="headerfile">cerrno</filename></entry>
238 <entry><filename class="headerfile">cctype</filename></entry>
239 <entry><filename class="headerfile">cfloat</filename></entry>
240 <entry><filename class="headerfile">ciso646</filename></entry>
243 <entry><filename class="headerfile">climits</filename></entry>
244 <entry><filename class="headerfile">clocale</filename></entry>
245 <entry><filename class="headerfile">cmath</filename></entry>
246 <entry><filename class="headerfile">csetjmp</filename></entry>
247 <entry><filename class="headerfile">csignal</filename></entry>
250 <entry><filename class="headerfile">cstdarg</filename></entry>
251 <entry><filename class="headerfile">cstddef</filename></entry>
252 <entry><filename class="headerfile">cstdio</filename></entry>
253 <entry><filename class="headerfile">cstdlib</filename></entry>
254 <entry><filename class="headerfile">cstring</filename></entry>
257 <entry><filename class="headerfile">ctime</filename></entry>
258 <entry><filename class="headerfile">cwchar</filename></entry>
259 <entry><filename class="headerfile">cwctype</filename></entry>
260 <entry namest="c4" nameend="c5"/>
267 The following header is deprecated
268 and might be removed from a future C++ standard.
271 <table frame="all" xml:id="table.cxx98_deprheaders">
272 <title>C++ 1998 Deprecated Library Header</title>
274 <tgroup cols="1" align="left" colsep="1" rowsep="1">
275 <colspec colname="c1"/>
278 <entry><filename class="headerfile">strstream</filename></entry>
285 <xref linkend="table.cxx11_headers"/> and
286 <xref linkend="table.cxx11_cheaders"/> show the C++11 include files.
287 These are available in C++11 compilation
288 mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>.
289 Including these headers in C++98/03 mode may result in compilation errors.
290 Unless specified otherwise below, they are also available in later modes
295 <table frame="all" xml:id="table.cxx11_headers">
296 <title>C++ 2011 Library Headers</title>
298 <tgroup cols="5" align="left" colsep="1" rowsep="1">
299 <colspec colname="c1"/>
300 <colspec colname="c2"/>
301 <colspec colname="c3"/>
302 <colspec colname="c4"/>
303 <colspec colname="c5"/>
307 <entry><filename class="headerfile">array</filename></entry>
308 <entry><filename class="headerfile">atomic</filename></entry>
309 <entry><filename class="headerfile">chrono</filename></entry>
310 <entry><filename class="headerfile">codecvt</filename></entry>
311 <entry><filename class="headerfile">condition_variable</filename></entry>
314 <entry><filename class="headerfile">forward_list</filename></entry>
315 <entry><filename class="headerfile">future</filename></entry>
316 <entry><filename class="headerfile">initalizer_list</filename></entry>
317 <entry><filename class="headerfile">mutex</filename></entry>
318 <entry><filename class="headerfile">random</filename></entry>
321 <entry><filename class="headerfile">ratio</filename></entry>
322 <entry><filename class="headerfile">regex</filename></entry>
323 <entry><filename class="headerfile">scoped_allocator</filename></entry>
324 <entry><filename class="headerfile">system_error</filename></entry>
325 <entry><filename class="headerfile">thread</filename></entry>
328 <entry><filename class="headerfile">tuple</filename></entry>
329 <entry><filename class="headerfile">typeindex</filename></entry>
330 <entry><filename class="headerfile">type_traits</filename></entry>
331 <entry><filename class="headerfile">unordered_map</filename></entry>
332 <entry><filename class="headerfile">unordered_set</filename></entry>
341 <table frame="all" xml:id="table.cxx11_cheaders">
342 <title>C++ 2011 Library Headers for C Library Facilities</title>
344 <tgroup cols="5" align="left" colsep="1" rowsep="1">
345 <colspec colname="c1"/>
346 <colspec colname="c2"/>
347 <colspec colname="c3"/>
348 <colspec colname="c4"/>
349 <colspec colname="c5"/>
352 <entry><filename class="headerfile">ccomplex</filename></entry>
353 <entry><filename class="headerfile">cfenv</filename></entry>
354 <entry><filename class="headerfile">cinttypes</filename></entry>
355 <entry><filename class="headerfile">cstdalign</filename></entry>
356 <entry><filename class="headerfile">cstdbool</filename></entry>
359 <entry><filename class="headerfile">cstdint</filename></entry>
360 <entry><filename class="headerfile">ctgmath</filename></entry>
361 <entry><filename class="headerfile">cuchar</filename></entry>
362 <entry namest="c4" nameend="c5"/>
369 <xref linkend="table.cxx14_headers"/> shows the C++14 include file.
370 This is available in C++14 compilation
371 mode, i.e. <literal>-std=c++14</literal> or <literal>-std=gnu++14</literal>.
372 Including this header in C++98/03 mode or C++11 will not result in
373 compilation errors, but will not define anything.
374 Unless specified otherwise below, it is also available in later modes
379 <table frame="all" xml:id="table.cxx14_headers">
380 <title>C++ 2014 Library Header</title>
382 <tgroup cols="1" align="left" colsep="1" rowsep="1">
383 <colspec colname="c1"/>
386 <entry><filename class="headerfile">shared_mutex</filename></entry>
393 <xref linkend="table.cxx17_headers"/> shows the C++17 include files.
394 These are available in C++17 compilation
395 mode, i.e. <literal>-std=c++17</literal> or <literal>-std=gnu++17</literal>.
396 Including these headers in earlier modes will not result in
397 compilation errors, but will not define anything.
398 Unless specified otherwise below, they are also available in later modes
403 <table frame="all" xml:id="table.cxx17_headers">
404 <title>C++ 2017 Library Headers</title>
406 <tgroup cols="5" align="left" colsep="1" rowsep="1">
407 <colspec colname="c1"/>
408 <colspec colname="c2"/>
409 <colspec colname="c3"/>
410 <colspec colname="c4"/>
411 <colspec colname="c5"/>
414 <entry><filename class="headerfile">any</filename></entry>
415 <entry><filename class="headerfile">charconv</filename></entry>
416 <entry><filename class="headerfile">execution</filename></entry>
417 <entry><filename class="headerfile">filesystem</filename></entry>
418 <entry><filename class="headerfile">memory_resource</filename></entry>
421 <entry><filename class="headerfile">optional</filename></entry>
422 <entry><filename class="headerfile">string_view</filename></entry>
423 <entry><filename class="headerfile">variant</filename></entry>
424 <entry namest="c4" nameend="c5"/>
431 <xref linkend="table.cxx20_headers"/>
432 shows the C++2a include files.
433 These are available in C++2a compilation
434 mode, i.e. <literal>-std=c++2a</literal> or <literal>-std=gnu++2a</literal>.
435 Including these headers in earlier modes will not result in
436 compilation errors, but will not define anything.
438 Unless specified otherwise below, they are also available in later modes
444 <table frame="all" xml:id="table.cxx20_headers">
445 <title>C++ 2020 Library Headers</title>
447 <tgroup cols="2" align="left" colsep="1" rowsep="1">
448 <colspec colname="c1"/>
449 <colspec colname="c2"/>
451 <colspec colname="c3"/>
452 <colspec colname="c4"/>
453 <colspec colname="c5"/>
457 <entry><filename class="headerfile">bit</filename></entry>
458 <entry><filename class="headerfile">version</filename></entry>
460 <!-- TODO compare, concepts, contract, span, syncstream -->
466 The following headers have been removed in the C++2a working draft.
467 They are still available when using this implementation, but in future
468 they might start to produce warnings or errors when included in C++2a mode.
469 Programs that intend to be portable should not include them.
472 <table frame="all" xml:id="table.cxx20_deprheaders">
473 <title>C++ 2020 Obsolete Headers</title>
475 <tgroup cols="5" align="left" colsep="1" rowsep="1">
476 <colspec colname="c1"/>
477 <colspec colname="c2"/>
478 <colspec colname="c3"/>
479 <colspec colname="c4"/>
480 <colspec colname="c5"/>
483 <entry><filename class="headerfile">ccomplex</filename></entry>
484 <entry><filename class="headerfile">ciso646</filename></entry>
485 <entry><filename class="headerfile">cstdalign</filename></entry>
486 <entry><filename class="headerfile">cstdbool</filename></entry>
487 <entry><filename class="headerfile">ctgmath</filename></entry>
494 <xref linkend="table.filesystemts_headers"/>,
495 shows the additional include file define by the
496 File System Technical Specification, ISO/IEC TS 18822.
497 This is available in C++11 and later compilation modes.
498 Including this header in earlier modes will not result in
499 compilation errors, but will not define anything.
503 <table frame="all" xml:id="table.filesystemts_headers">
504 <title>File System TS Header</title>
506 <tgroup cols="1" align="left" colsep="1" rowsep="1">
507 <colspec colname="c1"/>
510 <entry><filename class="headerfile">experimental/filesystem</filename></entry>
518 <xref linkend="table.libfundts_headers"/>,
519 shows the additional include files define by the C++ Extensions for
520 Library Fundamentals Technical Specification, ISO/IEC TS 19568.
521 These are available in C++14 and later compilation modes.
522 Including these headers in earlier modes will not result in
523 compilation errors, but will not define anything.
527 <table frame="all" xml:id="table.libfundts_headers">
528 <title>Library Fundamentals TS Headers</title>
530 <tgroup cols="5" align="left" colsep="1" rowsep="1">
531 <colspec colname="c1"/>
532 <colspec colname="c2"/>
533 <colspec colname="c3"/>
534 <colspec colname="c4"/>
535 <colspec colname="c5"/>
538 <entry><filename class="headerfile">experimental/algorithm</filename></entry>
539 <entry><filename class="headerfile">experimental/any</filename></entry>
540 <entry><filename class="headerfile">experimental/array</filename></entry>
541 <entry><filename class="headerfile">experimental/chrono</filename></entry>
542 <entry><filename class="headerfile">experimental/deque</filename></entry>
545 <entry><filename class="headerfile">experimental/forward_list</filename></entry>
546 <entry><filename class="headerfile">experimental/functional</filename></entry>
547 <entry><filename class="headerfile">experimental/iterator</filename></entry>
548 <entry><filename class="headerfile">experimental/list</filename></entry>
549 <entry><filename class="headerfile">experimental/map</filename></entry>
552 <entry><filename class="headerfile">experimental/memory</filename></entry>
553 <entry><filename class="headerfile">experimental/memory_resource</filename></entry>
554 <entry><filename class="headerfile">experimental/numeric</filename></entry>
555 <entry><filename class="headerfile">experimental/optional</filename></entry>
556 <entry><filename class="headerfile">experimental/propagate_const</filename></entry>
559 <entry><filename class="headerfile">experimental/random</filename></entry>
560 <entry><filename class="headerfile">experimental/ratio</filename></entry>
561 <entry><filename class="headerfile">experimental/regex</filename></entry>
562 <entry><filename class="headerfile">experimental/set</filename></entry>
563 <entry><filename class="headerfile">experimental/source_location</filename></entry>
566 <entry><filename class="headerfile">experimental/string</filename></entry>
567 <entry><filename class="headerfile">experimental/string_view</filename></entry>
568 <entry><filename class="headerfile">experimental/system_error</filename></entry>
569 <entry><filename class="headerfile">experimental/tuple</filename></entry>
570 <entry><filename class="headerfile">experimental/type_traits</filename></entry>
573 <entry><filename class="headerfile">experimental/unordered_map</filename></entry>
574 <entry><filename class="headerfile">experimental/unordered_set</filename></entry>
575 <entry><filename class="headerfile">experimental/utility</filename></entry>
576 <entry><filename class="headerfile">experimental/vector</filename></entry>
577 <entry namest="c4" nameend="c5"/>
585 In addition, TR1 includes as:
588 <table frame="all" xml:id="table.tr1_headers">
589 <title>C++ TR 1 Library Headers</title>
591 <tgroup cols="5" align="left" colsep="1" rowsep="1">
592 <colspec colname="c1"/>
593 <colspec colname="c2"/>
594 <colspec colname="c3"/>
595 <colspec colname="c4"/>
596 <colspec colname="c5"/>
600 <entry><filename class="headerfile">tr1/array</filename></entry>
601 <entry><filename class="headerfile">tr1/complex</filename></entry>
602 <entry><filename class="headerfile">tr1/memory</filename></entry>
603 <entry><filename class="headerfile">tr1/functional</filename></entry>
604 <entry><filename class="headerfile">tr1/random</filename></entry>
607 <entry><filename class="headerfile">tr1/regex</filename></entry>
608 <entry><filename class="headerfile">tr1/tuple</filename></entry>
609 <entry><filename class="headerfile">tr1/type_traits</filename></entry>
610 <entry><filename class="headerfile">tr1/unordered_map</filename></entry>
611 <entry><filename class="headerfile">tr1/unordered_set</filename></entry>
614 <entry><filename class="headerfile">tr1/utility</filename></entry>
615 <entry namest="c2" nameend="c5"/>
625 <table frame="all" xml:id="table.tr1_cheaders">
626 <title>C++ TR 1 Library Headers for C Library Facilities</title>
628 <tgroup cols="5" align="left" colsep="1" rowsep="1">
629 <colspec colname="c1"/>
630 <colspec colname="c2"/>
631 <colspec colname="c3"/>
632 <colspec colname="c4"/>
633 <colspec colname="c5"/>
637 <entry><filename class="headerfile">tr1/ccomplex</filename></entry>
638 <entry><filename class="headerfile">tr1/cfenv</filename></entry>
639 <entry><filename class="headerfile">tr1/cfloat</filename></entry>
640 <entry><filename class="headerfile">tr1/cmath</filename></entry>
641 <entry><filename class="headerfile">tr1/cinttypes</filename></entry>
644 <entry><filename class="headerfile">tr1/climits</filename></entry>
645 <entry><filename class="headerfile">tr1/cstdarg</filename></entry>
646 <entry><filename class="headerfile">tr1/cstdbool</filename></entry>
647 <entry><filename class="headerfile">tr1/cstdint</filename></entry>
648 <entry><filename class="headerfile">tr1/cstdio</filename></entry>
651 <entry><filename class="headerfile">tr1/cstdlib</filename></entry>
652 <entry><filename class="headerfile">tr1/ctgmath</filename></entry>
653 <entry><filename class="headerfile">tr1/ctime</filename></entry>
654 <entry><filename class="headerfile">tr1/cwchar</filename></entry>
655 <entry><filename class="headerfile">tr1/cwctype</filename></entry>
663 <para>Decimal floating-point arithmetic is available if the C++
664 compiler supports scalar decimal floating-point types defined via
665 <code>__attribute__((mode(SD|DD|LD)))</code>.
668 <table frame="all" xml:id="table.decfp_headers">
669 <title>C++ TR 24733 Decimal Floating-Point Header</title>
671 <tgroup cols="1" align="left" colsep="1" rowsep="1">
672 <colspec colname="c1"/>
675 <entry><filename class="headerfile">decimal/decimal</filename></entry>
682 Also included are files for the C++ ABI interface:
685 <table frame="all" xml:id="table.abi_headers">
686 <title>C++ ABI Headers</title>
688 <tgroup cols="2" align="left" colsep="1" rowsep="1">
689 <colspec colname="c1"/>
690 <colspec colname="c2"/>
692 <row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row>
698 And a large variety of extensions.
701 <table frame="all" xml:id="table.ext_headers">
702 <title>Extension Headers</title>
704 <tgroup cols="5" align="left" colsep="1" rowsep="1">
705 <colspec colname="c1"/>
706 <colspec colname="c2"/>
707 <colspec colname="c3"/>
708 <colspec colname="c4"/>
709 <colspec colname="c5"/>
713 <entry><filename class="headerfile">ext/algorithm</filename></entry>
714 <entry><filename class="headerfile">ext/atomicity.h</filename></entry>
715 <entry><filename class="headerfile">ext/array_allocator.h</filename></entry>
716 <entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry>
717 <entry><filename class="headerfile">ext/cast.h</filename></entry>
720 <entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry>
721 <entry><filename class="headerfile">ext/concurrence.h</filename></entry>
722 <entry><filename class="headerfile">ext/debug_allocator.h</filename></entry>
723 <entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry>
724 <entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry>
727 <entry><filename class="headerfile">ext/functional</filename></entry>
728 <entry><filename class="headerfile">ext/iterator</filename></entry>
729 <entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry>
730 <entry><filename class="headerfile">ext/memory</filename></entry>
731 <entry><filename class="headerfile">ext/mt_allocator.h</filename></entry>
734 <entry><filename class="headerfile">ext/new_allocator.h</filename></entry>
735 <entry><filename class="headerfile">ext/numeric</filename></entry>
736 <entry><filename class="headerfile">ext/numeric_traits.h</filename></entry>
737 <entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry>
738 <entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry>
741 <entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry>
742 <entry><filename class="headerfile">ext/pool_allocator.h</filename></entry>
743 <entry><filename class="headerfile">ext/rb_tree</filename></entry>
744 <entry><filename class="headerfile">ext/rope</filename></entry>
745 <entry><filename class="headerfile">ext/slist</filename></entry>
748 <entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry>
749 <entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry>
750 <entry><filename class="headerfile">ext/throw_allocator.h</filename></entry>
751 <entry><filename class="headerfile">ext/typelist.h</filename></entry>
752 <entry><filename class="headerfile">ext/type_traits.h</filename></entry>
755 <entry><filename class="headerfile">ext/vstring.h</filename></entry>
756 <entry namest="c2" nameend="c5"/>
765 <table frame="all" xml:id="table.debug_headers">
766 <title>Extension Debug Headers</title>
768 <tgroup cols="5" align="left" colsep="1" rowsep="1">
769 <colspec colname="c1"/>
770 <colspec colname="c2"/>
771 <colspec colname="c3"/>
772 <colspec colname="c4"/>
773 <colspec colname="c5"/>
777 <entry><filename class="headerfile">debug/array</filename></entry>
778 <entry><filename class="headerfile">debug/bitset</filename></entry>
779 <entry><filename class="headerfile">debug/deque</filename></entry>
780 <entry><filename class="headerfile">debug/forward_list</filename></entry>
781 <entry><filename class="headerfile">debug/list</filename></entry>
784 <entry><filename class="headerfile">debug/map</filename></entry>
785 <entry><filename class="headerfile">debug/set</filename></entry>
786 <entry><filename class="headerfile">debug/string</filename></entry>
787 <entry><filename class="headerfile">debug/unordered_map</filename></entry>
788 <entry><filename class="headerfile">debug/unordered_set</filename></entry>
791 <entry><filename class="headerfile">debug/vector</filename></entry>
792 <entry namest="c2" nameend="c5"/>
801 <table frame="all" xml:id="table.profile_headers">
802 <title>Extension Profile Headers</title>
804 <tgroup cols="4" align="left" colsep="1" rowsep="1">
805 <colspec colname="c1"/>
806 <colspec colname="c2"/>
807 <colspec colname="c3"/>
808 <colspec colname="c4"/>
812 <entry><filename class="headerfile">profile/bitset</filename></entry>
813 <entry><filename class="headerfile">profile/deque</filename></entry>
814 <entry><filename class="headerfile">profile/list</filename></entry>
815 <entry><filename class="headerfile">profile/map</filename></entry>
819 <entry><filename class="headerfile">profile/set</filename></entry>
820 <entry><filename class="headerfile">profile/unordered_map</filename></entry>
821 <entry><filename class="headerfile">profile/unordered_set</filename></entry>
822 <entry><filename class="headerfile">profile/vector</filename></entry>
831 <table frame="all" xml:id="table.parallel_headers">
832 <title>Extension Parallel Headers</title>
834 <tgroup cols="2" align="left" colsep="1" rowsep="1">
835 <colspec colname="c1"/>
836 <colspec colname="c2"/>
839 <entry><filename class="headerfile">parallel/algorithm</filename></entry>
840 <entry><filename class="headerfile">parallel/numeric</filename></entry>
848 <section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info>
851 <para> A few simple rules.
854 <para>First, mixing different dialects of the standard headers is not
855 possible. It's an all-or-nothing affair. Thus, code like
859 #include <array>
860 #include <functional>
863 <para>Implies C++11 mode. To use the entities in <array>, the C++11
864 compilation mode must be used, which implies the C++11 functionality
865 (and deprecations) in <functional> will be present.
868 <para>Second, the other headers can be included with either dialect of
869 the standard headers, although features and types specific to C++11
870 are still only enabled when in C++11 compilation mode. So, to use
871 rvalue references with <code>__gnu_cxx::vstring</code>, or to use the
872 debug-mode versions of <code>std::unordered_map</code>, one must use
873 the <code>std=gnu++11</code> compiler flag. (Or <code>std=c++11</code>, of course.)
876 <para>A special case of the second rule is the mixing of TR1 and C++11
877 facilities. It is possible (although not especially prudent) to
878 include both the TR1 version and the C++11 version of header in the
879 same translation unit:
883 #include <tr1/type_traits>
884 #include <type_traits>
887 <para> Several parts of C++11 diverge quite substantially from TR1 predecessors.
891 <section xml:id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"><info><title>The C Headers and <code>namespace std</code></title></info>
895 The standard specifies that if one includes the C-style header
896 (<math.h> in this case), the symbols will be available
897 in the global namespace and perhaps in
898 namespace <code>std::</code> (but this is no longer a firm
899 requirement.) On the other hand, including the C++-style
900 header (<cmath>) guarantees that the entities will be
901 found in namespace std and perhaps in the global namespace.
905 Usage of C++-style headers is recommended, as then
906 C-linkage names can be disambiguated by explicit qualification, such
907 as by <code>std::abort</code>. In addition, the C++-style headers can
908 use function overloading to provide a simpler interface to certain
909 families of C-functions. For instance in <cmath>, the
910 function <code>std::sin</code> has overloads for all the builtin
911 floating-point types. This means that <code>std::sin</code> can be
912 used uniformly, instead of a combination
913 of <code>std::sinf</code>, <code>std::sin</code>,
914 and <code>std::sinl</code>.
918 <section xml:id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"><info><title>Precompiled Headers</title></info>
922 <para>There are three base header files that are provided. They can be
923 used to precompile the standard headers and extensions into binary
924 files that may then be used to speed up compilations that use these headers.
930 <para>stdc++.h</para>
931 <para>Includes all standard headers. Actual content varies depending on
932 <link linkend="manual.intro.using.flags">language dialect</link>.
937 <para>stdtr1c++.h</para>
938 <para>Includes all of <stdc++.h>, and adds all the TR1 headers.
942 <listitem><para>extc++.h</para>
943 <para>Includes all of <stdc++.h>, and adds all the Extension headers
944 (and in C++98 mode also adds all the TR1 headers by including all of
945 <stdtr1c++.h>).
949 <para>To construct a .gch file from one of these base header files,
950 first find the include directory for the compiler. One way to do
956 #include <...> search starts here:
957 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
963 <para>Then, create a precompiled header file with the same flags that
964 will be used to compile other projects.</para>
967 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
970 <para>The resulting file will be quite large: the current size is around
971 thirty megabytes. </para>
973 <para>How to use the resulting file.</para>
976 g++ -I. -include stdc++.h -H -g -O2 hello.cc
979 <para>Verification that the PCH file is being used is easy:</para>
982 g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
984 . /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
985 . /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
988 <para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used.</para>
991 <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>.
998 <section xml:id="manual.intro.using.macros" xreflabel="Macros"><info><title>Macros</title></info>
999 <?dbhtml filename="using_macros.html"?>
1003 All library macros begin with <code>_GLIBCXX_</code>.
1007 Furthermore, all pre-processor macros, switches, and
1008 configuration options are gathered in the
1009 file <filename class="headerfile">c++config.h</filename>, which
1010 is generated during the libstdc++ configuration and build
1011 process. This file is then included when needed by files part of
1012 the public libstdc++ API, like
1013 <filename class="headerfile"><ios></filename>. Most of these
1014 macros should not be used by consumers of libstdc++, and are reserved
1015 for internal implementation use. <emphasis>These macros cannot
1016 be redefined</emphasis>.
1020 A select handful of macros control libstdc++ extensions and extra
1021 features, or provide versioning information for the API. Only
1022 those macros listed below are offered for consideration by the
1026 <para>Below are the macros which users may check for library version
1027 information. </para>
1031 <term><code>_GLIBCXX_RELEASE</code></term>
1033 <para>The major release number for libstdc++. This macro is defined
1034 to the GCC major version that the libstdc++ headers belong to,
1035 as an integer constant.
1036 When compiling with GCC it has the same value as GCC's pre-defined
1037 macro <symbol>__GNUC__</symbol>.
1038 This macro can be used when libstdc++ is used with a non-GNU
1039 compiler where <symbol>__GNUC__</symbol> is not defined, or has a
1040 different value that doesn't correspond to the libstdc++ version.
1041 This macro first appeared in the GCC 7.1 release and is not defined
1042 for GCC 6.x or older releases.
1047 <term><code>__GLIBCXX__</code></term>
1049 <para>The revision date of the libstdc++ source code,
1050 in compressed ISO date format, as an unsigned
1051 long. For notes about using this macro and details on the value of
1052 this macro for a particular release, please consult the
1053 <link linkend="abi.versioning.__GLIBCXX__">ABI History</link>
1060 <para>Below are the macros which users may change with #define/#undef or
1061 with -D/-U compiler flags. The default state of the symbol is
1064 <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
1065 that the symbol is initially chosen (or not) based on
1066 --enable/--disable options at library build and configure time
1068 <link linkend="manual.intro.setup.configure">Configure</link>),
1069 with the various --enable/--disable choices being translated to
1073 <para> <acronym>ABI</acronym> means that changing from the default value may
1074 mean changing the <acronym>ABI</acronym> of compiled code. In other words,
1075 these choices control code which has already been compiled (i.e., in a
1076 binary such as libstdc++.a/.so). If you explicitly #define or
1077 #undef these macros, the <emphasis>headers</emphasis> may see different code
1078 paths, but the <emphasis>libraries</emphasis> which you link against will not.
1079 Experimenting with different values with the expectation of
1080 consistent linkage requires changing the config headers before
1081 building/installing the library.
1085 <varlistentry><term><code>_GLIBCXX_USE_DEPRECATED</code></term>
1088 Defined by default. Not configurable. ABI-changing. Turning this off
1089 removes older ARM-style iostreams code, and other anachronisms
1090 from the API. This macro is dependent on the version of the
1091 standard being tracked, and as a result may give different results for
1092 <code>-std=c++98</code> and <code>-std=c++11</code>. This may
1093 be useful in updating old C++ code which no longer meet the
1094 requirements of the language, or for checking current code
1095 against new language standards.
1097 </listitem></varlistentry>
1099 <varlistentry><term><code>_GLIBCXX_USE_CXX11_ABI</code></term>
1102 Defined to the value <literal>1</literal> by default.
1103 Configurable via <code>--disable-libstdcxx-dual-abi</code>
1104 and/or <code>--with-default-libstdcxx-abi</code>.
1106 When defined to a non-zero value the library headers will use the
1107 new C++11-conforming ABI introduced in GCC 5, rather than the older
1108 ABI introduced in GCC 3.4. This changes the definition of several
1109 class templates, including <classname>std:string</classname>,
1110 <classname>std::list</classname> and some locale facets.
1111 For more details see <xref linkend="manual.intro.using.abi"/>.
1113 </listitem></varlistentry>
1115 <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
1118 Undefined by default. Configurable via
1119 <code>--enable-concept-checks</code>. When defined, performs
1120 compile-time checking on certain template instantiations to
1121 detect violations of the requirements of the standard. This
1122 macro has no effect for freestanding implementations.
1123 This is described in more detail in
1124 <link linkend="manual.ext.compile_checks">Compile Time Checks</link>.
1126 </listitem></varlistentry>
1128 <varlistentry><term><code>_GLIBCXX_ASSERTIONS</code></term>
1131 Undefined by default. When defined, enables extra error checking in
1132 the form of precondition assertions, such as bounds checking in
1133 strings and null pointer checks when dereferencing smart pointers.
1135 </listitem></varlistentry>
1136 <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
1139 Undefined by default. When defined, compiles user code using
1140 the <link linkend="manual.ext.debug_mode">debug mode</link>.
1141 When defined, <code>_GLIBCXX_ASSERTIONS</code> is defined
1142 automatically, so all the assertions enabled by that macro are also
1143 enabled in debug mode.
1145 </listitem></varlistentry>
1146 <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
1149 Undefined by default. When defined while compiling with
1150 the <link linkend="manual.ext.debug_mode">debug mode</link>, makes
1151 the debug mode extremely picky by making the use of libstdc++
1152 extensions and libstdc++-specific behavior into errors.
1154 </listitem></varlistentry>
1155 <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
1157 <para>Undefined by default. When defined, compiles user code
1158 using the <link linkend="manual.ext.parallel_mode">parallel
1161 </listitem></varlistentry>
1162 <varlistentry><term><code>_GLIBCXX_PARALLEL_ASSERTIONS</code></term>
1164 <para>Undefined by default, but when any parallel mode header is included
1165 this macro will be defined to a non-zero value if
1166 <code>_GLIBCXX_ASSERTIONS</code> has a non-zero value, otherwise to zero.
1167 When defined to a non-zero value, it enables extra error checking and
1168 assertions in the parallel mode.
1170 </listitem></varlistentry>
1172 <varlistentry><term><code>_GLIBCXX_PROFILE</code></term>
1174 <para>Undefined by default. When defined, compiles user code
1175 using the <link linkend="manual.ext.profile_mode">profile
1178 </listitem></varlistentry>
1180 <varlistentry><term><code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code></term>
1182 <para>Undefined by default. When defined to a non-zero integer constant,
1183 enables support for ISO/IEC 29124 Special Math Functions.
1185 </listitem></varlistentry>
1187 <varlistentry><term><code>_GLIBCXX_SANITIZE_VECTOR</code></term>
1190 Undefined by default. When defined, <classname>std::vector</classname>
1191 operations will be annotated so that AddressSanitizer can detect
1192 invalid accesses to the unused capacity of a
1193 <classname>std::vector</classname>. These annotations are only
1195 <classname>std::vector<T, std::allocator<T>></classname>
1196 and only when <classname>std::allocator</classname> is derived from
1197 <xref linkend="allocator.impl"><classname>new_allocator</classname>
1198 or <classname>malloc_allocator</classname></xref>. The annotations
1199 must be present on all vector operations or none, so this macro must
1200 be defined to the same value for all translation units that create,
1201 destroy or modify vectors.
1203 </listitem></varlistentry>
1208 <section xml:id="manual.intro.using.abi" xreflabel="Dual ABI">
1209 <info><title>Dual ABI</title></info>
1210 <?dbhtml filename="using_dual_abi.html"?>
1212 <para> In the GCC 5.1 release libstdc++ introduced a new library ABI that
1213 includes new implementations of <classname>std::string</classname> and
1214 <classname>std::list</classname>. These changes were necessary to conform
1215 to the 2011 C++ standard which forbids Copy-On-Write strings and requires
1216 lists to keep track of their size.
1219 <para> In order to maintain backwards compatibility for existing code linked
1220 to libstdc++ the library's soname has not changed and the old
1221 implementations are still supported in parallel with the new ones.
1222 This is achieved by defining the new implementations in an inline namespace
1223 so they have different names for linkage purposes, e.g. the new version of
1224 <classname>std::list<int></classname> is actually defined as
1225 <classname>std::__cxx11::list<int></classname>. Because the symbols
1226 for the new implementations have different names the definitions for both
1227 versions can be present in the same library.
1230 <para> The <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro (see
1231 <xref linkend="manual.intro.using.macros"/>) controls whether
1232 the declarations in the library headers use the old or new ABI.
1233 So the decision of which ABI to use can be made separately for each
1234 source file being compiled.
1235 Using the default configuration options for GCC the default value
1236 of the macro is <literal>1</literal> which causes the new ABI to be active,
1237 so to use the old ABI you must explicitly define the macro to
1238 <literal>0</literal> before including any library headers.
1239 (Be aware that some GNU/Linux distributions configure GCC 5 differently so
1240 that the default value of the macro is <literal>0</literal> and users must
1241 define it to <literal>1</literal> to enable the new ABI.)
1244 <para> Although the changes were made for C++11 conformance, the choice of ABI
1245 to use is independent of the <option>-std</option> option used to compile
1246 your code, i.e. for a given GCC build the default value of the
1247 <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro is the same for all dialects.
1248 This ensures that the <option>-std</option> does not change the ABI, so
1249 that it is straightforward to link C++03 and C++11 code together.
1252 <para> Because <classname>std::string</classname> is used extensively
1253 throughout the library a number of other types are also defined twice,
1254 including the stringstream classes and several facets used by
1255 <classname>std::locale</classname>. The standard facets which are always
1256 installed in a locale may be present twice, with both ABIs, to ensure that
1258 <code>std::use_facet<std::time_get<char>>(locale);</code>
1259 will work correctly for both <classname>std::time_get</classname> and
1260 <classname>std::__cxx11::time_get</classname> (even if a user-defined
1261 facet that derives from one or other version of
1262 <classname>time_get</classname> is installed in the locale).
1265 <para> Although the standard exception types defined in
1266 <filename class="headerfile"><stdexcept></filename> use strings, most
1267 are not defined twice, so that a <classname>std::out_of_range</classname>
1268 exception thrown in one file can always be caught by a suitable handler in
1269 another file, even if the two files are compiled with different ABIs.
1272 <para> One exception type does change when using the new ABI, namely
1273 <classname>std::ios_base::failure</classname>.
1274 This is necessary because the 2011 standard changed its base class from
1275 <classname>std::exception</classname> to
1276 <classname>std::system_error</classname>, which causes its layout to change.
1277 Exceptions due to iostream errors are thrown by a function inside
1278 <filename class="libraryfile">libstdc++.so</filename>, so whether the thrown
1279 exception uses the old <classname>std::ios_base::failure</classname> type
1280 or the new one depends on the ABI that was active when
1281 <filename class="libraryfile">libstdc++.so</filename> was built,
1282 <emphasis>not</emphasis> the ABI active in the user code that is using
1284 This means that for a given build of GCC the type thrown is fixed.
1285 In current releases the library throws a special type that can be caught
1286 by handlers for either the old or new type,
1287 but for GCC 7.1, 7.2 and 7.3 the library throws the new
1288 <classname>std::ios_base::failure</classname> type,
1289 and for GCC 5.x and 6.x the library throws the old type.
1290 Catch handlers of type <classname>std::ios_base::failure</classname>
1291 will only catch the exceptions if using a newer release,
1292 or if the handler is compiled with the same ABI as the type thrown by
1294 Handlers for <classname>std::exception</classname> will always catch
1295 iostreams exceptions, because the old and new type both inherit from
1296 <classname>std::exception</classname>.
1299 <section xml:id="manual.intro.using.abi.trouble" xreflabel="Dual ABI Troubleshooting"><info><title>Troubleshooting</title></info>
1301 <para> If you get linker errors about undefined references to symbols
1302 that involve types in the <code>std::__cxx11</code> namespace or the tag
1303 <code>[abi:cxx11]</code> then it probably indicates that you are trying to
1304 link together object files that were compiled with different values for the
1305 <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro. This commonly happens when
1306 linking to a third-party library that was compiled with an older version
1307 of GCC. If the third-party library cannot be rebuilt with the new ABI then
1308 you will need to recompile your code with the old ABI.
1311 <para> Not all uses of the new ABI will cause changes in symbol names, for
1312 example a class with a <classname>std::string</classname> member variable
1313 will have the same mangled name whether compiled with the old or new ABI.
1314 In order to detect such problems the new types and functions are
1315 annotated with the <property>abi_tag</property> attribute, allowing the
1316 compiler to warn about potential ABI incompatibilities in code using them.
1317 Those warnings can be enabled with the <option>-Wabi-tag</option> option.
1323 <section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
1324 <?dbhtml filename="using_namespaces.html"?>
1327 <section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info>
1332 <para> There are three main namespaces.
1336 <listitem><para>std</para>
1337 <para>The ISO C++ standards specify that "all library entities are defined
1338 within namespace std." This includes namespaces nested
1339 within namespace <code>std</code>, such as namespace
1340 <code>std::chrono</code>.
1343 <listitem><para>abi</para>
1344 <para>Specified by the C++ ABI. This ABI specifies a number of type and
1345 function APIs supplemental to those required by the ISO C++ Standard,
1346 but necessary for interoperability.
1350 <listitem><para>__gnu_</para>
1351 <para>Indicating one of several GNU extensions. Choices
1352 include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
1353 and <code>__gnu_pbds</code>.
1357 <para> The library uses a number of inline namespaces as implementation
1358 details that are not intended for users to refer to directly, these include
1359 <code>std::__detail</code>, <code>std::__cxx11</code> and <code>std::_V2</code>.
1362 <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>.
1368 <section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info>
1373 One standard requirement is that the library components are defined
1374 in <code>namespace std::</code>. Thus, in order to use these types or
1375 functions, one must do one of two things:
1379 <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source
1380 (either <code>using namespace std;</code> or i.e. <code>using
1381 std::string;</code>) This approach works well for individual source files, but
1382 should not be used in a global context, like header files.
1383 </para></listitem> <listitem><para>use a <emphasis>fully
1384 qualified name</emphasis> for each library symbol
1385 (i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
1386 used, and usually enhanced, by strategic use of typedefs. (In the
1387 cases where the qualified verbiage becomes unwieldy.)
1394 <section xml:id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"><info><title>Using Namespace Composition</title></info>
1398 Best practice in programming suggests sequestering new data or
1399 functionality in a sanely-named, unique namespace whenever
1400 possible. This is considered an advantage over dumping everything in
1401 the global namespace, as then name look-up can be explicitly enabled or
1402 disabled as above, symbols are consistently mangled without repetitive
1403 naming prefixes or macros, etc.
1406 <para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
1407 adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
1408 <emphasis>namespace composition</emphasis>. This is what happens if
1409 a <emphasis>using</emphasis>-declaration is put into a
1410 namespace-definition: the imported symbol(s) gets imported into the
1411 currently active namespace(s). For example:
1417 using std::tr1::array;
1419 class Window { ... };
1423 In this example, <code>std::string</code> gets imported into
1424 <code>namespace gtk</code>. The result is that use of
1425 <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
1427 <code>std::string</code> does not get imported into
1428 the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
1429 <code>using</code>-declarations can wrapped in macros that
1430 are set based on autoconf-tests to either "" or i.e. <code>using
1431 std::string;</code> (depending on whether the system has
1432 libstdc++ in <code>std::</code> or not). (ideas from
1433 Llewelly and Karl Nelson)
1440 <section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info>
1441 <?dbhtml filename="using_dynamic_or_shared.html"?>
1444 <section xml:id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"><info><title>Almost Nothing</title></info>
1447 Or as close as it gets: freestanding. This is a minimal
1448 configuration, with only partial support for the standard
1449 library. Assume only the following header files can be used:
1455 <filename class="headerfile">cstdarg</filename>
1461 <filename class="headerfile">cstddef</filename>
1467 <filename class="headerfile">cstdlib</filename>
1473 <filename class="headerfile">exception</filename>
1479 <filename class="headerfile">limits</filename>
1485 <filename class="headerfile">new</filename>
1491 <filename class="headerfile">exception</filename>
1497 <filename class="headerfile">typeinfo</filename>
1503 In addition, throw in
1509 <filename class="headerfile">cxxabi.h</filename>.
1516 C++11 <link linkend="manual.intro.using.flags">dialect</link> add
1522 <filename class="headerfile">initializer_list</filename>
1527 <filename class="headerfile">type_traits</filename>
1532 <para> There exists a library that offers runtime support for
1533 just these headers, and it is called
1534 <filename class="libraryfile">libsupc++.a</filename>. To use it, compile with <command>gcc</command> instead of <command>g++</command>, like so:
1538 <command>gcc foo.cc -lsupc++</command>
1542 No attempt is made to verify that only the minimal subset
1543 identified above is actually used at compile time. Violations
1544 are diagnosed as undefined symbols at link time.
1548 <section xml:id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"><info><title>Finding Dynamic or Shared Libraries</title></info>
1552 If the only library built is the static library
1553 (<filename class="libraryfile">libstdc++.a</filename>), or if
1554 specifying static linking, this section is can be skipped. But
1555 if building or using a shared library
1556 (<filename class="libraryfile">libstdc++.so</filename>), then
1557 additional location information will need to be provided.
1563 A quick read of the relevant part of the GCC
1564 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
1565 C++ Programs</link>, specifies linking against a C++
1566 library. More details from the
1567 GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/faq.html#rpath">FAQ</link>,
1568 which states <emphasis>GCC does not, by default, specify a
1569 location so that the dynamic linker can find dynamic libraries at
1573 Users will have to provide this information.
1576 Methods vary for different platforms and different styles, and
1577 are printed to the screen during installation. To summarize:
1582 At runtime set <literal>LD_LIBRARY_PATH</literal> in your
1583 environment correctly, so that the shared library for
1584 libstdc++ can be found and loaded. Be certain that you
1585 understand all of the other implications and behavior
1586 of <literal>LD_LIBRARY_PATH</literal> first.
1592 Compile the path to find the library at runtime into the
1593 program. This can be done by passing certain options to
1594 <command>g++</command>, which will in turn pass them on to
1595 the linker. The exact format of the options is dependent on
1596 which linker you use:
1601 GNU ld (default on GNU/Linux):
1602 <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename>
1608 <literal>-Wl,-R</literal><filename class="directory">destdir/lib</filename>
1615 Some linkers allow you to specify the path to the library by
1616 setting <literal>LD_RUN_PATH</literal> in your environment
1622 On some platforms the system administrator can configure the
1623 dynamic linker to always look for libraries in
1624 <filename class="directory">destdir/lib</filename>, for example
1625 by using the <command>ldconfig</command> utility on GNU/Linux
1626 or the <command>crle</command> utility on Solaris. This is a
1627 system-wide change which can make the system unusable so if you
1628 are unsure then use one of the other methods described above.
1633 Use the <command>ldd</command> utility on the linked executable
1635 which <filename class="libraryfile">libstdc++.so</filename>
1636 library the system will get at runtime.
1639 A <filename class="libraryfile">libstdc++.la</filename> file is
1640 also installed, for use with Libtool. If you use Libtool to
1641 create your executables, these details are taken care of for
1646 <section xml:id="manual.intro.using.linkage.experimental" xreflabel="Library Extensions"><info><title>Experimental Library Extensions</title></info>
1649 GCC 5.3 includes an implementation of the Filesystem library defined
1650 by the technical specification ISO/IEC TS 18822:2015. Because this is
1651 an experimental library extension, not part of the C++ standard, it
1652 is implemented in a separate library,
1653 <filename class="libraryfile">libstdc++fs.a</filename>, and there is
1654 no shared library for it. To use the library you should include
1655 <filename class="headerfile"><experimental/filesystem></filename>
1656 and link with <option>-lstdc++fs</option>. The library implementation
1657 is incomplete on non-POSIX platforms, specifically Windows support is
1662 Due to the experimental nature of the Filesystem library the usual
1663 guarantees about ABI stability and backwards compatibility do not apply
1664 to it. There is no guarantee that the components in any
1665 <filename class="headerfile"><experimental/xxx></filename>
1666 header will remain compatible between different GCC releases.
1671 <section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
1672 <?dbhtml filename="using_concurrency.html"?>
1675 <para>This section discusses issues surrounding the proper compilation
1676 of multithreaded applications which use the Standard C++
1677 library. This information is GCC-specific since the C++
1678 standard does not address matters of multithreaded applications.
1681 <section xml:id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"><info><title>Prerequisites</title></info>
1684 <para>All normal disclaimers aside, multithreaded C++ application are
1685 only supported when libstdc++ and all user code was built with
1686 compilers which report (via <code> gcc/g++ -v </code>) the same thread
1687 model and that model is not <emphasis>single</emphasis>. As long as your
1688 final application is actually single-threaded, then it should be
1689 safe to mix user code built with a thread model of
1690 <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built
1691 with another thread model useful on the platform. Other mixes
1692 may or may not work but are not considered supported. (Thus, if
1693 you distribute a shared C++ library in binary form only, it may
1694 be best to compile it with a GCC configured with
1695 --enable-threads for maximal interchangeability and usefulness
1696 with a user population that may have built GCC with either
1697 --enable-threads or --disable-threads.)
1699 <para>When you link a multithreaded application, you will probably
1700 need to add a library or flag to g++. This is a very
1701 non-standardized area of GCC across ports. Some ports support a
1702 special flag (the spelling isn't even standardized yet) to add
1703 all required macros to a compilation (if any such flags are
1704 required then you must provide the flag for all compilations not
1705 just linking) and link-library additions and/or replacements at
1706 link time. The documentation is weak. On several targets (including
1707 GNU/Linux, Solaris and various BSDs) -pthread is honored.
1708 Some other ports use other switches.
1709 This is not well documented anywhere other than
1710 in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries).
1714 Some uses of <classname>std::atomic</classname> also require linking
1715 to <filename class="libraryfile">libatomic</filename>.
1720 <section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info>
1724 In the terms of the 2011 C++ standard a thread-safe program is one which
1725 does not perform any conflicting non-atomic operations on memory locations
1726 and so does not contain any data races.
1727 The standard places requirements on the library to ensure that no data
1728 races are caused by the library itself or by programs which use the
1729 library correctly (as described below).
1730 The C++11 memory model and library requirements are a more formal version
1731 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
1732 prior to the 2011 standard.
1736 <para>The library strives to be thread-safe when all of the following
1741 <para>The system's libc is itself thread-safe,
1746 The compiler in use reports a thread model other than
1747 'single'. This can be tested via output from <code>gcc
1748 -v</code>. Multi-thread capable versions of gcc output
1749 something like this:
1753 Using built-in specs.
1756 gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
1759 <para>Look for "Thread model" lines that aren't equal to "single."</para>
1763 Requisite command-line flags are used for atomic operations
1764 and threading. Examples of this include <code>-pthread</code>
1765 and <code>-march=native</code>, although specifics vary
1766 depending on the host environment. See
1767 <link linkend="manual.intro.using.flags">Command Options</link> and
1768 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
1769 Dependent Options</link>.
1774 An implementation of the
1775 <filename class="headerfile">atomicity.h</filename> functions
1776 exists for the architecture in question. See the
1777 <link linkend="internals.thread_safety">internals
1778 documentation</link> for more details.
1784 <para>The user code must guard against concurrent function calls which
1785 access any particular library object's state when one or more of
1786 those accesses modifies the state. An object will be modified by
1787 invoking a non-const member function on it or passing it as a
1788 non-const argument to a library function. An object will not be
1789 modified by invoking a const member function on it or passing it to
1790 a function as a pointer- or reference-to-const.
1791 Typically, the application
1792 programmer may infer what object locks must be held based on the
1793 objects referenced in a function call and whether the objects are
1794 accessed as const or non-const. Without getting
1795 into great detail, here is an example which requires user-level
1799 library_class_a shared_object_a;
1801 void thread_main () {
1802 library_class_b *object_b = new library_class_b;
1803 shared_object_a.add_b (object_b); // must hold lock for shared_object_a
1804 shared_object_a.mutate (); // must hold lock for shared_object_a
1807 // Multiple copies of thread_main() are started in independent threads.</programlisting>
1808 <para>Under the assumption that object_a and object_b are never exposed to
1809 another thread, here is an example that does not require any
1813 void thread_main () {
1814 library_class_a object_a;
1815 library_class_b *object_b = new library_class_b;
1816 object_a.add_b (object_b);
1820 <para>All library types are safe to use in a multithreaded program
1821 if objects are not shared between threads or as
1822 long each thread carefully locks out access by any other
1823 thread while it modifies any object visible to another thread.
1824 Unless otherwise documented, the only exceptions to these rules
1825 are atomic operations on the types in
1826 <filename class="headerfile"><atomic></filename>
1827 and lock/unlock operations on the standard mutex types in
1828 <filename class="headerfile"><mutex></filename>. These
1829 atomic operations allow concurrent accesses to the same object
1830 without introducing data races.
1833 <para>The following member functions of standard containers can be
1834 considered to be const for the purposes of avoiding data races:
1835 <code>begin</code>, <code>end</code>, <code>rbegin</code>, <code>rend</code>,
1836 <code>front</code>, <code>back</code>, <code>data</code>,
1837 <code>find</code>, <code>lower_bound</code>, <code>upper_bound</code>,
1838 <code>equal_range</code>, <code>at</code>
1839 and, except in associative or unordered associative containers,
1840 <code>operator[]</code>. In other words, although they are non-const
1841 so that they can return mutable iterators, those member functions
1842 will not modify the container.
1843 Accessing an iterator might cause a non-modifying access to
1844 the container the iterator refers to (for example incrementing a
1845 list iterator must access the pointers between nodes, which are part
1846 of the container and so conflict with other accesses to the container).
1849 <para>Programs which follow the rules above will not encounter data
1850 races in library code, even when using library types which share
1851 state between distinct objects. In the example below the
1852 <code>shared_ptr</code> objects share a reference count, but
1853 because the code does not perform any non-const operations on the
1854 globally-visible object, the library ensures that the reference
1855 count updates are atomic and do not introduce data races:
1858 std::shared_ptr<int> global_sp;
1860 void thread_main() {
1861 auto local_sp = global_sp; // OK, copy constructor's parameter is reference-to-const
1863 int i = *global_sp; // OK, operator* is const
1864 int j = *local_sp; // OK, does not operate on global_sp
1866 // *global_sp = 2; // NOT OK, modifies int visible to other threads
1867 // *local_sp = 2; // NOT OK, modifies int visible to other threads
1869 // global_sp.reset(); // NOT OK, reset is non-const
1870 local_sp.reset(); // OK, does not operate on global_sp
1874 global_sp.reset(new int(1));
1875 std::thread t1(thread_main);
1876 std::thread t2(thread_main);
1882 <para>For further details of the C++11 memory model see Hans-J. Boehm's
1883 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/">Threads
1884 and memory model for C++</link> pages, particularly the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.hboehm.info/c++mm/threadsintro.html">introduction</link>
1885 and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/user-faq.html">FAQ</link>.
1889 <section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info>
1895 <section xml:id="manual.intro.using.concurrency.io" xreflabel="IO"><info><title>IO</title></info>
1897 <para>This gets a bit tricky. Please read carefully, and bear with me.
1900 <section xml:id="concurrency.io.structure" xreflabel="Structure"><info><title>Structure</title></info>
1903 type called <code>__basic_file</code> provides our abstraction layer
1904 for the <code>std::filebuf</code> classes. Nearly all decisions dealing
1905 with actual input and output must be made in <code>__basic_file</code>.
1907 <para>A generic locking mechanism is somewhat in place at the filebuf layer,
1908 but is not used in the current code. Providing locking at any higher
1909 level is akin to providing locking within containers, and is not done
1910 for the same reasons (see the links above).
1914 <section xml:id="concurrency.io.defaults" xreflabel="Defaults"><info><title>Defaults</title></info>
1916 <para>The __basic_file type is simply a collection of small wrappers around
1917 the C stdio layer (again, see the link under Structure). We do no
1918 locking ourselves, but simply pass through to calls to <code>fopen</code>,
1919 <code>fwrite</code>, and so forth.
1921 <para>So, for 3.0, the question of "is multithreading safe for I/O"
1922 must be answered with, "is your platform's C library threadsafe
1923 for I/O?" Some are by default, some are not; many offer multiple
1924 implementations of the C library with varying tradeoffs of threadsafety
1925 and efficiency. You, the programmer, are always required to take care
1926 with multiple threads.
1928 <para>(As an example, the POSIX standard requires that C stdio
1929 <code>FILE*</code> operations are atomic. POSIX-conforming C libraries
1930 (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize
1931 operations on <code>FILE*</code>s.
1932 However, you still need to not do stupid things like calling
1933 <code>fclose(fs)</code> in one thread followed by an access of
1934 <code>fs</code> in another.)
1936 <para>So, if your platform's C library is threadsafe, then your
1937 <code>fstream</code> I/O operations will be threadsafe at the lowest
1938 level. For higher-level operations, such as manipulating the data
1939 contained in the stream formatting classes (e.g., setting up callbacks
1940 inside an <code>std::ofstream</code>), you need to guard such accesses
1941 like any other critical shared resource.
1945 <section xml:id="concurrency.io.future" xreflabel="Future"><info><title>Future</title></info>
1948 second choice may be available for I/O implementations: libio. This is
1949 disabled by default, and in fact will not currently work due to other
1950 issues. It will be revisited, however.
1952 <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O
1953 implementation. When libio is in use, the <code>__basic_file</code>
1954 type is basically derived from FILE. (The real situation is more
1955 complex than that... it's derived from an internal type used to
1956 implement FILE. See libio/libioP.h to see scary things done with
1957 vtbls.) The result is that there is no "layer" of C stdio
1958 to go through; the filebuf makes calls directly into the same
1959 functions used to implement <code>fread</code>, <code>fwrite</code>,
1960 and so forth, using internal data structures. (And when I say
1961 "makes calls directly," I mean the function is literally
1962 replaced by a jump into an internal function. Fast but frightening.
1965 <para>Also, the libio internal locks are used. This requires pulling in
1966 large chunks of glibc, such as a pthreads implementation, and is one
1967 of the issues preventing widespread use of libio as the libstdc++
1968 cstdio implementation.
1970 <para>But we plan to make this work, at least as an option if not a future
1971 default. Platforms running a copy of glibc with a recent-enough
1972 version will see calls from libstdc++ directly into the glibc already
1973 installed. For other platforms, a copy of the libio subsection will
1974 be built and included in libstdc++.
1978 <section xml:id="concurrency.io.alt" xreflabel="Alt"><info><title>Alternatives</title></info>
1980 <para>Don't forget that other cstdio implementations are possible. You could
1981 easily write one to perform your own forms of locking, to solve your
1982 "interesting" problems.
1988 <section xml:id="manual.intro.using.concurrency.containers" xreflabel="Containers"><info><title>Containers</title></info>
1991 <para>This section discusses issues surrounding the design of
1992 multithreaded applications which use Standard C++ containers.
1993 All information in this section is current as of the gcc 3.0
1994 release and all later point releases. Although earlier gcc
1995 releases had a different approach to threading configuration and
1996 proper compilation, the basic code design rules presented here
1997 were similar. For information on all other aspects of
1998 multithreading as it relates to libstdc++, including details on
1999 the proper compilation of threaded code (and compatibility between
2000 threaded and non-threaded code), see Chapter 17.
2002 <para>Two excellent pages to read when working with the Standard C++
2003 containers and threads are
2004 <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
2005 https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html</link> and
2006 <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
2007 https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/Allocators.html</link>.
2009 <para><emphasis>However, please ignore all discussions about the user-level
2010 configuration of the lock implementation inside the STL
2011 container-memory allocator on those pages. For the sake of this
2012 discussion, libstdc++ configures the SGI STL implementation,
2013 not you. This is quite different from how gcc pre-3.0 worked.
2014 In particular, past advice was for people using g++ to
2015 explicitly define _PTHREADS or other macros or port-specific
2016 compilation options on the command line to get a thread-safe
2017 STL. This is no longer required for any port and should no
2018 longer be done unless you really know what you are doing and
2019 assume all responsibility.</emphasis>
2021 <para>Since the container implementation of libstdc++ uses the SGI
2022 code, we use the same definition of thread safety as SGI when
2023 discussing design. A key point that beginners may miss is the
2024 fourth major paragraph of the first page mentioned above
2025 (<emphasis>For most clients...</emphasis>), which points out that
2026 locking must nearly always be done outside the container, by
2027 client code (that'd be you, not us). There is a notable
2028 exceptions to this rule. Allocators called while a container or
2029 element is constructed uses an internal lock obtained and
2030 released solely within libstdc++ code (in fact, this is the
2031 reason STL requires any knowledge of the thread configuration).
2033 <para>For implementing a container which does its own locking, it is
2034 trivial to provide a wrapper class which obtains the lock (as
2035 SGI suggests), performs the container operation, and then
2036 releases the lock. This could be templatized <emphasis>to a certain
2037 extent</emphasis>, on the underlying container and/or a locking
2038 mechanism. Trying to provide a catch-all general template
2039 solution would probably be more trouble than it's worth.
2041 <para>The library implementation may be configured to use the
2042 high-speed caching memory allocator, which complicates thread
2043 safety issues. For all details about how to globally override
2044 this at application run-time
2045 see <link linkend="manual.intro.using.macros">here</link>. Also
2047 on <link linkend="std.util.memory.allocator">allocator</link>
2048 options and capabilities.
2054 <!-- Section 0x : Exception policies, expectations, topics -->
2055 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="using_exceptions.xml">
2058 <!-- Section 0x : Debug -->
2059 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="debug.xml">