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