diff options
Diffstat (limited to 'gcc-4.4.3/libstdc++-v3/doc/xml/faq.xml')
| -rw-r--r-- | gcc-4.4.3/libstdc++-v3/doc/xml/faq.xml | 1255 |
1 files changed, 0 insertions, 1255 deletions
diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/faq.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/faq.xml deleted file mode 100644 index c8907cabe..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/faq.xml +++ /dev/null @@ -1,1255 +0,0 @@ -<?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> |