
   #[1]home
   
                     libstdc++ Frequently Asked Questions
                                       
   The latest version of this document is always available at
   [2]http://sourceware.cygnus.com/libstdc++/faq/.
   
   To the [3]libstdc++-v3 homepage.
     _________________________________________________________________
   
                                   Questions
                                       
    1. [4]General Information
         1. [5]What is libstdc++-v3?
         2. [6]Why should I use libstdc++?
         3. [7]Who's in charge of it?
         4. [8]How do I get libstdc++?
         5. [9]When is libstdc++ going to be finished?
         6. [10]How do I contribute to the effort?
         7. [11]What if I have more questions?
    2. [12]Installation
         1. [13]How do I install libstdc++-v3?
         2. [14]Is this a drop-in replacement for the libstdc++ that's
            shipped with EGCS?
         3. [15]What is this CVS thing that you keep mentioning?
    3. [16]Platform-Specific Issues
         1. [17]Can libstdc++-v3 be used with <my favorite compiler>?
    4. [18]Known Bugs and Non-Bugs
         1. [19]What works already?
         2. [20]Bugs in EGCS (not libstdc++-v3)
         3. [21]Bugs in the C++ language/lib specification
    5. [22]Miscellaneous
         1. [23]string::iterator is not char*; vector<T>::iterator is not
            T*
         2. [24]What's next after libstdc++-v3?
         3. [25]What about the STL from SGI?
         4. [26]Extensions and Backward Compatibility
         5. [27]Compiling with "-fnew-abi"
    6. [28]Received Wisdom, Notes, and HOWTOs
         1. [29]What's this section for?
         2. [30]Chapter 17 (Intro)
         3. [31]Chapter 18 (Library Support)
         4. [32]Chapter 19 (Diagnostics)
         5. [33]Chapter 20 (Utilities)
         6. [34]Chapter 21 (Strings)
         7. [35]Chapter 22 (Localization)
         8. [36]Chapter 23 (Containers)
         9. [37]Chapter 24 (Iterators)
        10. [38]Chapter 25 (Algorithms)
        11. [39]Chapter 26 (Numerics)
        12. [40]Chapter 27 (I/O)
     _________________________________________________________________
   
                            1.0 General Information
                                       
1.1 What is libstdc++-v3?

   The EGCS Standard C++ Library v3, or libstdc++-2.90.x, is an ongoing
   project to implement the ISO 14882 Standard C++ library as described
   in chapters 17 through 27 and annex D. As the library reaches stable
   plateaus, it is captured in a snapshot and released. The current
   release is [41]the seventh snapshot. For those who want to see exactly
   how far the project has come, or just want the latest bleeding-edge
   code, the up-to-date source is available over anonymous CVS, and can
   even be browsed over the Web (see below).
   
   A more formal description of the V3 goals can be found in the official
   [42]design document.
     _________________________________________________________________
   
1.2 Why should I use libstdc++?

   The recent completion of the ISO C++ standardization gave the C++
   community a powerful set of reuseable tools in the form of the C++
   Standard Library. However, all existing C++ implementations are (as
   the Draft Standard used to say) "incomplet and incorrekt," and many
   suffer from limitations of the compilers that use them.
   
   The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is
   widely considered to be one of the leading compilers in the world. Its
   development has recently been taken over by the [43]EGCS team. All of
   the rapid development and near-legendary [44]portability that are the
   hallmarks of an open-source project are being applied to libstdc++.
   
   That means that all of the Standard classes and functions (such as
   string, vector<>, iostreams, and algorithms) will be freely available
   and fully compliant. Programmers will no longer need to "roll their
   own" nor be worried about platform-specific incompatabilities.
     _________________________________________________________________
   
1.3 Who's in charge of it?

   The libstdc++ project is contributed to by several developers all over
   the world, in the same way as EGCS (gcc) or Linux. Benjamin Kosnik,
   Gabriel Dos Reis, Nathan Myers, and Ulrich Drepper are the lead
   maintainers of the CVS archive.
   
   Development and discussion is held on the libstdc++ mailing list.
   Subscribing to the list, or searching the list archives, is open to
   everyone. You can read instructions for doing so on the [45]homepage.
   If you have questions, ideas, code, or are just curious, sign up!
     _________________________________________________________________
   
