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

   The fifth (and latest) snapshot of libstdc++-v3 is [45]available via
   ftp.
   
   The [46]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 [47]a recent
   Usenet article.
     _________________________________________________________________
   
1.6 How do I contribute to the effort?

   Cygnus has [48]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 [49]Phil
   Edwards or [50]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 EGCS (version 1.1.x works). Note that building
       EGCS is much easier and more automated than building the gcc/g++
       2.[78] series was.
     * The tools [51]autoconfand [52]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 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 [53]CVS entry in the GNU software catalogue has a
   better description as well as a [54]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.
   
   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:
     * Update to SGI STL 3.12
     * STL auto_ptr fixes
     * A string and vector iterator class=20
     * Minor valarray tweaks.
     * New buffering classes and abstractions for the underlying byte
       sequences, with filebufs approaching (unoptimized) usability.
     * Facets have been cached, stashed, and used throughout the iostream
       hierarchy. Note the caching strategy is still developing, and the
       actual locations they are saved may be changed.
     * Initialization of standard streams is done in a coherent and
       standards-conformant manner.
     * Preliminary wchar_t support has been added, although this isn't
       yet usable.
     * Libio has been imported directly into the distribution, resulting
       in it's larger size, but allowing input/output to work on other
       platforms--Solaris in particular.
       
   What works: (noted with the chapter # of the ISO-14882 standard)
     * exceptions, op new etc.(18, 19)
     * SGI-STL release 3.12 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, numpunct), stubs for
       the rest. (22)
     * Gabriel Dos Reis's valarray<>, and Drepper's complex<>. (However,
       note that numeric_limits<> is not tailored for your target. You
       must do that by hand.) (26)
     * 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)
     * Most facet implementations are stubs. (22)
     * Few optimizations for small-footprint/low-overhead. (22,27)
     * C headers are not wrapped in std:: namespace; C macros are not
       shadowed.
     * It has not been 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 is not complete yet,and C macros are not shadowed. Please
       consult the mailing list archives for more information .
     _________________________________________________________________
   
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 building src/misc-inst.cc, g++ gives an error concluding with
       no matching function for call to
       basic_ostream<_CharT,_Traits>::sentry::sentry
       (basic_ostream<char,char_traits<char>>&)
       Reported to the libstdc++ list by Mark Elbrecht on 19 April 1999;
       this is a bug that appears in egcs-1.1.2, under x86 platforms. It
       is fixed in the current EGCS sources.
     * 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.
       The function needs to be rewritten to either remove the recursion
       entirely, or change it into a tail-recursive form that EGCS knows
       how to optimize away. The quick'n'dirty fix is to edit stl_tree.h
       to comment out the inline keyword -- this accomplishes nothing
       other than to make the compiler quiet.
     * 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...
     _________________________________________________________________
   
4.2 Bugs in the C++ language/lib specification

   Yes, unfortunately, there are some. In a [55]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 [56]posted on his website.
   Developers who are having problems interpreting the Standard may wish
   to consult his notes.
     _________________________________________________________________
   
                               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++.
   
   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.
   
   [57]This question about the next libstdc++ prompted some brief but
   interesting [58]speculation.
     _________________________________________________________________
   
5.3 What about the STL from SGI?

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