l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.7/doc/xml/manual/using.xml

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