1.4 How do I get libstdc++?

   The seventh (and latest) snapshot of libstdc++-v3 is [46]available via
   ftp.
   
   The [47]homepage has instructions for retrieving the latest CVS
   sources, and for browsing the CVS sources over the web.
   
   The subset commonly known as the Standard Template Library (chapters
   23 through 25, mostly) is adapted from the SGI STL, which is also an
   ongoing work.
     _________________________________________________________________
   
1.5 When is libstdc++ going to be finished?

   Nathan Myers gave the best of all possible answers in [48]a recent
   Usenet article.
     _________________________________________________________________
   
1.6 How do I contribute to the effort?

   Cygnus has [49]a page devoted to this topic. Subscribing to the
   mailing list (see above, or the homepage) is a very good idea if you
   have something to contribute, or if you have spare time and want to
   help. Contributions don't have to be in the form of source code;
   anybody who is willing to help write documentation, for example, or
   has found a bug in code that we all thought was working, is more than
   welcome!
     _________________________________________________________________
   
1.7 What if I have more questions?

   If you have read the README and RELEASE-NOTES files, and your question
   remains unanswered, then just ask the mailing list. At present, you do
   not need to be subscribed to the list to send a message to it. More
   information is available on the homepage (including how to browse the
   list archives); to send to the list, use
   libstdc++@sourceware.cygnus.com.
   
   If you have a question that you think should be included here, or if
   you have a question about a question/answer here, contact [50]Phil
   Edwards or [51]Gabriel Dos Reis.
     _________________________________________________________________
   
                               2.0 Installation
                                       
2.1 How do I install libstdc++-v3?

   Complete instructions are not given here (this is a FAQ, not an
   installation document), but the tools required are few:
     * A release of libstdc++.
     * A recent release of GCC (version 2.95 works). Note that building
       GCC is much easier and more automated than building the GCC 2.[78]
       series was.
     * The tools [52]autoconfand [53]automake.
     * GNU make is the only make that supports these makefiles.
       
   The README and RELEASE-NOTES files contain the exact build and
   installation instructions. You may wish to browse those files over
   CVSweb ahead of time to get a feel for what's required.
     _________________________________________________________________
   
2.2 Is this a drop-in replacement for the libstdc++ that's shipped with EGCS?

   Not in the sense that you're probably thinking.
   
   Probably the easiest way to "replace" the older libstdc++-v2 is to do
   the following:
    1. Build GCC/EGCS as usual.
    2. Build libstdc++-v3 as usual.
    3. Build your code using -I and -L options so that EGCS finds the
       libstdc++-v3 headers and library before the older headers in the
       EGCS include tree.
       
   If you configured libstdc++-v3 to install under a directory called
   /lib3, for example, the command line would look something like
      g++ -Wall -I/lib3/include/g++-v3 -L/lib3/lib foo.cc -o foo


   More information (such as using SGI or GNU extensions, and setting the
   runtime library path) can be found in the RELEASE-NOTES.
   
   The libstdc++-v3 releases cannot easily be used to overwrite the
   egcs-1.1.*/libstdc++/ directory directly. If you wish to build a
   version of EGCS with libstdc++-v3 "built in" like that, you should
   join the mailing list and review the list archives. (Among other
   things, libstdc++-v3 needs to be built with certain compiler options
   that v2 (shipped with EGCS) is not, so you will have to edit a number
   of Makefiles.)
     _________________________________________________________________
   
2.3 What is this CVS thing that you keep mentioning?

   The Concurrent Versions System is one of several revision control
   packages. It was selected for GNU projects because it's free and very
   high quality. The [54]CVS entry in the GNU software catalogue has a
   better description as well as a [55]link to the makers of CVS.
   
   The "anonymous client checkout" feature of CVS is similar to anonymous
   FTP in that it allows anyone to retrieve the latest libstdc++ sources.
     _________________________________________________________________
   
                         3.0 Platform-Specific Issues
                                       
