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/.
7 To the [2]libstdc++-v3 homepage.
8 _________________________________________________________________
12 1. [3]General Information
13 1. [4]What is libstdc++-v3?
14 2. [5]Why should I use libstdc++?
15 3. [6]Who's in charge of it?
16 4. [7]How do I get libstdc++?
17 5. [8]When is libstdc++ going to be finished?
18 6. [9]How do I contribute to the effort?
19 7. [10]What happened to libg++? I need that!
20 8. [11]What if I have more questions?
22 1. [13]How do I install libstdc++-v3?
23 2. [14]Is this a drop-in replacement for the libstdc++ that's
25 3. [15]What is this CVS thing that you keep mentioning?
26 4. [16]How do I know if it works?
27 3. [17]Platform-Specific Issues
28 1. [18]Can libstdc++-v3 be used with <my favorite compiler>?
29 2. [19]Building under Cygwin hangs/explodes!?
30 4. [20]Known Bugs and Non-Bugs
31 1. [21]What works already?
32 2. [22]Bugs in gcc/g++ (not libstdc++-v3)
33 3. [23]Bugs in the C++ language/lib specification
34 4. [24]Things in libstdc++ that look like bugs
35 [25]The g++-3 headers are not ours
36 5. [26]Aw, that's easy to fix!
38 1. [28]string::iterator is not char*; vector<T>::iterator is not
40 2. [29]What's next after libstdc++-v3?
41 3. [30]What about the STL from SGI?
42 4. [31]Extensions and Backward Compatibility
43 5. [32]Compiling with "-fnew-abi"
44 6. [33]Is libstdc++-v3 thread-safe?
45 7. [34]How do I get a copy of the ISO C++ Standard?
46 _________________________________________________________________
48 1.0 General Information
50 1.1 What is libstdc++-v3?
52 The GNU Standard C++ Library v3, or libstdc++-2.90.x/2.9x, is an
53 ongoing project to implement the ISO 14882 Standard C++ library as
54 described in chapters 17 through 27 and annex D. As the library
55 reaches stable plateaus, it is captured in a snapshot and released.
56 The current release is [35]the tenth snapshot. For those who want to
57 see exactly how far the project has come, or just want the latest
58 bleeding-edge code, the up-to-date source is available over anonymous
59 CVS, and can even be browsed over the Web (see below).
61 A more formal description of the V3 goals can be found in the official
63 _________________________________________________________________
65 1.2 Why should I use libstdc++?
67 The completion of the ISO C++ standardization gave the C++ community a
68 powerful set of reuseable tools in the form of the C++ Standard
69 Library. However, all existing C++ implementations are (as the Draft
70 Standard used to say) "incomplet and incorrekt," and many suffer from
71 limitations of the compilers that use them.
73 The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is
74 widely considered to be one of the leading compilers in the world. Its
75 development has recently been taken over by the [37]GCC team. All of
76 the rapid development and near-legendary [38]portability that are the
77 hallmarks of an open-source project are being applied to libstdc++.
79 That means that all of the Standard classes and functions (such as
80 string, vector<>, iostreams, and algorithms) will be freely available
81 and fully compliant. Programmers will no longer need to "roll their
82 own" nor be worried about platform-specific incompatabilities.
83 _________________________________________________________________
85 1.3 Who's in charge of it?
87 The libstdc++ project is contributed to by several developers all over
88 the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel
89 Dos Reis, Phil Edwards, and Ulrich Drepper are the lead maintainers of
92 Development and discussion is held on the libstdc++ mailing list.
93 Subscribing to the list, or searching the list archives, is open to
94 everyone. You can read instructions for doing so on the [39]homepage.
95 If you have questions, ideas, code, or are just curious, sign up!
96 _________________________________________________________________
98 1.4 How do I get libstdc++?
100 The tenth (and latest) snapshot of libstdc++-v3 is [40]available via
103 The [41]homepage has instructions for retrieving the latest CVS
104 sources, and for browsing the CVS sources over the web.
106 The subset commonly known as the Standard Template Library (chapters
107 23 through 25, mostly) is adapted from the SGI STL, which is also an
109 _________________________________________________________________
111 1.5 When is libstdc++ going to be finished?
113 Nathan Myers gave the best of all possible answers, responding to a
114 Usenet article asking this question: Sooner, if you help.
115 _________________________________________________________________
117 1.6 How do I contribute to the effort?
119 Here is [42]a page devoted to this topic. Subscribing to the mailing
120 list (see above, or the homepage) is a very good idea if you have
121 something to contribute, or if you have spare time and want to help.
122 Contributions don't have to be in the form of source code; anybody who
123 is willing to help write documentation, for example, or has found a
124 bug in code that we all thought was working, is more than welcome!
125 _________________________________________________________________
127 1.7 What happened to libg++? I need that!
129 The most recent libg++ README states that libg++ is no longer being
130 actively maintained. It should not be used for new projects, and is
131 only being kicked along to support older code.
133 The libg++ was designed and created when there was no Standard to
134 provide guidance. Classes like linked lists are now provided for by
135 list<T> and do not need to be created by genclass. (For that matter,
136 templates exist now and are well-supported, whereas genclass (mostly)
139 There are other classes in libg++ that are not specified in the ISO
140 Standard (e.g., statistical analysis). While there are a lot of really
141 useful things that are used by a lot of people (e.g., statistics :-),
142 the Standards Committee couldn't include everything, and so a lot of
143 those "obvious" classes didn't get included.
145 Since libstdc++ is an implementation of the Standard Library, we have
146 no plans at this time to include non-Standard utilities in the
147 implementation, however handy they are. (The extensions provided in
148 the SGI STL aren't maintained by us and don't get a lot of our
149 attention, because they don't require a lot of our time.) It is
150 entirely plausable that the "useful stuff" from libg++ might be
151 extracted into an updated utilities library, but nobody has stated
154 (The [43]Boost site houses free C++ libraries that do varying things,
155 and happened to be started by members of the Standards Committee.
156 Certain "useful stuff" classes will probably migrate there.)
158 For the bold and/or desperate, the [44]GCC FAQ describes where to find
159 the last libg++ source.
160 _________________________________________________________________
162 1.8 What if I have more questions?
164 If you have read the README and RELEASE-NOTES files, and your question
165 remains unanswered, then just ask the mailing list. At present, you do
166 not need to be subscribed to the list to send a message to it. More
167 information is available on the homepage (including how to browse the
168 list archives); to send to the list, use [45]libstdc++@gcc.gnu.org.
170 If you have a question that you think should be included here, or if
171 you have a question about a question/answer here, contact [46]Phil
172 Edwards or [47]Gabriel Dos Reis.
173 _________________________________________________________________
177 2.1 How do I install libstdc++-v3?
179 Complete instructions are not given here (this is a FAQ, not an
180 installation document), but the tools required are few:
181 * A release of libstdc++.
182 * A recent release of GCC (version 2.95 works). Note that building
183 GCC is much easier and more automated than building the GCC 2.[78]
185 * If you plan on hacking around with the makefiles, you will need
186 the tools [48]autoconfand [49]automake.
187 * GNU Make is the only make that supports these makefiles.
189 The file [50]documentation.html provides a good overview of the steps
190 necessary to build, install, and use the library. Instructions for
191 configuring the library with new flags such as --enable-threads are
194 The top-level install.html and [51]RELEASE-NOTES files contain the
195 exact build and installation instructions. You may wish to browse
196 those files over CVSweb ahead of time to get a feel for what's
197 required. RELEASE-NOTES is located in the ".../docs/17_intro/"
198 directory of the distribution.
199 _________________________________________________________________
201 2.2 Is this a drop-in replacement for the libstdc++ that's shipped with g++?
203 Yes, as of 2.90.8, it is intended as such. And as of 2.91,
204 libstdc++-v3 is the library that's shipped with g++, so much of this
205 answer has become moot.
206 _________________________________________________________________
208 2.3 What is this CVS thing that you keep mentioning?
210 The Concurrent Versions System is one of several revision control
211 packages. It was selected for GNU projects because it's free (speech),
212 free (beer), and very high quality. The [52]CVS entry in the GNU
213 software catalogue has a better description as well as a [53]link to
216 The "anonymous client checkout" feature of CVS is similar to anonymous
217 FTP in that it allows anyone to retrieve the latest libstdc++ sources.
219 After the first of April, American users will have a "/pharmacy"
220 command-line option...
221 _________________________________________________________________
223 2.4 How do I know if it works?
225 libstdc++-v3 comes with its own testsuite. You do not need to actually
226 install the library ("gmake install") to run the testsuite. Note that
227 2.91 does not use DejaGNU yet.
229 To run the testsuite on the library after building it, use "gmake
230 check" while in your build directory. To run the testsuite on the
231 library after building and installing it, use "gmake check-install"
234 The testsuite subdirectory in your build directory will then contain
235 three files of the form YYYYMMDD-mkcheck*.txt. One of them
236 (-mkcheck.txt itself) contains the results of the tests; this can be
237 mailed to the list. The other files (-mkchecklog.txt and
238 -mkcheckfiles.txt) contain messages from the compiler while building
239 the test programs, and a list of the tests to be run, respectively.
241 If you find bugs in the testsuite programs themselves, or if you think
242 of a new test program that should be added to the suite, please write
243 up your idea and send it to the list!
244 _________________________________________________________________
246 3.0 Platform-Specific Issues
248 3.1 Can libstdc++-v3 be used with <my favorite compiler>?
252 Because GCC advances so rapidly, development and testing of libstdc++
253 is being done almost entirely under that compiler. If you are curious
254 about whether other, lesser compilers (*grin*) support libstdc++, you
255 are more than welcome to try. Configuring and building the library
256 (see above) will still require certain tools, however. Also keep in
257 mind that building libstdc++ does not imply that your compiler will be
258 able to use all of the features found in the C++ Standard Library.
260 Since the goal of ISO Standardization is for all C++ implementations
261 to be able to share code, the final libstdc++ should, in theory, be
262 useable under any ISO-compliant compiler. It will still be targeted
263 and optimized for GCC/g++, however.
264 _________________________________________________________________
266 3.2 Building under Cygwin hangs/explodes!?
268 Sometimes, yes. You're probably in the middle of generating the
269 numeric_limits specializations when it hangs, right? Thought so...
271 The <limits> header and its associated library code are
272 platform-specific. These files get generated from scratch during
273 installation, and it is this generator that is hanging. More
274 specifically, the only sure way to determine what the
275 numeric_limits<T>::traps boolean should be is to actually divide by
276 zero and see if it is trapped or not.
278 Under NT, this will occasionally just hang. On those occasions when
279 the test does not hang, the zero-division is in fact trapped. That
280 doesn't prevent hanging elsewhere.
282 You have two options. You can get a newer cygwin1.dll (see the Cygwin
283 paragraph in the [54]installation instructions). Or you can get a
284 prebuilt set of bits/std_limits.h and src/limitsMEMBERS.cc files from
285 Mumit Khan's [55]Cygwin-related website.
286 _________________________________________________________________
288 4.0 Known Bugs and Non-Bugs
290 Note that this section can get rapdily outdated -- such is the nature
291 of an open-source project. For the latest information, join the
292 mailing list or look through recent archives. The RELEASE- NOTES and
293 BUGS files are generally kept up-to-date.
295 4.1 What works already?
297 This is a verbatim clip from the "Status" section of the RELEASE-NOTES
298 for the latest snapshot.
300 - namespace std:: is now on by default.
301 - choice of "C" include strategies, including the shadow header work,
302 or generic global to std mapping of required "C" types.
303 - cpu/atomicity.h tweaks, additions of ia64 and arm support.
304 - abstraction of atomicity.h header to support notion of os/atomicity.h files.
305 - addition of backward header bits
306 - use of system_header pragma
307 - Conditional use of -Werror
308 - preliminary support for new g++ diagnostics capabilities, including
309 -fdiagnostics-show-location=once
310 - pedantic and shadow argument warning fixes
311 - Ugly, yet correct mechanism for dealing with "C" math adopted,
312 including the use of builtins.
313 - updates and configure/build work to support new libtool
314 - addition of strstream
317 - update to SGI STL 3.3
318 - libio sync between glibc/libstdc++-v3. Some divergence since initial
319 merge, but sources remain quite close.
321 - wide character work for IO when using libio
322 - addition of c_io_stdio and "C" IO abstraction layer.
323 - auto_ptr fixes, testsuite additions
324 - Attempts to use -ffunction-sections -fdata-sections and
325 --gc-sections, depending on use of GNU ld and specific features. As of
326 late, --gc-sections has been disabled due to problems with it throwing
327 away initialization sections. This work is ongoing.
328 - long double support
329 - sub directory removal, coherent organization of cpu and os-specific
330 files, consolidation of include directories, integration of the C++
331 support bits for operator new/delete,exceptions, etc. All includes
332 are now either in the include/* hierarchy or in libsupc++'s sub directory.
333 - Support for more platforms, including irix and bsd variants.
334 - filebuf tweaks to deal with variable-size buffers.
335 - filebuf implementation for putbackc, etc. al.
336 - ctype rewritten. Includes ctype, ctype, and others.
337 - codecvt rewritten. Includes codecvt,
338 codecvt. In addition,
339 implementation-defined conversions using iconv are now supported with
340 the __enc_traits partial-specialization of the State template
341 parameter of the codecvt class. In this manner, conversions between
342 encodings such as UCS4, USC2, UNICODE, UNICODEBIG, UNICODELITTLE, etc
344 - preliminary work on named locales
345 - preliminary documentation for locale implementation has been established.
346 - Many, many bug fixes.
347 - Many, many testsuite additions and consistent VERIFY usage.
348 - work on mkcheck to make it more flexible, use libtool, etc.
349 _________________________________________________________________
351 4.2 Bugs in gcc/g++ (not libstdc++-v3)
353 This is by no means meant to be complete nor exhaustive, but mentions
354 some problems that users may encounter when building or using
355 libstdc++. If you are experiencing one of these problems, you can find
356 more information on the libstdc++ and the GCC mailing lists.
357 * As of 2.91, these bugs have all been fixed. We look forward to new
358 ones, well, not exactly...
359 _________________________________________________________________
361 4.3 Bugs in the C++ language/lib specification
363 Yes, unfortunately, there are some. In a [56]message to the list,
364 Nathan Myers announced that he has started a list of problems in the
365 ISO C++ Standard itself, especially with regard to the chapters that
366 concern the library. The list itself is [57]posted on his website.
367 Developers who are having problems interpreting the Standard may wish
368 to consult his notes.
370 For those people who are not part of the ISO Library Group (i.e.,
371 nearly all of us needing to read this page in the first place :-), a
372 public list of the library defects is occasionally published [58]here.
373 _________________________________________________________________
375 4.4 Things in libstdc++ that look like bugs
377 There are things which are not bugs in the compiler (4.2) nor the
378 language specification (4.3), but aren't really bugs in libstdc++,
381 The biggest of these is the quadzillions of warnings about the library
382 headers emitted when -Weffc++ is used. Making libstdc++
383 "-Weffc++-clean" is not a goal of the project, for a few reasons.
384 Mainly, that option tries to enforce object-oriented programming,
385 while the Standard Library isn't necessarily trying to be OO. There
386 are multiple solutions under discussion.
388 The g++-3 headers are not ours
390 If you have found an extremely broken header file which is causing
391 problems for you, look carefully before submitting a "high" priority
392 bug report (which you probably shouldn't do anyhow; see the last
393 paragraph of the page describing [59]the GCC bug database).
395 If the headers are in ${prefix}/include/g++-3, then you are using the
396 old libstdc++-v2 library, which is nonstandard and unmaintained. Do
397 not report problems with -v2 to the -v3 mailing list.
399 Currently our header files are installed in ${prefix}/include/g++-v3
400 (see the 'v'?). This may change with the next release of GCC, as it
401 may be too confusing, but [60]the question has not yet been decided.
402 _________________________________________________________________
404 4.5 Aw, that's easy to fix!
406 If you have found a bug in the library and you think you have a
407 working fix, then send it in! The main GCC site has a page on
408 [61]submitting patches that covers the procedure, but for libstdc++
409 you should of course send the patch to our mailing list, not the GCC
410 mailing list. The libstdc++ [62]contributors' page also talks about
411 how to submit patches.
413 In addition to the description, the patch, and the ChangeLog entry, it
414 is a Good Thing if you can additionally create a small test program to
415 test for the presence of the bug that your patch fixes. Bugs have a
416 way of being reintroduced; if an old bug creeps back in, it will be
417 caught immediately by the [63]testsuite -- but only if such a test
419 _________________________________________________________________
423 5.1 string::iterator is not char*; vector<T>::iterator is not T*
425 If you have code that depends on container<T> iterators being
426 implemented as pointer-to-T, your code is broken.
428 While there are arguments for iterators to be implemented in that
429 manner, A) they aren't very good ones in the long term, and B) they
430 were never guaranteed by the Standard anyway. The type-safety achieved
431 by making iterators a real class rather than a typedef for T*
432 outweighs nearly all opposing arguments.
433 _________________________________________________________________
435 5.2 What's next after libstdc++-v3?
437 Hopefully, not much. The goal of libstdc++-v3 is to produce a
438 fully-compliant, fully-portable Standard Library. After that, we're
439 mostly done: there won't be any more compliance work to do.
441 The ISO Committee will meet periodically to review Defect Reports in
442 the C++ Standard. Undoubtably some of these will result in changes to
443 the Standard, which will be reflected in patches to libstdc++. Some of
444 that is already happening, see 4.2. Some of those changes are being
445 predicted by the library maintainers, and we add code to the library
446 based on what the current proposed resolution specifies.
448 The current libstdc++ contains extensions to the Library which must be
449 explicitly requested by client code (for example, the hash tables from
450 SGI). Other extensions may be added to libstdc++-v3 if they seem to be
451 "standard" enough. (For example, the "long long" type from C99.)
452 Bugfixes and rewrites (to improve or fix thread safety, for instance)
453 will of course be a continuing task.
455 [64]This question about the next libstdc++ prompted some brief but
456 interesting [65]speculation.
457 _________________________________________________________________
459 5.3 What about the STL from SGI?
461 The [66]STL from SGI is merged into libstdc++-v3 with changes as
462 necessary. Currently release 3.3 is being used. Changes in the STL
463 usually produce some weird bugs and lots of changes in the rest of the
464 libstd++ source as we scramble to keep up. :-)
466 In particular, string is not from SGI and makes no use of their "rope"
467 class (which is included as an optional extension), nor is valarray
468 and some others. Classes like vector<> are, however.
470 The FAQ for SGI's STL (one jump off of their main page) is recommended
472 _________________________________________________________________
474 5.4 Extensions and Backward Compatibility
476 Although you can specify -I options to make the preprocessor search
477 the g++-v3/ext and /backward directories, it is better to refer to
478 files there by their path, as in:
479 #include <ext/hash_map>
482 Extensions to the library have [67]their own page.
483 _________________________________________________________________
485 5.5 Compiling with "-fnew-abi"
487 Towards the end of July 1999, this subject was brought up again on the
488 mailing list under a different name. The related [68]thread (by the
489 name HOWTO-honor-std) is very instructive. More info is at the end of
492 This functionality is now automated and turned on by default.
493 _________________________________________________________________
495 5.6 Is libstdc++-v3 thread-safe?
497 Quick answer: no, as of 2.91 (tenth snapshot), the library is not
498 appropriate for multithreaded access. The string class is MT-safe.
500 This is assuming that your idea of "multithreaded" is the same as
501 ours... The general question of multithreading and libstdc++-v3 is
502 addressed in the chapter-specific advice for [69]Library Introduction.
503 Threadsafe containers are covered in more detail in [70]the Received
504 Wisdom section on containers.
505 _________________________________________________________________
507 5.7 How do I get a copy of the ISO C++ Standard?
509 Copies of the full ISO 14882 standard are available on line via the
510 ISO mirror site for committee members. Non-members, or those who have
511 not paid for the privilege of sitting on the committee and sustained
512 their two-meeting commitment for voting rights, may get a copy of the
513 standard from their respective national standards organization. In the
514 USA, this national standards organization is ANSI and their website is
515 right [71]here. (And if you've already registered with them, clicking
516 this link will take you to directly to the place where you can [72]buy
517 the standard on-line.
519 Who is your country's member body? Visit the [73]ISO homepage and find
521 _________________________________________________________________
523 Comments and suggestions are welcome, and may be sent to [74]Phil
524 Edwards or [75]Gabriel Dos Reis.
525 $Id: index.html,v 1.10 2000/12/03 23:47:49 jsm28 Exp $
529 1. http://gcc.gnu.org/onlinedocs/libstdc++/faq/
530 2. http://gcc.gnu.org/libstdc++/
531 3. ../faq/index.html#1_0
532 4. ../faq/index.html#1_1
533 5. ../faq/index.html#1_2
534 6. ../faq/index.html#1_3
535 7. ../faq/index.html#1_4
536 8. ../faq/index.html#1_5
537 9. ../faq/index.html#1_6
538 10. ../faq/index.html#1_7
539 11. ../faq/index.html#1_8
540 12. ../faq/index.html#2_0
541 13. ../faq/index.html#2_1
542 14. ../faq/index.html#2_2
543 15. ../faq/index.html#2_3
544 16. ../faq/index.html#2_4
545 17. ../faq/index.html#3_0
546 18. ../faq/index.html#3_1
547 19. ../faq/index.html#3_2
548 20. ../faq/index.html#4_0
549 21. ../faq/index.html#4_1
550 22. ../faq/index.html#4_2
551 23. ../faq/index.html#4_3
552 24. ../faq/index.html#4_4
553 25. ../faq/index.html#4_4_interface
554 26. ../faq/index.html#4_5
555 27. ../faq/index.html#5_0
556 28. ../faq/index.html#5_1
557 29. ../faq/index.html#5_2
558 30. ../faq/index.html#5_3
559 31. ../faq/index.html#5_4
560 32. ../faq/index.html#5_5
561 33. ../faq/index.html#5_6
562 34. ../faq/index.html#5_7
563 35. ftp://gcc.gnu.org/pub/libstdc++/libstdc++-2.91.tar.gz
564 36. ../17_intro/DESIGN
565 37. http://gcc.gnu.org/
566 38. http://gcc.gnu.org/gcc-2.95/buildstat.html
567 39. http://gcc.gnu.org/libstdc++/
568 40. ftp://gcc.gnu.org/pub/libstdc++/libstdc++-2.91.tar.gz
569 41. http://gcc.gnu.org/libstdc++/
570 42. ../17_intro/contribute.html
571 43. http://www.boost.org/
572 44. http://gcc.gnu.org/fom_serv/cache/33.html
573 45. mailto:libstdc++@gcc.gnu.org
574 46. mailto:pme@sources.redhat.com
575 47. mailto:gdr@gcc.gnu.org
576 48. http://sources.redhat.com/autoconf/
577 49. http://sources.redhat.com/automake/
578 50. ../documentation.html
579 51. ../17_intro/RELEASE-NOTES
580 52. http://www.gnu.org/software/cvs/cvs.html
581 53. http://www.cyclic.com/
583 55. http://www.xraylith.wisc.edu/~khan/software/gnu-win32/libstdc++-v3.html
584 56. http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html
585 57. http://www.cantrip.org/draft-bugs.txt
586 58. http://anubis.dkuug.dk/jtc1/sc22/wg21/
587 59. http://gcc.gnu.org/gnatswrite.html
588 60. http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html
589 61. http://gcc.gnu.org/contribute.html
590 62. ../17_intro/contribute.html
591 63. ../faq/index.html#2_4
592 64. http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html
593 65. http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html
594 66. http://www.sgi.com/Technology/STL/
595 67. ../ext/howto.html
596 68. http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00066.html
597 69. http://gcc.gnu.org/libstdc++/17_intro/howto.html#3
598 70. http://gcc.gnu.org/libstdc++/23_containers/howto.html
599 71. http://www.ansi.org/
600 72. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998
601 73. http://www.iso.ch/
602 74. mailto:pme@sources.redhat.com
603 75. mailto:gdr@gcc.gnu.org