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