OSDN Git Service

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