OSDN Git Service

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