3.1 Can libstdc++-v3 be used with <my favorite compiler>?

   Probably not. Yet.
   
   Because EGCS advances so rapidly, development and testing of libstdc++
   is being done almost entirely under that compiler. If you are curious
   about whether other, lesser compilers (*grin*) support libstdc++, you
   are more than welcome to try. Configuring and building the library
   (see above) will still require certain tools, however. Also keep in
   mind that building libstdc++ does not imply that your compiler will be
   able to use all of the features found in the C++ Standard Library.
   
   Since the goal of ISO Standardization is for all C++ implementations
   to be able to share code, the final libstdc++ should, in theory, be
   useable under any ISO-compliant compiler. It will still be targeted
   and optimized for EGCS/g++, however.
     _________________________________________________________________
   
                          4.0 Known Bugs and Non-Bugs
                                       
   Note that this section can get rapdily outdated -- such is the nature
   of an open-source project. For the latest information, join the
   mailing list or look through recent archives.
   
4.1 What works already?

   This is a verbatim clip from the "Status" section of the homepage and
   RELEASE-NOTES for the latest snapshot.
New:
---

- basic_string<char> has passed validation, with the cavet empor noted
  in BUGS. Documentation for string internals has been added to the
  source code. Ryszard Kabatek has optimized and fixed numerous member
  functions, also Alfred Minarik and Vadim Egorov.
- Include-path optimizations.
- The library and testsuite have been made namespace friendly
  thanks to Alfred Minarik
- bits/std_cmath.h and math/mathconf tweaks by Gabriel Dos Reis.
- complex, valarray, gslice  work by Gabriel Dos Reis.
- Preliminary port to cygwin by Mumit Khan
- basic_stringbuf was re-implemented to fix problems with ostringstreams.
- ios_base and basic_ios data member optimization/clarification. The
  ios heirarchy now has preliminary facet caching.
- istream::ws, getline, and all extraction operators were fixed and
  have undergone preliminary testing.
- Additional documentation by Phil Edwards.
- Many, many bug fixes.

   This is the same from the previous (sixth) snapshot, which lists some
   more changes. The docs themselves (see the Introduction notes under
   section 6.0) should be considered canonical).
New:
---
 - Update to SGI STL 3.2
 - Automatically-generated <limits> header for each architecture.
 - Partially re-written valarray.
 - Extensible documentation-synched-to-webpage architecture.
 - Check script to check installation and builds, with facilities for
   tracking size and compile speed.
 - Stringbufs and stringstreams for basic types work.
 - Various bugfixes.
 - Re-written num_get::do_get.

What works: (noted with the chapter # of the ISO-14882 standard)
-----------
 - exceptions, op new etc. (18, 19)
 - SGI-STL release 3.2 utilities, containers, algorithms, and iterators.
   (20,23,24,25), and ostreambuf_iterator<>. Plus fixes for auto_ptr,
   and an interator class for vector and string.
 - basic_string<> (21)
 - locale, some facets (ctype, num_put, collate), stubs for the rest. (22)
 - Gabriel Dos Reis's valarray<>, and Drepper's complex<>.
 - ios_base, basic_ios<>, basic_streambuf<>, basic_stringbuf<>,
   basic_filebuf<>, ostream<>, operator<< for integers, strings. (27)


What doesn't:
-------------
 - Too many parts of istream, op>>, op<<(double&) etc. (27)
 - Many facet implementations are stubs. (22)
 - Almost no optimizations for small-footprint/low-overhead. (22,27)
 - It has not been fully audited for standard conformance in the areas
   that do work--check out the testsuite directory for an idea of the
   limitations of the current implementation.
 - It has not been made thread-safe.
 - There has been some work to wrap the C headers in namespace std::, but
   it may not be complete yet, and C macros are not shadowed. Please consult
   the mailing list archives for more information.
 - Some parts of numeric_limits specialization for floating point types
   are stubs.
     _________________________________________________________________
   
4.2 Bugs in EGCS (not libstdc++-v3)

   This is by no means meant to be complete nor exhaustive, but mentions
   some problems that users may encounter when building or using
   libstdc++. If you are experiencing one of these problems, you can find
   more information on the libstdc++ and the EGCS mailing lists.
     * When using associative containers (like map), and compiling with
       -O3 (or -finline-functions) and -Winline, I get a zillion errors
       like:
   .../include/g++/stl_tree.h: In function `int __black_count(struct __rb_tree_
node_base *, struct __rb_tree_node_base *)':
   .../include/g++/stl_tree.h:1045: warning: can't inline call to `int __black_
count(struct __rb_tree_node_base *, struct __rb_tree_node_base *)'
   .../include/g++/stl_tree.h:1053: warning: called from here

       This has been discussed a number of times; the problem is that
       __black_count is marked inline but is also a recursive function.
       As of 12July1999, it has been rewritten into an optimized
       non-recursive form, so fresh checkouts/releases should no longer
       see this warning.
     * The whole -Weffc++ thing probably falls into the same
       not-really-a-bug-but-will-appear-to-the-end-user-as-a-bug
       category. That discussion occured before the list was being
       archived, though...
     * The reason that EGCS 1.1.2 cannot be used to build the library is
       that lookups do not work properly, and so the compiler will ICE
       when building the locale-related source files. This has been fixed
       in GCC 2.95. (See also the first entry in this group.)
     _________________________________________________________________
   
4.3 Bugs in the C++ language/lib specification

   Yes, unfortunately, there are some. In a [56]message to the list,
   Nathan Myers announced that he has started a list of problems in the
   ISO C++ Standard itself, especially with regard to the chapters that
   concern the library. The list itself is [57]posted on his website.
   Developers who are having problems interpreting the Standard may wish
   to consult his notes.
   
   For those people who are not part of the ISO Library Group (i.e.,
   nearly all of us needing to read this page in the first place :-), a
   public list of the library defects is occasionally published [58]here.
     _________________________________________________________________
   
                               5.0 Miscellaneous
                                       
5.1 string::iterator is not char*; vector<T>::iterator is not T*

   If you have code that depends on container<T> iterators being
   implemented as pointer-to-T, your code is broken.
   
   While there are arguments for iterators to be implemented in that
   manner, A) they aren't very good ones in the long term, and B) they
   were never guaranteed by the Standard anyway. The type-safety achieved
   by making iterators a real class rather than a typedef for T*
   outweighs nearly all opposing arguments.
     _________________________________________________________________
   
