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