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