5.2 What's next after libstdc++-v3?

   Hopefully, not much. The goal of libstdc++-v3 is to produce a
   fully-compliant, fully-portable Standard Library. After that, we're
   mostly done: there won't be any more compliance work to do.
   
   The ISO Committee will meet periodically to review Defect Reports in
   the C++ Standard. Undoubtably some of these will result in changes to
   the Standard, which will be reflected in patches to libstdc++. Some of
   that is already happening, see 4.2.
   
   The current libstdc++ contains extensions to the Library which must be
   explicitly requested by client code (for example, the hash tables from
   SGI). Other extensions may be added to libstdc++-v3 if they seem to be
   "standard" enough. Bugfixes and rewrites (to improve or fix thread
   safety, for instance) will of course be a continuing task.
   
   [59]This question about the next libstdc++ prompted some brief but
   interesting [60]speculation.
     _________________________________________________________________
   
5.3 What about the STL from SGI?

   The [61]STL from SGI is merged into libstdc++-v3 with changes as
   necessary. Currently release 3.2 is being used. Changes in the STL
   usually produce some weird bugs and lots of changes in the rest of the
   libstd++ source as we scramble to keep up. :-)
   
   In particular, string is not from SGI and makes no use of their "rope"
   class (which is included as an optional extension), nor is valarray
   and some others. Classes like vector<> are, however.
   
   The FAQ for SGI's STL (one jump off of their main page) is recommended
   reading.
     _________________________________________________________________
   
5.4 Extensions and Backward Compatibility

   Although you can specify -I options to make the preprocessor search
   the g++-v3/ext and /backward directories, it is better to refer to
   files there by their path, as in:
       #include <ext/hash_map>

     _________________________________________________________________
   
5.5 Compiling with "-fnew-abi"

   The library mostly works if you compile it (and programs you link with
   it) using "-fnew-abi -fno-honor-std" on a vanilla EGCS compiler.
   However, some features, such as RTTI and error handlers, might not
   link properly with a vanilla libgcc built in EGCS under the old ABI.
   If you rebuild libgcc using the "-f" flags above, you can get both
   complete language support and full benefits of -fnew-abi -- short
   mangled symbol names, far more efficient exception handling, and empty
   base optimization, to name a few. (Note that the new ABI may change
   from one EGCS snapshot to the next, so you would have to rebuild all
   your libraries each time you get a new compiler snapshot.)
   
   Towards the end of July, this subject was brought up again on the
   mailing list under a different name. The related [62]thread is very
   instructive.
     _________________________________________________________________
   
                    6.0 Received Wisdom, Notes, and HOWTOs
                                       
