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