l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.4/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
 706     </sect2>
 707   </sect1>
 708
 709   <sect1 id="manual.intro.using.namespaces" xreflabel="Namespaces">
 710     <?dbhtml filename="using_namespaces.html"?>
 711     <title>Namespaces</title>
 712
 713     <sect2 id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces">
 714       <title>Available Namespaces</title>
 715
 716
 717
 718 <para> There are three main namespaces.
 719 </para>
 720
 721 <itemizedlist>
 722   <listitem><para>std</para>
 723 <para>The ISO C++ standards specify that "all library entities are defined
 724 within namespace std." This includes namespaces nested
 725 within <code>namespace std</code>, such as <code>namespace
 726 std::tr1</code>.
 727 </para>
 728 </listitem>
 729 <listitem><para>abi</para>
 730 <para>Specified by the C++ ABI. This ABI specifies a number of type and
 731 function APIs supplemental to those required by the ISO C++ Standard,
 732 but necessary for interoperability.
 733 </para>
 734 </listitem>
 735
 736 <listitem><para>__gnu_</para>
 737 <para>Indicating one of several GNU extensions. Choices
 738 include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
 739 and <code>__gnu_pbds</code>.
 740 </para></listitem>
 741 </itemizedlist>
 742
 743 <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>.
 744 </para>
 745
 746
 747     </sect2>
 748
 749     <sect2 id="manual.intro.using.namespaces.std" xreflabel="namespace std">
 750       <title>namespace std</title>
 751
 752
 753 <para>
 754       One standard requirement is that the library components are defined
 755       in <code>namespace std::</code>. Thus, in order to use these types or
 756       functions, one must do one of two things:
 757 </para>
 758
 759 <itemizedlist>
 760   <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source
 761 (either <code>using namespace std;</code> or i.e. <code>using
 762 std::string;</code>) This approach works well for individual source files, but
 763 should not be used in a global context, like header files.
 764           </para></listitem> <listitem><para>use a <emphasis>fully
 765 qualified name</emphasis>for each library symbol
 766 (i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
 767 used, and usually enhanced, by strategic use of typedefs. (In the
 768 cases where the qualified verbiage becomes unwieldy.)
 769           </para>
 770         </listitem>
 771 </itemizedlist>
 772
 773     </sect2>
 774
 775     <sect2 id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition">
 776       <title>Using Namespace Composition</title>
 777
 778 <para>
 779 Best practice in programming suggests sequestering new data or
 780 functionality in a sanely-named, unique namespace whenever
 781 possible. This is considered an advantage over dumping everything in
 782 the global namespace, as then name look-up can be explicitly enabled or
 783 disabled as above, symbols are consistently mangled without repetitive
 784 naming prefixes or macros, etc.
 785 </para>
 786
 787 <para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
 788         adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
 789         <emphasis>namespace composition</emphasis>. This is what happens if
 790         a <emphasis>using</emphasis>-declaration is put into a
 791         namespace-definition: the imported symbol(s) gets imported into the
 792         currently active namespace(s). For example:
 793 </para>
 794 <programlisting>
 795 namespace gtk
 796 {
 797   using std::string;
 798   using std::tr1::array;
 799
 800   class Window { ... };
 801 }
 802 </programlisting>
 803 <para>
 804         In this example, <code>std::string</code> gets imported into
 805         <code>namespace gtk</code>.  The result is that use of
 806         <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
 807         As an added bonus,
 808         <code>std::string</code> does not get imported into
 809         the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
 810         <code>using</code>-declarations can wrapped in macros that
 811         are set based on autoconf-tests to either &quot;&quot; or i.e. <code>using
 812           std::string;</code> (depending on whether the system has
 813         libstdc++ in <code>std::</code> or not).  (ideas from
 814         <email>llewelly@dbritsch.dsl.xmission.com</email>, Karl Nelson <email>kenelson@ece.ucdavis.edu</email>)
 815 </para>
 816
 817
 818     </sect2>
 819   </sect1>
 820
 821   <sect1 id="manual.intro.using.macros" xreflabel="Macros">
 822     <?dbhtml filename="using_macros.html"?>
 823     <title>Macros</title>
 824
 825    <para>All pre-processor switches and configurations are all gathered
 826       in the file <code>c++config.h</code>, which is generated during
 827       the libstdc++ configuration and build process, and included by
 828       files part of the public libstdc++ API. Most of these macros
 829       should not be used by consumers of libstdc++, and are reserved
 830       for internal implementation use. <emphasis>These macros cannot be
 831       redefined</emphasis>. However, a select handful of these macro
 832       control libstdc++ extensions and extra features, or provide
 833       versioning information for the API, and are able to be used.
 834    </para>
 835
 836    <para>All library macros begin with <code>_GLIBCXX_</code> (except for
 837    versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>).
 838    </para>
 839
 840    <para>Below is the macro which users may check for library version
 841       information. </para>
 842
 843     <variablelist>
 844     <varlistentry>
 845       <term><code>__GLIBCXX__</code></term>
 846       <listitem>
 847         <para>The current version of
 848     libstdc++ in compressed ISO date format, form of an unsigned
 849     long. For details on the value of this particular macro for a
 850     particular release, please consult this <ulink url="abi.html">
 851     document</ulink>.
 852     </para>
 853     </listitem>
 854     </varlistentry>
 855     </variablelist>
 856
 857    <para>Below are the macros which users may change with #define/#undef or
 858       with -D/-U compiler flags.  The default state of the symbol is
 859       listed.</para>
 860
 861    <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
 862       that the symbol is initially chosen (or not) based on
 863       --enable/--disable options at library build and configure time
 864       (documented <link linkend="manual.intro.setup.configure">here</link>), with the
 865       various --enable/--disable choices being translated to
 866       #define/#undef).
 867    </para>
 868
 869    <para> <acronym>ABI</acronym> means that changing from the default value may
 870   mean changing the <acronym>ABI</acronym> of compiled code. In other words, these
 871   choices control code which has already been compiled (i.e., in a
 872   binary such as libstdc++.a/.so).  If you explicitly #define or
 873   #undef these macros, the <emphasis>headers</emphasis> may see different code
 874   paths, but the <emphasis>libraries</emphasis> which you link against will not.
 875   Experimenting with different values with the expectation of
 876   consistent linkage requires changing the config headers before
 877   building/installing the library.
 878    </para>
 879
 880     <variablelist>
 881     <varlistentry><term><code>_GLIBCXX_DEPRECATED</code></term>
 882     <listitem>
 883       <para>
 884         Defined by default. Not configurable. ABI-changing. Turning this off
 885         removes older ARM-style iostreams code, and other anachronisms
 886         from the API.  This macro is dependent on the version of the
 887         standard being tracked, and as a result may give different results for
 888         <code>-std=c++98</code> and <code>-std=c++0x</code>. This may
 889         be useful in updating old C++ code which no longer meet the
 890         requirements of the language, or for checking current code
 891         against new language standards.
 892     </para>
 893     </listitem></varlistentry>
 894
 895     <varlistentry><term><code>_GLIBCXX_FORCE_NEW</code></term>
 896     <listitem>
 897       <para>
 898         Undefined by default. When defined, memory allocation and
 899         allocators controlled by libstdc++ call operator new/delete
 900         without caching and pooling. Configurable via
 901         <code>--enable-libstdcxx-allocator</code>. ABI-changing.
 902       </para>
 903     </listitem></varlistentry>
 904
 905
 906     <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term>
 907     <listitem>
 908       <para>
 909         Undefined by default.  Configurable via
 910         <code>--enable-concept-checks</code>.  When defined, performs
 911         compile-time checking on certain template instantiations to
 912         detect violations of the requirements of the standard.  This
 913         is described in more detail <ulink
 914         url="../19_diagnostics/howto.html#3">here</ulink>.
 915       </para>
 916     </listitem></varlistentry>
 917
 918     <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
 919     <listitem>
 920       <para>
 921         Undefined by default. When defined, compiles
 922     user code using the <ulink url="../ext/debug.html#safe">libstdc++ debug
 923     mode</ulink>.
 924       </para>
 925     </listitem></varlistentry>
 926     <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
 927     <listitem>
 928       <para>
 929         Undefined by default. When defined while
 930     compiling with the <ulink url="../ext/debug.html#safe">libstdc++ debug
 931     mode</ulink>, makes the debug mode extremely picky by making the use
 932     of libstdc++ extensions and libstdc++-specific behavior into
 933     errors.
 934       </para>
 935     </listitem></varlistentry>
 936     <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
 937     <listitem>
 938       <para>Undefined by default. When defined, compiles
 939     user code using the <ulink url="../ext/parallel_mode.html">libstdc++ parallel
 940     mode</ulink>.
 941       </para>
 942     </listitem></varlistentry>
 943     </variablelist>
 944
 945
 946   </sect1>
 947
 948   <sect1 id="manual.intro.using.concurrency" xreflabel="Concurrency">
 949     <?dbhtml filename="using_concurrency.html"?>
 950     <title>Concurrency</title>
 951
 952    <para>This section discusses issues surrounding the proper compilation
 953       of multithreaded applications which use the Standard C++
 954       library.  This information is GCC-specific since the C++
 955       standard does not address matters of multithreaded applications.
 956    </para>
 957
 958     <sect2 id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq">
 959       <title>Prerequisites</title>
 960
 961    <para>All normal disclaimers aside, multithreaded C++ application are
 962       only supported when libstdc++ and all user code was built with
 963       compilers which report (via <code> gcc/g++ -v </code>) the same thread
 964       model and that model is not <emphasis>single</emphasis>.  As long as your
 965       final application is actually single-threaded, then it should be
 966       safe to mix user code built with a thread model of
 967       <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built
 968       with another thread model useful on the platform.  Other mixes
 969       may or may not work but are not considered supported.  (Thus, if
 970       you distribute a shared C++ library in binary form only, it may
 971       be best to compile it with a GCC configured with
 972       --enable-threads for maximal interchangeability and usefulness
 973       with a user population that may have built GCC with either
 974       --enable-threads or --disable-threads.)
 975    </para>
 976    <para>When you link a multithreaded application, you will probably
 977       need to add a library or flag to g++.  This is a very
 978       non-standardized area of GCC across ports.  Some ports support a
 979       special flag (the spelling isn't even standardized yet) to add
 980       all required macros to a compilation (if any such flags are
 981       required then you must provide the flag for all compilations not
 982       just linking) and link-library additions and/or replacements at
 983       link time.  The documentation is weak.  Here is a quick summary
 984       to display how ad hoc this is: On Solaris, both -pthreads and
 985       -threads (with subtly different meanings) are honored.  On OSF,
 986       -pthread and -threads (with subtly different meanings) are
 987       honored.  On Linux/i386, -pthread is honored.  On FreeBSD,
 988       -pthread is honored.  Some other ports use other switches.
 989       AFAIK, none of this is properly documented anywhere other than
 990       in ``gcc -dumpspecs'' (look at lib and cpp entries).
 991    </para>
 992
 993     </sect2>
 994
 995     <sect2 id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety">
 996       <title>Thread Safety</title>
 997
 998
 999 <para>
1000 We currently use the <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</ulink> definition of thread safety.
1001 </para>
1002
1003
1004       <para>The library strives to be thread-safe when all of the following
1005          conditions are met:
1006       </para>
1007       <itemizedlist>
1008        <listitem>
1009        <para>The system's libc is itself thread-safe,
1010        </para>
1011        </listitem>
1012        <listitem>
1013          <para>
1014            The compiler in use reports a thread model other than
1015            'single'. This can be tested via output from <code>gcc
1016            -v</code>. Multi-thread capable versions of gcc output
1017            something like this:
1018          </para>
1019 <programlisting>
1020 %gcc -v
1021 Using built-in specs.
1022 ...
1023 Thread model: posix
1024 gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
1025 </programlisting>
1026
1027 <para>Look for "Thread model" lines that aren't equal to "single."</para>
1028        </listitem>
1029        <listitem>
1030        <para>
1031          Requisite command-line flags are used for atomic operations
1032          and threading. Examples of this include <code>-pthread</code>
1033          and <code>-march=native</code>, although specifics vary
1034          depending on the host environment. See <ulink
1035          url="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
1036          Dependent Options</ulink>.
1037        </para>
1038        </listitem>
1039        <listitem>
1040          <para>
1041            An implementation of atomicity.h functions
1042            exists for the architecture in question. See the internals documentation for more <ulink url="../ext/concurrence.html">details</ulink>.
1043        </para>
1044        </listitem>
1045
1046       </itemizedlist>
1047       <para>The user-code must guard against concurrent method calls which may
1048          access any particular library object's state.  Typically, the
1049          application programmer may infer what object locks must be held
1050          based on the objects referenced in a method call.  Without getting
1051          into great detail, here is an example which requires user-level
1052          locks:
1053       </para>
1054       <programlisting>
1055      library_class_a shared_object_a;
1056
1057      thread_main () {
1058        library_class_b *object_b = new library_class_b;
1059        shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
1060        shared_object_a.mutate ();          // must hold lock for shared_object_a
1061      }
1062
1063      // Multiple copies of thread_main() are started in independent threads.</programlisting>
1064       <para>Under the assumption that object_a and object_b are never exposed to
1065          another thread, here is an example that should not require any
1066          user-level locks:
1067       </para>
1068       <programlisting>
1069      thread_main () {
1070        library_class_a object_a;
1071        library_class_b *object_b = new library_class_b;
1072        object_a.add_b (object_b);
1073        object_a.mutate ();
1074      } </programlisting>
1075       <para>All library objects are safe to use in a multithreaded program as
1076          long as each thread carefully locks out access by any other
1077          thread while it uses any object visible to another thread, i.e.,
1078          treat library objects like any other shared resource.  In general,
1079          this requirement includes both read and write access to objects;
1080          unless otherwise documented as safe, do not assume that two threads
1081          may access a shared standard library object at the same time.
1082       </para>
1083       <para>See chapters <ulink url="../17_intro/howto.html#3">17</ulink> (library
1084          introduction), <ulink url="../23_containers/howto.html#3">23</ulink>
1085          (containers), and <ulink url="../27_io/howto.html#9">27</ulink> (I/O) for
1086          more information.
1087       </para>
1088
1089
1090   </sect2>
1091   <sect2 id="manual.intro.using.concurrency.atomics" xreflabel="Atomics">
1092     <title>Atomics</title>
1093     <para>
1094     </para>
1095   </sect2>
1096
1097     <sect2 id="manual.intro.using.concurrency.io" xreflabel="IO">
1098       <title>IO</title>
1099    <para>I'll assume that you have already read the
1100       <ulink url="../17_intro/howto.html#3">general notes on library threads</ulink>,
1101       and the
1102       <ulink url="../23_containers/howto.html#3">notes on threaded container
1103       access</ulink> (you might not think of an I/O stream as a container, but
1104       the points made there also hold here).  If you have not read them,
1105       please do so first.
1106    </para>
1107    <para>This gets a bit tricky.  Please read carefully, and bear with me.
1108    </para>
1109
1110     <sect3 id="concurrency.io.structure" xreflabel="Structure">
1111       <title>Structure</title>
1112    <para>A wrapper
1113       type called <code>__basic_file</code> provides our abstraction layer
1114       for the <code>std::filebuf</code> classes.  Nearly all decisions dealing
1115       with actual input and output must be made in <code>__basic_file</code>.
1116    </para>
1117    <para>A generic locking mechanism is somewhat in place at the filebuf layer,
1118       but is not used in the current code.  Providing locking at any higher
1119       level is akin to providing locking within containers, and is not done
1120       for the same reasons (see the links above).
1121    </para>
1122     </sect3>
1123
1124     <sect3 id="concurrency.io.defaults" xreflabel="Defaults">
1125       <title>Defaults</title>
1126    <para>The __basic_file type is simply a collection of small wrappers around
1127       the C stdio layer (again, see the link under Structure).  We do no
1128       locking ourselves, but simply pass through to calls to <code>fopen</code>,
1129       <code>fwrite</code>, and so forth.
1130    </para>
1131    <para>So, for 3.0, the question of &quot;is multithreading safe for I/O&quot;
1132       must be answered with, &quot;is your platform's C library threadsafe
1133       for I/O?&quot;  Some are by default, some are not; many offer multiple
1134       implementations of the C library with varying tradeoffs of threadsafety
1135       and efficiency.  You, the programmer, are always required to take care
1136       with multiple threads.
1137    </para>
1138    <para>(As an example, the POSIX standard requires that C stdio FILE*
1139        operations are atomic.  POSIX-conforming C libraries (e.g, on Solaris
1140        and GNU/Linux) have an internal mutex to serialize operations on
1141        FILE*s.  However, you still need to not do stupid things like calling
1142        <code>fclose(fs)</code> in one thread followed by an access of
1143        <code>fs</code> in another.)
1144    </para>
1145    <para>So, if your platform's C library is threadsafe, then your
1146       <code>fstream</code> I/O operations will be threadsafe at the lowest
1147       level.  For higher-level operations, such as manipulating the data
1148       contained in the stream formatting classes (e.g., setting up callbacks
1149       inside an <code>std::ofstream</code>), you need to guard such accesses
1150       like any other critical shared resource.
1151    </para>
1152     </sect3>
1153
1154     <sect3 id="concurrency.io.future" xreflabel="Future">
1155       <title>Future</title>
1156    <para> A
1157       second choice may be available for I/O implementations:  libio.  This is
1158       disabled by default, and in fact will not currently work due to other
1159       issues.  It will be revisited, however.
1160    </para>
1161    <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O
1162       implementation.  When libio is in use, the <code>__basic_file</code>
1163       type is basically derived from FILE.  (The real situation is more
1164       complex than that... it's derived from an internal type used to
1165       implement FILE.  See libio/libioP.h to see scary things done with
1166       vtbls.)  The result is that there is no &quot;layer&quot; of C stdio
1167       to go through; the filebuf makes calls directly into the same
1168       functions used to implement <code>fread</code>, <code>fwrite</code>,
1169       and so forth, using internal data structures.  (And when I say
1170       &quot;makes calls directly,&quot; I mean the function is literally
1171       replaced by a jump into an internal function.  Fast but frightening.
1172       *grin*)
1173    </para>
1174    <para>Also, the libio internal locks are used.  This requires pulling in
1175       large chunks of glibc, such as a pthreads implementation, and is one
1176       of the issues preventing widespread use of libio as the libstdc++
1177       cstdio implementation.
1178    </para>
1179    <para>But we plan to make this work, at least as an option if not a future
1180       default.  Platforms running a copy of glibc with a recent-enough
1181       version will see calls from libstdc++ directly into the glibc already
1182       installed.  For other platforms, a copy of the libio subsection will
1183       be built and included in libstdc++.
1184    </para>
1185     </sect3>
1186
1187     <sect3 id="concurrency.io.alt" xreflabel="Alt">
1188       <title>Alternatives</title>
1189    <para>Don't forget that other cstdio implementations are possible.  You could
1190       easily write one to perform your own forms of locking, to solve your
1191       &quot;interesting&quot; problems.
1192    </para>
1193     </sect3>
1194
1195     </sect2>
1196
1197     <sect2 id="manual.intro.using.concurrency.containers" xreflabel="Containers">
1198       <title>Containers</title>
1199
1200    <para>This section discusses issues surrounding the design of
1201       multithreaded applications which use Standard C++ containers.
1202       All information in this section is current as of the gcc 3.0
1203       release and all later point releases.  Although earlier gcc
1204       releases had a different approach to threading configuration and
1205       proper compilation, the basic code design rules presented here
1206       were similar.  For information on all other aspects of
1207       multithreading as it relates to libstdc++, including details on
1208       the proper compilation of threaded code (and compatibility between
1209       threaded and non-threaded code), see Chapter 17.
1210    </para>
1211    <para>Two excellent pages to read when working with the Standard C++
1212       containers and threads are
1213       <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
1214       http://www.sgi.com/tech/stl/thread_safety.html</ulink> and
1215       <ulink url="http://www.sgi.com/tech/stl/Allocators.html">SGI's
1216       http://www.sgi.com/tech/stl/Allocators.html</ulink>.
1217    </para>
1218    <para><emphasis>However, please ignore all discussions about the user-level
1219       configuration of the lock implementation inside the STL
1220       container-memory allocator on those pages.  For the sake of this
1221       discussion, libstdc++ configures the SGI STL implementation,
1222       not you.  This is quite different from how gcc pre-3.0 worked.
1223       In particular, past advice was for people using g++ to
1224       explicitly define _PTHREADS or other macros or port-specific
1225       compilation options on the command line to get a thread-safe
1226       STL.  This is no longer required for any port and should no
1227       longer be done unless you really know what you are doing and
1228       assume all responsibility.</emphasis>
1229    </para>
1230    <para>Since the container implementation of libstdc++ uses the SGI
1231       code, we use the same definition of thread safety as SGI when
1232       discussing design.  A key point that beginners may miss is the
1233       fourth major paragraph of the first page mentioned above
1234       (&quot;For most clients,&quot;...), which points out that
1235       locking must nearly always be done outside the container, by
1236       client code (that'd be you, not us).  There is a notable
1237       exceptions to this rule.  Allocators called while a container or
1238       element is constructed uses an internal lock obtained and
1239       released solely within libstdc++ code (in fact, this is the
1240       reason STL requires any knowledge of the thread configuration).
1241    </para>
1242    <para>For implementing a container which does its own locking, it is
1243       trivial to provide a wrapper class which obtains the lock (as
1244       SGI suggests), performs the container operation, and then
1245       releases the lock.  This could be templatized <emphasis>to a certain
1246       extent</emphasis>, on the underlying container and/or a locking
1247       mechanism.  Trying to provide a catch-all general template
1248       solution would probably be more trouble than it's worth.
1249    </para>
1250    <para>The STL implementation is currently configured to use the
1251       high-speed caching memory allocator.  Some people like to
1252       test and/or normally run threaded programs with a different
1253       default.  For all details about how to globally override this
1254       at application run-time see <ulink url="../ext/howto.html#3">here</ulink>.
1255    </para>
1256    <para>There is a better way (not standardized yet):  It is possible to
1257       force the malloc-based allocator on a per-case-basis for some
1258       application code.  The library team generally believes that this
1259       is a better way to tune an application for high-speed using this
1260       implementation of the STL.  There is
1261       <ulink url="../ext/howto.html#3">more information on allocators here</ulink>.
1262    </para>
1263
1264     </sect2>
1265   </sect1>
1266
1267   <sect1 id="manual.intro.using.exception" xreflabel="Exceptions">
1268     <?dbhtml filename="using_exceptions.html"?>
1269     <title>Exceptions</title>
1270
1271   <sect2 id="intro.using.exception.propagating" xreflabel="Propagating Exceptions">
1272
1273     <title>Propagating Exceptions aka Exception Neutrality</title>
1274   <para>
1275   </para>
1276   </sect2>
1277
1278   <sect2 id="intro.using.exception.safety" xreflabel="Exception Safety">
1279     <title>Exception Safety</title>
1280   <para>
1281   </para>
1282   </sect2>
1283
1284   <sect2 id="intro.using.exception.no" xreflabel="-fno-exceptions">
1285     <title>Support for <literal>-fno-exceptions</literal></title>
1286   <para>
1287   </para>
1288   </sect2>
1289
1290   </sect1>
1291
1292 <!-- Section 0x : Debug -->
1293 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
1294             parse="xml" href="debug.xml">
1295 </xi:include>
1296
1297 </chapter>