6.1 What's this section for?

   We will be the first to say that the C++ Standard Library is somewhat
   new and unusual. Both beginners and seasoned veterans can get confused
   when writing new code or porting older code from other
   implementations.
   
   The libstdc++-v3 team is assembling a collection of useful tips and
   notes on how to do common tasks with the classes and functions offered
   by the Library. This section is broken up by the chapters of the ISO
   Standard which concern the Library.
     _________________________________________________________________
   
   
    Comments and suggestions are welcome, and may be sent to [63]Phil
    Edwards or [64]Gabriel Dos Reis.

References

   1. http://sourceware.cygnus.com/libstdc++/
   2. http://sourceware.cygnus.com/libstdc++/faq/html/index.html
   3. file://localhost/home/pedwards/libstdc++/docs/index.html
   4. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_0
   5. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_1
   6. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_2
   7. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_3
   8. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_4
   9. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_5
  10. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_6
  11. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#1_7
  12. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#2_0
  13. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#2_1
  14. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#2_2
  15. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#2_3
  16. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#3_0
  17. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#3_1
  18. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#4_0
  19. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#4_1
  20. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#4_2
  21. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#4_3
  22. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#5_0
  23. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#5_1
  24. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#5_2
  25. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#5_3
  26. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#5_4
  27. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#5_5
  28. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#6_0
  29. file://localhost/home/pedwards/libstdc++/docs/faq/index.html#6_1
  30. file://localhost/home/pedwards/libstdc++/docs/17_intro/howto.html
  31. file://localhost/home/pedwards/libstdc++/docs/18_support/howto.html
  32. file://localhost/home/pedwards/libstdc++/docs/19_diagnostics/howto.html
  33. file://localhost/home/pedwards/libstdc++/docs/20_util/howto.html
  34. file://localhost/home/pedwards/libstdc++/docs/21_strings/howto.html
  35. file://localhost/home/pedwards/libstdc++/docs/22_locale/howto.html
  36. file://localhost/home/pedwards/libstdc++/docs/23_containers/howto.html
  37. file://localhost/home/pedwards/libstdc++/docs/24_iterators/howto.html
  38. file://localhost/home/pedwards/libstdc++/docs/25_algorithms/howto.html
  39. file://localhost/home/pedwards/libstdc++/docs/26_numerics/howto.html
  40. file://localhost/home/pedwards/libstdc++/docs/27_io/howto.html
  41. ftp://sourceware.cygnus.com/pub/libstdc++/libstdc++-2.90.6.tar.gz
  42. file://localhost/home/pedwards/libstdc++/docs/17_intro/DESIGN
  43. http://egcs.cygnus.com/
  44. http://egcs.cygnus.com/gcc-2.95/buildstat.html
  45. file://localhost/home/pedwards/libstdc++/docs/index.html
  46. ftp://sourceware.cygnus.com/pub/libstdc++/libstdc++-2.90.6.tar.gz
  47. file://localhost/home/pedwards/libstdc++/docs/index.html
  48. http://www.deja.com/[ST_rn=3Dps]/getdoc.xp?AN=469581698&fmt=text
  49. file://localhost/home/pedwards/libstdc++/docs/17_intro/contribute.html
  50. mailto:pedwards@ball.com
  51. mailto:gdr@egcs.cygnus.com
  52. http://sourceware.cygnus.com/autoconf/
  53. http://sourceware.cygnus.com/automake/
  54. http://www.gnu.org/software/cvs/cvs.html
  55. http://www.cyclic.com/
  56. http://sourceware.cygnus.com/ml/libstdc++/1998/msg00006.html
  57. http://www.cantrip.org/draft-bugs.txt
  58. http://anubis.dkuug.dk/jtc1/sc22/wg21/
  59. http://sourceware.cygnus.com/ml/libstdc++/1999/msg00080.html
  60. http://sourceware.cygnus.com/ml/libstdc++/1999/msg00084.html
  61. http://www.sgi.com/Technology/STL/
  62. http://sourceware.cygnus.com/ml/libstdc++/1999-q3/msg00066.html
  63. mailto:pedwards@ball.com
  64. mailto:gdr@egcs.cygnus.com
