| |
| #[1]GNU C++ Standard Library [2]Copyright |
| |
| libstdc++ Frequently Asked Questions |
| |
| The latest version of this document is always available at |
| [3]http://gcc.gnu.org/onlinedocs/libstdc++/faq/. The main |
| documentation page is at |
| [4]http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html. |
| |
| To the [5]libstdc++-v3 homepage. |
| _________________________________________________________________ |
| |
| Questions |
| |
| 1. [6]General Information |
| 1. [7]What is libstdc++-v3? |
| 2. [8]Why should I use libstdc++? |
| 3. [9]Who's in charge of it? |
| 4. [10]How do I get libstdc++? |
| 5. [11]When is libstdc++ going to be finished? |
| 6. [12]How do I contribute to the effort? |
| 7. [13]What happened to libg++? I need that! |
| 8. [14]What if I have more questions? |
| 9. [15]What are the license terms for libstdc++-v3? |
| 2. [16]Installation |
| 1. [17]How do I install libstdc++-v3? |
| 2. [18][removed] |
| 3. [19]What is this SVN thing that you keep mentioning? |
| 4. [20]How do I know if it works? |
| 5. [21]This library is HUGE! And what's libsupc++? |
| 6. [22]Why do I get an error saying libstdc++.so.X is missing |
| when I run my program? |
| 3. [23]Platform-Specific Issues |
| 1. [24]Can libstdc++-v3 be used with <my favorite compiler>? |
| 2. [25][removed] |
| 3. [26][removed] |
| 4. [27]I can't use 'long long' on Solaris |
| 5. [28]_XOPEN_SOURCE / _GNU_SOURCE / etc is always defined |
| 6. [29]OS X ctype.h is broken! How can I hack it? |
| 7. [30]Threading is broken on i386 |
| 8. [31]Recent GNU/Linux glibc required? |
| 9. [32]Can't use wchar_t/wstring on FreeBSD |
| 10. [33]MIPS atomic operations |
| 4. [34]Known Bugs and Non-Bugs |
| 1. [35]What works already? |
| 2. [36]Bugs in gcc/g++ (not libstdc++-v3) |
| 3. [37]Bugs in the C++ language/lib specification |
| 4. [38]Things in libstdc++ that only look like bugs |
| o [39]reopening a stream fails |
| o [40]-Weffc++ complains too much |
| o [41]"ambiguous overloads" after including an old-style |
| header |
| o [42]The g++-3 headers are not ours |
| o [43]compilation errors from streambuf.h |
| o [44]errors about *Concept and constraints in the STL... |
| o [45]program crashes when using library code in a |
| dynamically-loaded library |
| o [46]"memory leaks" in containers |
| 5. [47]Aw, that's easy to fix! |
| 5. [48]Miscellaneous |
| 1. [49]string::iterator is not char*; vector<T>::iterator is not |
| T* |
| 2. [50]What's next after libstdc++-v3? |
| 3. [51]What about the STL from SGI? |
| 4. [52]Extensions and Backward Compatibility |
| 5. [53]Does libstdc++ support TR1? |
| 6. [54]Is libstdc++-v3 thread-safe? |
| 7. [55]How do I get a copy of the ISO C++ Standard? |
| 8. [56]What's an ABI and why is it so messy? |
| 9. [57]How do I make std::vector<T>::capacity() == |
| std::vector<T>::size? |
| _________________________________________________________________ |
| |
| 1.0 General Information |
| |
| 1.1 What is libstdc++-v3? |
| |
| The GNU Standard C++ Library v3 is an ongoing project to implement the |
| ISO 14882 Standard C++ library as described in chapters 17 through 27 |
| and annex D. For those who want to see exactly how far the project has |
| come, or just want the latest bleeding-edge code, the up-to-date |
| source is available over anonymous SVN, and can even be browsed over |
| the Web (see [58]1.4 below). |
| |
| The older libstdc++-v2 project is no longer maintained; the code has |
| been completely replaced and rewritten. [59]If you are using V2, then |
| you need to report bugs to your system vendor, not to the V3 list. |
| |
| A more formal description of the V3 goals can be found in the official |
| [60]design document. |
| _________________________________________________________________ |
| |
| 1.2 Why should I use libstdc++? |
| |
| The completion of the ISO C++ standardization gave the C++ community a |
| powerful set of reuseable tools in the form of the C++ Standard |
| Library. However, all existing C++ implementations are (as the Draft |
| Standard used to say) "incomplet and incorrekt," and many suffer from |
| limitations of the compilers that use them. |
| |
| The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is |
| widely considered to be one of the leading compilers in the world. Its |
| development is overseen by the [61]GCC team. All of the rapid |
| development and near-legendary [62]portability that are the hallmarks |
| of an open-source project are being applied to libstdc++. |
| |
| That means that all of the Standard classes and functions (such as |
| string, vector<>, iostreams, and algorithms) will be freely available |
| and fully compliant. Programmers will no longer need to "roll their |
| own" nor be worried about platform-specific incompatibilities. |
| _________________________________________________________________ |
| |
| 1.3 Who's in charge of it? |
| |
| The libstdc++ project is contributed to by several developers all over |
| the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel |
| Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and Paolo |
| Carlini are the lead maintainers of the SVN archive. |
| |
| Development and discussion is held on the libstdc++ mailing list. |
| Subscribing to the list, or searching the list archives, is open to |
| everyone. You can read instructions for doing so on the [63]homepage. |
| If you have questions, ideas, code, or are just curious, sign up! |
| _________________________________________________________________ |
| |
| 1.4 How do I get libstdc++? |
| |
| The [64]homepage has instructions for retrieving the latest SVN |
| sources, and for browsing the SVN sources over the web. |
| |
| Stable versions of libstdc++-v3 are included with releases of [65]the |
| GCC compilers. |
| |
| The subset commonly known as the Standard Template Library (chapters |
| 23 through 25, mostly) is adapted from the final release of the SGI |
| STL, with extensive changes. |
| _________________________________________________________________ |
| |
| 1.5 When is libstdc++ going to be finished? |
| |
| Nathan Myers gave the best of all possible answers, responding to a |
| Usenet article asking this question: Sooner, if you help. |
| _________________________________________________________________ |
| |
| 1.6 How do I contribute to the effort? |
| |
| Here is [66]a page devoted to this topic. Subscribing to the mailing |
| list (see above, or the homepage) is a very good idea if you have |
| something to contribute, or if you have spare time and want to help. |
| Contributions don't have to be in the form of source code; anybody who |
| is willing to help write documentation, for example, or has found a |
| bug in code that we all thought was working, is more than welcome! |
| _________________________________________________________________ |
| |
| 1.7 What happened to libg++? I need that! |
| |
| The most recent libg++ README states that libg++ is no longer being |
| actively maintained. It should not be used for new projects, and is |
| only being kicked along to support older code. |
| |
| The libg++ was designed and created when there was no Standard to |
| provide guidance. Classes like linked lists are now provided for by |
| list<T> and do not need to be created by genclass. (For that matter, |
| templates exist now and are well-supported, whereas genclass (mostly) |
| predates them.) |
| |
| There are other classes in libg++ that are not specified in the ISO |
| Standard (e.g., statistical analysis). While there are a lot of really |
| useful things that are used by a lot of people (e.g., statistics :-), |
| the Standards Committee couldn't include everything, and so a lot of |
| those "obvious" classes didn't get included. |
| |
| Since libstdc++ is an implementation of the Standard Library, we have |
| no plans at this time to include non-Standard utilities in the |
| implementation, however handy they are. (The extensions provided in |
| the SGI STL aren't maintained by us and don't get a lot of our |
| attention, because they don't require a lot of our time.) It is |
| entirely plausable that the "useful stuff" from libg++ might be |
| extracted into an updated utilities library, but nobody has started |
| such a project yet. |
| |
| (The [67]Boost site houses free C++ libraries that do varying things, |
| and happened to be started by members of the Standards Committee. |
| Certain "useful stuff" classes will probably migrate there.) |
| |
| For the bold and/or desperate, the [68]GCC extensions page describes |
| where to find the last libg++ source. |
| _________________________________________________________________ |
| |
| 1.8 What if I have more questions? |
| |
| If you have read the README and RELEASE-NOTES files, and your question |
| remains unanswered, then just ask the mailing list. At present, you do |
| not need to be subscribed to the list to send a message to it. More |
| information is available on the homepage (including how to browse the |
| list archives); to send to the list, use [69]libstdc++@gcc.gnu.org. |
| |
| If you have a question that you think should be included here, or if |
| you have a question about a question/answer here, contact [70]Phil |
| Edwards or [71]Gabriel Dos Reis. |
| _________________________________________________________________ |
| |
| 1.9 What are the license terms for libstdc++-v3? |
| |
| See [72]our license description for these and related questions. |
| _________________________________________________________________ |
| |
| 2.0 Installation |
| |
| 2.1 How do I install libstdc++-v3? |
| |
| Complete instructions are not given here (this is a FAQ, not an |
| installation document), but the tools required are few: |
| * A 3.x release of GCC. Note that building GCC is much easier and |
| more automated than building the GCC 2.[78] series was. If you are |
| using GCC 2.95, you can still build earlier snapshots of |
| libstdc++. |
| * GNU Make is required for GCC 3.4 and later. |
| * The GNU Autotools are needed if you are messing with the configury |
| or makefiles. |
| |
| The file [73]documentation.html provides a good overview of the steps |
| necessary to build, install, and use the library. Instructions for |
| configuring the library with new flags such as --enable-threads are |
| there also, as well as patches and instructions for working with GCC |
| 2.95. |
| |
| The top-level install.html and [74]RELEASE-NOTES files contain the |
| exact build and installation instructions. You may wish to browse |
| those files over ViewVC ahead of time to get a feel for what's |
| required. RELEASE-NOTES is located in the ".../docs/17_intro/" |
| directory of the distribution. |
| _________________________________________________________________ |
| |
| 2.2 [removed] |
| |
| This question has become moot and has been removed. The stub is here |
| to preserve numbering (and hence links/bookmarks). |
| _________________________________________________________________ |
| |
| 2.3 What is this SVN thing that you keep mentioning? |
| |
| Subversion is one of several revision control packages. It was |
| selected for GNU projects because it's free (speech), free (beer), and |
| very high quality. The [75]Subversion home page has a better |
| description. |
| |
| The "anonymous client checkout" feature of SVN is similar to anonymous |
| FTP in that it allows anyone to retrieve the latest libstdc++ sources. |
| |
| After the first of April, American users will have a "/pharmacy" |
| command-line option... |
| _________________________________________________________________ |
| |
| 2.4 How do I know if it works? |
| |
| libstdc++-v3 comes with its own testsuite. You do not need to actually |
| install the library ("make install") to run the testsuite, but you do |
| need DejaGNU, as described [76]here. |
| |
| To run the testsuite on the library after building it, use "make |
| check" while in your build directory. To run the testsuite on the |
| library after building and installing it, use "make check-install" |
| instead. |
| |
| If you find bugs in the testsuite programs themselves, or if you think |
| of a new test program that should be added to the suite, please write |
| up your idea and send it to the list! |
| _________________________________________________________________ |
| |
| 2.5 This library is HUGE! And what's libsupc++? |
| |
| Usually the size of libraries on disk isn't noticeable. When a link |
| editor (or simply "linker") pulls things from a static archive |
| library, only the necessary object files are copied into your |
| executable, not the entire library. Unfortunately, even if you only |
| need a single function or variable from an object file, the entire |
| object file is extracted. (There's nothing unique to C++ or |
| libstdc++-v3 about this; it's just common behavior, given here for |
| background reasons.) |
| |
| Some of the object files which make up libstdc++.a are rather large. |
| If you create a statically-linked executable with -static, those large |
| object files are suddenly part of your executable. Historically the |
| best way around this was to only place a very few functions (often |
| only a single one) in each source/object file; then extracting a |
| single function is the same as extracting a single .o file. For |
| libstdc++-v3 this is only possible to a certain extent; the object |
| files in question contain template classes and template functions, |
| pre-instantiated, and splitting those up causes severe maintenance |
| headaches. |
| |
| It's not a bug, and it's not really a problem. Nevertheless, some |
| people don't like it, so here are two pseudo-solutions: |
| |
| If the only functions from libstdc++.a which you need are language |
| support functions (those listed in [77]clause 18 of the standard, |
| e.g., new and delete), then try linking against libsupc++.a (Using gcc |
| instead of g++ and explicitly linking in -lsupc++ for the final link |
| step will do it). This library contains only those support routines, |
| one per object file. But if you are using anything from the rest of |
| the library, such as IOStreams or vectors, then you'll still need |
| pieces from libstdc++.a. |
| |
| The second method is one we hope to incorporate into the library build |
| process. Some platforms can place each function and variable into its |
| own section in a .o file. The GNU linker can then perform garbage |
| collection on unused sections; this reduces the situation to only |
| copying needed functions into the executable, as before, but all |
| happens automatically. |
| |
| Unfortunately the garbage collection in GNU ld is buggy; sections |
| (corresponding to functions and variables) which are used are |
| mistakenly removed, leading to horrible crashes when your executable |
| starts up. For the time being, this feature is not used when building |
| the library. |
| _________________________________________________________________ |
| |
| 2.6 Why do I get an error saying libstdc++.so.X is missing when I run my |
| program? |
| |
| Depending on your platform and library version, the message might be |
| similar to one of the following: |
| ./a.out: error while loading shared libraries: libstdc++.so.6: cannot open |
| shared object file: No such file or directory |
| |
| /usr/libexec/ld-elf.so.1: Shared object "libstdc++.so.6" not found |
| |
| This doesn't mean that the shared library isn't installed, only that |
| the dynamic linker can't find it. When a dynamically-linked executable |
| is run the linker finds and loads the required shared libraries by |
| searching a pre-configured list of directories. If the directory where |
| you've installed libstdc++ is not in this list then the libraries |
| won't be found. The simplest way to fix this is to use the |
| LD_LIBRARY_PATH environment variable, which is a colon-separated list |
| of directories in which the linker will search for shared libraries: |
| LD_LIBRARY_PATH=${prefix}/lib:$LD_LIBRARY_PATH |
| export LD_LIBRARY_PATH |
| |
| The exact environment variable to use will depend on your platform, |
| e.g. DYLD_LIBRARY_PATH for Darwin, |
| LD_LIBRARY_PATH_32/LD_LIBRARY_PATH_64 for Solaris 32-/64-bit, |
| LD_LIBRARYN32_PATH/LD_LIBRARY64_PATH for Irix N32/64-bit ABIs and |
| SHLIB_PATH for HP-UX. |
| |
| See the man pages for ld(1), ldd(1) and ldconfig(8) for more |
| information. The dynamic linker has different names on different |
| platforms but the man page is usually called something such as ld.so / |
| rtld / dld.so. |
| _________________________________________________________________ |
| |
| 3.0 Platform-Specific Issues |
| |
| 3.1 Can libstdc++-v3 be used with <my favorite compiler>? |
| |
| Probably not. Yet. |
| |
| Because GCC advances so rapidly, development and testing of libstdc++ |
| is being done almost entirely under that compiler. If you are curious |
| about whether other, lesser compilers (*grin*) support libstdc++, you |
| are more than welcome to try. Configuring and building the library |
| (see above) will still require certain tools, however. Also keep in |
| mind that building libstdc++ does not imply that your compiler will be |
| able to use all of the features found in the C++ Standard Library. |
| |
| Since the goal of ISO Standardization is for all C++ implementations |
| to be able to share code, the final libstdc++ should, in theory, be |
| usable under any ISO-compliant compiler. It will still be targeted and |
| optimized for GCC/g++, however. |
| _________________________________________________________________ |
| |
| 3.2 [removed] |
| |
| This question has become moot and has been removed. The stub is here |
| to preserve numbering (and hence links/bookmarks). |
| _________________________________________________________________ |
| |
| 3.3 [removed] |
| |
| This question has become moot and has been removed. The stub is here |
| to preserve numbering (and hence links/bookmarks). |
| _________________________________________________________________ |
| |
| 3.4 I can't use 'long long' on Solaris |
| |
| By default we try to support the C99 long long type. This requires |
| that certain functions from your C library be present. |
| |
| Up through release 3.0.2 the tests performed were too general, and |
| this feature was disabled when it did not need to be. The most |
| commonly reported platform affected was Solaris. |
| |
| This has been fixed for 3.0.3 and onwards. |
| _________________________________________________________________ |
| |
| 3.5 _XOPEN_SOURCE / _GNU_SOURCE / etc is always defined |
| |
| On Solaris, g++ (but not gcc) always defines the preprocessor macro |
| _XOPEN_SOURCE. On GNU/Linux, the same happens with _GNU_SOURCE. (This |
| is not an exhaustive list; other macros and other platforms are also |
| affected.) |
| |
| These macros are typically used in C library headers, guarding new |
| versions of functions from their older versions. The C++ standard |
| library includes the C standard library, but it requires the C90 |
| version, which for backwards-compatability reasons is often not the |
| default for many vendors. |
| |
| More to the point, the C++ standard requires behavior which is only |
| available on certain platforms after certain symbols are defined. |
| Usually the issue involves I/O-related typedefs. In order to ensure |
| correctness, the compiler simply predefines those symbols. |
| |
| Note that it's not enough to #define them only when the library is |
| being built (during installation). Since we don't have an 'export' |
| keyword, much of the library exists as headers, which means that the |
| symbols must also be defined as your programs are parsed and compiled. |
| |
| To see which symbols are defined, look for CPLUSPLUS_CPP_SPEC in the |
| gcc config headers for your target (and try changing them to see what |
| happens when building complicated code). You can also run "g++ -E -dM |
| - < /dev/null" to display a list of predefined macros for any |
| particular installation. |
| |
| This has been discussed on the mailing lists [78]quite a bit. |
| |
| This method is something of a wart. We'd like to find a cleaner |
| solution, but nobody yet has contributed the time. |
| _________________________________________________________________ |
| |
| 3.6 OS X ctype.h is broken! How can I hack it? |
| |
| This is a long-standing bug in the OS X support. Fortunately, the |
| patch is quite simple, and well-known. [79]Here's a link to the |
| solution. |
| _________________________________________________________________ |
| |
| 3.7 Threading is broken on i386 |
| |
| Support for atomic integer operations is/was broken on i386 platforms. |
| The assembly code accidentally used opcodes that are only available on |
| the i486 and later. So if you configured GCC to target, for example, |
| i386-linux, but actually used the programs on an i686, then you would |
| encounter no problems. Only when actually running the code on a i386 |
| will the problem appear. |
| |
| This is fixed in 3.2.2. |
| _________________________________________________________________ |
| |
| 3.8 Recent GNU/Linux glibc required? |
| |
| When running on GNU/Linux, libstdc++ 3.2.1 (shared library version |
| 5.0.1) and later uses localization and formatting code from the system |
| C library (glibc) version 2.2.5. That version of glibc is over a year |
| old and contains necessary bugfixes. Many GNU/Linux distros make glibc |
| version 2.3.x available now. |
| |
| The guideline is simple: the more recent the C++ library, the more |
| recent the C library. (This is also documented in the main GCC |
| installation instructions.) |
| _________________________________________________________________ |
| |
| 3.9 Can't use wchar_t/wstring on FreeBSD |
| |
| At the moment there are a few problems in FreeBSD's support for wide |
| character functions, and as a result the libstdc++ configury decides |
| that wchar_t support should be disabled. Once the underlying problems |
| are fixed in FreeBSD (soon), the library support will automatically |
| enable itself. |
| |
| You can fix the problems yourself, and learn more about the situation, |
| by reading [80]this short thread ("_GLIBCPP_USE_WCHAR_T undefined in |
| FreeBSD's c++config.h?"). |
| _________________________________________________________________ |
| |
| 3.10 MIPS atomic operations |
| |
| The atomic locking routines for MIPS targets requires MIPS II and |
| later. A patch went in just after the 3.3 release to make mips* use |
| the generic implementation instead. You can also configure for |
| mipsel-elf as a workaround. |
| |
| mips*-*-linux* continues to use the MIPS II routines, and more work in |
| this area is expected. |
| _________________________________________________________________ |
| |
| 4.0 Known Bugs and Non-Bugs |
| |
| Note that this section can get rapdily outdated -- such is the nature |
| of an open-source project. For the latest information, join the |
| mailing list or look through recent archives. The RELEASE- NOTES and |
| BUGS files are generally kept up-to-date. |
| |
| For 3.0.1, the most common "bug" is an apparently missing "../" in |
| include/Makefile, resulting in files like gthr.h and gthr-single.h not |
| being found. Please read [81]the configuration instructions for GCC, |
| specifically the part about configuring in a separate build directory, |
| and how strongly recommended it is. Building in the source directory |
| is fragile, is rarely tested, and tends to break, as in this case. |
| This was fixed for 3.0.2. |
| |
| For 3.1, the most common "bug" is a parse error when using <fstream>, |
| ending with a message, "bits/basic_file.h:52: parse error before `{' |
| token." Please read [82]the installation instructions for GCC, |
| specifically the part about not installing newer versions on top of |
| older versions. If you install 3.1 over a 3.0.x release, then the |
| wrong basic_file.h header will be found (its location changed between |
| releases). |
| |
| Please do not report these as bugs. We know about them. Reporting this |
| -- or any other problem that's already been fixed -- hinders the |
| development of GCC, because we have to take time to respond to your |
| report. Thank you. |
| _________________________________________________________________ |
| |
| 4.1 What works already? |
| |
| Short answer: Pretty much everything works except for some corner |
| cases. Also, localization is incomplete. For whether it works well, or |
| as you expect it to work, see 5.2. |
| |
| Long answer: See the docs/html/17_intro/CHECKLIST file, which is badly |
| outdated... Also see the RELEASE-NOTES file, which is kept more up to |
| date. |
| _________________________________________________________________ |
| |
| 4.2 Bugs in gcc/g++ (not libstdc++-v3) |
| |
| This is by no means meant to be complete nor exhaustive, but mentions |
| some problems that users may encounter when building or using |
| libstdc++. If you are experiencing one of these problems, you can find |
| more information on the libstdc++ and the GCC mailing lists. |
| |
| Before reporting a bug, examine the [83]bugs database with the |
| category set to "libstdc++". The BUGS file in the source tree also |
| tracks known serious problems. |
| * Debugging is problematic, due to bugs in line-number generation |
| (mostly fixed in the compiler) and gdb lagging behind the compiler |
| (lack of personnel). We recommend configuring the compiler using |
| --with-dwarf2 if the DWARF2 debugging format is not already the |
| default on your platform. Also, [84]changing your GDB settings can |
| have a profound effect on your C++ debugging experiences. :-) |
| _________________________________________________________________ |
| |
| 4.3 Bugs in the C++ language/lib specification |
| |
| Yes, unfortunately, there are some. In a [85]message to the list, |
| Nathan Myers announced that he has started a list of problems in the |
| ISO C++ Standard itself, especially with regard to the chapters that |
| concern the library. The list itself is [86]posted on his website. |
| Developers who are having problems interpreting the Standard may wish |
| to consult his notes. |
| |
| For those people who are not part of the ISO Library Group (i.e., |
| nearly all of us needing to read this page in the first place :-), a |
| public list of the library defects is occasionally published [87]here. |
| Some of these have resulted in [88]code changes. |
| _________________________________________________________________ |
| |
| 4.4 Things in libstdc++ that only look like bugs |
| |
| There are things which are not bugs in the compiler (4.2) nor the |
| language specification (4.3), but aren't really bugs in libstdc++, |
| either. Really! Please do not report these as bugs. |
| |
| -Weffc++ The biggest of these is the quadzillions of warnings about |
| the library headers emitted when -Weffc++ is used. Making libstdc++ |
| "-Weffc++-clean" is not a goal of the project, for a few reasons. |
| Mainly, that option tries to enforce object-oriented programming, |
| while the Standard Library isn't necessarily trying to be OO. |
| |
| reopening a stream fails Did I just say that -Weffc++ was our biggest |
| false-bug report? I lied. (It used to be.) Today it seems to be |
| reports that after executing a sequence like |
| #include <fstream> |
| ... |
| std::fstream fs("a_file"); |
| // . |
| // . do things with fs... |
| // . |
| fs.close(); |
| fs.open("a_new_file"); |
| |
| all operations on the re-opened fs will fail, or at least act very |
| strangely. Yes, they often will, especially if fs reached the EOF |
| state on the previous file. The reason is that the state flags are not |
| cleared on a successful call to open(). The standard unfortunately did |
| not specify behavior in this case, and to everybody's great sorrow, |
| the [89]proposed LWG resolution in DR #22 is to leave the flags |
| unchanged. You must insert a call to fs.clear() between the calls to |
| close() and open(), and then everything will work like we all expect |
| it to work. Update: for GCC 4.0 we implemented the resolution of |
| [90]DR #409 and open() now calls clear() on success! |
| |
| rel_ops Another is the rel_ops namespace and the template comparison |
| operator functions contained therein. If they become visible in the |
| same namespace as other comparison functions (e.g., 'using' them and |
| the <iterator> header), then you will suddenly be faced with huge |
| numbers of ambiguity errors. This was discussed on the -v3 list; |
| Nathan Myers [91]sums things up here. The collisions with |
| vector/string iterator types have been fixed for 3.1. |
| |
| The g++-3 headers are not ours |
| |
| If you have found an extremely broken header file which is causing |
| problems for you, look carefully before submitting a "high" priority |
| bug report (which you probably shouldn't do anyhow; see the last |
| paragraph of the page describing [92]the GCC bug database). |
| |
| If the headers are in ${prefix}/include/g++-3, or if the installed |
| library's name looks like libstdc++-2.10.a or libstdc++-libc6-2.10.so, |
| then you are using the old libstdc++-v2 library, which is nonstandard |
| and unmaintained. Do not report problems with -v2 to the -v3 mailing |
| list. |
| |
| For GCC versions 3.0 and 3.1 the libstdc++-v3 header files are |
| installed in ${prefix}/include/g++-v3 (see the 'v'?). Starting with |
| version 3.2 the headers are installed in |
| ${prefix}/include/c++/${version} as this prevents headers from |
| previous versions being found by mistake. |
| |
| glibc If you're on a GNU/Linux system and have just upgraded to glibc |
| 2.2, but are still using gcc 2.95.2, then you should have read the |
| glibc FAQ, specifically 2.34: |
| 2.34. When compiling C++ programs, I get a compilation error in streambuf.h. |
| |
| {BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to |
| apply a patch to the include files in /usr/include/g++, because the fpos_t |
| type has changed in glibc 2.2. The patch is at |
| http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff |
| |
| |
| Note that 2.95.x shipped with the [93]old v2 library which is no |
| longer maintained. Also note that gcc 2.95.3 fixes this problem, but |
| requires a separate patch for libstdc++-v3. |
| |
| concept checks If you see compilation errors containing messages about |
| fooConcept and a constraints member function, then most likely you |
| have violated one of the requirements for types used during |
| instantiation of template containers and functions. For example, |
| EqualityComparableConcept appears if your types must be comparable |
| with == and you have not provided this capability (a typo, or wrong |
| visibility, or you just plain forgot, etc). |
| |
| More information, including how to optionally enable/disable the |
| checks, is available [94]here. |
| |
| dlopen/dlsym If you are using the C++ library across |
| dynamically-loaded objects, make certain that you are passing the |
| correct options when compiling and linking: |
| // compile your library components |
| g++ -fPIC -c a.cc |
| g++ -fPIC -c b.cc |
| ... |
| g++ -fPIC -c z.cc |
| |
| // create your library |
| g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o |
| |
| // link the executable |
| g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl |
| |
| "memory leaks" in containers A few people have reported that the |
| standard containers appear to leak memory when tested with memory |
| checkers such as [95]valgrind. The library's default allocators keep |
| free memory in a pool for later reuse, rather than returning it to the |
| OS. Although this memory is always reachable by the library and is |
| never lost, memory debugging tools can report it as a leak. If you |
| want to test the library for memory leaks please read [96]Tips for |
| memory leak hunting first. |
| _________________________________________________________________ |
| |
| 4.5 Aw, that's easy to fix! |
| |
| If you have found a bug in the library and you think you have a |
| working fix, then send it in! The main GCC site has a page on |
| [97]submitting patches that covers the procedure, but for libstdc++ |
| you should also send the patch to our mailing list in addition to the |
| GCC patches mailing list. The libstdc++ [98]contributors' page also |
| talks about how to submit patches. |
| |
| In addition to the description, the patch, and the ChangeLog entry, it |
| is a Good Thing if you can additionally create a small test program to |
| test for the presence of the bug that your patch fixes. Bugs have a |
| way of being reintroduced; if an old bug creeps back in, it will be |
| caught immediately by the [99]testsuite -- but only if such a test |
| exists. |
| _________________________________________________________________ |
| |
| 5.0 Miscellaneous |
| |
| 5.1 string::iterator is not char*; vector<T>::iterator is not T* |
| |
| If you have code that depends on container<T> iterators being |
| implemented as pointer-to-T, your code is broken. |
| |
| While there are arguments for iterators to be implemented in that |
| manner, A) they aren't very good ones in the long term, and B) they |
| were never guaranteed by the Standard anyway. The type-safety achieved |
| by making iterators a real class rather than a typedef for T* |
| outweighs nearly all opposing arguments. |
| |
| Code which does assume that a vector iterator i is a pointer can often |
| be fixed by changing i in certain expressions to &*i . Future |
| revisions of the Standard are expected to bless this usage for |
| vector<> (but not for basic_string<>). |
| _________________________________________________________________ |
| |
| 5.2 What's next after libstdc++-v3? |
| |
| Hopefully, not much. The goal of libstdc++-v3 is to produce a |
| fully-compliant, fully-portable Standard Library. After that, we're |
| mostly done: there won't be any more compliance work to do. However: |
| 1. The ISO Committee will meet periodically to review Defect Reports |
| in the C++ Standard. Undoubtedly some of these will result in |
| changes to the Standard, which will be reflected in patches to |
| libstdc++. Some of that is already happening, see [100]4.3. Some |
| of those changes are being predicted by the library maintainers, |
| and we add code to the library based on what the current proposed |
| resolution specifies. Those additions are listed in [101]the |
| extensions page. |
| 2. Performance tuning. Lots of performance tuning. This too is |
| already underway for post-3.0 releases, starting with memory |
| expansion in container classes and buffer usage in synchronized |
| stream objects. |
| 3. An ABI for libstdc++ is being developed, so that multiple |
| binary-incompatible copies of the library can be replaced with a |
| single backwards-compatible library, like libgcc_s.so is. |
| 4. The current libstdc++ contains extensions to the Library which |
| must be explicitly requested by client code (for example, the hash |
| tables from SGI). Other extensions may be added to libstdc++-v3 if |
| they seem to be "standard" enough. (For example, the "long long" |
| type from C99.) Bugfixes and rewrites (to improve or fix thread |
| safety, for instance) will of course be a continuing task. |
| 5. There is an effort underway to add significant extensions to the |
| standard library specification. The latest version of this effort |
| is described in [102]The C++ Library Technical Report 1. See |
| [103]5.5. |
| |
| [104]This question about the next libstdc++ prompted some brief but |
| interesting [105]speculation. |
| _________________________________________________________________ |
| |
| 5.3 What about the STL from SGI? |
| |
| The [106]STL from SGI, version 3.3, was the final merge of the STL |
| codebase. The code in libstdc++ contains many fixes and changes, and |
| the SGI code is no longer under active development. We expect that no |
| future merges will take place. |
| |
| In particular, string is not from SGI and makes no use of their "rope" |
| class (which is included as an optional extension), nor is valarray |
| and some others. Classes like vector<> are, however we have made |
| significant changes to them since then. |
| |
| The FAQ for SGI's STL (one jump off of their main page) is recommended |
| reading. |
| _________________________________________________________________ |
| |
| 5.4 Extensions and Backward Compatibility |
| |
| Headers in the ext and backward subdirectories should be referred to |
| by their relative paths: |
| #include <ext/hash_map> |
| |
| rather than using -I or other options. This is more portable and |
| forward-compatible. (The situation is the same as that of other |
| headers whose directories are not searched directly, e.g., |
| <sys/stat.h>, <X11/Xlib.h>. |
| |
| At this time most of the features of the SGI STL extension have been |
| replaced by standardized libraries. In particular, the unordered_map |
| and unordered_set containers of TR1 are suitable replacement for the |
| non-standard hash_map and hash_set containers in the SGI STL. See |
| [107]5.5 for more details. |
| |
| The extensions are no longer in the global or std namespaces, instead |
| they are declared in the __gnu_cxx namespace. For maximum portability, |
| consider defining a namespace alias to use to talk about extensions, |
| e.g.: |
| #ifdef __GNUC__ |
| #if __GNUC__ < 3 |
| #include <hash_map.h> |
| namespace Sgi { using ::hash_map; }; // inherit globals |
| #else |
| #include <ext/hash_map> |
| #if __GNUC_MINOR__ == 0 |
| namespace Sgi = std; // GCC 3.0 |
| #else |
| namespace Sgi = ::__gnu_cxx; // GCC 3.1 and later |
| #endif |
| #endif |
| #else // ... there are other compilers, right? |
| namespace Sgi = std; |
| #endif |
| |
| Sgi::hash_map<int,int> my_map; |
| |
| This is a bit cleaner than defining typedefs for all the |
| instantiations you might need. |
| |
| Note: explicit template specializations must be declared in the same |
| namespace as the original template. This means you cannot use a |
| namespace alias when declaring an explicit specialization. |
| |
| Extensions to the library have [108]their own page. |
| _________________________________________________________________ |
| |
| 5.5 Does libstdc++ support TR1? |
| |
| The C++ Standard Library Technical Report adds many new features to |
| the library. The latest version of this effort is described in |
| [109]Technical Report 1. |
| |
| libstdc++ strives to implement all of TR1. An [110]overview of the |
| implementation status is available. |
| |
| Briefly, the features of TR1 and the current status are: |
| |
| Reference_wrapper - Complete - Useful to pass references to functions |
| that take their parameters by value. |
| |
| Reference-counted smart pointers - Complete - The shared_ptr and |
| weak_ptr allow several object to know about a pointer and whether it |
| is valid. When the last reference to the pointer is destroyed the |
| pointer is freed. |
| |
| Function objects - Complete - Function return types (i.e, result_of), |
| the functions template mem_fn (a generalization of mem_fun and |
| mem_fun_red), function object binders (e.g, bind, a generalization of |
| bind1st and bind2nd), and polymorhpic function wrappers (e.g, class |
| template function). |
| |
| Type traits - Complete - The type_traits class gives templates the |
| ability to probe information about the input type and enable |
| type-dependent logic to be performed without the need of template |
| specializations. |
| |
| A random number engine - Complete - This library contains randow |
| number generators with several different choices of distribution. |
| |
| Tuples - Complete - The tuple class implements small heterogeneous |
| arrays. This is an enhanced pair. In fact, the standard pair is |
| enhanced with a tuple interface. |
| |
| Fixed-size arrays - Complete - The array class implements small |
| fixed-sized arrays with container semantics. |
| |
| Unordered containers - Complete - The unordered_set, unordered_map, |
| unordered_multiset, and unordered_multimap containers are hashed |
| versions of the map, set, multimap, and multiset containers |
| respectively. These classes are suitable replacements for the SGI STL |
| hash_map and hash_set extensions. |
| |
| C99 compatibility - Under construction - There are many features |
| designed to minimize the divergence of the C and the C++ languages. |
| |
| Special functions - Under construction - Twenty-three mathematical |
| functions familiar to physicists and engineers are included: |
| cylindrical and spherical Bessel and Neumann functions, hypergeometric |
| functions, Laguerre polynomials, Legendre functions, elliptic |
| integrals, exponential integrals and the Riemann zeta function all for |
| your computing pleasure. |
| |
| A regular expression engine This library provides for regular |
| expression objects with traversal of text with return of |
| subexpressions. |
| _________________________________________________________________ |
| |
| 5.6 Is libstdc++-v3 thread-safe? |
| |
| libstdc++-v3 strives to be thread-safe when all of the following |
| conditions are met: |
| * The system's libc is itself thread-safe, |
| * gcc -v reports a thread model other than 'single', |
| * [pre-3.3 only] a non-generic implementation of atomicity.h exists |
| for the architecture in question. |
| |
| The user-code must guard against concurrent method calls which may |
| access any particular library object's state. Typically, the |
| application programmer may infer what object locks must be held based |
| on the objects referenced in a method call. Without getting into great |
| detail, here is an example which requires user-level locks: |
| library_class_a shared_object_a; |
| |
| thread_main () { |
| library_class_b *object_b = new library_class_b; |
| shared_object_a.add_b (object_b); // must hold lock for shared_object_ |
| a |
| shared_object_a.mutate (); // must hold lock for shared_object_ |
| a |
| } |
| |
| // Multiple copies of thread_main() are started in independent threads. |
| |
| Under the assumption that object_a and object_b are never exposed to |
| another thread, here is an example that should not require any |
| user-level locks: |
| thread_main () { |
| library_class_a object_a; |
| library_class_b *object_b = new library_class_b; |
| object_a.add_b (object_b); |
| object_a.mutate (); |
| } |
| |
| All library objects are safe to use in a multithreaded program as long |
| as each thread carefully locks out access by any other thread while it |
| uses any object visible to another thread, i.e., treat library objects |
| like any other shared resource. In general, this requirement includes |
| both read and write access to objects; unless otherwise documented as |
| safe, do not assume that two threads may access a shared standard |
| library object at the same time. |
| |
| See chapters [111]17 (library introduction), [112]23 (containers), and |
| [113]27 (I/O) for more information. |
| _________________________________________________________________ |
| |
| 5.7 How do I get a copy of the ISO C++ Standard? |
| |
| Copies of the full ISO 14882 standard are available on line via the |
| ISO mirror site for committee members. Non-members, or those who have |
| not paid for the privilege of sitting on the committee and sustained |
| their two-meeting commitment for voting rights, may get a copy of the |
| standard from their respective national standards organization. In the |
| USA, this national standards organization is ANSI and their website is |
| right [114]here. (And if you've already registered with them, clicking |
| this link will take you to directly to the place where you can |
| [115]buy the standard on-line. |
| |
| Who is your country's member body? Visit the [116]ISO homepage and |
| find out! |
| _________________________________________________________________ |
| |
| 5.8 What's an ABI and why is it so messy? |
| |
| "ABI" stands for "Application Binary Interface." Conventionally, it |
| refers to a great mass of details about how arguments are arranged on |
| the call stack and/or in registers, and how various types are arranged |
| and padded in structs. A single CPU design may suffer multiple ABIs |
| designed by different development tool vendors who made different |
| choices, or even by the same vendor for different target applications |
| or compiler versions. In ideal circumstances the CPU designer presents |
| one ABI and all the OSes and compilers use it. In practice every ABI |
| omits details that compiler implementers (consciously or accidentally) |
| must choose for themselves. |
| |
| That ABI definition suffices for compilers to generate code so a |
| program can interact safely with an OS and its lowest-level libraries. |
| Users usually want an ABI to encompass more detail, allowing libraries |
| built with different compilers (or different releases of the same |
| compiler!) to be linked together. For C++, this includes many more |
| details than for C, and CPU designers (for good reasons elaborated |
| below) have not stepped up to publish C++ ABIs. The details include |
| virtual function implementation, struct inheritance layout, name |
| mangling, and exception handling. Such an ABI has been defined for GNU |
| C++, and is immediately useful for embedded work relying only on a |
| "free-standing implementation" that doesn't include (much of) the |
| standard library. It is a good basis for the work to come. |
| |
| A useful C++ ABI must also incorporate many details of the standard |
| library implementation. For a C ABI, the layouts of a few structs |
| (such as FILE, stat, jmpbuf, and the like) and a few macros suffice. |
| For C++, the details include the complete set of names of functions |
| and types used, the offsets of class members and virtual functions, |
| and the actual definitions of all inlines. C++ exposes many more |
| library details to the caller than C does. It makes defining a |
| complete ABI a much bigger undertaking, and requires not just |
| documenting library implementation details, but carefully designing |
| those details so that future bug fixes and optimizations don't force |
| breaking the ABI. |
| |
| There are ways to help isolate library implementation details from the |
| ABI, but they trade off against speed. Library details used in inner |
| loops (e.g., getchar) must be exposed and frozen for all time, but |
| many others may reasonably be kept hidden from user code, so they may |
| later be changed. Deciding which, and implementing the decisions, must |
| happen before you can reasonably document a candidate C++ ABI that |
| encompasses the standard library. |
| _________________________________________________________________ |
| |
| 5.9 How do I make std::vector<T>::capacity() == std::vector<T>::size()? |
| |
| The standard idiom for deallocating a std::vector<T>'s unused memory |
| is to create a temporary copy of the vector and swap their contents, |
| e.g. for std::vector<T> v |
| std::vector<T>(v).swap(v); |
| |
| |
| The copy will take O(n) time and the swap is constant time. |
| |
| See [117]Shrink-to-fit strings for a similar solution for strings. |
| _________________________________________________________________ |
| |
| See [118]license.html for copying conditions. Comments and suggestions |
| are welcome, and may be sent to [119]the libstdc++ mailing list. |
| |
| References |
| |
| 1. ../documentation.html |
| 2. ../17_intro/license.html |
| 3. http://gcc.gnu.org/onlinedocs/libstdc++/faq/ |
| 4. http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html |
| 5. http://gcc.gnu.org/libstdc++/ |
| 6. ../faq/index.html#1_0 |
| 7. ../faq/index.html#1_1 |
| 8. ../faq/index.html#1_2 |
| 9. ../faq/index.html#1_3 |
| 10. ../faq/index.html#1_4 |
| 11. ../faq/index.html#1_5 |
| 12. ../faq/index.html#1_6 |
| 13. ../faq/index.html#1_7 |
| 14. ../faq/index.html#1_8 |
| 15. ../faq/index.html#1_9 |
| 16. ../faq/index.html#2_0 |
| 17. ../faq/index.html#2_1 |
| 18. ../faq/index.html#2_2 |
| 19. ../faq/index.html#2_3 |
| 20. ../faq/index.html#2_4 |
| 21. ../faq/index.html#2_5 |
| 22. ../faq/index.html#2_6 |
| 23. ../faq/index.html#3_0 |
| 24. ../faq/index.html#3_1 |
| 25. ../faq/index.html#3_2 |
| 26. ../faq/index.html#3_3 |
| 27. ../faq/index.html#3_4 |
| 28. ../faq/index.html#3_5 |
| 29. ../faq/index.html#3_6 |
| 30. ../faq/index.html#3_7 |
| 31. ../faq/index.html#3_8 |
| 32. ../faq/index.html#3_9 |
| 33. ../faq/index.html#3_10 |
| 34. ../faq/index.html#4_0 |
| 35. ../faq/index.html#4_1 |
| 36. ../faq/index.html#4_2 |
| 37. ../faq/index.html#4_3 |
| 38. ../faq/index.html#4_4 |
| 39. ../faq/index.html#4_4_iostreamclear |
| 40. ../faq/index.html#4_4_Weff |
| 41. ../faq/index.html#4_4_rel_ops |
| 42. ../faq/index.html#4_4_interface |
| 43. ../faq/index.html#4_4_glibc |
| 44. ../faq/index.html#4_4_checks |
| 45. ../faq/index.html#4_4_dlsym |
| 46. ../faq/index.html#4_4_leak |
| 47. ../faq/index.html#4_5 |
| 48. ../faq/index.html#5_0 |
| 49. ../faq/index.html#5_1 |
| 50. ../faq/index.html#5_2 |
| 51. ../faq/index.html#5_3 |
| 52. ../faq/index.html#5_4 |
| 53. ../faq/index.html#5_5 |
| 54. ../faq/index.html#5_6 |
| 55. ../faq/index.html#5_7 |
| 56. ../faq/index.html#5_8 |
| 57. ../faq/index.html#5_9 |
| 58. ../faq/index.html#1_4 |
| 59. ../faq/index.html#4_4_interface |
| 60. ../17_intro/DESIGN |
| 61. http://gcc.gnu.org/ |
| 62. http://gcc.gnu.org/gcc-3.3/buildstat.html |
| 63. http://gcc.gnu.org/libstdc++/ |
| 64. http://gcc.gnu.org/libstdc++/ |
| 65. http://gcc.gnu.org/releases.html |
| 66. ../17_intro/contribute.html |
| 67. http://www.boost.org/ |
| 68. http://gcc.gnu.org/extensions.html |
| 69. mailto:libstdc++@gcc.gnu.org |
| 70. mailto:pme@gcc.gnu.org |
| 71. mailto:gdr@gcc.gnu.org |
| 72. ../17_intro/license.html |
| 73. ../documentation.html |
| 74. ../17_intro/RELEASE-NOTES |
| 75. http://subversion.tigris.org/ |
| 76. http://gcc.gnu.org/install/test.html |
| 77. ../18_support/howto.html |
| 78. http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris |
| 79. http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html |
| 80. http://gcc.gnu.org/ml/libstdc++/2003-02/subjects.html#00286 |
| 81. http://gcc.gnu.org/install/configure.html |
| 82. http://gcc.gnu.org/install/ |
| 83. http://gcc.gnu.org/bugs.html |
| 84. http://gcc.gnu.org/ml/libstdc++/2002-02/msg00034.html |
| 85. http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html |
| 86. http://www.cantrip.org/draft-bugs.txt |
| 87. http://anubis.dkuug.dk/jtc1/sc22/wg21/ |
| 88. ../faq/index.html#5_2 |
| 89. ../ext/howto.html#5 |
| 90. ../ext/howto.html#5 |
| 91. http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html |
| 92. http://gcc.gnu.org/bugs.html |
| 93. ../faq/index.html#4_4_interface |
| 94. ../19_diagnostics/howto.html#3 |
| 95. http://developer.kde.org/~sewardj/ |
| 96. ../debug.html#mem |
| 97. http://gcc.gnu.org/contribute.html |
| 98. ../17_intro/contribute.html |
| 99. ../faq/index.html#2_4 |
| 100. ../faq/index.html#4_3 |
| 101. ../ext/howto.html#5 |
| 102. http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf |
| 103. ../faq/index.html#5_5 |
| 104. http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html |
| 105. http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html |
| 106. http://www.sgi.com/tech/stl/ |
| 107. ../faq/index.html#5_5 |
| 108. ../ext/howto.html |
| 109. http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf |
| 110. ../ext/tr1.html |
| 111. ../17_intro/howto.html#3 |
| 112. ../23_containers/howto.html#3 |
| 113. ../27_io/howto.html#9 |
| 114. http://www.ansi.org/ |
| 115. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003 |
| 116. http://www.iso.ch/ |
| 117. ../21_strings/howto.html#6 |
| 118. ../17_intro/license.html |
| 119. mailto:libstdc++@gcc.gnu.org |