OSDN Git Service

2003-03-12 Jonathan Wakely <redi@gcc.gnu.org>
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / docs / html / faq / index.txt
1
2                      libstdc++ Frequently Asked Questions
3
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.
8
9    To the [3]libstdc++-v3 homepage.
10      _________________________________________________________________
11
12                                    Questions
13
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?
24     2. [14]Installation
25          1. [15]How do I install libstdc++-v3?
26          2. [16][removed]
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>?
32          2. [22][removed]
33          3. [23][removed]
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          7. [27]Threading is broken on i386
38          8. [28]Recent GNU/Linux glibc required?
39          9. [29]Can't use wchar_t/wstring on FreeBSD
40     4. [30]Known Bugs and Non-Bugs
41          1. [31]What works already?
42          2. [32]Bugs in gcc/g++ (not libstdc++-v3)
43          3. [33]Bugs in the C++ language/lib specification
44          4. [34]Things in libstdc++ that only look like bugs
45                o [35]reopening a stream fails
46                o [36]-Weffc++ complains too much
47                o [37]"ambiguous overloads" after including an old-style
48                  header
49                o [38]The g++-3 headers are not ours
50                o [39]compilation errors from streambuf.h
51                o [40]errors about *Concept and constraints in the STL...
52                o [41]program crashes when using library code in a
53                  dynamically-loaded library
54                o [42]"memory leaks" in containers
55          5. [43]Aw, that's easy to fix!
56     5. [44]Miscellaneous
57          1. [45]string::iterator is not char*; vector<T>::iterator is not
58             T*
59          2. [46]What's next after libstdc++-v3?
60          3. [47]What about the STL from SGI?
61          4. [48]Extensions and Backward Compatibility
62          5. [49][removed]
63          6. [50]Is libstdc++-v3 thread-safe?
64          7. [51]How do I get a copy of the ISO C++ Standard?
65          8. [52]What's an ABI and why is it so messy?
66      _________________________________________________________________
67
68                             1.0 General Information
69
70 1.1 What is libstdc++-v3?
71
72    The GNU Standard C++ Library v3 is an ongoing project to implement the
73    ISO 14882 Standard C++ library as described in chapters 17 through 27
74    and annex D. As the library reaches stable plateaus, it is captured in
75    a snapshot and released. The latest release is [53]the fourteenth
76    snapshot but newer versions have been included in recent GCC releases.
77    For those who want to see exactly how far the project has come, or
78    just want the latest bleeding-edge code, the up-to-date source is
79    available over anonymous CVS, and can even be browsed over the Web
80    (see [54]1.4 below).
81
82    The older libstdc++-v2 project is no longer maintained; the code has
83    been completely replaced and rewritten. [55]If you are using V2, then
84    you need to report bugs to your system vendor, not to the V3 list.
85
86    A more formal description of the V3 goals can be found in the official
87    [56]design document.
88      _________________________________________________________________
89
90 1.2 Why should I use libstdc++?
91
92    The completion of the ISO C++ standardization gave the C++ community a
93    powerful set of reuseable tools in the form of the C++ Standard
94    Library. However, all existing C++ implementations are (as the Draft
95    Standard used to say) "incomplet and incorrekt," and many suffer from
96    limitations of the compilers that use them.
97
98    The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is
99    widely considered to be one of the leading compilers in the world. Its
100    development has recently been taken over by the [57]GCC team. All of
101    the rapid development and near-legendary [58]portability that are the
102    hallmarks of an open-source project are being applied to libstdc++.
103
104    That means that all of the Standard classes and functions (such as
105    string, vector<>, iostreams, and algorithms) will be freely available
106    and fully compliant. Programmers will no longer need to "roll their
107    own" nor be worried about platform-specific incompatibilities.
108      _________________________________________________________________
109
110 1.3 Who's in charge of it?
111
112    The libstdc++ project is contributed to by several developers all over
113    the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel
114    Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and Paolo
115    Carlini are the lead maintainers of the CVS archive.
116
117    Development and discussion is held on the libstdc++ mailing list.
118    Subscribing to the list, or searching the list archives, is open to
119    everyone. You can read instructions for doing so on the [59]homepage.
120    If you have questions, ideas, code, or are just curious, sign up!
121      _________________________________________________________________
122
123 1.4 How do I get libstdc++?
124
125    The fourteenth (and latest) snapshot of libstdc++-v3 is [60]available
126    via ftp.
127
128    The [61]homepage has instructions for retrieving the latest CVS
129    sources, and for browsing the CVS sources over the web.
130
131    The subset commonly known as the Standard Template Library (chapters
132    23 through 25, mostly) is adapted from the final release of the SGI
133    STL.
134      _________________________________________________________________
135
136 1.5 When is libstdc++ going to be finished?
137
138    Nathan Myers gave the best of all possible answers, responding to a
139    Usenet article asking this question: Sooner, if you help.
140      _________________________________________________________________
141
142 1.6 How do I contribute to the effort?
143
144    Here is [62]a page devoted to this topic. Subscribing to the mailing
145    list (see above, or the homepage) is a very good idea if you have
146    something to contribute, or if you have spare time and want to help.
147    Contributions don't have to be in the form of source code; anybody who
148    is willing to help write documentation, for example, or has found a
149    bug in code that we all thought was working, is more than welcome!
150      _________________________________________________________________
151
152 1.7 What happened to libg++? I need that!
153
154    The most recent libg++ README states that libg++ is no longer being
155    actively maintained. It should not be used for new projects, and is
156    only being kicked along to support older code.
157
158    The libg++ was designed and created when there was no Standard to
159    provide guidance. Classes like linked lists are now provided for by
160    list<T> and do not need to be created by genclass. (For that matter,
161    templates exist now and are well-supported, whereas genclass (mostly)
162    predates them.)
163
164    There are other classes in libg++ that are not specified in the ISO
165    Standard (e.g., statistical analysis). While there are a lot of really
166    useful things that are used by a lot of people (e.g., statistics :-),
167    the Standards Committee couldn't include everything, and so a lot of
168    those "obvious" classes didn't get included.
169
170    Since libstdc++ is an implementation of the Standard Library, we have
171    no plans at this time to include non-Standard utilities in the
172    implementation, however handy they are. (The extensions provided in
173    the SGI STL aren't maintained by us and don't get a lot of our
174    attention, because they don't require a lot of our time.) It is
175    entirely plausable that the "useful stuff" from libg++ might be
176    extracted into an updated utilities library, but nobody has stated
177    such a project yet.
178
179    (The [63]Boost site houses free C++ libraries that do varying things,
180    and happened to be started by members of the Standards Committee.
181    Certain "useful stuff" classes will probably migrate there.)
182
183    For the bold and/or desperate, the [64]GCC extensions page describes
184    where to find the last libg++ source.
185      _________________________________________________________________
186
187 1.8 What if I have more questions?
188
189    If you have read the README and RELEASE-NOTES files, and your question
190    remains unanswered, then just ask the mailing list. At present, you do
191    not need to be subscribed to the list to send a message to it. More
192    information is available on the homepage (including how to browse the
193    list archives); to send to the list, use [65]libstdc++@gcc.gnu.org.
194
195    If you have a question that you think should be included here, or if
196    you have a question about a question/answer here, contact [66]Phil
197    Edwards or [67]Gabriel Dos Reis.
198      _________________________________________________________________
199
200 1.9 What are the license terms for libstdc++-v3?
201
202    See [68]our license description for these and related questions.
203      _________________________________________________________________
204
205                                2.0 Installation
206
207 2.1 How do I install libstdc++-v3?
208
209    Complete instructions are not given here (this is a FAQ, not an
210    installation document), but the tools required are few:
211      * A 3.x release of GCC. Note that building GCC is much easier and
212        more automated than building the GCC 2.[78] series was. If you are
213        using GCC 2.95, you can still build earlier snapshots of
214        libstdc++.
215      * GNU Make is recommended, but should not be required.
216      * The GNU Autotools are needed if you are messing with the configury
217        or makefiles.
218
219    The file [69]documentation.html provides a good overview of the steps
220    necessary to build, install, and use the library. Instructions for
221    configuring the library with new flags such as --enable-threads are
222    there also, as well as patches and instructions for working with GCC
223    2.95.
224
225    The top-level install.html and [70]RELEASE-NOTES files contain the
226    exact build and installation instructions. You may wish to browse
227    those files over CVSweb ahead of time to get a feel for what's
228    required. RELEASE-NOTES is located in the ".../docs/17_intro/"
229    directory of the distribution.
230      _________________________________________________________________
231
232 2.2 [removed]
233
234    This question has become moot and has been removed. The stub is here
235    to preserve numbering (and hence links/bookmarks).
236      _________________________________________________________________
237
238 2.3 What is this CVS thing that you keep mentioning?
239
240    The Concurrent Versions System is one of several revision control
241    packages. It was selected for GNU projects because it's free (speech),
242    free (beer), and very high quality. The [71]CVS entry in the GNU
243    software catalogue has a better description as well as a [72]link to
244    the makers of CVS.
245
246    The "anonymous client checkout" feature of CVS is similar to anonymous
247    FTP in that it allows anyone to retrieve the latest libstdc++ sources.
248
249    After the first of April, American users will have a "/pharmacy"
250    command-line option...
251      _________________________________________________________________
252
253 2.4 How do I know if it works?
254
255    libstdc++-v3 comes with its own testsuite. You do not need to actually
256    install the library ("make install") to run the testsuite.
257
258    To run the testsuite on the library after building it, use "make
259    check" while in your build directory. To run the testsuite on the
260    library after building and installing it, use "make check-install"
261    instead.
262
263    If you find bugs in the testsuite programs themselves, or if you think
264    of a new test program that should be added to the suite, please write
265    up your idea and send it to the list!
266      _________________________________________________________________
267
268 2.4 This library is HUGE! And what's libsupc++?
269
270    Usually the size of libraries on disk isn't noticeable. When a link
271    editor (or simply "linker") pulls things from a static archive
272    library, only the necessary object files are copied into your
273    executable, not the entire library. Unfortunately, even if you only
274    need a single function or variable from an object file, the entire
275    object file is extracted. (There's nothing unique to C++ or
276    libstdc++-v3 about this; it's just common behavior, given here for
277    background reasons.)
278
279    Some of the object files which make up libstdc++.a are rather large.
280    If you create a statically-linked executable with -static, those large
281    object files are suddenly part of your executable. Historically the
282    best way around this was to only place a very few functions (often
283    only a single one) in each source/object file; then extracting a
284    single function is the same as extracting a single .o file. For
285    libstdc++-v3 this is only possible to a certain extent; the object
286    files in question contain template classes and template functions,
287    pre-instantiated, and splitting those up causes severe maintenance
288    headaches.
289
290    It's not a bug, and it's not really a problem. Nevertheless, some
291    people don't like it, so here are two pseudo-solutions:
292
293    If the only functions from libstdc++.a which you need are language
294    support functions (those listed in [73]clause 18 of the standard,
295    e.g., new and delete), then try linking against libsupc++.a (usually
296    specifying -lsupc++ when calling g++ for the final link step will do
297    it). This library contains only those support routines, one per object
298    file. But if you are using anything from the rest of the library, such
299    as IOStreams or vectors, then you'll still need pieces from
300    libstdc++.a.
301
302    The second method is one we hope to incorporate into the library build
303    process. Some platforms can place each function and variable into its
304    own section in a .o file. The GNU linker can then perform garbage
305    collection on unused sections; this reduces the situation to only
306    copying needed functions into the executable, as before, but all
307    happens automatically.
308
309    Unfortunately the garbage collection in GNU ld is buggy; sections
310    (corresponding to functions and variables) which are used are
311    mistakenly removed, leading to horrible crashes when your executable
312    starts up. For the time being, this feature is not used when building
313    the library.
314      _________________________________________________________________
315
316                          3.0 Platform-Specific Issues
317
318 3.1 Can libstdc++-v3 be used with <my favorite compiler>?
319
320    Probably not. Yet.
321
322    Because GCC advances so rapidly, development and testing of libstdc++
323    is being done almost entirely under that compiler. If you are curious
324    about whether other, lesser compilers (*grin*) support libstdc++, you
325    are more than welcome to try. Configuring and building the library
326    (see above) will still require certain tools, however. Also keep in
327    mind that building libstdc++ does not imply that your compiler will be
328    able to use all of the features found in the C++ Standard Library.
329
330    Since the goal of ISO Standardization is for all C++ implementations
331    to be able to share code, the final libstdc++ should, in theory, be
332    usable under any ISO-compliant compiler. It will still be targeted and
333    optimized for GCC/g++, however.
334      _________________________________________________________________
335
336 3.2 [removed]
337
338    This question has become moot and has been removed. The stub is here
339    to preserve numbering (and hence links/bookmarks).
340      _________________________________________________________________
341
342 3.3 [removed]
343
344    This question has become moot and has been removed. The stub is here
345    to preserve numbering (and hence links/bookmarks).
346      _________________________________________________________________
347
348 3.4 I can't use 'long long' on Solaris
349
350    By default we try to support the C99 long long type. This requires
351    that certain functions from your C library be present.
352
353    Up through release 3.0.2 the tests performed were too general, and
354    this feature was disabled when it did not need to be. The most
355    commonly reported platform affected was Solaris.
356
357    This has been fixed for 3.0.3 and onwards.
358      _________________________________________________________________
359
360 3.5 _XOPEN_SOURCE / _GNU_SOURCE / etc is always defined
361
362    On Solaris, g++ (but not gcc) always defines the preprocessor macro
363    _XOPEN_SOURCE. On GNU/Linux, the same happens with _GNU_SOURCE. (This
364    is not an exhaustive list; other macros and other platforms are also
365    affected.)
366
367    These macros are typically used in C library headers, guarding new
368    versions of functions from their older versions. The C++ standard
369    library includes the C standard library, but it requires the C90
370    version, which for backwards-compatability reasons is often not the
371    default for many vendors.
372
373    More to the point, the C++ standard requires behavior which is only
374    available on certain platforms after certain symbols are defined.
375    Usually the issue involves I/O-related typedefs. In order to ensure
376    correctness, the compiler simply predefines those symbols.
377
378    Note that it's not enough to #define them only when the library is
379    being built (during installation). Since we don't have an 'export'
380    keyword, much of the library exists as headers, which means that the
381    symbols must also be defined as your programs are parsed and compiled.
382
383    To see which symbols are defined, look for CPLUSPLUS_CPP_SPEC in the
384    gcc config headers for your target (and try changing them to see what
385    happens when building complicated code). You can also run "g++ -E -dM
386    - < /dev/null" to display a list of predefined macros for any
387    particular installation.
388
389    This has been discussed on the mailing lists [74]quite a bit.
390
391    This method is something of a wart. We'd like to find a cleaner
392    solution, but nobody yet has contributed the time.
393      _________________________________________________________________
394
395 3.6 OS X ctype.h is broken! How can I hack it?
396
397    This is a long-standing bug in the OS X support. Fortunately, the
398    patch is quite simple, and well-known. [75]Here's a link to the
399    solution.
400      _________________________________________________________________
401
402 3.7 Threading is broken on i386
403
404    Support for atomic integer operations is/was broken on i386 platforms.
405    The assembly code accidentally used opcodes that are only available on
406    the i486 and later. So if you configured GCC to target, for example,
407    i386-linux, but actually used the programs on an i686, then you would
408    encounter no problems. Only when actually running the code on a i386
409    will the problem appear.
410
411    This is fixed in 3.2.2.
412      _________________________________________________________________
413
414 3.8 Recent GNU/Linux glibc required?
415
416    For 3.2.1 (shared library version 5.0.1) and later, the library uses
417    localization and formatting code from the system C library (glibc)
418    version 2.2.5. That version of glibc is over a year old and contains
419    necessary bugfixes. Many GNU/Linux distros make glibc version 2.3.x
420    available now.
421
422    The guideline is simple: the more recent the C++ library, the more
423    recent the C library. (This is also documented in the main GCC
424    installation instructions.)
425      _________________________________________________________________
426
427 3.9 Can't use wchar_t/wstring on FreeBSD
428
429    At the moment there are a few problems in FreeBSD's support for wide
430    character functions, and as a result the libstdc++ configury decides
431    that wchar_t support should be disabled. Once the underlying problems
432    are fixed in FreeBSD (soon), the library support will automatically
433    enable itself.
434
435    You can fix the problems yourself, and learn more about the situation,
436    by reading [76]this short thread ("_GLIBCPP_USE_WCHAR_T undefined in
437    FreeBSD's c++config.h?").
438      _________________________________________________________________
439
440                           4.0 Known Bugs and Non-Bugs
441
442    Note that this section can get rapdily outdated -- such is the nature
443    of an open-source project. For the latest information, join the
444    mailing list or look through recent archives. The RELEASE- NOTES and
445    BUGS files are generally kept up-to-date.
446
447    For 3.0.1, the most common "bug" is an apparently missing "../" in
448    include/Makefile, resulting in files like gthr.h and gthr-single.h not
449    being found. Please read [77]the configuration instructions for GCC,
450    specifically the part about configuring in a separate build directory,
451    and how strongly recommended it is. Building in the source directory
452    is fragile, is rarely tested, and tends to break, as in this case.
453    This was fixed for 3.0.2.
454
455    For 3.1, the most common "bug" is a parse error when using <fstream>,
456    ending with a message, "bits/basic_file.h:52: parse error before `{'
457    token." Please read [78]the installation instructions for GCC,
458    specifically the part about not installing newer versions on top of
459    older versions. If you install 3.1 over a 3.0.x release, then the
460    wrong basic_file.h header will be found (its location changed between
461    releases).
462
463    Please do not report these as bugs. We know about them. Reporting this
464    -- or any other problem that's already been fixed -- hinders the
465    development of GCC, because we have to take time to respond to your
466    report. Thank you.
467
468 4.1 What works already?
469
470    This is a verbatim clip from the "Status" section of the RELEASE-NOTES
471    for the latest snapshot. For a list of fixed bugs, see that file.
472 New:
473 ---
474 (post 3.0.97)
475 - more doxygen documentation
476 - more named locale fixups
477 - stdio_filebuf that takes fd, FILE
478 - io performance tuning
479 - allocation tuning, valgrind fixups
480 - __cxa_demangle now supported
481 (3.0.97)
482 - more doxygen documentation.
483 - more named locale bug fixes
484 - support for symbol versioning when using GNU ld >= 2.12
485 - wide-io
486 - tuning for executable size
487 (3.0.96)
488 - more doxygen documentation.
489 - extensions moved out of namespace std
490 - HPUX long long support
491 - more string optimizations
492 - support for NetBSD cross compiles
493 - concept_check merge from boost
494 - header simplification
495 - named locale bug shakeout
496 - thread testsuite
497 (3.0.95)
498 - add S390, m68k, x86-64 support.
499 - doxygen documentation has been extended, including man pages.
500 - verbose terminate handling has been added.
501 - some libsupc++ tweaks
502 - warnings for deprecated headers now active.
503 - dejagnu testsuite preliminary documentation.
504 - dejagnu testsuite default.
505 - dejagnu testsuite cross compiler, multilib safe.
506 - long long iostreams on by default, rework of ISO C99 support.
507 - iterator re-write and testsuites.
508 - container testsuites.
509 - allocator revamp and testsuites.
510 - more concept-checking work.
511 - basic_string optimization and MT fixes.
512 - new limits implementation.
513 - update -fno-exceptions code, verify it works.
514 - full named locale support fpr all facets, choice of gnu,
515   ieee_1003.1-200x (POSIX 2), or generic models. Full support depends
516   on target OS and underlying "C" library support.
517      _________________________________________________________________
518
519 4.2 Bugs in gcc/g++ (not libstdc++-v3)
520
521    This is by no means meant to be complete nor exhaustive, but mentions
522    some problems that users may encounter when building or using
523    libstdc++. If you are experiencing one of these problems, you can find
524    more information on the libstdc++ and the GCC mailing lists.
525
526    Before reporting a bug, examine the [79]bugs database with the
527    category set to "libstdc++". The BUGS file in the source tree also
528    tracks known serious problems.
529      * Debugging is problematic, due to bugs in line-number generation
530        (mostly fixed in the compiler) and gdb lagging behind the compiler
531        (lack of personnel). We recommend configuring the compiler using
532        --with-dwarf2 if the DWARF2 debugging format is not already the
533        default on your platform. Also, [80]changing your GDB settings can
534        have a profound effect on your C++ debugging experiences. :-)
535      _________________________________________________________________
536
537 4.3 Bugs in the C++ language/lib specification
538
539    Yes, unfortunately, there are some. In a [81]message to the list,
540    Nathan Myers announced that he has started a list of problems in the
541    ISO C++ Standard itself, especially with regard to the chapters that
542    concern the library. The list itself is [82]posted on his website.
543    Developers who are having problems interpreting the Standard may wish
544    to consult his notes.
545
546    For those people who are not part of the ISO Library Group (i.e.,
547    nearly all of us needing to read this page in the first place :-), a
548    public list of the library defects is occasionally published [83]here.
549    Some of these have resulted in [84]code changes.
550      _________________________________________________________________
551
552 4.4 Things in libstdc++ that only look like bugs
553
554    There are things which are not bugs in the compiler (4.2) nor the
555    language specification (4.3), but aren't really bugs in libstdc++,
556    either. Really! Please do not report these as bugs.
557
558    -Weffc++ The biggest of these is the quadzillions of warnings about
559    the library headers emitted when -Weffc++ is used. Making libstdc++
560    "-Weffc++-clean" is not a goal of the project, for a few reasons.
561    Mainly, that option tries to enforce object-oriented programming,
562    while the Standard Library isn't necessarily trying to be OO.
563
564    reopening a stream fails Did I just say that -Weffc++ was our biggest
565    false-bug report? I lied. (It used to be.) Today it seems to be
566    reports that after executing a sequence like
567     #include <fstream>
568     ...
569     std::fstream  fs("a_file");
570     // .
571     // . do things with fs...
572     // .
573     fs.close();
574     fs.open("a_new_file");
575
576    all operations on the re-opened fs will fail, or at least act very
577    strangely. Yes, they often will, especially if fs reached the EOF
578    state on the previous file. The reason is that the state flags are not
579    cleared on a successful call to open(). The standard unfortunately did
580    not specify behavior in this case, and to everybody's great sorrow,
581    the [85]proposed LWG resolution (see DR #22) is to leave the flags
582    unchanged. You must insert a call to fs.clear() between the calls to
583    close() and open(), and then everything will work like we all expect
584    it to work.
585
586    rel_ops Another is the rel_ops namespace and the template comparison
587    operator functions contained therein. If they become visible in the
588    same namespace as other comparison functions (e.g., 'using' them and
589    the <iterator> header), then you will suddenly be faced with huge
590    numbers of ambiguity errors. This was discussed on the -v3 list;
591    Nathan Myers [86]sums things up here. The collisions with
592    vector/string iterator types have been fixed for 3.1.
593
594   The g++-3 headers are not ours
595
596    If you have found an extremely broken header file which is causing
597    problems for you, look carefully before submitting a "high" priority
598    bug report (which you probably shouldn't do anyhow; see the last
599    paragraph of the page describing [87]the GCC bug database).
600
601    If the headers are in ${prefix}/include/g++-3, or if the installed
602    library's name looks like libstdc++-2.10.a or libstdc++-libc6-2.10.so,
603    then you are using the old libstdc++-v2 library, which is nonstandard
604    and unmaintained. Do not report problems with -v2 to the -v3 mailing
605    list.
606
607    For GCC versions 3.0 and 3.1 the libstdc++-v3 header files are
608    installed in ${prefix}/include/g++-v3 (see the 'v'?). Starting with
609    version 3.2 the headers are installed in
610    ${prefix}/include/c++/${version} as this prevents headers from
611    previous versions being found by mistake.
612
613    glibc If you're on a GNU/Linux system and have just upgraded to glibc
614    2.2, but are still using gcc 2.95.2, then you should have read the
615    glibc FAQ, specifically 2.34:
616 2.34.   When compiling C++ programs, I get a compilation error in streambuf.h.
617
618 {BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to
619 apply a patch to the include files in /usr/include/g++, because the fpos_t
620 type has changed in glibc 2.2.  The patch is at
621 http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
622
623
624    Note that 2.95.x shipped with the [88]old v2 library which is no
625    longer maintained. Also note that gcc 2.95.3 fixes this problem, but
626    requires a separate patch for libstdc++-v3.
627
628    concept checks If you see compilation errors containing messages about
629    fooConcept and a constraints member function, then most likely you
630    have violated one of the requirements for types used during
631    instantiation of template containers and functions. For example,
632    EqualityComparableConcept appears if your types must be comparable
633    with == and you have not provided this capability (a typo, or wrong
634    visibility, or you just plain forgot, etc).
635
636    More information, including how to optionally enable/disable the
637    checks, is available [89]here.
638
639    dlopen/dlsym If you are using the C++ library across
640    dynamically-loaded objects, make certain that you are passing the
641    correct options when compiling and linking:
642     // compile the library components
643     g++ -fPIC -c a.cc
644     g++ -fPIC -c b.cc
645     ...
646     g++ -fPIC -c z.cc
647
648     // create the library
649     g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o
650
651     // link the executable
652     g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl
653
654    "memory leaks" in containers A few people have reported that the
655    standard containers appear to leak memory when tested with memory
656    checkers such as [90]valgrind. The library's default allocators keep
657    free memory in a pool for later reuse, rather than returning it to the
658    OS. Although this memory is always reachable by the library and is
659    never lost, memory debugging tools can report it as a leak. If you
660    want to test the library for memory leaks please read [91]Tips for
661    memory leak hunting first.
662      _________________________________________________________________
663
664 4.5 Aw, that's easy to fix!
665
666    If you have found a bug in the library and you think you have a
667    working fix, then send it in! The main GCC site has a page on
668    [92]submitting patches that covers the procedure, but for libstdc++
669    you should also send the patch to our mailing list in addition to the
670    GCC patches mailing list. The libstdc++ [93]contributors' page also
671    talks about how to submit patches.
672
673    In addition to the description, the patch, and the ChangeLog entry, it
674    is a Good Thing if you can additionally create a small test program to
675    test for the presence of the bug that your patch fixes. Bugs have a
676    way of being reintroduced; if an old bug creeps back in, it will be
677    caught immediately by the [94]testsuite -- but only if such a test
678    exists.
679      _________________________________________________________________
680
681                                5.0 Miscellaneous
682
683 5.1 string::iterator is not char*; vector<T>::iterator is not T*
684
685    If you have code that depends on container<T> iterators being
686    implemented as pointer-to-T, your code is broken.
687
688    While there are arguments for iterators to be implemented in that
689    manner, A) they aren't very good ones in the long term, and B) they
690    were never guaranteed by the Standard anyway. The type-safety achieved
691    by making iterators a real class rather than a typedef for T*
692    outweighs nearly all opposing arguments.
693
694    Code which does assume that a vector iterator i is a pointer can often
695    be fixed by changing i in certain expressions to &*i . Future
696    revisions of the Standard are expected to bless this usage for
697    vector<> (but not for basic_string<>).
698      _________________________________________________________________
699
700 5.2 What's next after libstdc++-v3?
701
702    Hopefully, not much. The goal of libstdc++-v3 is to produce a
703    fully-compliant, fully-portable Standard Library. After that, we're
704    mostly done: there won't be any more compliance work to do. However:
705     1. The ISO Committee will meet periodically to review Defect Reports
706        in the C++ Standard. Undoubtedly some of these will result in
707        changes to the Standard, which will be reflected in patches to
708        libstdc++. Some of that is already happening, see 4.2. Some of
709        those changes are being predicted by the library maintainers, and
710        we add code to the library based on what the current proposed
711        resolution specifies. Those additions are listed in [95]the
712        extensions page.
713     2. Performance tuning. Lots of performance tuning. This too is
714        already underway for post-3.0 releases, starting with memory
715        expansion in container classes and buffer usage in synchronized
716        stream objects.
717     3. An ABI for libstdc++ is being developed, so that multiple
718        binary-incompatible copies of the library can be replaced with a
719        single backwards-compatible library, like libgcc_s.so is.
720     4. The current libstdc++ contains extensions to the Library which
721        must be explicitly requested by client code (for example, the hash
722        tables from SGI). Other extensions may be added to libstdc++-v3 if
723        they seem to be "standard" enough. (For example, the "long long"
724        type from C99.) Bugfixes and rewrites (to improve or fix thread
725        safety, for instance) will of course be a continuing task.
726
727    [96]This question about the next libstdc++ prompted some brief but
728    interesting [97]speculation.
729      _________________________________________________________________
730
731 5.3 What about the STL from SGI?
732
733    The [98]STL from SGI, version 3.3, was the most recent merge of the
734    STL codebase. The code in libstdc++ contains many fixes and changes,
735    and it is very likely that the SGI code is no longer under active
736    development. We expect that no future merges will take place.
737
738    In particular, string is not from SGI and makes no use of their "rope"
739    class (which is included as an optional extension), nor is valarray
740    and some others. Classes like vector<> are, however.
741
742    The FAQ for SGI's STL (one jump off of their main page) is recommended
743    reading.
744      _________________________________________________________________
745
746 5.4 Extensions and Backward Compatibility
747
748    Headers in the ext and backward subdirectories should be referred to
749    by their relative paths:
750       #include <ext/hash_map>
751
752    rather than using -I or other options. This is more portable and
753    forward-compatible. (The situation is the same as that of other
754    headers whose directories are not searched directly, e.g.,
755    <sys/stat.h>, <X11/Xlib.h>.
756
757    The extensions are no longer in the global or std namespaces, instead
758    they are declared in the __gnu_cxx namespace. For maximum portability,
759    consider defining a namespace alias to use to talk about extensions,
760    e.g.:
761       #ifdef __GNUC__
762       #if __GNUC__ < 3
763         #include <hash_map.h>
764         namespace Sgi { using ::hash_map; }; // inherit globals
765       #else
766         #include <ext/hash_map>
767         #if __GNUC_MINOR__ == 0
768           namespace Sgi = std;               // GCC 3.0
769         #else
770           namespace Sgi = ::__gnu_cxx;       // GCC 3.1 and later
771         #endif
772       #endif
773       #else      // ...  there are other compilers, right?
774         namespace Sgi = std;
775       #endif
776
777       Sgi::hash_map<int,int> my_map;
778
779    This is a bit cleaner than defining typedefs for all the
780    instantiations you might need.
781
782    Extensions to the library have [99]their own page.
783      _________________________________________________________________
784
785 5.5 [removed]
786
787    This question has become moot and has been removed. The stub is here
788    to preserve numbering (and hence links/bookmarks).
789      _________________________________________________________________
790
791 5.6 Is libstdc++-v3 thread-safe?
792
793    When the system's libc is itself thread-safe, a non-generic
794    implementation of atomicity.h exists for the architecture, and gcc
795    itself reports a thread model other than single; libstdc++-v3 strives
796    to be thread-safe. The user-code must guard against concurrent method
797    calls which may access any particular library object's state.
798    Typically, the application programmer may infer what object locks must
799    be held based on the objects referenced in a method call. Without
800    getting into great detail, here is an example which requires
801    user-level locks:
802      library_class_a shared_object_a;
803
804      thread_main () {
805        library_class_b *object_b = new library_class_b;
806        shared_object_a.add_b (object_b);   // must hold lock for shared_object_
807 a
808        shared_object_a.mutate ();          // must hold lock for shared_object_
809 a
810      }
811
812      // Multiple copies of thread_main() are started in independent threads.
813
814    Under the assumption that object_a and object_b are never exposed to
815    another thread, here is an example that should not require any
816    user-level locks:
817      thread_main () {
818        library_class_a object_a;
819        library_class_b *object_b = new library_class_b;
820        object_a.add_b (object_b);
821        object_a.mutate ();
822      }
823
824    All library objects are safe to use in a multithreaded program as long
825    as each thread carefully locks out access by any other thread while it
826    uses any object visible to another thread. In general, this
827    requirement includes both read and write access to objects; unless
828    otherwise documented as safe, do not assume that two threads may
829    access a shared standard library object at the same time.
830
831    See chapters [100]17 (library introduction), [101]23 (containers), and
832    [102]27 (I/O) for more information.
833      _________________________________________________________________
834
835 5.7 How do I get a copy of the ISO C++ Standard?
836
837    Copies of the full ISO 14882 standard are available on line via the
838    ISO mirror site for committee members. Non-members, or those who have
839    not paid for the privilege of sitting on the committee and sustained
840    their two-meeting commitment for voting rights, may get a copy of the
841    standard from their respective national standards organization. In the
842    USA, this national standards organization is ANSI and their website is
843    right [103]here. (And if you've already registered with them, clicking
844    this link will take you to directly to the place where you can
845    [104]buy the standard on-line.
846
847    Who is your country's member body? Visit the [105]ISO homepage and
848    find out!
849      _________________________________________________________________
850
851 5.8 What's an ABI and why is it so messy?
852
853    "ABI" stands for "Application Binary Interface." Conventionally, it
854    refers to a great mass of details about how arguments are arranged on
855    the call stack and/or in registers, and how various types are arranged
856    and padded in structs. A single CPU design may suffer multiple ABIs
857    designed by different development tool vendors who made different
858    choices, or even by the same vendor for different target applications
859    or compiler versions. In ideal circumstances the CPU designer presents
860    one ABI and all the OSes and compilers use it. In practice every ABI
861    omits details that compiler implementers (consciously or accidentally)
862    must choose for themselves.
863
864    That ABI definition suffices for compilers to generate code so a
865    program can interact safely with an OS and its lowest-level libraries.
866    Users usually want an ABI to encompass more detail, allowing libraries
867    built with different compilers (or different releases of the same
868    compiler!) to be linked together. For C++, this includes many more
869    details than for C, and CPU designers (for good reasons elaborated
870    below) have not stepped up to publish C++ ABIs. The details include
871    virtual function implementation, struct inheritance layout, name
872    mangling, and exception handling. Such an ABI has been defined for GNU
873    C++, and is immediately useful for embedded work relying only on a
874    "free-standing implementation" that doesn't include (much of) the
875    standard library. It is a good basis for the work to come.
876
877    A useful C++ ABI must also incorporate many details of the standard
878    library implementation. For a C ABI, the layouts of a few structs
879    (such as FILE, stat, jmpbuf, and the like) and a few macros suffice.
880    For C++, the details include the complete set of names of functions
881    and types used, the offsets of class members and virtual functions,
882    and the actual definitions of all inlines. C++ exposes many more
883    library details to the caller than C does. It makes defining a
884    complete ABI a much bigger undertaking, and requires not just
885    documenting library implementation details, but carefully designing
886    those details so that future bug fixes and optimizations don't force
887    breaking the ABI.
888
889    There are ways to help isolate library implementation details from the
890    ABI, but they trade off against speed. Library details used in inner
891    loops (e.g., getchar) must be exposed and frozen for all time, but
892    many others may reasonably be kept hidden from user code, so they may
893    later be changed. Deciding which, and implementing the decisions, must
894    happen before you can reasonably document a candidate C++ ABI that
895    encompasses the standard library.
896      _________________________________________________________________
897
898    See [106]license.html for copying conditions. Comments and suggestions
899    are welcome, and may be sent to [107]the libstdc++ mailing list. 
900
901 References
902
903    1. http://gcc.gnu.org/onlinedocs/libstdc++/faq/
904    2. http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html
905    3. http://gcc.gnu.org/libstdc++/
906    4. ../faq/index.html#1_0
907    5. ../faq/index.html#1_1
908    6. ../faq/index.html#1_2
909    7. ../faq/index.html#1_3
910    8. ../faq/index.html#1_4
911    9. ../faq/index.html#1_5
912   10. ../faq/index.html#1_6
913   11. ../faq/index.html#1_7
914   12. ../faq/index.html#1_8
915   13. ../faq/index.html#1_9
916   14. ../faq/index.html#2_0
917   15. ../faq/index.html#2_1
918   16. ../faq/index.html#2_2
919   17. ../faq/index.html#2_3
920   18. ../faq/index.html#2_4
921   19. ../faq/index.html#2_5
922   20. ../faq/index.html#3_0
923   21. ../faq/index.html#3_1
924   22. ../faq/index.html#3_2
925   23. ../faq/index.html#3_3
926   24. ../faq/index.html#3_4
927   25. ../faq/index.html#3_5
928   26. ../faq/index.html#3_6
929   27. ../faq/index.html#3_7
930   28. ../faq/index.html#3_8
931   29. ../faq/index.html#3_9
932   30. ../faq/index.html#4_0
933   31. ../faq/index.html#4_1
934   32. ../faq/index.html#4_2
935   33. ../faq/index.html#4_3
936   34. ../faq/index.html#4_4
937   35. ../faq/index.html#4_4_iostreamclear
938   36. ../faq/index.html#4_4_Weff
939   37. ../faq/index.html#4_4_rel_ops
940   38. ../faq/index.html#4_4_interface
941   39. ../faq/index.html#4_4_glibc
942   40. ../faq/index.html#4_4_checks
943   41. ../faq/index.html#4_4_dlsym
944   42. ../faq/index.html#4_4_leak
945   43. ../faq/index.html#4_5
946   44. ../faq/index.html#5_0
947   45. ../faq/index.html#5_1
948   46. ../faq/index.html#5_2
949   47. ../faq/index.html#5_3
950   48. ../faq/index.html#5_4
951   49. ../faq/index.html#5_5
952   50. ../faq/index.html#5_6
953   51. ../faq/index.html#5_7
954   52. ../faq/index.html#5_8
955   53. http://gcc.gnu.org/libstdc++/index.html#download
956   54. ../faq/index.html#1_4
957   55. ../faq/index.html#4_4_interface
958   56. ../17_intro/DESIGN
959   57. http://gcc.gnu.org/
960   58. http://gcc.gnu.org/gcc-3.0/buildstat.html
961   59. http://gcc.gnu.org/libstdc++/
962   60. http://gcc.gnu.org/libstdc++/index.html#download
963   61. http://gcc.gnu.org/libstdc++/
964   62. ../17_intro/contribute.html
965   63. http://www.boost.org/
966   64. http://gcc.gnu.org/extensions.html
967   65. mailto:libstdc++@gcc.gnu.org
968   66. mailto:pme@gcc.gnu.org
969   67. mailto:gdr@gcc.gnu.org
970   68. ../17_intro/license.html
971   69. ../documentation.html
972   70. ../17_intro/RELEASE-NOTES
973   71. http://www.gnu.org/software/cvs/cvs.html
974   72. http://www.cvshome.org/
975   73. ../18_support/howto.html
976   74. http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris
977   75. http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html
978   76. http://gcc.gnu.org/ml/libstdc++/2003-02/subjects.html#00286
979   77. http://gcc.gnu.org/install/configure.html
980   78. http://gcc.gnu.org/install/
981   79. http://gcc.gnu.org/bugs.html
982   80. http://gcc.gnu.org/ml/libstdc++/2002-02/msg00034.html
983   81. http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html
984   82. http://www.cantrip.org/draft-bugs.txt
985   83. http://anubis.dkuug.dk/jtc1/sc22/wg21/
986   84. ../faq/index.html#5_2
987   85. ../ext/howto.html#5
988   86. http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html
989   87. http://gcc.gnu.org/gnatswrite.html
990   88. ../faq/index.html#4_4_interface
991   89. ../19_diagnostics/howto.html#3
992   90. http://developer.kde.org/~sewardj/
993   91. ../debug.html#mem
994   92. http://gcc.gnu.org/contribute.html
995   93. ../17_intro/contribute.html
996   94. ../faq/index.html#2_4
997   95. ../ext/howto.html#5
998   96. http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html
999   97. http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html
1000   98. http://www.sgi.com/Technology/STL/
1001   99. ../ext/howto.html
1002  100. ../17_intro/howto.html#3
1003  101. ../23_containers/howto.html#3
1004  102. ../27_io/howto.html#9
1005  103. http://www.ansi.org/
1006  104. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998
1007  105. http://www.iso.ch/
1008  106. ../17_intro/license.html
1009  107. mailto:libstdc++@gcc.gnu.org