| blob | 09f1a3c370ad85143a29e87c1d2ddc305ece0462 |
2 <!DOCTYPE html
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
7 <head>
21 </head>
22 <body>
27 in the following chapters of the Standard when describing the actual
30 </p>
33 <!-- ####################################################### -->
34 <hr />
36 <ul>
42 </ul>
44 <hr />
46 <!-- ####################################################### -->
49 <p>The C++ standard specifies the entire set of header files that must be
50 available to all hosted implementations. Actually, the word
52 don't necessarily have to be in any kind of external file. The
54 contents of that header become
55 available, no matter how.
56 </p>
60 <p> There are two main types of include files: header files related to
61 a specific version of the ISO C++ standard (called Standard Headers),
62 and all others (TR1, C++ ABI, and Extensions).</p>
64 <p>Two dialects of standard headers are supported, corresponding to
66 200x standard.
67 </p>
69 <p>C++98/03 include files. These are available in the default compilation mode, ie <code>-std=c++98</code> or <code>-std=gnu++98</code>.
70 </p>
73 <tr><td><algorithm></td><td><iomanip></td><td><list></td><td><ostream></td><td><streambuf></td></tr>
74 <tr><td><bitset></td><td><ios></td><td><locale></td><td><queue></td><td><string></td></tr>
75 <tr><td><complex></td><td><iosfwd></td><td><map></td><td><set></td><td><typeinfo></td></tr>
76 <tr><td><deque></td><td><iostream></td><td><memory></td><td><sstream></td><td><utility></td></tr>
77 <tr><td><exception></td><td><istream></td><td><new></td><td><stack></td><td><valarray></td></tr>
78 <tr><td><fstream></td><td><iterator></td><td><numeric></td><td><stdexcept></td><td><vector></td></tr>
80 </table></center>
82 <p></p>
85 <tr><td><cassert></td><td><ciso646></td><td><csetjmp></td><td><cstdio></td><td><ctime></td></tr>
86 <tr><td><cctype></td><td><climits></td><td><csignal></td><td><cstdlib></td><td><cwchar></td></tr>
87 <tr><td><cerrno></td><td><clocale></td><td><cstdarg></td><td><cstring></td><td><cwctype></td></tr>
89 </table></center>
91 <p>C++0x include files. These are only available in C++0x compilation mode, ie <code>-std=c++0x</code> or <code>-std=gnu++0x</code>.
92 </p>
95 <tr><td><algorithm></td><td><iomanip></td><td><locale></td><td><regex></td><td><tuple></td></tr>
96 <tr><td><array></td><td><ios></td><td><map></td><td><set></td><td><typeinfo></td></tr>
97 <tr><td><bitset></td><td><iosfwd></td><td><memory></td><td><sstream></td><td><type_traits></td></tr>
98 <tr><td><complex></td><td><iostream></td><td><new></td><td><stack></td><td><unordered_map></td></tr>
99 <tr><td><deque></td><td><istream></td><td><numeric></td><td><stdexcept></td><td><unordered_set></td></tr>
100 <tr><td><exception></td><td><iterator></td><td><ostream></td><td><streambuf></td><td><utility></td></tr>
101 <tr><td><fstream></td><td><limits></td><td><queue></td><td><string></td><td><valarray></td></tr>
102 <tr><td><functional></td><td><list></td><td><random></td><td><system_error></td><td><vector></td></tr>
103 </table></center>
105 <p></p>
108 <tr><td><cassert></td><td><cfloat></td><td><cmath></td><td><cstddef></td><td><ctgmath></td></tr>
109 <tr><td><ccomplex></td><td><cinttypes></td><td><csetjmp></td><td><cstdint></td><td><ctime></td></tr>
110 <tr><td><cctype></td><td><ciso646></td><td><csignal></td><td><cstdio></td><td><cuchar></td></tr>
111 <tr><td><cerrno></td><td><climits></td><td><cstdarg></td><td><cstdlib></td><td><cwchar></td></tr>
112 <tr><td><cfenv></td><td><clocale></td><td><cstdbool></td><td><cstring></td><td><cwctype></td></tr>
113 </table></center>
116 <p>In addition, TR1 includes as:
117 </p>
120 <tr><td><tr1/array></td><td><tr1/memory></td><td><tr1/regex></td><td><tr1/type_traits></td><td><tr1/unordered_set></td></tr>
121 <tr><td><tr1/complex></td><td><tr1/random></td><td><tr1/tuple></td><td><tr1/unordered_map></td><td><tr1/utility></td></tr>
123 </table></center>
125 <p></p>
128 <tr><td><tr1/cmath></td><td><tr1/cfloat></td><td><tr1/cstdarg></td><td><tr1/cstdio></td><td><tr1/ctime></td></tr>
129 <tr><td><tr1/ccomplex></td><td><tr1/cinttypes></td><td><tr1/cstdbool></td><td><tr1/cstdlib></td><td><tr1/cwchar></td></tr>
130 <tr><td><tr1/cfenv></td><td><tr1/climits></td><td><tr1/cstdint></td><td><tr1/ctgmath></td><td><tr1/cwctype></td></tr>
131 </table></center>
133 <p>Also included are files for the C++ ABI interface:
134 </p>
137 </table></center>
139 <p>And a large variety of extensions.
140 </p>
143 <tr><td><ext/algorithm></td><td><ext/debug_allocator.h></td><td><ext/mt_allocator.h></td><td><ext/pod_char_traits.h></td><td><ext/stdio_sync_filebuf.h></td></tr>
144 <tr><td><ext/array_allocator.h></td><td><ext/enc_filebuf.h></td><td><ext/new_allocator.h></td><td><ext/pool_allocator.h></td><td><ext/throw_allocator.h></td></tr>
145 <tr><td><ext/atomicity.h></td><td><ext/functional></td><td><ext/numeric></td><td><ext/rb_tree></td><td><ext/typelist.h></td></tr>
146 <tr><td><ext/bitmap_allocator.h></td><td><ext/iterator></td><td><ext/numeric_traits.h></td><td><ext/rope></td><td><ext/type_traits.h></td></tr>
147 <tr><td><ext/codecvt_specializations.h></td><td><ext/malloc_allocator.h></td><td><ext/pb_ds/assoc_container.h></td><td><ext/slist></td><td><ext/vstring.h></td></tr>
148 <tr><td><ext/concurrence.h></td><td><ext/memory></td><td><ext/pb_ds/priority_queue.h></td><td><ext/stdio_filebuf.h></td></tr>
149 </table></center>
151 <p></p>
154 <tr><td><debug/bitset></td><td><debug/list></td><td><debug/set></td><td><debug/unordered_map></td><td><debug/vector></td></tr>
155 <tr><td><debug/deque></td><td><debug/map></td><td><debug/string></td><td><debug/unordered_set></td></tr>
156 </table></center>
158 <p></p>
162 </table></center>
164 <hr />
167 <p> A few simple rules.
168 </p>
170 <p>First, mixing different dialects of the standard headers is not
171 possible. It's an all-or-nothing affair. Thus, code like
172 </p>
174 <pre>
177 </pre>
180 compilation mode must be used, which implies the C++0x functionality
182 </p>
184 <p>Second, the other headers can be included with either dialect of
185 the standard headers, although features and types specific to C++0x
186 are still only enabled when in C++0x compilation mode. So, to use
190 </p>
193 facilities. It is possible (although not especially prudent) to
194 include both the TR1 version and the C++0x version of header in the
195 same translation unit:
196 </p>
198 <pre>
201 </pre>
204 </p>
207 <hr />
209 <p>
210 The standard specifies that if one includes the C-style header
212 in the global namespace and perhaps in
214 requirement.) One the other hand, including the C++-style
216 found in namespace std and perhaps in the global namespace.
217 </p>
219 <p>
220 Usage of C++-style headers is recommended, as then
221 C-linkage names can be disambiguated by explicit qualification, such
223 use function overloading to provide a simpler interface to certain
227 used uniformly, instead of a combination
230 </p>
232 <hr />
235 <p>There are three base header files that are provided. They can be
236 used to precompile the standard headers and extensions into binary
237 files that may the be used to speed compiles that use these headers.
238 </p>
241 <ul>
242 <li>stdc++.h
243 <p>Includes all standard headers. Actual content varies depending on
244 language dialect.
245 </p>
246 </li>
248 <li>stdtr1c++.h
250 </p>
251 </li>
253 <li>extc++.h
255 </p></li>
256 </ul>
260 <p>First, find the include directory for the compiler. One way to do
261 this is:</p>
263 <pre>
264 g++ -v hello.cc
268 ...
269 End of search list.
270 </pre>
273 <p>Then, create a precompiled header file with the same flags that
274 will be used to compile other projects.</p>
276 <pre>
277 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
278 </pre>
280 <p>The resulting file will be quite large: the current size is around
281 thirty megabytes. </p>
285 <pre>
286 g++ -I. -include stdc++.h -H -g -O2 hello.cc
287 </pre>
291 <pre>
292 g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
293 ! ./stdc++.h.gch
296 </pre>
298 <p>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 </p>
299 <p></p>
301 <p> Detailed information about creating precompiled header files can be found in the GCC <a href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</a>.
302 </p>
305 <hr />
309 <p> There are three main namespaces.
310 </p>
312 <ul>
313 <li>std
315 within namespace std." This includes namepaces nested
317 std::tr1</code>.
318 </p>
319 </li>
320 <li>abi
321 <p>Specified by the C++ ABI. This ABI specifies a number of type and
322 function APIs supplemental to those required by the ISO C++ Standard,
323 but necessary for interoperability.
324 </p>
325 </li>
327 <li>__gnu_
328 <p>Indicating one of several GNU extensions. Choices
331 </p></li>
332 </ul>
334 <p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</a>.
335 </p>
338 <hr />
341 <p>
342 One standard requirement is that the library components are defined
344 functions, one must do one of two things:
345 </p>
350 std::string;</code>) This approach works well for individual source files, but
351 should not be used in a global context, like header files.
353 qualified name</i></span> for each library symbol
355 used, and usually enhanced, by strategic use of typedefs. (In the
356 cases where the qualified verbiage becomes unwieldy.)
357 </p></li>
358 </ul></div>
360 <hr />
363 <p>
364 Best practice in programming suggests sequestering new data or
365 functionality in a sanely-named, unique namespace whenever
366 possible. This is considered an advantage over dumping everything in
367 the global namespace, as then name look-up can be explicitly enabled or
368 disabled as above, symbols are consistently mangled without repetitive
369 naming prefixes or macros, etc.
370 </p>
372 <p>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
376 namespace-definition: the imported symbol(s) gets imported into the
377 currently active namespace(s). For example:
378 </p>
380 namespace gtk
381 {
382 using std::string;
383 using std::tr1::array;
385 class Window { ... };
386 }
387 </pre>
388 <p>
391 <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
392 As an added bonus,
394 the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
397 std::string;</code> (depending on whether the system has
399 <tt><<a href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>></tt>, Karl Nelson
401 </p>
403 <hr />
406 <p>All pre-processor switches and configurations are all gathered
408 the libstdc++ configuration and build process, and included by
409 files part of the public libstdc++ API. Most of these macros
410 should not be used by consumers of libstdc++, and are reserved
411 for internal implementation use. <strong>These macros cannot be
412 redefined</strong>. However, a select handful of these macro
413 control libstdc++ extensions and extra features, or provide
414 versioning information for the API, and are able to be used.
415 </p>
419 </p>
421 <p>Below is the macro which users may check for library version
422 information. </p>
424 <dl>
426 libstdc++ in compressed ISO date format, form of an unsigned
427 long. For details on the value of this particular macro for a
431 <p>Below are the macros which users may change with #define/#undef or
432 with -D/-U compiler flags. The default state of the symbol is
433 listed.</p>
436 that the symbol is initially chosen (or not) based on
437 --enable/--disable options at library build and configure time
439 various --enable/--disable choices being translated to
440 #define/#undef).
441 </p>
444 mean changing the ABI of compiled code. In other words, these
445 choices control code which has already been compiled (i.e., in a
446 binary such as libstdc++.a/.so). If you explicitly #define or
449 Experimenting with different values with the expectation of
450 consistent linkage requires changing the config headers before
451 building/installing the library.
452 </p>
454 <dl>
456 <dd>Defined by default. Not configurable. ABI-changing. Turning this off
457 removes older ARM-style iostreams code, and other anachronisms
458 from the API. This macro is dependent on the version of the
459 standard being tracked, and as a result may give different results for
461 be useful in updating old C++ code which no longer meet the
462 requirements of the language, or for checking current code
463 against new language standards. </dd>
466 default. When defined, memory allocation and allocators controlled
467 by libstdc++ call operator new/delete without caching and
468 pooling. Configurable via
470 </dd>
475 When defined, performs compile-time checking on certain template
476 instantiations to detect violations of the requirements of the
477 standard. This is described in more detail <a
481 <dd>Undefined by default. When defined, compiles
483 mode</a>.
484 </dd>
486 <dd>Undefined by default. When defined while
488 mode</a>, makes the debug mode extremely picky by making the use
489 of libstdc++ extensions and libstdc++-specific behavior into
490 errors.
491 </dd>
493 <dd>Undefined by default. When defined, compiles
495 mode</a>.
496 </dd>
497 </dl>
499 <hr />
501 <p>This section discusses issues surrounding the proper compilation
502 of multithreaded applications which use the Standard C++
503 library. This information is GCC-specific since the C++
504 standard does not address matters of multithreaded applications.
505 Unless explicitly prefaced, all information in this section is
506 relevant to the GCC 3.0 release and all later releases.
507 </p>
508 <p>Earlier GCC releases had a somewhat different approach to
509 threading configuration and proper compilation. Before GCC 3.0,
510 configuration of the threading model was dictated by compiler
511 command-line options and macros (both of which were somewhat
512 thread-implementation and port-specific). There were no
513 guarantees related to being able to link code compiled with one
514 set of options and macro setting with another set. For GCC 3.0,
515 configuration of the threading model used with libraries and
516 user-code is performed when GCC is configured and built using
517 the --enable-threads and --disable-threads options. The ABI is
518 stable for symbol name-mangling and limited functional
519 compatibility exists between code compiled under different
520 threading models.
521 </p>
522 <p>All normal disclaimers aside, multithreaded C++ application are
523 only supported when libstdc++ and all user code was built with
526 final application is actually single-threaded, then it should be
527 safe to mix user code built with a thread model of
529 with another thread model useful on the platform. Other mixes
530 may or may not work but are not considered supported. (Thus, if
531 you distribute a shared C++ library in binary form only, it may
532 be best to compile it with a GCC configured with
533 --enable-threads for maximal interchangeability and usefulness
534 with a user population that may have built GCC with either
535 --enable-threads or --disable-threads.)
536 </p>
537 <p>When you link a multithreaded application, you will probably
538 need to add a library or flag to g++. This is a very
539 non-standardized area of GCC across ports. Some ports support a
540 special flag (the spelling isn't even standardized yet) to add
541 all required macros to a compilation (if any such flags are
542 required then you must provide the flag for all compilations not
543 just linking) and link-library additions and/or replacements at
544 link time. The documentation is weak. Here is a quick summary
545 to display how ad hoc this is: On Solaris, both -pthreads and
546 -threads (with subtly different meanings) are honored. On OSF,
547 -pthread and -threads (with subtly different meanings) are
548 honored. On Linux/i386, -pthread is honored. On FreeBSD,
549 -pthread is honored. Some other ports use other switches.
550 AFAIK, none of this is properly documented anywhere other than
551 in ``gcc -dumpspecs'' (look at lib and cpp entries).
552 </p>
556 </p>
557 <p>The libstdc++ library has been designed so that it can be used in
558 multithreaded applications (with libstdc++-v2 this was
559 only true of the STL parts.) The first problem is
561 platforms. Due to historical reasons, some of the library is
562 written against per-CPU-architecture spinlocks and other parts
563 against the gthr.h abstraction layer which is provided by gcc.
564 A minor problem that pops up every so often is different
566 library (not a general program). We currently use the <a
568 definition that SGI</a> uses for their STL subset. However, the
569 exception for read-only containers only applies to the STL
570 components. This definition is widely-used and something similar
571 will be used in the next version of the C++ standard library.
572 </p>
573 <p>Here is a small link farm to threads (no pun) in the mail archives
574 that discuss the threading problem. Each link is to the first
575 relevant message in the thread; from there you can use
577 latest-to-oldest order.
578 </p>
579 <ul>
580 <li>Our threading expert Loren gives a breakdown of
584 This message</a> inspired a recent updating of issues with threading
585 and the SGI STL library. It also contains some example
586 POSIX-multithreaded STL code.</li>
587 </ul>
588 <p> (A large selection of links to older messages has been removed; many
589 of the messages from 1999 were lost in a disk crash, and the few
590 people with access to the backup tapes have been too swamped with work
591 to restore them. Many of the points have been superseded anyhow.)
592 </p>
593 <p>This section will be updated as new and interesting issues come
594 to light.
595 </p>
598 </p>
600 <hr />
602 <p>The ISO standard defines the following phrase:
603 </p>
604 <blockquote><dl>
606 <dd>behavior, for a well-formed program construct and correct data, that
607 depends on the implementation <strong>and that each implementation
608 shall document</strong>.
609 </dd>
610 </dl></blockquote>
611 <p>We do so here, for the C++ library only. Behavior of the compiler,
612 linker, runtime loader, and other elements of "the
613 implementation" are documented elsewhere. Everything listed in
614 Annex B, Implementation Qualities, are also part of the compiler, not
615 the library.
616 </p>
617 <p>For each entry, we give the section number of the standard, when
618 applicable. This list is probably incomplet and inkorrekt.
619 </p>
621 interactive stream support is implied.
622 </p>
624 discussed in the various sections on multithreading (see above).
625 </p>
626 <!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec
627 can throw whatever we want; see also its footnote. Let's list those
628 in the sections where the function itself occurs.
629 -->
632 </p>
634 sections, libstdc++ has zero control over what the cleanup code hands
635 back to the runtime loader. Talk to the compiler people. :-)
636 </p>
643 classes publicly derived from it, simply returns the name of the
646 demangle them, or call a
651 user-defined exceptions.)
652 </p>
655 previous entry for more).
656 </p>
658 supply libraries that can accept allocators that encapsulate more
659 general memory models and that support non-equal instances. In such
660 implementations, any requirements imposed on allocators by containers
661 beyond those requirements that appear in Table 32, and the semantics
662 of containers and algorithms when allocator instances compare
664 have any allocators which compare non-equal, so we can't describe how
665 they behave.
666 </p>
672 Nope, these types are called implementation-defined because you
673 shouldn't be taking advantage of their underlying types. Listing them
674 here would defeat the purpose. :-)
675 </p>
678 for what does exist.
679 </p>
681 implementation will be described
683 </p>
686 </p>
689 performed on the standard stream objects will
690 flush the buffers, and <!-- this line might go away -->
691 destroy and recreate the underlying buffer instances. Whether or not
692 the previously-written I/O is destroyed in this process depends mostly
693 on the --enable-libio choice: for stdio, if the written data is
694 already in the stdio buffer, the data may be completely safe!
695 </p>
698 additional work than the minimum required. We are not currently taking
699 advantage of this yet.
700 </p>
705 </p>
708 </p>
711 </p>
713 <!--
714 <dt><code></code></dt>
715 <dd>
716 </dd>
717 -->
720 </p>
724 <!-- ####################################################### -->
726 <hr />
729 Comments and suggestions are welcome, and may be sent to
731 </em></p>
734 </body>
735 </html>