using.xml revision 1.9
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"?> 5 6 <section xml:id="manual.intro.using.flags" xreflabel="Flags"><info><title>Command Options</title></info> 7 8 <para> 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. 13 </para> 14 15 <para> 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. 21 </para> 22 23 <table frame="all" xml:id="table.cmd_options"> 24<title>C++ Command Options</title> 25 26<tgroup cols="2" align="left" colsep="1" rowsep="1"> 27<colspec colname="c1"/> 28<colspec colname="c2"/> 29 30 <thead> 31 <row> 32 <entry>Option Flags</entry> 33 <entry>Description</entry> 34 </row> 35 </thead> 36 37 <tbody> 38 <row> 39 <entry><literal>-std=c++98</literal> or <literal>-std=c++03</literal> 40 </entry> 41 <entry>Use the 1998 ISO C++ standard plus amendments.</entry> 42 </row> 43 44 <row> 45 <entry><literal>-std=gnu++98</literal> or <literal>-std=gnu++03</literal> 46 </entry> 47 <entry>As directly above, with GNU extensions.</entry> 48 </row> 49 50 <row> 51 <entry><literal>-std=c++11</literal></entry> 52 <entry>Use the 2011 ISO C++ standard.</entry> 53 </row> 54 55 <row> 56 <entry><literal>-std=gnu++11</literal></entry> 57 <entry>As directly above, with GNU extensions.</entry> 58 </row> 59 60 <row> 61 <entry><literal>-std=c++14</literal></entry> 62 <entry>Use the 2014 ISO C++ standard.</entry> 63 </row> 64 65 <row> 66 <entry><literal>-std=gnu++14</literal></entry> 67 <entry>As directly above, with GNU extensions.</entry> 68 </row> 69 70 <row> 71 <entry><literal>-fexceptions</literal></entry> 72 <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry> 73 </row> 74 75 <row> 76 <entry><literal>-frtti</literal></entry> 77 <entry>As above, but RTTI-free dialect.</entry> 78 </row> 79 80 <row> 81 <entry><literal>-pthread</literal></entry> 82 <entry>For ISO C++11 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>. 87 </entry> 88 </row> 89 90 <row> 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>. 95 </entry> 96 </row> 97 98 <row> 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 </entry> 104 </row> 105 106 <row> 107 <entry><literal>-fopenmp</literal></entry> 108 <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry> 109 </row> 110 </tbody> 111 112</tgroup> 113</table> 114 115 </section> 116 117 <section xml:id="manual.intro.using.headers" xreflabel="Headers"><info><title>Headers</title></info> 118 <?dbhtml filename="using_headers.html"?> 119 120 121 <section xml:id="manual.intro.using.headers.all" xreflabel="Header Files"><info><title>Header Files</title></info> 122 123 124 <para> 125 The C++ standard specifies the entire set of header files that 126 must be available to all hosted implementations. Actually, the 127 word "files" is a misnomer, since the contents of the 128 headers don't necessarily have to be in any kind of external 129 file. The only rule is that when one <code>#include</code>s a 130 header, the contents of that header become available, no matter 131 how. 132 </para> 133 134 <para> 135 That said, in practice files are used. 136 </para> 137 138 <para> 139 There are two main types of include files: header files related 140 to a specific version of the ISO C++ standard (called Standard 141 Headers), and all others (TS, TR1, C++ ABI, and Extensions). 142 </para> 143 144 <para> 145 Multiple dialects of standard headers are supported, corresponding to 146 the 1998 standard as updated for 2003, the 2011 standard, the 2014 147 standard, and so on. 148 </para> 149 150 <para> 151 <xref linkend="table.cxx98_headers"/> and 152 <xref linkend="table.cxx98_cheaders"/> and 153 <xref linkend="table.cxx98_deprheaders"/> 154 show the C++98/03 include files. 155 These are available in the C++98 compilation mode, 156 i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>. 157 Unless specified otherwise below, they are also available in later modes 158 (C++11, C++14 etc). 159 </para> 160 161<table frame="all" xml:id="table.cxx98_headers"> 162<title>C++ 1998 Library Headers</title> 163 164<tgroup cols="5" align="left" colsep="1" rowsep="1"> 165<colspec colname="c1"/> 166<colspec colname="c2"/> 167<colspec colname="c3"/> 168<colspec colname="c4"/> 169<colspec colname="c5"/> 170<tbody> 171<row> 172<entry><filename class="headerfile">algorithm</filename></entry> 173<entry><filename class="headerfile">bitset</filename></entry> 174<entry><filename class="headerfile">complex</filename></entry> 175<entry><filename class="headerfile">deque</filename></entry> 176<entry><filename class="headerfile">exception</filename></entry> 177</row> 178<row> 179<entry><filename class="headerfile">fstream</filename></entry> 180<entry><filename class="headerfile">functional</filename></entry> 181<entry><filename class="headerfile">iomanip</filename></entry> 182<entry><filename class="headerfile">ios</filename></entry> 183<entry><filename class="headerfile">iosfwd</filename></entry> 184</row> 185<row> 186<entry><filename class="headerfile">iostream</filename></entry> 187<entry><filename class="headerfile">istream</filename></entry> 188<entry><filename class="headerfile">iterator</filename></entry> 189<entry><filename class="headerfile">limits</filename></entry> 190<entry><filename class="headerfile">list</filename></entry> 191</row> 192<row> 193<entry><filename class="headerfile">locale</filename></entry> 194<entry><filename class="headerfile">map</filename></entry> 195<entry><filename class="headerfile">memory</filename></entry> 196<entry><filename class="headerfile">new</filename></entry> 197<entry><filename class="headerfile">numeric</filename></entry> 198</row> 199<row> 200<entry><filename class="headerfile">ostream</filename></entry> 201<entry><filename class="headerfile">queue</filename></entry> 202<entry><filename class="headerfile">set</filename></entry> 203<entry><filename class="headerfile">sstream</filename></entry> 204<entry><filename class="headerfile">stack</filename></entry> 205</row> 206<row> 207<entry><filename class="headerfile">stdexcept</filename></entry> 208<entry><filename class="headerfile">streambuf</filename></entry> 209<entry><filename class="headerfile">string</filename></entry> 210<entry><filename class="headerfile">utility</filename></entry> 211<entry><filename class="headerfile">typeinfo</filename></entry> 212</row> 213<row> 214<entry><filename class="headerfile">valarray</filename></entry> 215<entry><filename class="headerfile">vector</filename></entry> 216<entry namest="c3" nameend="c5"/> 217</row> 218</tbody> 219</tgroup> 220</table> 221 222<para/> 223<table frame="all" xml:id="table.cxx98_cheaders"> 224<title>C++ 1998 Library Headers for C Library Facilities</title> 225 226<tgroup cols="5" align="left" colsep="1" rowsep="1"> 227<colspec colname="c1"/> 228<colspec colname="c2"/> 229<colspec colname="c3"/> 230<colspec colname="c4"/> 231<colspec colname="c5"/> 232<tbody> 233<row> 234<entry><filename class="headerfile">cassert</filename></entry> 235<entry><filename class="headerfile">cerrno</filename></entry> 236<entry><filename class="headerfile">cctype</filename></entry> 237<entry><filename class="headerfile">cfloat</filename></entry> 238<entry><filename class="headerfile">ciso646</filename></entry> 239</row> 240<row> 241<entry><filename class="headerfile">climits</filename></entry> 242<entry><filename class="headerfile">clocale</filename></entry> 243<entry><filename class="headerfile">cmath</filename></entry> 244<entry><filename class="headerfile">csetjmp</filename></entry> 245<entry><filename class="headerfile">csignal</filename></entry> 246</row> 247<row> 248<entry><filename class="headerfile">cstdarg</filename></entry> 249<entry><filename class="headerfile">cstddef</filename></entry> 250<entry><filename class="headerfile">cstdio</filename></entry> 251<entry><filename class="headerfile">cstdlib</filename></entry> 252<entry><filename class="headerfile">cstring</filename></entry> 253</row> 254<row> 255<entry><filename class="headerfile">ctime</filename></entry> 256<entry><filename class="headerfile">cwchar</filename></entry> 257<entry><filename class="headerfile">cwctype</filename></entry> 258<entry namest="c4" nameend="c5"/> 259</row> 260</tbody> 261</tgroup> 262</table> 263 264<para> 265 The following header is deprecated 266 and might be removed from a future C++ standard. 267</para> 268 269<table frame="all" xml:id="table.cxx98_deprheaders"> 270<title>C++ 1998 Deprecated Library Header</title> 271 272<tgroup cols="1" align="left" colsep="1" rowsep="1"> 273<colspec colname="c1"/> 274<tbody> 275<row> 276<entry><filename class="headerfile">strstream</filename></entry> 277</row> 278</tbody> 279</tgroup> 280</table> 281 282<para> 283<xref linkend="table.cxx11_headers"/> and 284<xref linkend="table.cxx11_cheaders"/> show the C++11 include files. 285These are available in C++11 compilation 286mode, i.e. <literal>-std=c++11</literal> or <literal>-std=gnu++11</literal>. 287Including these headers in C++98/03 mode may result in compilation errors. 288Unless specified otherwise below, they are also available in later modes 289(C++14 etc). 290</para> 291 292<para/> 293<table frame="all" xml:id="table.cxx11_headers"> 294<title>C++ 2011 Library Headers</title> 295 296<tgroup cols="5" align="left" colsep="1" rowsep="1"> 297<colspec colname="c1"/> 298<colspec colname="c2"/> 299<colspec colname="c3"/> 300<colspec colname="c4"/> 301<colspec colname="c5"/> 302<tbody> 303 304<row> 305<entry><filename class="headerfile">array</filename></entry> 306<entry><filename class="headerfile">atomic</filename></entry> 307<entry><filename class="headerfile">chrono</filename></entry> 308<entry><filename class="headerfile">codecvt</filename></entry> 309<entry><filename class="headerfile">condition_variable</filename></entry> 310</row> 311<row> 312<entry><filename class="headerfile">forward_list</filename></entry> 313<entry><filename class="headerfile">future</filename></entry> 314<entry><filename class="headerfile">initalizer_list</filename></entry> 315<entry><filename class="headerfile">mutex</filename></entry> 316<entry><filename class="headerfile">random</filename></entry> 317</row> 318<row> 319<entry><filename class="headerfile">ratio</filename></entry> 320<entry><filename class="headerfile">regex</filename></entry> 321<entry><filename class="headerfile">scoped_allocator</filename></entry> 322<entry><filename class="headerfile">system_error</filename></entry> 323<entry><filename class="headerfile">thread</filename></entry> 324</row> 325<row> 326<entry><filename class="headerfile">tuple</filename></entry> 327<entry><filename class="headerfile">typeindex</filename></entry> 328<entry><filename class="headerfile">type_traits</filename></entry> 329<entry><filename class="headerfile">unordered_map</filename></entry> 330<entry><filename class="headerfile">unordered_set</filename></entry> 331</row> 332 333</tbody> 334</tgroup> 335</table> 336 337<para/> 338 339<table frame="all" xml:id="table.cxx11_cheaders"> 340<title>C++ 2011 Library Headers for C Library Facilities</title> 341 342<tgroup cols="5" align="left" colsep="1" rowsep="1"> 343<colspec colname="c1"/> 344<colspec colname="c2"/> 345<colspec colname="c3"/> 346<colspec colname="c4"/> 347<colspec colname="c5"/> 348<tbody> 349<row> 350<entry><filename class="headerfile">ccomplex</filename></entry> 351<entry><filename class="headerfile">cfenv</filename></entry> 352<entry><filename class="headerfile">cinttypes</filename></entry> 353<entry><filename class="headerfile">cstdalign</filename></entry> 354<entry><filename class="headerfile">cstdbool</filename></entry> 355</row> 356<row> 357<entry><filename class="headerfile">cstdint</filename></entry> 358<entry><filename class="headerfile">ctgmath</filename></entry> 359<entry><filename class="headerfile">cuchar</filename></entry> 360<entry namest="c4" nameend="c5"/> 361</row> 362</tbody> 363</tgroup> 364</table> 365 366<para> 367<xref linkend="table.cxx14_headers"/> shows the C++14 include file. 368This is available in C++14 compilation 369mode, i.e. <literal>-std=c++14</literal> or <literal>-std=gnu++14</literal>. 370Including this header in C++98/03 mode or C++11 will not result in 371compilation errors, but will not define anything. 372Unless specified otherwise below, it is also available in later modes 373(C++17 etc). 374</para> 375 376<para/> 377<table frame="all" xml:id="table.cxx14_headers"> 378<title>C++ 2014 Library Header</title> 379 380<tgroup cols="1" align="left" colsep="1" rowsep="1"> 381<colspec colname="c1"/> 382<tbody> 383<row> 384<entry><filename class="headerfile">shared_mutex</filename></entry> 385</row> 386</tbody> 387</tgroup> 388</table> 389 390<para> 391<xref linkend="table.cxx17_headers"/> shows the C++17 include files. 392These are available in C++17 compilation 393mode, i.e. <literal>-std=c++17</literal> or <literal>-std=gnu++17</literal>. 394Including these headers in earlier modes will not result in 395compilation errors, but will not define anything. 396Unless specified otherwise below, they are also available in later modes 397(C++20 etc). 398</para> 399 400<para/> 401<table frame="all" xml:id="table.cxx17_headers"> 402<title>C++ 2017 Library Headers</title> 403 404<tgroup cols="4" align="left" colsep="1" rowsep="1"> 405<colspec colname="c1"/> 406<colspec colname="c2"/> 407<colspec colname="c3"/> 408<colspec colname="c4"/> 409<tbody> 410<row> 411<entry><filename class="headerfile">any</filename></entry> 412<entry><filename class="headerfile">optional</filename></entry> 413<entry><filename class="headerfile">string_view</filename></entry> 414<entry><filename class="headerfile">variant</filename></entry> 415</row> 416</tbody> 417</tgroup> 418</table> 419 420 421<para> 422<xref linkend="table.filesystemts_headers"/>, 423shows the additional include file define by the 424File System Technical Specification, ISO/IEC TS 18822. 425This is available in C++11 and later compilation modes. 426Including this header in earlier modes will not result in 427compilation errors, but will not define anything. 428</para> 429 430<para/> 431<table frame="all" xml:id="table.filesystemts_headers"> 432<title>File System TS Header</title> 433 434<tgroup cols="1" align="left" colsep="1" rowsep="1"> 435<colspec colname="c1"/> 436<tbody> 437<row> 438<entry><filename class="headerfile">experimental/filesystem</filename></entry> 439</row> 440</tbody> 441</tgroup> 442</table> 443 444 445<para> 446<xref linkend="table.libfundts_headers"/>, 447shows the additional include files define by the C++ Extensions for 448Library Fundamentals Technical Specification, ISO/IEC TS 19568. 449These are available in C++14 and later compilation modes. 450Including these headers in earlier modes will not result in 451compilation errors, but will not define anything. 452</para> 453 454<para/> 455<table frame="all" xml:id="table.libfundts_headers"> 456<title>Library Fundamentals TS Headers</title> 457 458<tgroup cols="5" align="left" colsep="1" rowsep="1"> 459<colspec colname="c1"/> 460<colspec colname="c2"/> 461<colspec colname="c3"/> 462<colspec colname="c4"/> 463<colspec colname="c5"/> 464<tbody> 465<row> 466<entry><filename class="headerfile">experimental/algorithm</filename></entry> 467<entry><filename class="headerfile">experimental/any</filename></entry> 468<entry><filename class="headerfile">experimental/array</filename></entry> 469<entry><filename class="headerfile">experimental/chrono</filename></entry> 470<entry><filename class="headerfile">experimental/deque</filename></entry> 471</row> 472<row> 473<entry><filename class="headerfile">experimental/forward_list</filename></entry> 474<entry><filename class="headerfile">experimental/functional</filename></entry> 475<entry><filename class="headerfile">experimental/iterator</filename></entry> 476<entry><filename class="headerfile">experimental/list</filename></entry> 477<entry><filename class="headerfile">experimental/map</filename></entry> 478</row> 479<row> 480<entry><filename class="headerfile">experimental/memory</filename></entry> 481<entry><filename class="headerfile">experimental/memory_resource</filename></entry> 482<entry><filename class="headerfile">experimental/numeric</filename></entry> 483<entry><filename class="headerfile">experimental/optional</filename></entry> 484<entry><filename class="headerfile">experimental/propagate_const</filename></entry> 485</row> 486<row> 487<entry><filename class="headerfile">experimental/random</filename></entry> 488<entry><filename class="headerfile">experimental/ratio</filename></entry> 489<entry><filename class="headerfile">experimental/regex</filename></entry> 490<entry><filename class="headerfile">experimental/set</filename></entry> 491<entry><filename class="headerfile">experimental/source_location</filename></entry> 492</row> 493<row> 494<entry><filename class="headerfile">experimental/string</filename></entry> 495<entry><filename class="headerfile">experimental/string_view</filename></entry> 496<entry><filename class="headerfile">experimental/system_error</filename></entry> 497<entry><filename class="headerfile">experimental/tuple</filename></entry> 498<entry><filename class="headerfile">experimental/type_traits</filename></entry> 499</row> 500<row> 501<entry><filename class="headerfile">experimental/unordered_map</filename></entry> 502<entry><filename class="headerfile">experimental/unordered_set</filename></entry> 503<entry><filename class="headerfile">experimental/utility</filename></entry> 504<entry><filename class="headerfile">experimental/vector</filename></entry> 505<entry /> 506</row> 507</tbody> 508</tgroup> 509</table> 510 511 512<para> 513 In addition, TR1 includes as: 514</para> 515 516<table frame="all" xml:id="table.tr1_headers"> 517<title>C++ TR 1 Library Headers</title> 518 519<tgroup cols="5" align="left" colsep="1" rowsep="1"> 520<colspec colname="c1"/> 521<colspec colname="c2"/> 522<colspec colname="c3"/> 523<colspec colname="c4"/> 524<colspec colname="c5"/> 525<tbody> 526 527<row> 528<entry><filename class="headerfile">tr1/array</filename></entry> 529<entry><filename class="headerfile">tr1/complex</filename></entry> 530<entry><filename class="headerfile">tr1/memory</filename></entry> 531<entry><filename class="headerfile">tr1/functional</filename></entry> 532<entry><filename class="headerfile">tr1/random</filename></entry> 533</row> 534<row> 535<entry><filename class="headerfile">tr1/regex</filename></entry> 536<entry><filename class="headerfile">tr1/tuple</filename></entry> 537<entry><filename class="headerfile">tr1/type_traits</filename></entry> 538<entry><filename class="headerfile">tr1/unordered_map</filename></entry> 539<entry><filename class="headerfile">tr1/unordered_set</filename></entry> 540</row> 541<row> 542<entry><filename class="headerfile">tr1/utility</filename></entry> 543<entry namest="c2" nameend="c5"/> 544</row> 545 546</tbody> 547</tgroup> 548</table> 549 550<para/> 551 552 553<table frame="all" xml:id="table.tr1_cheaders"> 554<title>C++ TR 1 Library Headers for C Library Facilities</title> 555 556<tgroup cols="5" align="left" colsep="1" rowsep="1"> 557<colspec colname="c1"/> 558<colspec colname="c2"/> 559<colspec colname="c3"/> 560<colspec colname="c4"/> 561<colspec colname="c5"/> 562<tbody> 563 564<row> 565<entry><filename class="headerfile">tr1/ccomplex</filename></entry> 566<entry><filename class="headerfile">tr1/cfenv</filename></entry> 567<entry><filename class="headerfile">tr1/cfloat</filename></entry> 568<entry><filename class="headerfile">tr1/cmath</filename></entry> 569<entry><filename class="headerfile">tr1/cinttypes</filename></entry> 570</row> 571<row> 572<entry><filename class="headerfile">tr1/climits</filename></entry> 573<entry><filename class="headerfile">tr1/cstdarg</filename></entry> 574<entry><filename class="headerfile">tr1/cstdbool</filename></entry> 575<entry><filename class="headerfile">tr1/cstdint</filename></entry> 576<entry><filename class="headerfile">tr1/cstdio</filename></entry> 577</row> 578<row> 579<entry><filename class="headerfile">tr1/cstdlib</filename></entry> 580<entry><filename class="headerfile">tr1/ctgmath</filename></entry> 581<entry><filename class="headerfile">tr1/ctime</filename></entry> 582<entry><filename class="headerfile">tr1/cwchar</filename></entry> 583<entry><filename class="headerfile">tr1/cwctype</filename></entry> 584</row> 585 586</tbody> 587</tgroup> 588</table> 589 590 591<para>Decimal floating-point arithmetic is available if the C++ 592compiler supports scalar decimal floating-point types defined via 593<code>__attribute__((mode(SD|DD|LD)))</code>. 594</para> 595 596<table frame="all" xml:id="table.decfp_headers"> 597<title>C++ TR 24733 Decimal Floating-Point Header</title> 598 599<tgroup cols="1" align="left" colsep="1" rowsep="1"> 600<colspec colname="c1"/> 601<tbody> 602<row> 603<entry><filename class="headerfile">decimal/decimal</filename></entry> 604</row> 605</tbody> 606</tgroup> 607</table> 608 609<para> 610 Also included are files for the C++ ABI interface: 611</para> 612 613<table frame="all" xml:id="table.abi_headers"> 614<title>C++ ABI Headers</title> 615 616<tgroup cols="2" align="left" colsep="1" rowsep="1"> 617<colspec colname="c1"/> 618<colspec colname="c2"/> 619<tbody> 620<row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row> 621</tbody> 622</tgroup> 623</table> 624 625<para> 626 And a large variety of extensions. 627</para> 628 629<table frame="all" xml:id="table.ext_headers"> 630<title>Extension Headers</title> 631 632<tgroup cols="5" align="left" colsep="1" rowsep="1"> 633<colspec colname="c1"/> 634<colspec colname="c2"/> 635<colspec colname="c3"/> 636<colspec colname="c4"/> 637<colspec colname="c5"/> 638<tbody> 639 640<row> 641<entry><filename class="headerfile">ext/algorithm</filename></entry> 642<entry><filename class="headerfile">ext/atomicity.h</filename></entry> 643<entry><filename class="headerfile">ext/array_allocator.h</filename></entry> 644<entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry> 645<entry><filename class="headerfile">ext/cast.h</filename></entry> 646</row> 647<row> 648<entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry> 649<entry><filename class="headerfile">ext/concurrence.h</filename></entry> 650<entry><filename class="headerfile">ext/debug_allocator.h</filename></entry> 651<entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry> 652<entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry> 653</row> 654<row> 655<entry><filename class="headerfile">ext/functional</filename></entry> 656<entry><filename class="headerfile">ext/iterator</filename></entry> 657<entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry> 658<entry><filename class="headerfile">ext/memory</filename></entry> 659<entry><filename class="headerfile">ext/mt_allocator.h</filename></entry> 660</row> 661<row> 662<entry><filename class="headerfile">ext/new_allocator.h</filename></entry> 663<entry><filename class="headerfile">ext/numeric</filename></entry> 664<entry><filename class="headerfile">ext/numeric_traits.h</filename></entry> 665<entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry> 666<entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry> 667</row> 668<row> 669<entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry> 670<entry><filename class="headerfile">ext/pool_allocator.h</filename></entry> 671<entry><filename class="headerfile">ext/rb_tree</filename></entry> 672<entry><filename class="headerfile">ext/rope</filename></entry> 673<entry><filename class="headerfile">ext/slist</filename></entry> 674</row> 675<row> 676<entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry> 677<entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry> 678<entry><filename class="headerfile">ext/throw_allocator.h</filename></entry> 679<entry><filename class="headerfile">ext/typelist.h</filename></entry> 680<entry><filename class="headerfile">ext/type_traits.h</filename></entry> 681</row> 682<row> 683<entry><filename class="headerfile">ext/vstring.h</filename></entry> 684<entry namest="c2" nameend="c5"/> 685</row> 686 687</tbody> 688</tgroup> 689</table> 690 691<para/> 692 693<table frame="all" xml:id="table.debug_headers"> 694<title>Extension Debug Headers</title> 695 696<tgroup cols="5" align="left" colsep="1" rowsep="1"> 697<colspec colname="c1"/> 698<colspec colname="c2"/> 699<colspec colname="c3"/> 700<colspec colname="c4"/> 701<colspec colname="c5"/> 702<tbody> 703 704<row> 705<entry><filename class="headerfile">debug/array</filename></entry> 706<entry><filename class="headerfile">debug/bitset</filename></entry> 707<entry><filename class="headerfile">debug/deque</filename></entry> 708<entry><filename class="headerfile">debug/forward_list</filename></entry> 709<entry><filename class="headerfile">debug/list</filename></entry> 710</row> 711<row> 712<entry><filename class="headerfile">debug/map</filename></entry> 713<entry><filename class="headerfile">debug/set</filename></entry> 714<entry><filename class="headerfile">debug/string</filename></entry> 715<entry><filename class="headerfile">debug/unordered_map</filename></entry> 716<entry><filename class="headerfile">debug/unordered_set</filename></entry> 717</row> 718<row> 719<entry><filename class="headerfile">debug/vector</filename></entry> 720<entry namest="c2" nameend="c5"/> 721</row> 722 723</tbody> 724</tgroup> 725</table> 726 727<para/> 728 729<table frame="all" xml:id="table.profile_headers"> 730<title>Extension Profile Headers</title> 731 732<tgroup cols="4" align="left" colsep="1" rowsep="1"> 733<colspec colname="c1"/> 734<colspec colname="c2"/> 735<colspec colname="c3"/> 736<colspec colname="c4"/> 737<tbody> 738 739<row> 740<entry><filename class="headerfile">profile/bitset</filename></entry> 741<entry><filename class="headerfile">profile/deque</filename></entry> 742<entry><filename class="headerfile">profile/list</filename></entry> 743<entry><filename class="headerfile">profile/map</filename></entry> 744</row> 745 746<row> 747<entry><filename class="headerfile">profile/set</filename></entry> 748<entry><filename class="headerfile">profile/unordered_map</filename></entry> 749<entry><filename class="headerfile">profile/unordered_set</filename></entry> 750<entry><filename class="headerfile">profile/vector</filename></entry> 751</row> 752 753</tbody> 754</tgroup> 755</table> 756 757<para/> 758 759<table frame="all" xml:id="table.parallel_headers"> 760<title>Extension Parallel Headers</title> 761 762<tgroup cols="2" align="left" colsep="1" rowsep="1"> 763<colspec colname="c1"/> 764<colspec colname="c2"/> 765<tbody> 766<row> 767<entry><filename class="headerfile">parallel/algorithm</filename></entry> 768<entry><filename class="headerfile">parallel/numeric</filename></entry> 769</row> 770</tbody> 771</tgroup> 772</table> 773 774 </section> 775 776 <section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info> 777 778 779<para> A few simple rules. 780</para> 781 782<para>First, mixing different dialects of the standard headers is not 783possible. It's an all-or-nothing affair. Thus, code like 784</para> 785 786<programlisting> 787#include <array> 788#include <functional> 789</programlisting> 790 791<para>Implies C++11 mode. To use the entities in <array>, the C++11 792compilation mode must be used, which implies the C++11 functionality 793(and deprecations) in <functional> will be present. 794</para> 795 796<para>Second, the other headers can be included with either dialect of 797the standard headers, although features and types specific to C++11 798are still only enabled when in C++11 compilation mode. So, to use 799rvalue references with <code>__gnu_cxx::vstring</code>, or to use the 800debug-mode versions of <code>std::unordered_map</code>, one must use 801the <code>std=gnu++11</code> compiler flag. (Or <code>std=c++11</code>, of course.) 802</para> 803 804<para>A special case of the second rule is the mixing of TR1 and C++11 805facilities. It is possible (although not especially prudent) to 806include both the TR1 version and the C++11 version of header in the 807same translation unit: 808</para> 809 810<programlisting> 811#include <tr1/type_traits> 812#include <type_traits> 813</programlisting> 814 815<para> Several parts of C++11 diverge quite substantially from TR1 predecessors. 816</para> 817 </section> 818 819 <section xml:id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"><info><title>The C Headers and <code>namespace std</code></title></info> 820 821 822<para> 823 The standard specifies that if one includes the C-style header 824 (<math.h> in this case), the symbols will be available 825 in the global namespace and perhaps in 826 namespace <code>std::</code> (but this is no longer a firm 827 requirement.) On the other hand, including the C++-style 828 header (<cmath>) guarantees that the entities will be 829 found in namespace std and perhaps in the global namespace. 830 </para> 831 832<para> 833Usage of C++-style headers is recommended, as then 834C-linkage names can be disambiguated by explicit qualification, such 835as by <code>std::abort</code>. In addition, the C++-style headers can 836use function overloading to provide a simpler interface to certain 837families of C-functions. For instance in <cmath>, the 838function <code>std::sin</code> has overloads for all the builtin 839floating-point types. This means that <code>std::sin</code> can be 840used uniformly, instead of a combination 841of <code>std::sinf</code>, <code>std::sin</code>, 842and <code>std::sinl</code>. 843</para> 844 </section> 845 846 <section xml:id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"><info><title>Precompiled Headers</title></info> 847 848 849 850<para>There are three base header files that are provided. They can be 851used to precompile the standard headers and extensions into binary 852files that may then be used to speed up compilations that use these headers. 853</para> 854 855 856<itemizedlist> 857<listitem> 858 <para>stdc++.h</para> 859<para>Includes all standard headers. Actual content varies depending on 860<link linkend="manual.intro.using.flags">language dialect</link>. 861</para> 862</listitem> 863 864<listitem> 865 <para>stdtr1c++.h</para> 866<para>Includes all of <stdc++.h>, and adds all the TR1 headers. 867</para> 868</listitem> 869 870<listitem><para>extc++.h</para> 871<para>Includes all of <stdc++.h>, and adds all the Extension headers 872(and in C++98 mode also adds all the TR1 headers by including all of 873<stdtr1c++.h>). 874</para></listitem> 875</itemizedlist> 876 877<para>To construct a .gch file from one of these base header files, 878first find the include directory for the compiler. One way to do 879this is:</para> 880 881<programlisting> 882g++ -v hello.cc 883 884#include <...> search starts here: 885 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0 886... 887End of search list. 888</programlisting> 889 890 891<para>Then, create a precompiled header file with the same flags that 892will be used to compile other projects.</para> 893 894<programlisting> 895g++ -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 896</programlisting> 897 898<para>The resulting file will be quite large: the current size is around 899thirty megabytes. </para> 900 901<para>How to use the resulting file.</para> 902 903<programlisting> 904g++ -I. -include stdc++.h -H -g -O2 hello.cc 905</programlisting> 906 907<para>Verification that the PCH file is being used is easy:</para> 908 909<programlisting> 910g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe 911! ./stdc++.h.gch 912. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream 913. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string 914</programlisting> 915 916<para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used.</para> 917<para/> 918 919<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>. 920</para> 921 922 </section> 923 </section> 924 925 926 <section xml:id="manual.intro.using.macros" xreflabel="Macros"><info><title>Macros</title></info> 927 <?dbhtml filename="using_macros.html"?> 928 929 930 <para> 931 All library macros begin with <code>_GLIBCXX_</code>. 932 </para> 933 934 <para> 935 Furthermore, all pre-processor macros, switches, and 936 configuration options are gathered in the 937 file <filename class="headerfile">c++config.h</filename>, which 938 is generated during the libstdc++ configuration and build 939 process. This file is then included when needed by files part of 940 the public libstdc++ API, like 941 <filename class="headerfile"><ios></filename>. Most of these 942 macros should not be used by consumers of libstdc++, and are reserved 943 for internal implementation use. <emphasis>These macros cannot 944 be redefined</emphasis>. 945 </para> 946 947 <para> 948 A select handful of macros control libstdc++ extensions and extra 949 features, or provide versioning information for the API. Only 950 those macros listed below are offered for consideration by the 951 general public. 952 </para> 953 954 <para>Below are the macros which users may check for library version 955 information. </para> 956 957 <variablelist> 958 <varlistentry> 959 <term><code>_GLIBCXX_RELEASE</code></term> 960 <listitem> 961 <para>The major release number for libstdc++. This macro is defined 962 to the GCC major version that the libstdc++ headers belong to, 963 as an integer constant. 964 When compiling with GCC it has the same value as GCC's pre-defined 965 macro <symbol>__GNUC__</symbol>. 966 This macro can be used when libstdc++ is used with a non-GNU 967 compiler where <symbol>__GNUC__</symbol> is not defined, or has a 968 different value that doesn't correspond to the libstdc++ version. 969 This macro first appeared in the GCC 7.1 release and is not defined 970 for GCC 6.x or older releases. 971 </para> 972 </listitem> 973 </varlistentry> 974 <varlistentry> 975 <term><code>__GLIBCXX__</code></term> 976 <listitem> 977 <para>The revision date of the libstdc++ source code, 978 in compressed ISO date format, as an unsigned 979 long. For notes about using this macro and details on the value of 980 this macro for a particular release, please consult the 981 <link linkend="abi.versioning.__GLIBCXX__">ABI History</link> 982 appendix. 983 </para> 984 </listitem> 985 </varlistentry> 986 </variablelist> 987 988 <para>Below are the macros which users may change with #define/#undef or 989 with -D/-U compiler flags. The default state of the symbol is 990 listed.</para> 991 992 <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means 993 that the symbol is initially chosen (or not) based on 994 --enable/--disable options at library build and configure time 995 (documented in 996 <link linkend="manual.intro.setup.configure">Configure</link>), 997 with the various --enable/--disable choices being translated to 998 #define/#undef). 999 </para> 1000 1001 <para> <acronym>ABI</acronym> means that changing from the default value may 1002 mean changing the <acronym>ABI</acronym> of compiled code. In other words, 1003 these choices control code which has already been compiled (i.e., in a 1004 binary such as libstdc++.a/.so). If you explicitly #define or 1005 #undef these macros, the <emphasis>headers</emphasis> may see different code 1006 paths, but the <emphasis>libraries</emphasis> which you link against will not. 1007 Experimenting with different values with the expectation of 1008 consistent linkage requires changing the config headers before 1009 building/installing the library. 1010 </para> 1011 1012 <variablelist> 1013 <varlistentry><term><code>_GLIBCXX_USE_DEPRECATED</code></term> 1014 <listitem> 1015 <para> 1016 Defined by default. Not configurable. ABI-changing. Turning this off 1017 removes older ARM-style iostreams code, and other anachronisms 1018 from the API. This macro is dependent on the version of the 1019 standard being tracked, and as a result may give different results for 1020 <code>-std=c++98</code> and <code>-std=c++11</code>. This may 1021 be useful in updating old C++ code which no longer meet the 1022 requirements of the language, or for checking current code 1023 against new language standards. 1024 </para> 1025 </listitem></varlistentry> 1026 1027 <varlistentry><term><code>_GLIBCXX_USE_CXX11_ABI</code></term> 1028 <listitem> 1029 <para> 1030 Defined to the value <literal>1</literal> by default. 1031 Configurable via <code>--disable-libstdcxx-dual-abi</code> 1032 and/or <code>--with-default-libstdcxx-abi</code>. 1033 ABI-changing. 1034 When defined to a non-zero value the library headers will use the 1035 new C++11-conforming ABI introduced in GCC 5, rather than the older 1036 ABI introduced in GCC 3.4. This changes the definition of several 1037 class templates, including <classname>std:string</classname>, 1038 <classname>std::list</classname> and some locale facets. 1039 For more details see <xref linkend="manual.intro.using.abi"/>. 1040 </para> 1041 </listitem></varlistentry> 1042 1043 <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term> 1044 <listitem> 1045 <para> 1046 Undefined by default. Configurable via 1047 <code>--enable-concept-checks</code>. When defined, performs 1048 compile-time checking on certain template instantiations to 1049 detect violations of the requirements of the standard. This 1050 macro has no effect for freestanding implementations. 1051 This is described in more detail in 1052 <link linkend="manual.ext.compile_checks">Compile Time Checks</link>. 1053 </para> 1054 </listitem></varlistentry> 1055 1056 <varlistentry><term><code>_GLIBCXX_ASSERTIONS</code></term> 1057 <listitem> 1058 <para> 1059 Undefined by default. When defined, enables extra error checking in 1060 the form of precondition assertions, such as bounds checking in 1061 strings and null pointer checks when dereferencing smart pointers. 1062 </para> 1063 </listitem></varlistentry> 1064 <varlistentry><term><code>_GLIBCXX_DEBUG</code></term> 1065 <listitem> 1066 <para> 1067 Undefined by default. When defined, compiles user code using 1068 the <link linkend="manual.ext.debug_mode">debug mode</link>. 1069 When defined, <code>_GLIBCXX_ASSERTIONS</code> is defined 1070 automatically, so all the assertions enabled by that macro are also 1071 enabled in debug mode. 1072 </para> 1073 </listitem></varlistentry> 1074 <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term> 1075 <listitem> 1076 <para> 1077 Undefined by default. When defined while compiling with 1078 the <link linkend="manual.ext.debug_mode">debug mode</link>, makes 1079 the debug mode extremely picky by making the use of libstdc++ 1080 extensions and libstdc++-specific behavior into errors. 1081 </para> 1082 </listitem></varlistentry> 1083 <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term> 1084 <listitem> 1085 <para>Undefined by default. When defined, compiles user code 1086 using the <link linkend="manual.ext.parallel_mode">parallel 1087 mode</link>. 1088 </para> 1089 </listitem></varlistentry> 1090 <varlistentry><term><code>_GLIBCXX_PARALLEL_ASSERTIONS</code></term> 1091 <listitem> 1092 <para>Undefined by default, but when any parallel mode header is included 1093 this macro will be defined to a non-zero value if 1094 <code>_GLIBCXX_ASSERTIONS</code> has a non-zero value, otherwise to zero. 1095 When defined to a non-zero value, it enables extra error checking and 1096 assertions in the parallel mode. 1097 </para> 1098 </listitem></varlistentry> 1099 1100 <varlistentry><term><code>_GLIBCXX_PROFILE</code></term> 1101 <listitem> 1102 <para>Undefined by default. When defined, compiles user code 1103 using the <link linkend="manual.ext.profile_mode">profile 1104 mode</link>. 1105 </para> 1106 </listitem></varlistentry> 1107 1108 <varlistentry><term><code>__STDCPP_WANT_MATH_SPEC_FUNCS__</code></term> 1109 <listitem> 1110 <para>Undefined by default. When defined to a non-zero integer constant, 1111 enables support for ISO/IEC 29124 Special Math Functions. 1112 </para> 1113 </listitem></varlistentry> 1114 </variablelist> 1115 1116 </section> 1117 1118<section xml:id="manual.intro.using.abi" xreflabel="Dual ABI"> 1119 <info><title>Dual ABI</title></info> 1120 <?dbhtml filename="using_dual_abi.html"?> 1121 1122<para> In the GCC 5.1 release libstdc++ introduced a new library ABI that 1123 includes new implementations of <classname>std::string</classname> and 1124 <classname>std::list</classname>. These changes were necessary to conform 1125 to the 2011 C++ standard which forbids Copy-On-Write strings and requires 1126 lists to keep track of their size. 1127</para> 1128 1129<para> In order to maintain backwards compatibility for existing code linked 1130 to libstdc++ the library's soname has not changed and the old 1131 implementations are still supported in parallel with the new ones. 1132 This is achieved by defining the new implementations in an inline namespace 1133 so they have different names for linkage purposes, e.g. the new version of 1134 <classname>std::list<int></classname> is actually defined as 1135 <classname>std::__cxx11::list<int></classname>. Because the symbols 1136 for the new implementations have different names the definitions for both 1137 versions can be present in the same library. 1138</para> 1139 1140<para> The <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro (see 1141 <xref linkend="manual.intro.using.macros"/>) controls whether 1142 the declarations in the library headers use the old or new ABI. 1143 So the decision of which ABI to use can be made separately for each 1144 source file being compiled. 1145 Using the default configuration options for GCC the default value 1146 of the macro is <literal>1</literal> which causes the new ABI to be active, 1147 so to use the old ABI you must explicitly define the macro to 1148 <literal>0</literal> before including any library headers. 1149 (Be aware that some GNU/Linux distributions configure GCC 5 differently so 1150 that the default value of the macro is <literal>0</literal> and users must 1151 define it to <literal>1</literal> to enable the new ABI.) 1152</para> 1153 1154<para> Although the changes were made for C++11 conformance, the choice of ABI 1155 to use is independent of the <option>-std</option> option used to compile 1156 your code, i.e. for a given GCC build the default value of the 1157 <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro is the same for all dialects. 1158 This ensures that the <option>-std</option> does not change the ABI, so 1159 that it is straightforward to link C++03 and C++11 code together. 1160</para> 1161 1162<para> Because <classname>std::string</classname> is used extensively 1163 throughout the library a number of other types are also defined twice, 1164 including the stringstream classes and several facets used by 1165 <classname>std::locale</classname>. The standard facets which are always 1166 installed in a locale may be present twice, with both ABIs, to ensure that 1167 code like 1168 <code>std::use_facet<std::time_get<char>>(locale);</code> 1169 will work correctly for both <classname>std::time_get</classname> and 1170 <classname>std::__cxx11::time_get</classname> (even if a user-defined 1171 facet that derives from one or other version of 1172 <classname>time_get</classname> is installed in the locale). 1173</para> 1174 1175<para> Although the standard exception types defined in 1176 <filename class="headerfile"><stdexcept></filename> use strings, most 1177 are not defined twice, so that a <classname>std::out_of_range</classname> 1178 exception thrown in one file can always be caught by a suitable handler in 1179 another file, even if the two files are compiled with different ABIs. 1180</para> 1181 1182<para> One exception type does change when using the new ABI, namely 1183 <classname>std::ios_base::failure</classname>. 1184 This is necessary because the 2011 standard changed its base class from 1185 <classname>std::exception</classname> to 1186 <classname>std::system_error</classname>, which causes its layout to change. 1187 Exceptions due to iostream errors are thrown by a function inside 1188 <filename class="libraryfile">libstdc++.so</filename>, so whether the thrown 1189 exception uses the old <classname>std::ios_base::failure</classname> type 1190 or the new one depends on the ABI that was active when 1191 <filename class="libraryfile">libstdc++.so</filename> was built, 1192 <emphasis>not</emphasis> the ABI active in the user code that is using 1193 iostreams. 1194 This means that for a given build of GCC the type thrown is fixed. 1195 In current releases the library throws a special type that can be caught 1196 by handlers for either the old or new type, 1197 but for GCC 7.1, 7.2 and 7.3 the library throws the new 1198 <classname>std::ios_base::failure</classname> type, 1199 and for GCC 5.x and 6.x the library throws the old type. 1200 Catch handlers of type <classname>std::ios_base::failure</classname> 1201 will only catch the exceptions if using a newer release, 1202 or if the handler is compiled with the same ABI as the type thrown by 1203 the library. 1204 Handlers for <classname>std::exception</classname> will always catch 1205 iostreams exceptions, because the old and new type both inherit from 1206 <classname>std::exception</classname>. 1207</para> 1208 1209<section xml:id="manual.intro.using.abi.trouble" xreflabel="Dual ABI Troubleshooting"><info><title>Troubleshooting</title></info> 1210 1211<para> If you get linker errors about undefined references to symbols 1212 that involve types in the <code>std::__cxx11</code> namespace or the tag 1213 <code>[abi:cxx11]</code> then it probably indicates that you are trying to 1214 link together object files that were compiled with different values for the 1215 <symbol>_GLIBCXX_USE_CXX11_ABI</symbol> macro. This commonly happens when 1216 linking to a third-party library that was compiled with an older version 1217 of GCC. If the third-party library cannot be rebuilt with the new ABI then 1218 you will need to recompile your code with the old ABI. 1219</para> 1220 1221<para> Not all uses of the new ABI will cause changes in symbol names, for 1222 example a class with a <classname>std::string</classname> member variable 1223 will have the same mangled name whether compiled with the old or new ABI. 1224 In order to detect such problems the new types and functions are 1225 annotated with the <property>abi_tag</property> attribute, allowing the 1226 compiler to warn about potential ABI incompatibilities in code using them. 1227 Those warnings can be enabled with the <option>-Wabi-tag</option> option. 1228</para> 1229 1230</section> 1231</section> 1232 1233 <section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info> 1234 <?dbhtml filename="using_namespaces.html"?> 1235 1236 1237 <section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info> 1238 1239 1240 1241 1242<para> There are three main namespaces. 1243</para> 1244 1245<itemizedlist> 1246 <listitem><para>std</para> 1247<para>The ISO C++ standards specify that "all library entities are defined 1248within namespace std." This includes namespaces nested 1249within namespace <code>std</code>, such as namespace 1250<code>std::chrono</code>. 1251</para> 1252</listitem> 1253<listitem><para>abi</para> 1254<para>Specified by the C++ ABI. This ABI specifies a number of type and 1255function APIs supplemental to those required by the ISO C++ Standard, 1256but necessary for interoperability. 1257</para> 1258</listitem> 1259 1260<listitem><para>__gnu_</para> 1261<para>Indicating one of several GNU extensions. Choices 1262include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>, 1263and <code>__gnu_pbds</code>. 1264</para></listitem> 1265</itemizedlist> 1266 1267<para> The library uses a number of inline namespaces as implementation 1268details that are not intended for users to refer to directly, these include 1269<code>std::__detail</code>, <code>std::__cxx11</code> and <code>std::_V2</code>. 1270</para> 1271 1272<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>. 1273</para> 1274 1275 1276 </section> 1277 1278 <section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info> 1279 1280 1281 1282<para> 1283 One standard requirement is that the library components are defined 1284 in <code>namespace std::</code>. Thus, in order to use these types or 1285 functions, one must do one of two things: 1286</para> 1287 1288<itemizedlist> 1289 <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source 1290(either <code>using namespace std;</code> or i.e. <code>using 1291std::string;</code>) This approach works well for individual source files, but 1292should not be used in a global context, like header files. 1293 </para></listitem> <listitem><para>use a <emphasis>fully 1294qualified name</emphasis> for each library symbol 1295(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be 1296used, and usually enhanced, by strategic use of typedefs. (In the 1297cases where the qualified verbiage becomes unwieldy.) 1298 </para> 1299 </listitem> 1300</itemizedlist> 1301 1302 </section> 1303 1304 <section xml:id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"><info><title>Using Namespace Composition</title></info> 1305 1306 1307<para> 1308Best practice in programming suggests sequestering new data or 1309functionality in a sanely-named, unique namespace whenever 1310possible. This is considered an advantage over dumping everything in 1311the global namespace, as then name look-up can be explicitly enabled or 1312disabled as above, symbols are consistently mangled without repetitive 1313naming prefixes or macros, etc. 1314</para> 1315 1316<para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to 1317 adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called 1318 <emphasis>namespace composition</emphasis>. This is what happens if 1319 a <emphasis>using</emphasis>-declaration is put into a 1320 namespace-definition: the imported symbol(s) gets imported into the 1321 currently active namespace(s). For example: 1322</para> 1323<programlisting> 1324namespace gtk 1325{ 1326 using std::string; 1327 using std::tr1::array; 1328 1329 class Window { ... }; 1330} 1331</programlisting> 1332<para> 1333 In this example, <code>std::string</code> gets imported into 1334 <code>namespace gtk</code>. The result is that use of 1335 <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification. 1336 As an added bonus, 1337 <code>std::string</code> does not get imported into 1338 the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the 1339 <code>using</code>-declarations can wrapped in macros that 1340 are set based on autoconf-tests to either "" or i.e. <code>using 1341 std::string;</code> (depending on whether the system has 1342 libstdc++ in <code>std::</code> or not). (ideas from 1343 Llewelly and Karl Nelson) 1344</para> 1345 1346 1347 </section> 1348 </section> 1349 1350 <section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info> 1351 <?dbhtml filename="using_dynamic_or_shared.html"?> 1352 1353 1354 <section xml:id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"><info><title>Almost Nothing</title></info> 1355 1356 <para> 1357 Or as close as it gets: freestanding. This is a minimal 1358 configuration, with only partial support for the standard 1359 library. Assume only the following header files can be used: 1360 </para> 1361 1362 <itemizedlist> 1363 <listitem> 1364 <para> 1365 <filename class="headerfile">cstdarg</filename> 1366 </para> 1367 </listitem> 1368 1369 <listitem> 1370 <para> 1371 <filename class="headerfile">cstddef</filename> 1372 </para> 1373 </listitem> 1374 1375 <listitem> 1376 <para> 1377 <filename class="headerfile">cstdlib</filename> 1378 </para> 1379 </listitem> 1380 1381 <listitem> 1382 <para> 1383 <filename class="headerfile">exception</filename> 1384 </para> 1385 </listitem> 1386 1387 <listitem> 1388 <para> 1389 <filename class="headerfile">limits</filename> 1390 </para> 1391 </listitem> 1392 1393 <listitem> 1394 <para> 1395 <filename class="headerfile">new</filename> 1396 </para> 1397 </listitem> 1398 1399 <listitem> 1400 <para> 1401 <filename class="headerfile">exception</filename> 1402 </para> 1403 </listitem> 1404 1405 <listitem> 1406 <para> 1407 <filename class="headerfile">typeinfo</filename> 1408 </para> 1409 </listitem> 1410 </itemizedlist> 1411 1412 <para> 1413 In addition, throw in 1414 </para> 1415 1416 <itemizedlist> 1417 <listitem> 1418 <para> 1419 <filename class="headerfile">cxxabi.h</filename>. 1420 </para> 1421 </listitem> 1422 </itemizedlist> 1423 1424 <para> 1425 In the 1426 C++11 <link linkend="manual.intro.using.flags">dialect</link> add 1427 </para> 1428 1429 <itemizedlist> 1430 <listitem> 1431 <para> 1432 <filename class="headerfile">initializer_list</filename> 1433 </para> 1434 </listitem> 1435 <listitem> 1436 <para> 1437 <filename class="headerfile">type_traits</filename> 1438 </para> 1439 </listitem> 1440 </itemizedlist> 1441 1442 <para> There exists a library that offers runtime support for 1443 just these headers, and it is called 1444 <filename class="libraryfile">libsupc++.a</filename>. To use it, compile with <command>gcc</command> instead of <command>g++</command>, like so: 1445 </para> 1446 1447 <para> 1448 <command>gcc foo.cc -lsupc++</command> 1449 </para> 1450 1451 <para> 1452 No attempt is made to verify that only the minimal subset 1453 identified above is actually used at compile time. Violations 1454 are diagnosed as undefined symbols at link time. 1455 </para> 1456 </section> 1457 1458 <section xml:id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"><info><title>Finding Dynamic or Shared Libraries</title></info> 1459 1460 1461 <para> 1462 If the only library built is the static library 1463 (<filename class="libraryfile">libstdc++.a</filename>), or if 1464 specifying static linking, this section is can be skipped. But 1465 if building or using a shared library 1466 (<filename class="libraryfile">libstdc++.so</filename>), then 1467 additional location information will need to be provided. 1468 </para> 1469 <para> 1470 But how? 1471 </para> 1472 <para> 1473A quick read of the relevant part of the GCC 1474 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 1475 C++ Programs</link>, specifies linking against a C++ 1476 library. More details from the 1477 GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/faq.html#rpath">FAQ</link>, 1478 which states <emphasis>GCC does not, by default, specify a 1479 location so that the dynamic linker can find dynamic libraries at 1480 runtime.</emphasis> 1481 </para> 1482 <para> 1483 Users will have to provide this information. 1484 </para> 1485 <para> 1486 Methods vary for different platforms and different styles, and 1487 are printed to the screen during installation. To summarize: 1488 </para> 1489 <itemizedlist> 1490 <listitem> 1491 <para> 1492 At runtime set <literal>LD_LIBRARY_PATH</literal> in your 1493 environment correctly, so that the shared library for 1494 libstdc++ can be found and loaded. Be certain that you 1495 understand all of the other implications and behavior 1496 of <literal>LD_LIBRARY_PATH</literal> first. 1497 </para> 1498 1499 </listitem> 1500 <listitem> 1501 <para> 1502 Compile the path to find the library at runtime into the 1503 program. This can be done by passing certain options to 1504 <command>g++</command>, which will in turn pass them on to 1505 the linker. The exact format of the options is dependent on 1506 which linker you use: 1507 </para> 1508 <itemizedlist> 1509 <listitem> 1510 <para> 1511 GNU ld (default on GNU/Linux): 1512 <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename> 1513 </para> 1514 </listitem> 1515 <listitem> 1516 <para> 1517 Solaris ld: 1518 <literal>-Wl,-R</literal><filename class="directory">destdir/lib</filename> 1519 </para> 1520 </listitem> 1521 </itemizedlist> 1522 </listitem> 1523 <listitem> 1524 <para> 1525 Some linkers allow you to specify the path to the library by 1526 setting <literal>LD_RUN_PATH</literal> in your environment 1527 when linking. 1528 </para> 1529 </listitem> 1530 <listitem> 1531 <para> 1532 On some platforms the system administrator can configure the 1533 dynamic linker to always look for libraries in 1534 <filename class="directory">destdir/lib</filename>, for example 1535 by using the <command>ldconfig</command> utility on GNU/Linux 1536 or the <command>crle</command> utility on Solaris. This is a 1537 system-wide change which can make the system unusable so if you 1538 are unsure then use one of the other methods described above. 1539 </para> 1540 </listitem> 1541 </itemizedlist> 1542 <para> 1543 Use the <command>ldd</command> utility on the linked executable 1544 to show 1545 which <filename class="libraryfile">libstdc++.so</filename> 1546 library the system will get at runtime. 1547 </para> 1548 <para> 1549 A <filename class="libraryfile">libstdc++.la</filename> file is 1550 also installed, for use with Libtool. If you use Libtool to 1551 create your executables, these details are taken care of for 1552 you. 1553 </para> 1554 </section> 1555 1556 <section xml:id="manual.intro.using.linkage.experimental" xreflabel="Library Extensions"><info><title>Experimental Library Extensions</title></info> 1557 1558 <para> 1559 GCC 5.3 includes an implementation of the Filesystem library defined 1560 by the technical specification ISO/IEC TS 18822:2015. Because this is 1561 an experimental library extension, not part of the C++ standard, it 1562 is implemented in a separate library, 1563 <filename class="libraryfile">libstdc++fs.a</filename>, and there is 1564 no shared library for it. To use the library you should include 1565 <filename class="headerfile"><experimental/filesystem></filename> 1566 and link with <option>-lstdc++fs</option>. The library implementation 1567 is incomplete on non-POSIX platforms, specifically Windows support is 1568 rudimentary. 1569 </para> 1570 1571 <para> 1572 Due to the experimental nature of the Filesystem library the usual 1573 guarantees about ABI stability and backwards compatibility do not apply 1574 to it. There is no guarantee that the components in any 1575 <filename class="headerfile"><experimental/xxx></filename> 1576 header will remain compatible between different GCC releases. 1577 </para> 1578 </section> 1579 </section> 1580 1581 <section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info> 1582 <?dbhtml filename="using_concurrency.html"?> 1583 1584 1585 <para>This section discusses issues surrounding the proper compilation 1586 of multithreaded applications which use the Standard C++ 1587 library. This information is GCC-specific since the C++ 1588 standard does not address matters of multithreaded applications. 1589 </para> 1590 1591 <section xml:id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"><info><title>Prerequisites</title></info> 1592 1593 1594 <para>All normal disclaimers aside, multithreaded C++ application are 1595 only supported when libstdc++ and all user code was built with 1596 compilers which report (via <code> gcc/g++ -v </code>) the same thread 1597 model and that model is not <emphasis>single</emphasis>. As long as your 1598 final application is actually single-threaded, then it should be 1599 safe to mix user code built with a thread model of 1600 <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built 1601 with another thread model useful on the platform. Other mixes 1602 may or may not work but are not considered supported. (Thus, if 1603 you distribute a shared C++ library in binary form only, it may 1604 be best to compile it with a GCC configured with 1605 --enable-threads for maximal interchangeability and usefulness 1606 with a user population that may have built GCC with either 1607 --enable-threads or --disable-threads.) 1608 </para> 1609 <para>When you link a multithreaded application, you will probably 1610 need to add a library or flag to g++. This is a very 1611 non-standardized area of GCC across ports. Some ports support a 1612 special flag (the spelling isn't even standardized yet) to add 1613 all required macros to a compilation (if any such flags are 1614 required then you must provide the flag for all compilations not 1615 just linking) and link-library additions and/or replacements at 1616 link time. The documentation is weak. On several targets (including 1617 GNU/Linux, Solaris and various BSDs) -pthread is honored. 1618 Some other ports use other switches. 1619 This is not well documented anywhere other than 1620 in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries). 1621 </para> 1622 1623 <para> 1624 Some uses of <classname>std::atomic</classname> also require linking 1625 to <filename class="libraryfile">libatomic</filename>. 1626 </para> 1627 1628 </section> 1629 1630 <section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info> 1631 1632 1633<para> 1634In the terms of the 2011 C++ standard a thread-safe program is one which 1635does not perform any conflicting non-atomic operations on memory locations 1636and so does not contain any data races. 1637The standard places requirements on the library to ensure that no data 1638races are caused by the library itself or by programs which use the 1639library correctly (as described below). 1640The C++11 memory model and library requirements are a more formal version 1641of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</link> definition of thread safety, which the library used 1642prior to the 2011 standard. 1643</para> 1644 1645 1646 <para>The library strives to be thread-safe when all of the following 1647 conditions are met: 1648 </para> 1649 <itemizedlist> 1650 <listitem> 1651 <para>The system's libc is itself thread-safe, 1652 </para> 1653 </listitem> 1654 <listitem> 1655 <para> 1656 The compiler in use reports a thread model other than 1657 'single'. This can be tested via output from <code>gcc 1658 -v</code>. Multi-thread capable versions of gcc output 1659 something like this: 1660 </para> 1661<programlisting> 1662%gcc -v 1663Using built-in specs. 1664... 1665Thread model: posix 1666gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) 1667</programlisting> 1668 1669<para>Look for "Thread model" lines that aren't equal to "single."</para> 1670 </listitem> 1671 <listitem> 1672 <para> 1673 Requisite command-line flags are used for atomic operations 1674 and threading. Examples of this include <code>-pthread</code> 1675 and <code>-march=native</code>, although specifics vary 1676 depending on the host environment. See 1677 <link linkend="manual.intro.using.flags">Command Options</link> and 1678 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine 1679 Dependent Options</link>. 1680 </para> 1681 </listitem> 1682 <listitem> 1683 <para> 1684 An implementation of the 1685 <filename class="headerfile">atomicity.h</filename> functions 1686 exists for the architecture in question. See the 1687 <link linkend="internals.thread_safety">internals 1688 documentation</link> for more details. 1689 </para> 1690 </listitem> 1691 1692 </itemizedlist> 1693 1694 <para>The user code must guard against concurrent function calls which 1695 access any particular library object's state when one or more of 1696 those accesses modifies the state. An object will be modified by 1697 invoking a non-const member function on it or passing it as a 1698 non-const argument to a library function. An object will not be 1699 modified by invoking a const member function on it or passing it to 1700 a function as a pointer- or reference-to-const. 1701 Typically, the application 1702 programmer may infer what object locks must be held based on the 1703 objects referenced in a function call and whether the objects are 1704 accessed as const or non-const. Without getting 1705 into great detail, here is an example which requires user-level 1706 locks: 1707 </para> 1708 <programlisting> 1709 library_class_a shared_object_a; 1710 1711 void thread_main () { 1712 library_class_b *object_b = new library_class_b; 1713 shared_object_a.add_b (object_b); // must hold lock for shared_object_a 1714 shared_object_a.mutate (); // must hold lock for shared_object_a 1715 } 1716 1717 // Multiple copies of thread_main() are started in independent threads.</programlisting> 1718 <para>Under the assumption that object_a and object_b are never exposed to 1719 another thread, here is an example that does not require any 1720 user-level locks: 1721 </para> 1722 <programlisting> 1723 void thread_main () { 1724 library_class_a object_a; 1725 library_class_b *object_b = new library_class_b; 1726 object_a.add_b (object_b); 1727 object_a.mutate (); 1728 } </programlisting> 1729 1730 <para>All library types are safe to use in a multithreaded program 1731 if objects are not shared between threads or as 1732 long each thread carefully locks out access by any other 1733 thread while it modifies any object visible to another thread. 1734 Unless otherwise documented, the only exceptions to these rules 1735 are atomic operations on the types in 1736 <filename class="headerfile"><atomic></filename> 1737 and lock/unlock operations on the standard mutex types in 1738 <filename class="headerfile"><mutex></filename>. These 1739 atomic operations allow concurrent accesses to the same object 1740 without introducing data races. 1741 </para> 1742 1743 <para>The following member functions of standard containers can be 1744 considered to be const for the purposes of avoiding data races: 1745 <code>begin</code>, <code>end</code>, <code>rbegin</code>, <code>rend</code>, 1746 <code>front</code>, <code>back</code>, <code>data</code>, 1747 <code>find</code>, <code>lower_bound</code>, <code>upper_bound</code>, 1748 <code>equal_range</code>, <code>at</code> 1749 and, except in associative or unordered associative containers, 1750 <code>operator[]</code>. In other words, although they are non-const 1751 so that they can return mutable iterators, those member functions 1752 will not modify the container. 1753 Accessing an iterator might cause a non-modifying access to 1754 the container the iterator refers to (for example incrementing a 1755 list iterator must access the pointers between nodes, which are part 1756 of the container and so conflict with other accesses to the container). 1757 </para> 1758 1759 <para>Programs which follow the rules above will not encounter data 1760 races in library code, even when using library types which share 1761 state between distinct objects. In the example below the 1762 <code>shared_ptr</code> objects share a reference count, but 1763 because the code does not perform any non-const operations on the 1764 globally-visible object, the library ensures that the reference 1765 count updates are atomic and do not introduce data races: 1766 </para> 1767 <programlisting> 1768 std::shared_ptr<int> global_sp; 1769 1770 void thread_main() { 1771 auto local_sp = global_sp; // OK, copy constructor's parameter is reference-to-const 1772 1773 int i = *global_sp; // OK, operator* is const 1774 int j = *local_sp; // OK, does not operate on global_sp 1775 1776 // *global_sp = 2; // NOT OK, modifies int visible to other threads 1777 // *local_sp = 2; // NOT OK, modifies int visible to other threads 1778 1779 // global_sp.reset(); // NOT OK, reset is non-const 1780 local_sp.reset(); // OK, does not operate on global_sp 1781 } 1782 1783 int main() { 1784 global_sp.reset(new int(1)); 1785 std::thread t1(thread_main); 1786 std::thread t2(thread_main); 1787 t1.join(); 1788 t2.join(); 1789 } 1790 </programlisting> 1791 1792 <para>For further details of the C++11 memory model see Hans-J. Boehm's 1793 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/">Threads 1794 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> 1795 and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.hboehm.info/c++mm/user-faq.html">FAQ</link>. 1796 </para> 1797 1798 </section> 1799 <section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info> 1800 1801 <para> 1802 </para> 1803 </section> 1804 1805 <section xml:id="manual.intro.using.concurrency.io" xreflabel="IO"><info><title>IO</title></info> 1806 1807 <para>This gets a bit tricky. Please read carefully, and bear with me. 1808 </para> 1809 1810 <section xml:id="concurrency.io.structure" xreflabel="Structure"><info><title>Structure</title></info> 1811 1812 <para>A wrapper 1813 type called <code>__basic_file</code> provides our abstraction layer 1814 for the <code>std::filebuf</code> classes. Nearly all decisions dealing 1815 with actual input and output must be made in <code>__basic_file</code>. 1816 </para> 1817 <para>A generic locking mechanism is somewhat in place at the filebuf layer, 1818 but is not used in the current code. Providing locking at any higher 1819 level is akin to providing locking within containers, and is not done 1820 for the same reasons (see the links above). 1821 </para> 1822 </section> 1823 1824 <section xml:id="concurrency.io.defaults" xreflabel="Defaults"><info><title>Defaults</title></info> 1825 1826 <para>The __basic_file type is simply a collection of small wrappers around 1827 the C stdio layer (again, see the link under Structure). We do no 1828 locking ourselves, but simply pass through to calls to <code>fopen</code>, 1829 <code>fwrite</code>, and so forth. 1830 </para> 1831 <para>So, for 3.0, the question of "is multithreading safe for I/O" 1832 must be answered with, "is your platform's C library threadsafe 1833 for I/O?" Some are by default, some are not; many offer multiple 1834 implementations of the C library with varying tradeoffs of threadsafety 1835 and efficiency. You, the programmer, are always required to take care 1836 with multiple threads. 1837 </para> 1838 <para>(As an example, the POSIX standard requires that C stdio 1839 <code>FILE*</code> operations are atomic. POSIX-conforming C libraries 1840 (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize 1841 operations on <code>FILE*</code>s. 1842 However, you still need to not do stupid things like calling 1843 <code>fclose(fs)</code> in one thread followed by an access of 1844 <code>fs</code> in another.) 1845 </para> 1846 <para>So, if your platform's C library is threadsafe, then your 1847 <code>fstream</code> I/O operations will be threadsafe at the lowest 1848 level. For higher-level operations, such as manipulating the data 1849 contained in the stream formatting classes (e.g., setting up callbacks 1850 inside an <code>std::ofstream</code>), you need to guard such accesses 1851 like any other critical shared resource. 1852 </para> 1853 </section> 1854 1855 <section xml:id="concurrency.io.future" xreflabel="Future"><info><title>Future</title></info> 1856 1857 <para> A 1858 second choice may be available for I/O implementations: libio. This is 1859 disabled by default, and in fact will not currently work due to other 1860 issues. It will be revisited, however. 1861 </para> 1862 <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O 1863 implementation. When libio is in use, the <code>__basic_file</code> 1864 type is basically derived from FILE. (The real situation is more 1865 complex than that... it's derived from an internal type used to 1866 implement FILE. See libio/libioP.h to see scary things done with 1867 vtbls.) The result is that there is no "layer" of C stdio 1868 to go through; the filebuf makes calls directly into the same 1869 functions used to implement <code>fread</code>, <code>fwrite</code>, 1870 and so forth, using internal data structures. (And when I say 1871 "makes calls directly," I mean the function is literally 1872 replaced by a jump into an internal function. Fast but frightening. 1873 *grin*) 1874 </para> 1875 <para>Also, the libio internal locks are used. This requires pulling in 1876 large chunks of glibc, such as a pthreads implementation, and is one 1877 of the issues preventing widespread use of libio as the libstdc++ 1878 cstdio implementation. 1879 </para> 1880 <para>But we plan to make this work, at least as an option if not a future 1881 default. Platforms running a copy of glibc with a recent-enough 1882 version will see calls from libstdc++ directly into the glibc already 1883 installed. For other platforms, a copy of the libio subsection will 1884 be built and included in libstdc++. 1885 </para> 1886 </section> 1887 1888 <section xml:id="concurrency.io.alt" xreflabel="Alt"><info><title>Alternatives</title></info> 1889 1890 <para>Don't forget that other cstdio implementations are possible. You could 1891 easily write one to perform your own forms of locking, to solve your 1892 "interesting" problems. 1893 </para> 1894 </section> 1895 1896 </section> 1897 1898 <section xml:id="manual.intro.using.concurrency.containers" xreflabel="Containers"><info><title>Containers</title></info> 1899 1900 1901 <para>This section discusses issues surrounding the design of 1902 multithreaded applications which use Standard C++ containers. 1903 All information in this section is current as of the gcc 3.0 1904 release and all later point releases. Although earlier gcc 1905 releases had a different approach to threading configuration and 1906 proper compilation, the basic code design rules presented here 1907 were similar. For information on all other aspects of 1908 multithreading as it relates to libstdc++, including details on 1909 the proper compilation of threaded code (and compatibility between 1910 threaded and non-threaded code), see Chapter 17. 1911 </para> 1912 <para>Two excellent pages to read when working with the Standard C++ 1913 containers and threads are 1914 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's 1915 http://www.sgi.com/tech/stl/thread_safety.html</link> and 1916 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/Allocators.html">SGI's 1917 http://www.sgi.com/tech/stl/Allocators.html</link>. 1918 </para> 1919 <para><emphasis>However, please ignore all discussions about the user-level 1920 configuration of the lock implementation inside the STL 1921 container-memory allocator on those pages. For the sake of this 1922 discussion, libstdc++ configures the SGI STL implementation, 1923 not you. This is quite different from how gcc pre-3.0 worked. 1924 In particular, past advice was for people using g++ to 1925 explicitly define _PTHREADS or other macros or port-specific 1926 compilation options on the command line to get a thread-safe 1927 STL. This is no longer required for any port and should no 1928 longer be done unless you really know what you are doing and 1929 assume all responsibility.</emphasis> 1930 </para> 1931 <para>Since the container implementation of libstdc++ uses the SGI 1932 code, we use the same definition of thread safety as SGI when 1933 discussing design. A key point that beginners may miss is the 1934 fourth major paragraph of the first page mentioned above 1935 (<emphasis>For most clients...</emphasis>), which points out that 1936 locking must nearly always be done outside the container, by 1937 client code (that'd be you, not us). There is a notable 1938 exceptions to this rule. Allocators called while a container or 1939 element is constructed uses an internal lock obtained and 1940 released solely within libstdc++ code (in fact, this is the 1941 reason STL requires any knowledge of the thread configuration). 1942 </para> 1943 <para>For implementing a container which does its own locking, it is 1944 trivial to provide a wrapper class which obtains the lock (as 1945 SGI suggests), performs the container operation, and then 1946 releases the lock. This could be templatized <emphasis>to a certain 1947 extent</emphasis>, on the underlying container and/or a locking 1948 mechanism. Trying to provide a catch-all general template 1949 solution would probably be more trouble than it's worth. 1950 </para> 1951 <para>The library implementation may be configured to use the 1952 high-speed caching memory allocator, which complicates thread 1953 safety issues. For all details about how to globally override 1954 this at application run-time 1955 see <link linkend="manual.intro.using.macros">here</link>. Also 1956 useful are details 1957 on <link linkend="std.util.memory.allocator">allocator</link> 1958 options and capabilities. 1959 </para> 1960 1961 </section> 1962</section> 1963 1964<!-- Section 0x : Exception policies, expectations, topics --> 1965<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="using_exceptions.xml"> 1966</xi:include> 1967 1968<!-- Section 0x : Debug --> 1969<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="debug.xml"> 1970</xi:include> 1971 1972</chapter> 1973