2 libstdc++ Frequently Asked Questions
4 The latest version of this document is always available at
5 [1]http://gcc.gnu.org/onlinedocs/libstdc++/faq/. The main
6 documentation page is at
7 [2]http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html.
9 To the [3]libstdc++-v3 homepage.
10 _________________________________________________________________
14 1. [4]General Information
15 1. [5]What is libstdc++-v3?
16 2. [6]Why should I use libstdc++?
17 3. [7]Who's in charge of it?
18 4. [8]How do I get libstdc++?
19 5. [9]When is libstdc++ going to be finished?
20 6. [10]How do I contribute to the effort?
21 7. [11]What happened to libg++? I need that!
22 8. [12]What if I have more questions?
23 9. [13]What are the license terms for libstdc++-v3?
25 1. [15]How do I install libstdc++-v3?
27 3. [17]What is this CVS thing that you keep mentioning?
28 4. [18]How do I know if it works?
29 5. [19]This library is HUGE! And what's libsupc++?
30 3. [20]Platform-Specific Issues
31 1. [21]Can libstdc++-v3 be used with <my favorite compiler>?
34 4. [24]I can't use 'long long' on Solaris
35 5. [25]_XOPEN_SOURCE / _GNU_SOURCE / etc is always defined
36 6. [26]OS X ctype.h is broken! How can I hack it?
37 4. [27]Known Bugs and Non-Bugs
38 1. [28]What works already?
39 2. [29]Bugs in gcc/g++ (not libstdc++-v3)
40 3. [30]Bugs in the C++ language/lib specification
41 4. [31]Things in libstdc++ that look like bugs
42 o [32]reopening a stream fails
43 o [33]-Weffc++ complains too much
44 o [34]"ambiguous overloads" after including an old-style
46 o [35]The g++-3 headers are not ours
47 o [36]compilation errors from streambuf.h
48 o [37]errors about *Cconcept and constraints in the STL...
49 5. [38]Aw, that's easy to fix!
51 1. [40]string::iterator is not char*; vector<T>::iterator is not
53 2. [41]What's next after libstdc++-v3?
54 3. [42]What about the STL from SGI?
55 4. [43]Extensions and Backward Compatibility
57 6. [45]Is libstdc++-v3 thread-safe?
58 7. [46]How do I get a copy of the ISO C++ Standard?
59 8. [47]What's an ABI and why is it so messy?
60 _________________________________________________________________
62 1.0 General Information
64 1.1 What is libstdc++-v3?
66 The GNU Standard C++ Library v3 is an ongoing project to implement the
67 ISO 14882 Standard C++ library as described in chapters 17 through 27
68 and annex D. As the library reaches stable plateaus, it is captured in
69 a snapshot and released. The current release is [48]the fourteenth
70 snapshot. For those who want to see exactly how far the project has
71 come, or just want the latest bleeding-edge code, the up-to-date
72 source is available over anonymous CVS, and can even be browsed over
75 The older libstdc++-v2 project is no longer maintained; the code has
76 been completely replaced and rewritten. [49]If you are using V2, then
77 you need to report bugs to your system vendor, not to the V3 list.
79 A more formal description of the V3 goals can be found in the official
81 _________________________________________________________________
83 1.2 Why should I use libstdc++?
85 The completion of the ISO C++ standardization gave the C++ community a
86 powerful set of reuseable tools in the form of the C++ Standard
87 Library. However, all existing C++ implementations are (as the Draft
88 Standard used to say) "incomplet and incorrekt," and many suffer from
89 limitations of the compilers that use them.
91 The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is
92 widely considered to be one of the leading compilers in the world. Its
93 development has recently been taken over by the [51]GCC team. All of
94 the rapid development and near-legendary [52]portability that are the
95 hallmarks of an open-source project are being applied to libstdc++.
97 That means that all of the Standard classes and functions (such as
98 string, vector<>, iostreams, and algorithms) will be freely available
99 and fully compliant. Programmers will no longer need to "roll their
100 own" nor be worried about platform-specific incompatibilities.
101 _________________________________________________________________
103 1.3 Who's in charge of it?
105 The libstdc++ project is contributed to by several developers all over
106 the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel
107 Dos Reis, Phil Edwards, and Ulrich Drepper are the lead maintainers of
110 Development and discussion is held on the libstdc++ mailing list.
111 Subscribing to the list, or searching the list archives, is open to
112 everyone. You can read instructions for doing so on the [53]homepage.
113 If you have questions, ideas, code, or are just curious, sign up!
114 _________________________________________________________________
116 1.4 How do I get libstdc++?
118 The fourteenth (and latest) snapshot of libstdc++-v3 is [54]available
121 The [55]homepage has instructions for retrieving the latest CVS
122 sources, and for browsing the CVS sources over the web.
124 The subset commonly known as the Standard Template Library (chapters
125 23 through 25, mostly) is adapted from the final release of the SGI
127 _________________________________________________________________
129 1.5 When is libstdc++ going to be finished?
131 Nathan Myers gave the best of all possible answers, responding to a
132 Usenet article asking this question: Sooner, if you help.
133 _________________________________________________________________
135 1.6 How do I contribute to the effort?
137 Here is [56]a page devoted to this topic. Subscribing to the mailing
138 list (see above, or the homepage) is a very good idea if you have
139 something to contribute, or if you have spare time and want to help.
140 Contributions don't have to be in the form of source code; anybody who
141 is willing to help write documentation, for example, or has found a
142 bug in code that we all thought was working, is more than welcome!
143 _________________________________________________________________
145 1.7 What happened to libg++? I need that!
147 The most recent libg++ README states that libg++ is no longer being
148 actively maintained. It should not be used for new projects, and is
149 only being kicked along to support older code.
151 The libg++ was designed and created when there was no Standard to
152 provide guidance. Classes like linked lists are now provided for by
153 list<T> and do not need to be created by genclass. (For that matter,
154 templates exist now and are well-supported, whereas genclass (mostly)
157 There are other classes in libg++ that are not specified in the ISO
158 Standard (e.g., statistical analysis). While there are a lot of really
159 useful things that are used by a lot of people (e.g., statistics :-),
160 the Standards Committee couldn't include everything, and so a lot of
161 those "obvious" classes didn't get included.
163 Since libstdc++ is an implementation of the Standard Library, we have
164 no plans at this time to include non-Standard utilities in the
165 implementation, however handy they are. (The extensions provided in
166 the SGI STL aren't maintained by us and don't get a lot of our
167 attention, because they don't require a lot of our time.) It is
168 entirely plausable that the "useful stuff" from libg++ might be
169 extracted into an updated utilities library, but nobody has stated
172 (The [57]Boost site houses free C++ libraries that do varying things,
173 and happened to be started by members of the Standards Committee.
174 Certain "useful stuff" classes will probably migrate there.)
176 For the bold and/or desperate, the [58]GCC FAQ describes where to find
177 the last libg++ source.
178 _________________________________________________________________
180 1.8 What if I have more questions?
182 If you have read the README and RELEASE-NOTES files, and your question
183 remains unanswered, then just ask the mailing list. At present, you do
184 not need to be subscribed to the list to send a message to it. More
185 information is available on the homepage (including how to browse the
186 list archives); to send to the list, use [59]libstdc++@gcc.gnu.org.
188 If you have a question that you think should be included here, or if
189 you have a question about a question/answer here, contact [60]Phil
190 Edwards or [61]Gabriel Dos Reis.
191 _________________________________________________________________
193 1.9 What are the license terms for libstdc++-v3?
195 See [62]our license description for these and related questions.
196 _________________________________________________________________
200 2.1 How do I install libstdc++-v3?
202 Complete instructions are not given here (this is a FAQ, not an
203 installation document), but the tools required are few:
204 * A 3.x release of GCC. Note that building GCC is much easier and
205 more automated than building the GCC 2.[78] series was. If you are
206 using GCC 2.95, you can still build earlier snapshots of
208 * GNU Make is recommended, but should not be required.
209 * The GNU Autotools are needed if you are messing with the configury
212 The file [63]documentation.html provides a good overview of the steps
213 necessary to build, install, and use the library. Instructions for
214 configuring the library with new flags such as --enable-threads are
215 there also, as well as patches and instructions for working with GCC
218 The top-level install.html and [64]RELEASE-NOTES files contain the
219 exact build and installation instructions. You may wish to browse
220 those files over CVSweb ahead of time to get a feel for what's
221 required. RELEASE-NOTES is located in the ".../docs/17_intro/"
222 directory of the distribution.
223 _________________________________________________________________
227 This question has become moot and has been removed. The stub is here
228 to preserve numbering (and hence links/bookmarks).
229 _________________________________________________________________
231 2.3 What is this CVS thing that you keep mentioning?
233 The Concurrent Versions System is one of several revision control
234 packages. It was selected for GNU projects because it's free (speech),
235 free (beer), and very high quality. The [65]CVS entry in the GNU
236 software catalogue has a better description as well as a [66]link to
239 The "anonymous client checkout" feature of CVS is similar to anonymous
240 FTP in that it allows anyone to retrieve the latest libstdc++ sources.
242 After the first of April, American users will have a "/pharmacy"
243 command-line option...
244 _________________________________________________________________
246 2.4 How do I know if it works?
248 libstdc++-v3 comes with its own testsuite. You do not need to actually
249 install the library ("make install") to run the testsuite.
251 To run the testsuite on the library after building it, use "make
252 check" while in your build directory. To run the testsuite on the
253 library after building and installing it, use "make check-install"
256 If you find bugs in the testsuite programs themselves, or if you think
257 of a new test program that should be added to the suite, please write
258 up your idea and send it to the list!
259 _________________________________________________________________
261 2.4 This library is HUGE! And what's libsupc++?
263 Usually the size of libraries on disk isn't noticeable. When a link
264 editor (or simply "linker") pulls things from a static archive
265 library, only the necessary object files are copied into your
266 executable, not the entire library. Unfortunately, even if you only
267 need a single function or variable from an object file, the entire
268 object file is extracted. (There's nothing unique to C++ or
269 libstdc++-v3 about this; it's just common behavior, given here for
272 Some of the object files which make up libstdc++.a are rather large.
273 If you create a statically-linked executable with -static, those large
274 object files are suddenly part of your executable. Historically the
275 best way around this was to only place a very few functions (often
276 only a single one) in each source/object file; then extracting a
277 single function is the same as extracting a single .o file. For
278 libstdc++-v3 this is only possible to a certain extent; the object
279 files in question contain template classes and template functions,
280 pre-instantiated, and splitting those up causes severe maintenance
283 It's not a bug, and it's not really a problem. Nevertheless, some
284 people don't like it, so here are two pseudo-solutions:
286 If the only functions from libstdc++.a which you need are language
287 support functions (those listed in [67]clause 18 of the standard,
288 e.g., new and delete), then try linking against libsupc++.a (usually
289 specifying -lsupc++ when calling g++ for the final link step will do
290 it). This library contains only those support routines, one per object
291 file. But if you are using anything from the rest of the library, such
292 as IOStreams or vectors, then you'll still need pieces from
295 The second method is one we hope to incorporate into the library build
296 process. Some platforms can place each function and variable into its
297 own section in a .o file. The GNU linker can then perform garbage
298 collection on unused sections; this reduces the situation to only
299 copying needed functions into the executable, as before, but all
300 happens automatically.
302 Unfortunately the garbage collection in GNU ld is buggy; sections
303 (corresponding to functions and variables) which are used are
304 mistakenly removed, leading to horrible crashes when your executable
305 starts up. For the time being, this feature is not used when building
307 _________________________________________________________________
309 3.0 Platform-Specific Issues
311 3.1 Can libstdc++-v3 be used with <my favorite compiler>?
315 Because GCC advances so rapidly, development and testing of libstdc++
316 is being done almost entirely under that compiler. If you are curious
317 about whether other, lesser compilers (*grin*) support libstdc++, you
318 are more than welcome to try. Configuring and building the library
319 (see above) will still require certain tools, however. Also keep in
320 mind that building libstdc++ does not imply that your compiler will be
321 able to use all of the features found in the C++ Standard Library.
323 Since the goal of ISO Standardization is for all C++ implementations
324 to be able to share code, the final libstdc++ should, in theory, be
325 usable under any ISO-compliant compiler. It will still be targeted and
326 optimized for GCC/g++, however.
327 _________________________________________________________________
331 This question has become moot and has been removed. The stub is here
332 to preserve numbering (and hence links/bookmarks).
333 _________________________________________________________________
337 This question has become moot and has been removed. The stub is here
338 to preserve numbering (and hence links/bookmarks).
339 _________________________________________________________________
341 3.4 I can't use 'long long' on Solaris
343 By default we try to support the C99 long long type. This requires
344 that certain functions from your C library be present.
346 Up through release 3.0.2 the tests performed were too general, and
347 this feature was disabled when it did not need to be. The most
348 commonly reported platform affected was Solaris.
350 This has been fixed for 3.0.3 and onwards.
351 _________________________________________________________________
353 3.5 _XOPEN_SOURCE / _GNU_SOURCE / etc is always defined
355 On Solaris, g++ (but not gcc) always defines the preprocessor macro
356 _XOPEN_SOURCE. On GNU/Linux, the same happens with _GNU_SOURCE. (This
357 is not an exhaustive list; other macros and other platforms are also
360 These macros are typically used in C library headers, guarding new
361 versions of functions from their older versions. The C++ standard
362 library includes the C standard library, but it requires the C90
363 version, which for backwards-compatability reasons is often not the
364 default for many vendors.
366 More to the point, the C++ standard requires behavior which is only
367 available on certain platforms after certain symbols are defined.
368 Usually the issue involves I/O-related typedefs. In order to ensure
369 correctness, the compiler simply predefines those symbols.
371 Note that it's not enough to #define them only when the library is
372 being built (during installation). Since we don't have an 'export'
373 keyword, much of the library exists as headers, which means that the
374 symbols must also be defined as your programs are parsed and compiled.
376 To see which symbols are defined, look for CPLUSPLUS_CPP_SPEC in the
377 gcc config headers for your target (and try changing them to see what
378 happens when building complicated code). You can also run "g++ -E -dM
379 - < /dev/null" to display a list of predefined macros for any
380 particular installation.
382 This has been discussed on the mailing lists [68]quite a bit.
384 This method is something of a wart. We'd like to find a cleaner
385 solution, but nobody yet has contributed the time.
386 _________________________________________________________________
388 3.6 OS X ctype.h is broken! How can I hack it?
390 This is a long-standing bug in the OS X support. Fortunately, the
391 patch is quite simple, and well-known. [69]Here's a link to the
393 _________________________________________________________________
395 4.0 Known Bugs and Non-Bugs
397 Note that this section can get rapdily outdated -- such is the nature
398 of an open-source project. For the latest information, join the
399 mailing list or look through recent archives. The RELEASE- NOTES and
400 BUGS files are generally kept up-to-date.
402 For 3.0.1, the most common "bug" is an apparently missing "../" in
403 include/Makefile, resulting in files like gthr.h and gthr-single.h not
406 Please read [70]the configuration instructions for GCC, specifically
407 the part about configuring in a separate build directory, and how
408 strongly recommended it is. Building in the source directory is
409 fragile, is rarely tested, and tends to break, as in this case. This
412 Please do not report these as bugs. We know about them. Reporting this
413 -- or any other problem that's already been fixed -- hinders the
414 development of GCC, because we have to take time to respond to your
417 4.1 What works already?
419 This is a verbatim clip from the "Status" section of the RELEASE-NOTES
420 for the latest snapshot. For a list of fixed bugs, see that file.
423 - more doxygen documentation.
424 - more named locale bug fixes
425 - support for symbol versioning when using GNU ld >= 2.12
427 - tuning for executable size
428 _________________________________________________________________
430 4.2 Bugs in gcc/g++ (not libstdc++-v3)
432 This is by no means meant to be complete nor exhaustive, but mentions
433 some problems that users may encounter when building or using
434 libstdc++. If you are experiencing one of these problems, you can find
435 more information on the libstdc++ and the GCC mailing lists.
437 Before reporting a bug, examine the [71]bugs database with the
438 category set to "libstdc++". The BUGS file in the source tree also
439 tracks known serious problems.
440 * Debugging is problematic, due to bugs in line-number generation
441 (mostly fixed in the compiler) and gdb lagging behind the compiler
442 (lack of personnel). We recommend configuring the compiler using
443 --with-dwarf2 if the DWARF2 debugging format is not already the
444 default on your platform. Also, [72]changing your GDB settings can
445 have a profound effect on your C++ debugging experiences. :-)
446 _________________________________________________________________
448 4.3 Bugs in the C++ language/lib specification
450 Yes, unfortunately, there are some. In a [73]message to the list,
451 Nathan Myers announced that he has started a list of problems in the
452 ISO C++ Standard itself, especially with regard to the chapters that
453 concern the library. The list itself is [74]posted on his website.
454 Developers who are having problems interpreting the Standard may wish
455 to consult his notes.
457 For those people who are not part of the ISO Library Group (i.e.,
458 nearly all of us needing to read this page in the first place :-), a
459 public list of the library defects is occasionally published [75]here.
460 Some of these have resulted in [76]code changes.
461 _________________________________________________________________
463 4.4 Things in libstdc++ that look like bugs
465 There are things which are not bugs in the compiler (4.2) nor the
466 language specification (4.3), but aren't really bugs in libstdc++,
467 either. Really! Please do not report these as bugs.
469 -Weffc++ The biggest of these is the quadzillions of warnings about
470 the library headers emitted when -Weffc++ is used. Making libstdc++
471 "-Weffc++-clean" is not a goal of the project, for a few reasons.
472 Mainly, that option tries to enforce object-oriented programming,
473 while the Standard Library isn't necessarily trying to be OO.
475 reopening a stream fails Did I just say that -Weffc++ was our biggest
476 false-bug report? I lied. (It used to be.) Today it seems to be
477 reports that after executing a sequence like
480 std::fstream fs("a_file");
482 // . do things with fs...
485 fs.open("a_new_file");
487 all operations on the re-opened fs will fail, or at least act very
488 strangely. Yes, they often will, especially if fs reached the EOF
489 state on the previous file. The reason is that the state flags are not
490 cleared on a successful call to open(). The standard unfortunately did
491 not specify behavior in this case, and to everybody's great sorrow,
492 the [77]proposed LWG resolution (see DR #22) is to leave the flags
493 unchanged. You must insert a call to fs.clear() between the calls to
494 close() and open(), and then everything will work like we all expect
497 rel_ops Another is the rel_ops namespace and the template comparison
498 operator functions contained therein. If they become visible in the
499 same namespace as other comparison functions (e.g., 'using' them and
500 the <iterator> header), then you will suddenly be faced with huge
501 numbers of ambiguity errors. This was discussed on the -v3 list;
502 Nathan Myers [78]sums things up here.
504 The g++-3 headers are not ours
506 If you have found an extremely broken header file which is causing
507 problems for you, look carefully before submitting a "high" priority
508 bug report (which you probably shouldn't do anyhow; see the last
509 paragraph of the page describing [79]the GCC bug database).
511 If the headers are in ${prefix}/include/g++-3, or if the installed
512 library's name looks like libstdc++-2.10.a or libstdc++-libc6-2.10.so,
513 then you are using the old libstdc++-v2 library, which is nonstandard
514 and unmaintained. Do not report problems with -v2 to the -v3 mailing
517 Currently our header files are installed in ${prefix}/include/g++-v3
518 (see the 'v'?). This may change with the next release of GCC, as it
519 may be too confusing, but [80]the question has not yet been decided.
521 glibc If you're on a GNU/Linux system and have just upgraded to glibc
522 2.2, but are still using gcc 2.95.2, then you should have read the
523 glibc FAQ, specifically 2.34:
524 2.34. When compiling C++ programs, I get a compilation error in streambuf.h.
526 {BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to
527 apply a patch to the include files in /usr/include/g++, because the fpos_t
528 type has changed in glibc 2.2. The patch is at
529 http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
532 Note that 2.95.x shipped with the [81]old v2 library which is no
533 longer maintained. Also note that gcc 2.95.3 fixes this problem, but
534 requires a separate patch for libstdc++-v3.
536 concept checks If you see compilation errors containing messages about
537 fooConcept and a constraints member function, then most likely you
538 have violated one of the requirements for types used during
539 instantiation of template containers and functions. For example,
540 EqualityComparableConcept appears if your types must be comparable
541 with == and you have not provided this capability (a typo, or wrong
542 visibility, or you just plain forgot, etc).
544 More information, including how to optionally enable/disable the
545 checks, is available [82]here.
546 _________________________________________________________________
548 4.5 Aw, that's easy to fix!
550 If you have found a bug in the library and you think you have a
551 working fix, then send it in! The main GCC site has a page on
552 [83]submitting patches that covers the procedure, but for libstdc++
553 you should also send the patch to our mailing list in addition to the
554 GCC patches mailing list. The libstdc++ [84]contributors' page also
555 talks about how to submit patches.
557 In addition to the description, the patch, and the ChangeLog entry, it
558 is a Good Thing if you can additionally create a small test program to
559 test for the presence of the bug that your patch fixes. Bugs have a
560 way of being reintroduced; if an old bug creeps back in, it will be
561 caught immediately by the [85]testsuite -- but only if such a test
563 _________________________________________________________________
567 5.1 string::iterator is not char*; vector<T>::iterator is not T*
569 If you have code that depends on container<T> iterators being
570 implemented as pointer-to-T, your code is broken.
572 While there are arguments for iterators to be implemented in that
573 manner, A) they aren't very good ones in the long term, and B) they
574 were never guaranteed by the Standard anyway. The type-safety achieved
575 by making iterators a real class rather than a typedef for T*
576 outweighs nearly all opposing arguments.
578 Code which does assume that a vector iterator i is a pointer can often
579 be fixed by changing i in certain expressions to &*i . Future
580 revisions of the Standard are expected to bless this usage for
581 vector<> (but not for basic_string<>).
582 _________________________________________________________________
584 5.2 What's next after libstdc++-v3?
586 Hopefully, not much. The goal of libstdc++-v3 is to produce a
587 fully-compliant, fully-portable Standard Library. After that, we're
588 mostly done: there won't be any more compliance work to do. However:
589 1. The ISO Committee will meet periodically to review Defect Reports
590 in the C++ Standard. Undoubtedly some of these will result in
591 changes to the Standard, which will be reflected in patches to
592 libstdc++. Some of that is already happening, see 4.2. Some of
593 those changes are being predicted by the library maintainers, and
594 we add code to the library based on what the current proposed
595 resolution specifies. Those additions are listed in [86]the
597 2. Performance tuning. Lots of performance tuning. This too is
598 already underway for post-3.0 releases, starting with memory
599 expansion in container classes and buffer usage in synchronized
601 3. An ABI for libstdc++ will eventually be developed, so that
602 multiple binary-incompatible copies of the library can be replaced
603 with a single backwards-compatible library, like libgcc_s.so is.
604 4. The current libstdc++ contains extensions to the Library which
605 must be explicitly requested by client code (for example, the hash
606 tables from SGI). Other extensions may be added to libstdc++-v3 if
607 they seem to be "standard" enough. (For example, the "long long"
608 type from C99.) Bugfixes and rewrites (to improve or fix thread
609 safety, for instance) will of course be a continuing task.
611 [87]This question about the next libstdc++ prompted some brief but
612 interesting [88]speculation.
613 _________________________________________________________________
615 5.3 What about the STL from SGI?
617 The [89]STL from SGI, version 3.3, was the most recent merge of the
618 STL codebase. The code in libstdc++ contains many fixes and changes,
619 and it is very likely that the SGI code is no longer under active
620 development. We expect that no future merges will take place.
622 In particular, string is not from SGI and makes no use of their "rope"
623 class (which is included as an optional extension), nor is valarray
624 and some others. Classes like vector<> are, however.
626 The FAQ for SGI's STL (one jump off of their main page) is recommended
628 _________________________________________________________________
630 5.4 Extensions and Backward Compatibility
632 Although you can specify -I options to make the preprocessor search
633 the g++-v3/ext and /backward directories, it is better to refer to
634 files there by their path, as in:
635 #include <ext/hash_map>
638 Extensions to the library have [90]their own page.
639 _________________________________________________________________
643 This question has become moot and has been removed. The stub is here
644 to preserve numbering (and hence links/bookmarks).
645 _________________________________________________________________
647 5.6 Is libstdc++-v3 thread-safe?
649 When the system's libc is itself thread-safe, a non-generic
650 implementation of atomicity.h exists for the architecture, and gcc
651 itself reports a thread model other than single; libstdc++-v3 strives
652 to be thread-safe. The user-code must guard against concurrent method
653 calls which may access any particular library object's state.
654 Typically, the application programmer may infer what object locks must
655 be held based on the objects referenced in a method call. Without
656 getting into great detail, here is an example which requires
658 library_class_a shared_object_a;
661 library_class_b *object_b = new library_class_b;
662 shared_object_a.add_b (object_b); // must hold lock for shared_object_
664 shared_object_a.mutate (); // must hold lock for shared_object_
668 // Multiple copies of thread_main() are started in independent threads.
670 Under the assumption that object_a and object_b are never exposed to
671 another thread, here is an example that should not require any
674 library_class_a object_a;
675 library_class_b *object_b = new library_class_b;
676 object_a.add_b (object_b);
680 All library objects are safe to use in a multithreaded program as long
681 as each thread carefully locks out access by any other thread while it
682 uses any object visible to another thread. In general, this
683 requirement includes both read and write access to objects; unless
684 otherwise documented as safe, do not assume that two threads may
685 access a shared standard library object at the same time.
687 See chapters [91]17 (library introduction), [92]23 (containers), and
688 [93]27 (I/O) for more information.
689 _________________________________________________________________
691 5.7 How do I get a copy of the ISO C++ Standard?
693 Copies of the full ISO 14882 standard are available on line via the
694 ISO mirror site for committee members. Non-members, or those who have
695 not paid for the privilege of sitting on the committee and sustained
696 their two-meeting commitment for voting rights, may get a copy of the
697 standard from their respective national standards organization. In the
698 USA, this national standards organization is ANSI and their website is
699 right [94]here. (And if you've already registered with them, clicking
700 this link will take you to directly to the place where you can [95]buy
701 the standard on-line.
703 Who is your country's member body? Visit the [96]ISO homepage and find
705 _________________________________________________________________
707 5.8 What's an ABI and why is it so messy?
709 "ABI" stands for "Application Binary Interface." Conventionally, it
710 refers to a great mass of details about how arguments are arranged on
711 the call stack and/or in registers, and how various types are arranged
712 and padded in structs. A single CPU design may suffer multiple ABIs
713 designed by different development tool vendors who made different
714 choices, or even by the same vendor for different target applications
715 or compiler versions. In ideal circumstances the CPU designer presents
716 one ABI and all the OSes and compilers use it. In practice every ABI
717 omits details that compiler implementers (consciously or accidentally)
718 must choose for themselves.
720 That ABI definition suffices for compilers to generate code so a
721 program can interact safely with an OS and its lowest-level libraries.
722 Users usually want an ABI to encompass more detail, allowing libraries
723 built with different compilers (or different releases of the same
724 compiler!) to be linked together. For C++, this includes many more
725 details than for C, and CPU designers (for good reasons elaborated
726 below) have not stepped up to publish C++ ABIs. The details include
727 virtual function implementation, struct inheritance layout, name
728 mangling, and exception handling. Such an ABI has been defined for GNU
729 C++, and is immediately useful for embedded work relying only on a
730 "free-standing implementation" that doesn't include (much of) the
731 standard library. It is a good basis for the work to come.
733 A useful C++ ABI must also incorporate many details of the standard
734 library implementation. For a C ABI, the layouts of a few structs
735 (such as FILE, stat, jmpbuf, and the like) and a few macros suffice.
736 For C++, the details include the complete set of names of functions
737 and types used, the offsets of class members and virtual functions,
738 and the actual definitions of all inlines. C++ exposes many more
739 library details to the caller than C does. It makes defining a
740 complete ABI a much bigger undertaking, and requires not just
741 documenting library implementation details, but carefully designing
742 those details so that future bug fixes and optimizations don't force
745 There are ways to help isolate library implementation details from the
746 ABI, but they trade off against speed. Library details used in inner
747 loops (e.g., getchar) must be exposed and frozen for all time, but
748 many others may reasonably be kept hidden from user code, so they may
749 later be changed. Deciding which, and implementing the decisions, must
750 happen before you can reasonably document a candidate C++ ABI that
751 encompasses the standard library.
752 _________________________________________________________________
754 See [97]license.html for copying conditions. Comments and suggestions
755 are welcome, and may be sent to [98]the libstdc++ mailing list.
759 1. http://gcc.gnu.org/onlinedocs/libstdc++/faq/
760 2. http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html
761 3. http://gcc.gnu.org/libstdc++/
762 4. ../faq/index.html#1_0
763 5. ../faq/index.html#1_1
764 6. ../faq/index.html#1_2
765 7. ../faq/index.html#1_3
766 8. ../faq/index.html#1_4
767 9. ../faq/index.html#1_5
768 10. ../faq/index.html#1_6
769 11. ../faq/index.html#1_7
770 12. ../faq/index.html#1_8
771 13. ../faq/index.html#1_9
772 14. ../faq/index.html#2_0
773 15. ../faq/index.html#2_1
774 16. ../faq/index.html#2_2
775 17. ../faq/index.html#2_3
776 18. ../faq/index.html#2_4
777 19. ../faq/index.html#2_5
778 20. ../faq/index.html#3_0
779 21. ../faq/index.html#3_1
780 22. ../faq/index.html#3_2
781 23. ../faq/index.html#3_3
782 24. ../faq/index.html#3_4
783 25. ../faq/index.html#3_5
784 26. ../faq/index.html#3_6
785 27. ../faq/index.html#4_0
786 28. ../faq/index.html#4_1
787 29. ../faq/index.html#4_2
788 30. ../faq/index.html#4_3
789 31. ../faq/index.html#4_4
790 32. ../faq/index.html#4_4_iostreamclear
791 33. ../faq/index.html#4_4_Weff
792 34. ../faq/index.html#4_4_rel_ops
793 35. ../faq/index.html#4_4_interface
794 36. ../faq/index.html#4_4_glibc
795 37. ../faq/index.html#4_4_checks
796 38. ../faq/index.html#4_5
797 39. ../faq/index.html#5_0
798 40. ../faq/index.html#5_1
799 41. ../faq/index.html#5_2
800 42. ../faq/index.html#5_3
801 43. ../faq/index.html#5_4
802 44. ../faq/index.html#5_5
803 45. ../faq/index.html#5_6
804 46. ../faq/index.html#5_7
805 47. ../faq/index.html#5_8
806 48. http://gcc.gnu.org/libstdc++/download.html
807 49. ../faq/index.html#4_4_interface
808 50. ../17_intro/DESIGN
809 51. http://gcc.gnu.org/
810 52. http://gcc.gnu.org/gcc-2.95/buildstat.html
811 53. http://gcc.gnu.org/libstdc++/
812 54. http://gcc.gnu.org/libstdc++/download.html
813 55. http://gcc.gnu.org/libstdc++/
814 56. ../17_intro/contribute.html
815 57. http://www.boost.org/
816 58. http://gcc.gnu.org/fom_serv/cache/33.html
817 59. mailto:libstdc++@gcc.gnu.org
818 60. mailto:pme@gcc.gnu.org
819 61. mailto:gdr@gcc.gnu.org
820 62. ../17_intro/license.html
821 63. ../documentation.html
822 64. ../17_intro/RELEASE-NOTES
823 65. http://www.gnu.org/software/cvs/cvs.html
824 66. http://www.cvshome.org/
825 67. ../18_support/howto.html
826 68. http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris
827 69. http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html
828 70. http://gcc.gnu.org/install/configure.html
829 71. http://gcc.gnu.org/bugs.html
830 72. http://gcc.gnu.org/ml/libstdc++/2002-02/msg00034.html
831 73. http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html
832 74. http://www.cantrip.org/draft-bugs.txt
833 75. http://anubis.dkuug.dk/jtc1/sc22/wg21/
834 76. ../faq/index.html#5_2
835 77. ../ext/howto.html#5
836 78. http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html
837 79. http://gcc.gnu.org/gnatswrite.html
838 80. http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html
839 81. ../faq/index.html#4_4_interface
840 82. ../19_diagnostics/howto.html#3
841 83. http://gcc.gnu.org/contribute.html
842 84. ../17_intro/contribute.html
843 85. ../faq/index.html#2_4
844 86. ../ext/howto.html#5
845 87. http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html
846 88. http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html
847 89. http://www.sgi.com/Technology/STL/
848 90. ../ext/howto.html
849 91. ../17_intro/howto.html#3
850 92. ../23_containers/howto.html#3
851 93. ../27_io/howto.html#9
852 94. http://www.ansi.org/
853 95. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998
854 96. http://www.iso.ch/
855 97. ../17_intro/license.html
856 98. mailto:libstdc++@gcc.gnu.org