OSDN Git Service

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