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