libstdc++-v3/doc/xml/manual/using.xml

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