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