1 <?xml version="1.0" encoding="ISO-8859-1"?>
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
8 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
9 <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards), Benjamin Kosnik, Felix Natter" />
10 <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL" />
11 <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17." />
12 <meta name="GENERATOR" content="vi and eight fingers" />
13 <title>libstdc++ HOWTO: Chapter 17: Library Introduction</title>
14 <link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
15 <link rel="Start" href="../documentation.html" type="text/html"
16 title="GNU C++ Standard Library" />
17 <link rel="Next" href="../18_support/howto.html" type="text/html"
18 title="Library Support" />
19 <link rel="Copyright" href="license.html" type="text/html" />
20 <link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
24 <h1 class="centered"><a name="top">Chapter 17: Library Introduction</a></h1>
26 <p>Chapter 17 is actually a list of definitions and descriptions used
27 in the following chapters of the Standard when describing the actual
28 library. Here, we use "Introduction" as an introduction
29 to the <em>GNU implementation of</em> the ISO Standard C++ Library.
33 <!-- ####################################################### -->
37 <li><a href="#2.0">Header Files</a></li>
38 <li><a href="#3.0">Namespaces</a></li>
39 <li><a href="#6">Macros</a></li>
40 <li><a href="#5">Implementation specific behavior</a></li>
41 <li><a href="#7">Multithreading</a></li>
46 <!-- ####################################################### -->
48 <h2><a name="2.0">Header Files</a></h2>
49 <p>The C++ standard specifies the entire set of header files that must be
50 available to all hosted implementations. Actually, the word
51 "files" is a misnomer, since the contents of the headers
52 don't necessarily have to be in any kind of external file. The
53 only rule is that when one <code>#include</code>'s a header, the
54 contents of that header become
55 available, no matter how.
58 <p>That said, in practice files are used.</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
65 the 1998 standard as updated for 2003, and the draft of the upcoming
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>.
72 <center><table border="1"><caption>C++98 Library Headers</caption>
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>
79 <tr><td><functional></td><td><limits></td></tr>
84 <center><table border="1"><caption>C++98 Headers for C Library Facilities</caption>
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>
88 <tr><td><cfloat></td><td><cmath></td><td><cstddef></td></tr>
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>.
94 <center><table border="1"><caption>C++0x Library Headers</caption>
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>
107 <center><table border="1"><caption>C++0x Headers for C Library Facilities</caption>
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>
116 <p>In addition, TR1 includes as:
119 <center><table border="1"><caption>TR1 Library Headers</caption>
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>
122 <tr><td><tr1/functional></td></tr>
127 <center><table border="1"><caption>TR1 Headers for C Library Facilities</caption>
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>
133 <p>Also included are files for the C++ ABI interface:
135 <center><table border="1"><caption>C++ ABI Headers</caption>
136 <tr><td><cxxabi.h></td><td><cxxabi_forced.h></td></tr>
139 <p>And a large variety of extensions.
142 <center><table border="1"><caption>Extension Headers</caption>
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>
153 <center><table border="1"><caption>Extension Debug Headers</caption>
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>
160 <center><table border="1"><caption>Extension Parallel Headers</caption>
161 <tr><td><parallel/algorithm></td><td><parallel/numeric></td></tr>
165 <h2><a name="2.1">Recipes for mixing headers</a></h2>
167 <p> A few simple rules.
170 <p>First, mixing different dialects of the standard headers is not
171 possible. It's an all-or-nothing affair. Thus, code like
175 #include <array>
176 #include <functional>
179 <p>Implies C++0x mode. To use the entities in <array>, the C++0x
180 compilation mode must be used, which implies the C++0x functionality
181 (and deprecations) in <functional> will be present.
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
187 rvalue references with <code>__gnu_cxx::vstring</code>, or to use the
188 debug-mode versions of <code>std::unordered_map</code>, one must use
189 the <code>std=gnu++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.)
192 <p>A special case of the second rule is the mixing of TR1 and C++0x
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:
199 #include <tr1/type_traits>
200 #include <type_traits>
203 <p> Several parts of C++0x diverge quite substantially from TR1 predecessors.
208 <h2><a name="2.2">The C Headers and <code>namespace std</code></a></h2>
210 The standard specifies that if one includes the C-style header
211 (<math.h> in this case), the symbols will be available
212 in the global namespace and perhaps in
213 namespace <code>std::</code> (but this is no longer a firm
214 requirement.) One the other hand, including the C++-style
215 header (<cmath>) guarantees that the entities will be
216 found in namespace std and perhaps in the global namespace.
220 Usage of C++-style headers is recommended, as then
221 C-linkage names can be disambiguated by explicit qualification, such
222 as by <code>std::abort</code>. In addition, the C++-style headers can
223 use function overloading to provide a simpler interface to certain
224 families of C-functions. For instance in <cmath>, the
225 function <code>std::sin</code> has overloads for all the builtin
226 floating-point types. This means that <code>std::sin</code> can be
227 used uniformly, instead of a combination
228 of <code>std::sinf</code>, <code>std::sin</code>,
229 and <code>std::sinl</code>.
233 <h2><a name="2.3">Precompiled Headers</a></h2>
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.
243 <p>Includes all standard headers. Actual content varies depending on
249 <p>Includes all of <stdc++.h>, and adds all the TR1 headers.
254 <p>Includes all of <stdtr1c++.h>, and adds all the Extension headers.
258 <p>How to construct a .gch file from one of these base header files.</p>
260 <p>First, find the include directory for the compiler. One way to do
266 #include <...> search starts here:
267 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0
273 <p>Then, create a precompiled header file with the same flags that
274 will be used to compile other projects.</p>
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
280 <p>The resulting file will be quite large: the current size is around
281 thirty megabytes. </p>
283 <p>How to use the resulting file.</p>
286 g++ -I. -include stdc++.h -H -g -O2 hello.cc
289 <p>Verification that the PCH file is being used is easy:</p>
292 g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
294 . /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
295 . /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string
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>
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>.
306 <h2><a name="3.0">Namespaces</a></h2>
309 <p> There are three main namespaces.
314 <p>The ISO C++ standards specify that "all library entities are defined
315 within namespace std." This includes namepaces nested
316 within <code>namespace std</code>, such as <code>namespace
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.
328 <p>Indicating one of several GNU extensions. Choices
329 include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>,
330 and <code>__gnu_pbds</code>.
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>.
339 <h2><a name="3.1">Namespace <code>std::</code></a></h2>
342 One standard requirement is that the library components are defined
343 in <code>namespace std::</code>. Thus, in order to use these types or
344 functions, one must do one of two things:
347 <div class="itemizedlist"><ul type="disc"> <li><p>put a kind of
348 <span class="emphasis"><i>using-declaration</i></span> in your source
349 (either <code>using namespace std;</code> or i.e. <code>using
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.
352 </p></li> <li><p>use a <span class="emphasis"><i>fully
353 qualified name</i></span> for each library symbol
354 (i.e. <code>std::string</code>, <code>std::cout</code>) Always can be
355 used, and usually enhanced, by strategic use of typedefs. (In the
356 cases where the qualified verbiage becomes unwieldy.)
361 <h2><a name="3.2">Using namespace composition</a></h2>
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.
372 <p>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to
373 adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called
374 <span class="emphasis"><i>namespace composition</i></span>. This is what happens if
375 a <span class="emphasis"><i>using</i></span>-declaration is put into a
376 namespace-definition: the imported symbol(s) gets imported into the
377 currently active namespace(s). For example:
379 <pre class="programlisting">
383 using std::tr1::array;
385 class Window { ... };
389 In this example, <code>std::string</code> gets imported into
390 <code>namespace gtk</code>. The result is that use of
391 <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification.
393 <code>std::string</code> does not get imported into
394 the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
395 <code>using</code>-declarations can wrapped in macros that
396 are set based on autoconf-tests to either "" or i.e. <code>using
397 std::string;</code> (depending on whether the system has
398 libstdc++ in <code>std::</code> or not). (ideas from
399 <tt><<a href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>></tt>, Karl Nelson
400 <tt><<a href="mailto:kenelson@ece.ucdavis.edu">kenelson@ece.ucdavis.edu</a>></tt>)
404 <h2><a name="6">Macros for libstdc++</a></h2>
406 <p>All pre-processor switches and configurations are all gathered
407 in the file <code>c++config.h</code>, which is generated during
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.
417 <p>All library macros begin with <code>_GLIBCXX_</code> (except for
418 versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>).
421 <p>Below is the macro which users may check for library version
425 <dt><code>__GLIBCXX__</code></dt> <dd>The current version of
426 libstdc++ in compressed ISO date format, form of an unsigned
427 long. For details on the value of this particular macro for a
428 particular release, please consult this <a href="abi.html">
429 document</a>.</dd> </dl>
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
435 <p>"Configurable" (or "Not configurable") means
436 that the symbol is initially chosen (or not) based on
437 --enable/--disable options at library build and configure time
438 (documented <a href="../configopts.html">here</a>), with the
439 various --enable/--disable choices being translated to
443 <p> "ABI" means that changing from the default value may
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
447 #undef these macros, the <em>headers</em> may see different code
448 paths, but the <em>libraries</em> which you link against will not.
449 Experimenting with different values with the expectation of
450 consistent linkage requires changing the config headers before
451 building/installing the library.
455 <dt><code>_GLIBCXX_DEPRECATED</code></dt>
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
460 <code>-std=c++98</code> and <code>-std=c++0x</code>. This may
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>
465 <dt><code>_GLIBCXX_FORCE_NEW</code></dt> <dd>Undefined by
466 default. When defined, memory allocation and allocators controlled
467 by libstdc++ call operator new/delete without caching and
468 pooling. Configurable via
469 <code>--enable-libstdcxx-allocator</code>. ABI-changing.
473 <dt><code>_GLIBCXX_CONCEPT_CHECKS</code></dt> <dd>Undefined by
474 default. Configurable via <code>--enable-concept-checks</code>.
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
478 href="../19_diagnostics/howto.html#3">here</a>.</dd>
480 <dt><code>_GLIBCXX_DEBUG</code></dt>
481 <dd>Undefined by default. When defined, compiles
482 user code using the <a href="../ext/debug.html#safe">libstdc++ debug
485 <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt>
486 <dd>Undefined by default. When defined while
487 compiling with the <a href="../ext/debug.html#safe">libstdc++ debug
488 mode</a>, makes the debug mode extremely picky by making the use
489 of libstdc++ extensions and libstdc++-specific behavior into
492 <dt><code>_GLIBCXX_PARALLEL</code></dt>
493 <dd>Undefined by default. When defined, compiles
494 user code using the <a href="../ext/parallel_mode.html">libstdc++ parallel
500 <h2><a name="7">The Standard C++ library and multithreading</a></h2>
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.
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
522 <p>All normal disclaimers aside, multithreaded C++ application are
523 only supported when libstdc++ and all user code was built with
524 compilers which report (via <code> gcc/g++ -v </code>) the same thread
525 model and that model is not <em>single</em>. As long as your
526 final application is actually single-threaded, then it should be
527 safe to mix user code built with a thread model of
528 <em>single</em> with a libstdc++ and other C++ libraries built
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.)
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).
553 <p>See <a href="../faq/index.html#5_6">FAQ</a> (general overview), <a
554 href="../23_containers/howto.html#3">23</a> (containers), and <a
555 href="../27_io/howto.html#9">27</a> (I/O) for more information.
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
560 finding a <em>fast</em> method of implementation portable to all
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
565 interpretations of what "thread-safe" means for a
566 library (not a general program). We currently use the <a
567 href="http://www.sgi.com/tech/stl/thread_safety.html">same
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.
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
576 "Thread Next" to move down the thread. This farm is in
577 latest-to-oldest order.
580 <li>Our threading expert Loren gives a breakdown of
581 <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
582 six situations involving threads</a> for the 3.0 release series.</li>
583 <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
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>
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.)
593 <p>This section will be updated as new and interesting issues come
596 <p>Return <a href="#top">to top of page</a> or
597 <a href="../faq/index.html">to the FAQ</a>.
601 <h2><a name="5">Behavior specific to libstdc++</a></h2>
602 <p>The ISO standard defines the following phrase:
605 <dt><code>[1.3.5] implementation-defined behavior</code></dt>
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>.
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
617 <p>For each entry, we give the section number of the standard, when
618 applicable. This list is probably incomplet and inkorrekt.
620 <p><strong>[1.9]/11 #3</strong> If <code>isatty(3)</code> is true, then
621 interactive stream support is implied.
623 <p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
624 discussed in the various sections on multithreading (see above).
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.
630 <p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described
631 <a href="../18_support/howto.html#1">here</a>.
633 <p><strong>[18.3]/8</strong> Even though it's listed in the library
634 sections, libstdc++ has zero control over what the cleanup code hands
635 back to the runtime loader. Talk to the compiler people. :-)
637 <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br />
638 <strong>[18.5.2]/5</strong> (bad_cast),<br />
639 <strong>[18.5.3]/5</strong> (bad_typeid),<br />
640 <strong>[18.6.1]/8</strong> (exception),<br />
641 <strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code>
642 member function of class <code>std::exception</code>, and these other
643 classes publicly derived from it, simply returns the name of the
644 class. But they are the <em>mangled</em> names; you will need to call
645 <code>c++filt</code> and pass the names as command-line parameters to
646 demangle them, or call a
647 <a href="../18_support/howto.html#5">runtime demangler function</a>.
648 (The classes in <code><stdexcept></code> have constructors which
649 require an argument to use later for <code>what()</code> calls, so the
650 problem of <code>what()</code>'s value does not arise in most
651 user-defined exceptions.)
653 <p><strong>[18.5.1]/7</strong> The return value of
654 <code>std::type_info::name()</code> is the mangled type name (see the
655 previous entry for more).
657 <p><strong>[20.1.5]/5</strong> <em>"Implementors are encouraged to
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
663 non-equal, are implementation-defined."</em> As yet we don't
664 have any allocators which compare non-equal, so we can't describe how
667 <p><strong>[21.1.3.1]/3,4</strong>,<br />
668 <strong>[21.1.3.2]/2</strong>,<br />
669 <strong>[23.*]'s foo::iterator</strong>,<br />
670 <strong>[27.*]'s foo::*_type</strong>,<br />
671 <strong>others...</strong>
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. :-)
676 <p><strong>[21.1.3.1]/5</strong> I don't really know about the mbstate_t
677 stuff... see the <a href="../22_locale/howto.html">chapter 22 notes</a>
680 <p><strong>[22.*]</strong> Anything and everything we have on locale
681 implementation will be described
682 <a href="../22_locale/howto.html">over here</a>.
684 <p><strong>[26.2.8]/9</strong> I have no idea what
685 <code>complex<T></code>'s pow(0,0) returns.
687 <p><strong>[27.4.2.4]/2</strong> Calling
688 <code>std::ios_base::sync_with_stdio</code> after I/O has already been
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!
696 <p><strong>[27.6.1.1.2]</strong>,<br />
697 <strong>[27.6.2.3]</strong> The I/O sentry ctor and dtor can perform
698 additional work than the minimum required. We are not currently taking
699 advantage of this yet.
701 <p><strong>[27.7.1.3]/16</strong>,<br />
702 <strong>[27.8.1.4]/10</strong>
703 The effects of <code>pubsetbuf/setbuf</code> are described
704 <a href="../27_io/howto.html#2">in this chapter</a>.
706 <p><strong>[27.8.1.4]/16</strong> Calling <code>fstream::sync</code> when
707 a get area exists will... whatever <code>fflush()</code> does, I think.
709 <p>Return <a href="#top">to top of page</a> or
710 <a href="../faq/index.html">to the FAQ</a>.
714 <dt><code></code></dt>
718 <p>Return <a href="#top">to top of page</a> or
719 <a href="../faq/index.html">to the FAQ</a>.
724 <!-- ####################################################### -->
727 <p class="fineprint"><em>
728 See <a href="license.html">license.html</a> for copying conditions.
729 Comments and suggestions are welcome, and may be sent to
730 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
OSDN Git Service
