OSDN Git Service

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