--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[ ]>
+
+<book>
+
+<article id="faq" xreflabel="Frequently Asked Questions">
+<?dbhtml filename="faq.html"?>
+
+<articleinfo>
+ <title>Frequently Asked Questions</title>
+ <copyright>
+ <year>
+ 2008
+ </year>
+ <holder>
+ <ulink url="http://fsf.org">FSF</ulink>
+ </holder>
+ </copyright>
+</articleinfo>
+
+<!-- FAQ starts here -->
+<qandaset>
+
+<!-- General Information -->
+<qandadiv id="faq.info" xreflabel="General Information">
+<title>General Information</title>
+
+<qandaentry id="faq.what">
+ <question id="faq.what.q">
+ <para>
+ What is libstdc++?
+ </para>
+ </question>
+ <answer id="faq.what.a">
+ <para>
+ 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 <ulink url="http://gcc.gnu.org/svn.html">web</ulink>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.why">
+ <question id="q-why">
+ <para>
+ Why should I use libstdc++?
+ </para>
+ </question>
+ <answer id="a-why">
+ <para>
+ 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) <quote>incomplet and
+ incorrekt</quote>, and many suffer from limitations of the compilers
+ that use them.
+ </para>
+ <para>
+ The GNU compiler collection
+ (<command>gcc</command>, <command>g++</command>, etc) is widely
+ considered to be one of the leading compilers in the world. Its
+ development is overseen by the
+ <ulink url="http://gcc.gnu.org/">GCC team</ulink>. All of
+ the rapid development and near-legendary
+ <ulink url="http://gcc.gnu.org/buildstat.html">portability</ulink>
+ that are the hallmarks of an open-source project are being
+ applied to libstdc++.
+ </para>
+ <para>
+ That means that all of the Standard classes and functions will be
+ freely available and fully compliant. (Such as
+ <classname>string</classname>,
+ <classname>vector<></classname>, iostreams, and algorithms.)
+ Programmers will no longer need to <quote>roll their own</quote>
+ nor be worried about platform-specific incompatibilities.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.who">
+ <question id="q-who">
+ <para>
+ Who's in charge of it?
+ </para>
+ </question>
+ <answer id="a-who">
+ <para>
+ 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.
+ </para>
+ <para>
+ 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 <ulink url="http://gcc.gnu.org/libstdc++/">homepage</ulink>.
+ If you have questions, ideas, code, or are just curious, sign up!
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.when">
+ <question id="q-when">
+ <para>
+ When is libstdc++ going to be finished?
+ </para>
+ </question>
+ <answer id="a-when">
+ <para>
+ Nathan Myers gave the best of all possible answers, responding to
+ a Usenet article asking this question: <emphasis>Sooner, if you
+ help.</emphasis>
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.how">
+ <question id="q-how">
+ <para>
+ How do I contribute to the effort?
+ </para>
+ </question>
+ <answer id="a-how">
+ <para>
+ Here is <link linkend="appendix.contrib">a page devoted to
+ this topic</link>. 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 and is
+ willing to provide details, is more than welcome!
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.whereis_old">
+ <question id="q-whereis_old">
+ <para>
+ What happened to the older libg++? I need that!
+ </para>
+ </question>
+ <answer id="a-whereis_old">
+ <para>
+ 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.
+ </para>
+ <para>
+ More information in the <link linkend="manual.appendix.porting.backwards">backwards compatibility documentation</link>
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.more_questions">
+ <question id="q-more_questions">
+ <para>
+ What if I have more questions?
+ </para>
+ </question>
+ <answer id="a-more_questions">
+ <para>
+ If you have read the README file, 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 a message to the list,
+ use <email>libstdc++@gcc.gnu.org</email>.
+ </para>
+
+ <para>
+ If you have a question that you think should be included
+ here, or if you have a question <emphasis>about</emphasis> a question/answer
+ here, please send email to the libstdc++ mailing list, as above.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+<!-- License -->
+<qandadiv id="faq.license" xreflabel="License QA">
+<title>License</title>
+
+<qandaentry id="faq.license.what">
+ <question id="q-license.what">
+ <para>
+ What are the license terms for libstdc++?
+ </para>
+ </question>
+ <answer id="a-license.what">
+ <para>
+ See <link linkend="manual.intro.status.license">our license description</link>
+ for these and related questions.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.license.any_program">
+ <question id="q-license.any_program">
+ <para>
+ So any program which uses libstdc++ falls under the GPL?
+ </para>
+ </question>
+ <answer id="a-license.any_program">
+ <para>
+ No. The special exception permits use of the library in
+ proprietary applications.
+ </para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry id="faq.license.lgpl">
+ <question id="q-license.lgpl">
+ <para>
+ How is that different from the GNU {Lesser,Library} GPL?
+ </para>
+ </question>
+ <answer id="a-license.lgpl">
+ <para>
+ The LGPL requires that users be able to replace the LGPL code with a
+ modified version; this is trivial if the library in question is a C
+ shared library. But there's no way to make that work with C++, where
+ much of the library consists of inline functions and templates, which
+ are expanded inside the code that uses the library. So to allow people
+ to replace the library code, someone using the library would have to
+ distribute their own source, rendering the LGPL equivalent to the GPL.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.license.what_restrictions">
+ <question id="q-license.what_restrictions">
+ <para>
+ I see. So, what restrictions are there on programs that use the library?
+ </para>
+ </question>
+ <answer id="a-license.what_restrictions">
+ <para>
+ None. We encourage such programs to be released as open source,
+ but we won't punish you or sue you if you choose otherwise.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+<!-- Installation -->
+<qandadiv id="faq.installation" xreflabel="Installation">
+<title>Installation</title>
+
+<qandaentry id="faq.how_to_install">
+ <question id="q-how_to_install">
+ <para>How do I install libstdc++?
+ </para>
+ </question>
+ <answer id="a-how_to_install">
+ <para>
+ Often libstdc++ comes pre-installed as an integral part of many
+ existing Linux and Unix systems, as well as many embedded
+ development tools. It may be necessary to install extra
+ development packages to get the headers, or the documentation, or
+ the source: please consult your vendor for details.
+ </para>
+ <para>
+ To build and install from the GNU GCC sources, please consult the
+ <link linkend="manual.intro.setup">setup
+ documentation</link> for detailed
+ instructions. You may wish to browse those files ahead
+ of time to get a feel for what's required.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.how_to_get_sources">
+ <question id="q-how_to_get_sources">
+ <para>How does one get current libstdc++ sources?
+ </para>
+ </question>
+ <answer id="a-how_to_get_sources">
+ <para>
+ Libstdc++ sources for all official releases can be obtained as
+ part of the GCC sources, available from various sites and
+ mirrors. A full <ulink url="http://gcc.gnu.org/mirrors.html">list of
+ download sites</ulink> is provided on the main GCC site.
+ </para>
+ <para>
+ Current libstdc++ sources can always be checked out of the main
+ GCC source repository using the appropriate version control
+ tool. At this time, that tool
+ is <application>Subversion</application>.
+ </para>
+ <para>
+ <application>Subversion</application>, or <acronym>SVN</acronym>, 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 <ulink url="http://subversion.tigris.org"> Subversion
+ home page</ulink> has a better description.
+ </para>
+ <para>
+ The <quote>anonymous client checkout</quote> feature of SVN is
+ similar to anonymous FTP in that it allows anyone to retrieve
+ the latest libstdc++ sources.
+ </para>
+ <para>
+ For more information
+ see <ulink url="http://gcc.gnu.org/svn.html"><acronym>SVN</acronym>
+ details</ulink>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.how_to_test">
+ <question id="q-how_to_test">
+ <para>How do I know if it works?
+ </para>
+ </question>
+ <answer id="a-how_to_test">
+ <para>
+ Libstdc++ comes with its own validation testsuite, which includes
+ conformance testing, regression testing, ABI testing, and
+ performance testing. Please consult the
+ <ulink url="http://gcc.gnu.org/install/test.html">testing
+ documentation</ulink> for more details.
+ </para>
+ <para>
+ 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,
+ <emphasis>please</emphasis> write up your idea and send it to the list!
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.how_to_set_paths">
+ <question id="q-how_to_set_paths">
+ <para>How do I insure that the dynamically linked library will be found?
+ </para>
+ </question>
+ <answer id="a-how_to_set_paths">
+ <para>
+ Depending on your platform and library version, the error message might
+ be similar to one of the following:
+ </para>
+
+ <screen>
+ ./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
+ </screen>
+
+ <para>
+ 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 <literal>LD_LIBRARY_PATH</literal> environment variable,
+ which is a colon-separated list of directories in which the linker
+ will search for shared libraries:
+ </para>
+
+ <screen>
+ LD_LIBRARY_PATH=${prefix}/lib:$LD_LIBRARY_PATH
+ export LD_LIBRARY_PATH
+ </screen>
+
+ <para>
+ 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.
+ </para>
+ <para>
+ See the man pages for <command>ld</command>, <command>ldd</command>
+ and <command>ldconfig</command> for more information. The dynamic
+ linker has different names on different platforms but the man page
+ is usually called something such as <filename>ld.so/rtld/dld.so</filename>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.what_is_libsupcxx">
+ <question id="q-what_is_libsupcxx">
+ <para>
+ What's libsupc++?
+ </para>
+ </question>
+ <answer id="a-what_is_libsupcxx">
+ <para>
+ If the only functions from <filename>libstdc++.a</filename>
+ which you need are language support functions (those listed in
+ <link linkend="manual.support">clause 18</link> of the
+ standard, e.g., <function>new</function> and
+ <function>delete</function>), then try linking against
+ <filename>libsupc++.a</filename>, which is a subset of
+ <filename>libstdc++.a</filename>. (Using <command>gcc</command>
+ instead of <command>g++</command> and explicitly linking in
+ <filename>libsupc++.a</filename> via <literal>-lsupc++</literal>
+ 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
+ <filename>libstdc++.a</filename>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.size">
+ <question id="q-size">
+ <para>
+ This library is HUGE!
+ </para>
+ </question>
+ <answer id="a-size">
+ <para>
+ Usually the size of libraries on disk isn't noticeable. When a
+ link editor (or simply <quote>linker</quote>) 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++ about this; it's just common behavior, given here
+ for background reasons.)
+ </para>
+ <para>
+ Some of the object files which make up libstdc++.a are rather large.
+ If you create a statically-linked executable with
+ <literal>-static</literal>, 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++ 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.
+ </para>
+ <para>
+ On supported platforms, libstdc++ takes advantage of garbage
+ collection in the GNU linker to get a result similar to separating
+ each symbol into a separate source and object files. On these platforms,
+ GNU ld 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.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+
+<!-- Platform-Specific Issues -->
+<qandadiv id="faq.platform-specific" xreflabel="Platform-Specific Issues">
+<title>Platform-Specific Issues</title>
+
+<qandaentry id="faq.other_compilers">
+ <question id="q-other_compilers">
+ <para>
+ Can libstdc++ be used with non-GNU compilers?
+ </para>
+ </question>
+ <answer id="a-other_compilers">
+ <para>
+ Perhaps.
+ </para>
+ <para>
+ Since the goal of ISO Standardization is for all C++
+ implementations to be able to share code, libstdc++ should be
+ usable under any ISO-compliant compiler, at least in theory.
+ </para>
+ <para>
+ However, the reality is that libstdc++ is targeted and optimized
+ for GCC/g++. This means that often libstdc++ uses specific,
+ non-standard features of g++ that are not present in older
+ versions of proprietary compilers. It may take as much as a year or two
+ after an official release of GCC that contains these features for
+ proprietary tools support these constructs.
+ </para>
+ <para>
+ In the near past, specific released versions of libstdc++ have
+ been known to work with versions of the EDG C++ compiler, and
+ vendor-specific proprietary C++ compilers such as the Intel ICC
+ C++ compiler.
+ </para>
+
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.solaris_long_long">
+ <question id="q-solaris_long_long">
+ <para>
+ No 'long long' type on Solaris?
+ </para>
+ </question>
+ <answer id="a-solaris_long_long">
+ <para>
+ By default we try to support the C99 <type>long long</type> type.
+ This requires that certain functions from your C library be present.
+ </para>
+ <para>
+ Up through release 3.0.2 the platform-specific tests performed by
+ libstdc++ were too general, resulting in a conservative approach
+ to enabling the <type>long long</type> code paths. The most
+ commonly reported platform affected was Solaris.
+ </para>
+ <para>
+ This has been fixed for libstdc++ releases greater than 3.0.3.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.predefined">
+ <question id="q-predefined">
+ <para>
+ <constant>_XOPEN_SOURCE</constant> and <constant>_GNU_SOURCE</constant> are always defined?
+ </para>
+ </question>
+ <answer id="a-predefined">
+ <para>On Solaris, g++ (but not gcc) always defines the preprocessor
+ macro <constant>_XOPEN_SOURCE</constant>. On GNU/Linux, the same happens
+ with <constant>_GNU_SOURCE</constant>. (This is not an exhaustive list;
+ other macros and other platforms are also affected.)
+ </para>
+ <para>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-compatibility reasons is often not the
+ default for many vendors.
+ </para>
+ <para>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.
+ </para>
+ <para>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.
+ </para>
+ <para>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
+ <command>g++ -E -dM - < /dev/null"</command> to display
+ a list of predefined macros for any particular installation.
+ </para>
+ <para>This has been discussed on the mailing lists
+ <ulink url="http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris">quite a bit</ulink>.
+ </para>
+ <para>This method is something of a wart. We'd like to find a cleaner
+ solution, but nobody yet has contributed the time.
+ </para>
+
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.darwin_ctype">
+ <question id="q-darwin_ctype">
+ <para>
+ Mac OS X <filename class="headerfile">ctype.h</filename> is broken! How can I fix it?
+ </para>
+ </question>
+ <answer id="a-darwin_ctype">
+ <para>This is a long-standing bug in the OS X support. Fortunately,
+ the patch is quite simple, and well-known.
+ <ulink url="http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html"> Here's a
+ link to the solution</ulink>.
+ </para>
+
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.threads_i386">
+ <question id="q-threads_i386">
+ <para>
+ Threading is broken on i386?
+ </para>
+ </question>
+ <answer id="a-threads_i386">
+ <para>
+ </para>
+ <para>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.
+ </para>
+ <para>This is fixed in 3.2.2.
+ </para>
+
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.atomic_mips">
+ <question id="q-atomic_mips">
+ <para>
+ MIPS atomic operations
+ </para>
+ </question>
+ <answer id="a-atomic_mips">
+ <para>
+ 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.
+ </para>
+ <para>
+ The mips*-*-linux* port continues to use the MIPS II routines, and more
+ work in this area is expected.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.linux_glibc">
+ <question id="q-linux_glibc">
+ <para>
+ Recent GNU/Linux glibc required?
+ </para>
+ </question>
+ <answer id="a-linux_glibc">
+ <para>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.
+ </para>
+ <para>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.)
+ </para>
+
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.freebsd_wchar">
+ <question id="q-freebsd_wchar">
+ <para>
+ Can't use wchar_t/wstring on FreeBSD
+ </para>
+ </question>
+ <answer id="a-freebsd_wchar">
+ <para>
+ Older versions of FreeBSD's C library do not have sufficient
+ support for wide character functions, and as a result the
+ libstdc++ configury decides that wchar_t support should be
+ disabled. In addition, the libstdc++ platform checks that
+ enabled <type>wchar_t</type> were quite strict, and not granular
+ enough to detect when the minimal support to
+ enable <type>wchar_t</type> and C++ library structures
+ like <classname>wstring</classname> were present. This impacted Solaris,
+ Darwin, and BSD variants, and is fixed in libstdc++ versions post 4.1.0.
+ </para>
+ <para>
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+
+<!-- Known Bugs -->
+<qandadiv id="faq.known_bugs" xreflabel="Known Bugs">
+<title>Known Bugs</title>
+
+<qandaentry id="faq.what_works">
+ <question id="q-what_works">
+ <para>
+ What works already?
+ </para>
+ </question>
+ <answer id="a-what_works">
+ <para>
+ Short answer: Pretty much everything <emphasis>works</emphasis>
+ except for some corner cases. Support for localization
+ in <classname>locale</classname> may be incomplete on non-GNU
+ platforms. Also dependant on the underlying platform is support
+ for <type>wchar_t</type> and <type>long
+ long</type> specializations, and details of thread support.
+ </para>
+ <para>
+ Long answer: See the implementation status pages for
+ <link linkend="status.iso.1998">C++98</link>,
+ <link linkend="status.iso.tr1">TR1</link>, and
+ <link linkend="status.iso.200x">C++0x</link>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.standard_bugs">
+ <question id="q-standard_bugs">
+ <para>
+ Bugs in the ISO C++ language or library specification
+ </para>
+ </question>
+ <answer id="a-standard_bugs">
+ <para>
+ Unfortunately, there are some.
+ </para>
+ <para>
+ 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 <ulink url="http://anubis.dkuug.dk/jtc1/sc22/wg21/">here</ulink>.
+ Some of these issues have resulted in code changes in libstdc++.
+ </para>
+ <para>
+ If you think you've discovered a new bug that is not listed,
+ please post a message describing your problem
+ to <email>libstdc++@gcc.gnu.org</email> or the Usenet group
+ comp.lang.c++.moderated.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.compiler_bugs">
+ <question id="q-compiler_bugs">
+ <para>
+ Bugs in the compiler (gcc/g++) and not libstdc++
+ </para>
+ </question>
+ <answer id="a-compiler_bugs">
+ <para>
+ On occasion, the compiler is wrong. Please be advised that this
+ happens much less often than one would think, and avoid jumping to
+ conclusions.
+ </para>
+ <para>
+ First, examine the ISO C++ standard. Second, try another compiler
+ or an older version of the GNU compilers. Third, you can find more
+ information on the libstdc++ and the GCC mailing lists: search
+ these lists with terms describing your issue.
+ </para>
+ <para>
+ Before reporting a bug, please examine the
+ <ulink url="http://gcc.gnu.org/bugs.html">bugs database</ulink> with the
+ category set to <quote>g++</quote>.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+<!-- Known Non-Bugs -->
+<qandadiv id="faq.known_non-bugs" xreflabel="Known Non-Bugs">
+<title>Known Non-Bugs</title>
+
+<qandaentry id="faq.stream_reopening_fails">
+ <question id="q-stream_reopening_fails">
+ <para>
+ Reopening a stream fails
+ </para>
+ </question>
+ <answer id="a-stream_reopening_fails">
+ <para>
+ One of the most-reported non-bug reports. Executing a sequence like:
+ </para>
+
+ <literallayout>
+ #include <fstream>
+ ...
+ std::fstream fs(<quote>a_file</quote>);
+ // .
+ // . do things with fs...
+ // .
+ fs.close();
+ fs.open(<quote>a_new_file</quote>);
+ </literallayout>
+
+ <para>
+ All operations on the re-opened <varname>fs</varname> will fail, or at
+ least act very strangely. Yes, they often will, especially if
+ <varname>fs</varname> reached the EOF state on the previous file. The
+ reason is that the state flags are <emphasis>not</emphasis> cleared
+ on a successful call to open(). The standard unfortunately did
+ not specify behavior in this case, and to everybody's great sorrow,
+ the <link linkend="manual.intro.status.bugs">proposed LWG resolution in
+ DR #22</link> is to leave the flags unchanged. You must insert a call
+ to <function>fs.clear()</function> between the calls to close() and open(),
+ and then everything will work like we all expect it to work.
+ <emphasis>Update:</emphasis> for GCC 4.0 we implemented the resolution
+ of <link linkend="manual.intro.status.bugs">DR #409</link> and open()
+ now calls <function>clear()</function> on success!
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.wefcxx_verbose">
+ <question id="q-wefcxx_verbose">
+ <para>
+ -Weffc++ complains too much
+ </para>
+ </question>
+ <answer id="a-wefcxx_verbose">
+ <para>
+ Many warnings are emitted when <literal>-Weffc++</literal> is used. Making
+ libstdc++ <literal>-Weffc++</literal>-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.
+ </para>
+ <para>
+ We do, however, try to have libstdc++ sources as clean as possible. If
+ you see some simple changes that pacify <literal>-Weffc++</literal>
+ without other drawbacks, send us a patch.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.ambiguous_overloads">
+ <question id="q-ambiguous_overloads">
+ <para>
+ Ambiguous overloads after including an old-style header
+ </para>
+ </question>
+ <answer id="a-ambiguous_overloads">
+ <para>
+ Another problem is the <literal>rel_ops</literal> namespace and the template
+ comparison operator functions contained therein. If they become
+ visible in the same namespace as other comparison functions
+ (e.g., <quote>using</quote> 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
+ <ulink url="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums
+ things up here</ulink>. The collisions with vector/string iterator
+ types have been fixed for 3.1.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.v2_headers">
+ <question id="q-v2_headers">
+ <para>
+ The g++-3 headers are <emphasis>not ours</emphasis>
+ </para>
+ </question>
+ <answer id="a-v2_headers">
+ <para>
+ 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 <ulink url="http://gcc.gnu.org/bugs.html">the GCC
+ bug database</ulink>).
+ </para>
+ <para>
+ If the headers are in <filename>${prefix}/include/g++-3</filename>, or
+ if the installed library's name looks like
+ <filename>libstdc++-2.10.a</filename> or
+ <filename>libstdc++-libc6-2.10.so</filename>, 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.
+ </para>
+ <para>
+ For GCC versions 3.0 and 3.1 the libstdc++ header files are
+ installed in <filename>${prefix}/include/g++-v3</filename> (see the
+ 'v'?). Starting with version 3.2 the headers are installed in
+ <filename>${prefix}/include/c++/${version}</filename> as this prevents
+ headers from previous versions being found by mistake.
+ </para>
+
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.boost_concept_checks">
+ <question id="q-boost_concept_checks">
+ <para>
+ Errors about <emphasis>*Concept</emphasis> and
+ <emphasis>constraints</emphasis> in the STL
+ </para>
+ </question>
+ <answer id="a-boost_concept_checks">
+ <para>
+ If you see compilation errors containing messages about
+ <errortext>foo Concept </errortext>and something to do with a
+ <errortext>constraints</errortext> 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).
+ </para>
+ <para>
+ More information, including how to optionally enable/disable the
+ checks, is available
+ <link linkend="manual.diagnostics.concept_checking">here</link>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.dlopen_crash">
+ <question id="q-dlopen_crash">
+ <para>
+ Program crashes when using library code in a
+ dynamically-loaded library
+ </para>
+ </question>
+ <answer id="a-dlopen_crash">
+ <para>
+ If you are using the C++ library across dynamically-loaded
+ objects, make certain that you are passing the correct options
+ when compiling and linking:
+ </para>
+
+ <literallayout>
+ // 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
+ </literallayout>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.memory_leaks">
+ <question id="q-memory_leaks">
+ <para>
+ <quote>Memory leaks</quote> in containers
+ </para>
+ </question>
+ <answer id="a-memory_leaks">
+ <para>
+ A few people have reported that the standard containers appear
+ to leak memory when tested with memory checkers such as
+ <ulink url="http://valgrind.org/">valgrind</ulink>.
+ 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
+ <link linkend="debug.memory">Tips for memory leak hunting</link>
+ first.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.list_size_on">
+ <question id="q-list_size_on">
+ <para>
+ list::size() is O(n)!
+ </para>
+ </question>
+ <answer id="a-list_size_on">
+ <para>
+ See
+ the <link linkend="manual.containers">Containers</link>
+ chapter.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.easy_to_fix">
+ <question id="q-easy_to_fix">
+ <para>
+ Aw, that's easy to fix!
+ </para>
+ </question>
+ <answer id="a-easy_to_fix">
+ <para>
+ 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 <ulink url="http://gcc.gnu.org/contribute.html">submitting
+ patches</ulink> 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++
+ <link linkend="appendix.contrib">contributors' page</link>
+ also talks about how to submit patches.
+ </para>
+ <para>
+ 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
+ <ulink url="#2_4">testsuite</ulink> -- but only if such a test exists.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+
+<!-- Miscellaneous -->
+<qandadiv id="faq.misc" xreflabel="Miscellaneous">
+<title>Miscellaneous</title>
+
+<qandaentry id="faq.iterator_as_pod">
+ <question id="faq.iterator_as_pod_q">
+ <para>
+ string::iterator is not char*; vector<T>::iterator is not T*
+ </para>
+ </question>
+ <answer id="faq.iterator_as_pod_a">
+ <para>
+ If you have code that depends on container<T> iterators
+ being implemented as pointer-to-T, your code is broken. It's
+ considered a feature, not a bug, that libstdc++ points this out.
+ </para>
+ <para>
+ 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 <type>T*</type> outweighs nearly all opposing
+ arguments.
+ </para>
+ <para>
+ Code which does assume that a vector iterator <varname>i</varname>
+ is a pointer can often be fixed by changing <varname>i</varname> in
+ certain expressions to <varname>&*i</varname>. Future revisions
+ of the Standard are expected to bless this usage for
+ vector<> (but not for basic_string<>).
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.what_is_next">
+ <question id="q-what_is_next">
+ <para>
+ What's next after libstdc++?
+ </para>
+ </question>
+ <answer id="a-what_is_next">
+ <para>
+ Hopefully, not much. The goal of libstdc++ is to produce a
+ fully-compliant, fully-portable Standard Library. After that,
+ we're mostly done: there won't <emphasis>be</emphasis> any
+ more compliance work to do.
+ </para>
+ <para>
+ There is an effort underway to add significant extensions to
+ the standard library specification. The latest version of
+ this effort is described in
+ <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">
+ The C++ Library Technical Report 1</ulink>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.sgi_stl">
+ <question id="q-sgi_stl">
+ <para>
+ What about the STL from SGI?
+ </para>
+ </question>
+ <answer id="a-sgi_stl">
+ <para>
+ The <ulink url="http://www.sgi.com/tech/stl/">STL from SGI</ulink>,
+ 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.
+ </para>
+ <para>
+ In particular, <classname>string</classname> is not from SGI and makes no
+ use of their "rope" class (which is included as an
+ optional extension), nor is <classname>valarray</classname> and some others.
+ Classes like <classname>vector<></classname> are, but have been
+ extensively modified.
+ </para>
+ <para>
+ More information on the evolution of libstdc++ can be found at the
+ <link linkend="appendix.porting.api">API
+ evolution</link>
+ and <link linkend="manual.appendix.porting.backwards">backwards
+ compatibility</link> documentation.
+ </para>
+ <para>
+ The FAQ for SGI's STL (one jump off of their main page) is
+ still recommended reading.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.extensions_and_backwards_compat">
+ <question id="q-extensions_and_backwards_compat">
+ <para>
+ Extensions and Backward Compatibility
+ </para>
+ </question>
+ <answer id="a-extensions_and_backwards_compat">
+ <para>
+ See the <link linkend="manual.appendix.porting.backwards">link</link> on backwards compatibility and <link linkend="appendix.porting.api">link</link> on evolution.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.tr1_support">
+ <question id="q-tr1_support">
+ <para>
+ Does libstdc++ support TR1?
+ </para>
+ </question>
+ <answer id="a-tr1_support">
+ <para>
+ Yes.
+ </para>
+ <para>
+ The C++ Standard Library Technical Report adds many new features to
+ the library. The latest version of this effort is described in
+ <ulink url=
+ "http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">
+ Technical Report 1</ulink>.
+ </para>
+ <para>
+ The implementation status of TR1 in libstdc++ can be tracked <link
+ linkend="status.iso.tr1">on the TR1 status
+ page</link>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.get_iso_cxx">
+ <question id="q-get_iso_cxx">
+ <para>How do I get a copy of the ISO C++ Standard?
+ </para>
+ </question>
+ <answer id="a-get_iso_cxx">
+ <para>
+ 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 <ulink url="http://www.ansi.org">here</ulink>. (And if
+ you've already registered with them, clicking this link will take
+ you to directly to the place where you can
+ <ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line</ulink>.
+ </para>
+ <para>
+ Who is your country's member body? Visit the
+ <ulink url="http://www.iso.ch/">ISO homepage</ulink> and find out!
+ </para>
+ <para>
+ The 2003 version of the standard (the 1998 version plus TC1) is
+ available in print, ISBN 0-470-84674-7.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.what_is_abi">
+ <question id="q-what_is_abi">
+ <para>
+ What's an ABI and why is it so messy?
+ </para>
+ </question>
+ <answer id="a-what_is_abi">
+ <para>
+ <acronym>ABI</acronym> stands for <quote>Application Binary
+ Interface</quote>. 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.
+ </para>
+ <para>
+ 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 <quote>free-standing implementation</quote> that doesn't include (much
+ of) the standard library. It is a good basis for the work to come.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry id="faq.size_equals_capacity">
+ <question id="q-size_equals_capacity">
+ <para>
+ How do I make std::vector<T>::capacity() == std::vector<T>::size?
+ </para>
+ </question>
+ <answer id="a-size_equals_capacity">
+ <para>
+ The standard idiom for deallocating a <classname>vector<T></classname>'s
+ unused memory is to create a temporary copy of the vector and swap their
+ contents, e.g. for <classname>vector<T> v</classname>
+ </para>
+ <literallayout>
+ std::vector<T>(v).swap(v);
+ </literallayout>
+ <para>
+ The copy will take O(n) time and the swap is constant time.
+ </para>
+ <para>
+ See <link linkend="strings.string.shrink">Shrink-to-fit
+ strings</link> for a similar solution for strings.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+
+<!-- FAQ ends here -->
+</qandaset>
+
+</article>
+
+</book>
projects / msp430-gcc.git / blobdiff