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