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