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

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