diff options
Diffstat (limited to 'gcc-4.4.3/libstdc++-v3/doc/xml')
53 files changed, 0 insertions, 29505 deletions
diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/api.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/api.xml deleted file mode 100644 index c4c2f8f3f..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/api.xml +++ /dev/null @@ -1,106 +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="api" xreflabel="API"> -<?dbhtml filename="api.html"?> - -<articleinfo> - <title>API and Source Level Documentation</title> - <copyright> - <year> - 2008 - </year> - <holder> - <ulink url="http://www.fsf.org/">FSF - </ulink> - </holder> - </copyright> - <legalnotice> - <para> - <ulink url="17_intro/license.html">License - </ulink> - </para> - </legalnotice> -</articleinfo> - -<para> -The GNU C++ library sources have been specially formatted so that with the -proper invocation of another tool (Doxygen), a set of HTML pages -are generated from the sources files themselves. The resultant -documentation is referred to as Source Level Documentation, and is -useful for examining the signatures of public member functions for -the library classes, finding out what is in a particular include -file, looking at inheritance diagrams, etc. -</para> - -<para> -The source-level documentation for the most recent releases can be -viewed online: -</para> - -<itemizedlist> - <listitem> - <para> - <ulink url="libstdc++-html-USERS-3.4/index.html">for the 3.4 release - </ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="libstdc++-html-USERS-4.1/index.html">for the 4.1 release - </ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="libstdc++-html-USERS-4.2/index.html">for the 4.2 release - </ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="libstdc++-html-USERS-4.3/index.html">for the 4.3 release - </ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="libstdc++-html-USERS-4.4/index.html">for the 4.4 release - </ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="latest-doxygen/index.html">"the latest collection" - </ulink> - (For the main development tree; see the date on the first page.) - </para> - </listitem> -</itemizedlist> - -<para> -This generated HTML collection, as above, is also available for download in the libstdc++ snapshots directory at - <literal><URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/></literal>. - You will almost certainly need to use one of the - <ulink url="http://gcc.gnu.org/mirrors.html">mirror sites</ulink> to download - the tarball. After unpacking, simply load libstdc++-html-*/index.html - into a browser. -</para> - -<para> -Documentation for older releases is available for download only, not -online viewing. -</para> - -<para> -In addition, an initial set of man pages are also available in the -same place as the HTML collections. Start with C++Intro(3). -</para> - -</article> - -</book> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/authors.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/authors.xml deleted file mode 100644 index 43d8d8641..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/authors.xml +++ /dev/null @@ -1,184 +0,0 @@ -<authorgroup> - -<!-- - <author> - <firstname>Benjamin</firstname> - <surname>Kosnik</surname> - - <affiliation> - <shortaffil>Red Hat</shortaffil> - <orgname>Red Hat, Inc.</orgname> - <address> - <email>libstdc++@gcc.gnu.org</email> - </address> - </affiliation> - - <authorblurb> - <para> - </para> - </authorblurb> - </author> ---> - - <author> - <firstname></firstname> - <surname></surname> - - <authorblurb> - <para> - </para> - </authorblurb> - </author> - - <author> - <firstname>Paolo</firstname> - <surname>Carlini</surname> - - <authorblurb> - <para> - TR1, LWG Active, Closed, Defects lists. - </para> - </authorblurb> - </author> - - <author> - <firstname>Phil</firstname> - <surname>Edwards</surname> - - <authorblurb> - <para> - Originating author, started HOWTO and FAQ, worked on sections - Demangling, Macros, Strings, Iterators, Backwards - Compatibility, SGI Extensions, Configure, Build, Install. - </para> - </authorblurb> - </author> - - <author> - <firstname>Doug</firstname> - <surname>Gregor</surname> - - <authorblurb> - <para> - Debug Mode, TR1 function objects - </para> - </authorblurb> - </author> - - <author> - <firstname>Benjamin</firstname> - <surname>Kosnik</surname> - - <authorblurb> - <para> - Allocators, ABI, API evolution and deprecation history, - Backwards Compatibility, Thread, Debug Support, Locales, - Facets, Parallel Mode, Headers, Namespaces, Construction and - Structure, DocBook conversion and layout. - </para> - </authorblurb> - </author> - - - <author> - <firstname>Dhruv</firstname> - <surname>Matani</surname> - - <authorblurb> - <para> - bitmap_allocator - </para> - </authorblurb> - </author> - - <author> - <firstname>Jason</firstname> - <surname>Merrill</surname> - - <authorblurb> - <para> - License, __verbose_terminate_handler - </para> - </authorblurb> - </author> - - <author> - <firstname>Mark</firstname> - <surname>Mitchell</surname> - - <authorblurb> - <para> - Porting - </para> - </authorblurb> - </author> - - <author> - <firstname>Nathan</firstname> - <surname>Myers</surname> - - <authorblurb> - <para> - Referenced counted string, C++1998 implementation status. - </para> - </authorblurb> - </author> - - <author> - <firstname>Felix</firstname> - <surname>Natter</surname> - - <authorblurb> - <para> - Namespace composition, Backwards Compatibility. - </para> - </authorblurb> - </author> - - - <author> - <firstname>Stefan</firstname> - <surname>Olsson</surname> - - <authorblurb> - <para> - mt_allocator - </para> - </authorblurb> - </author> - - <author> - <firstname>Johannes</firstname> - <surname>Singler</surname> - - <authorblurb> - <para> - Parallel mode - </para> - </authorblurb> - </author> - - <author> - <firstname>Ami</firstname> - <surname>Tavory</surname> - - <authorblurb> - <para> - Policy Based Data Structures, Associative Containers, Unordered - Containers. - </para> - </authorblurb> - </author> - - <author> - <firstname>Jonathan</firstname> - <surname>Wakely</surname> - - <authorblurb> - <para> - shared_ptr, markup editing and styling - </para> - </authorblurb> - </author> - -</authorgroup> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/book.txml b/gcc-4.4.3/libstdc++-v3/doc/xml/book.txml deleted file mode 100644 index 990ca3bea..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/book.txml +++ /dev/null @@ -1,33 +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 id="api" xreflabel="Source Level Documentation"> -<title>Source Level Documentation</title> - -<bookinfo> - <copyright> - <year>2007</year> - <holder> - <ulink url="fsf.org">FSF - </ulink> - </holder> - </copyright> - <legalnotice> - <para> - <ulink url="17_intro/license.html">License - </ulink> - </para> - </legalnotice> -</bookinfo> - -<part> -<title></title> - <chapter> - <title></title> - <para></para> - </chapter> -</part> - -</book> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/chapter.txml b/gcc-4.4.3/libstdc++-v3/doc/xml/chapter.txml deleted file mode 100644 index 9cf5b74e8..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/chapter.txml +++ /dev/null @@ -1,54 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<chapter id="manual.intro" xreflabel="Introduction"> - -<chapterinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</chapterinfo> - -<title>Introduction</title> - -<sect1 id="manual.intro.status" xreflabel="Status"> - <title>Status</title> - <para> - The GNU C++ ... - </para> -</sect1> - -<sect1 id="manual.intro.setup" xreflabel="Setup"> - <title>Setup</title> - <para> - The GNU C++ ... - </para> - <sect2 id="manual.intro.setup.next1" xreflabel="Next1"> - <title>Next1</title> - <para> - The GNU C++ ... - </para> - </sect2> - <sect2 id="manual.intro.setup.next2" xreflabel="Next2"> - <title>Next2</title> - <para> - The GNU C++ ... - </para> - </sect2> -</sect1> - -<sect1 id="manual.intro.using" xreflabel="Using"> - <title>Using</title> - <para> - The GNU C++ ... - </para> -</sect1> - -</chapter> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/class.txml b/gcc-4.4.3/libstdc++-v3/doc/xml/class.txml deleted file mode 100644 index 4e628f8c7..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/class.txml +++ /dev/null @@ -1,154 +0,0 @@ -<sect1 id="manual.util.memory.allocator" xreflabel="allocator"> -<?dbhtml filename="allocator.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - allocator - </keyword> - </keywordset> -</sect1info> - -<title>allocator</title> - -<para> -</para> - -<sect2 id="allocator.req" xreflabel="allocator.req"> -<title>Requirements</title> - - <para> - </para> - <itemizedlist> - <listitem> - <para> - </para> - </listitem> - <listitem> - <para> - </para> - </listitem> - </itemizedlist> - - <para> - </para> -</sect2> - -<sect2 id="allocator.design_issues" xreflabel="allocator.design_issues"> -<title>Design Issues</title> - - <para> - </para> - - <para> - </para> -</sect2> - -<sect2 id="allocator.impl" xreflabel="allocator.impl"> -<title>Implementation</title> - - <sect3> - <title>Interface Design</title> - - <para> - </para> - - <para> - </para> - </sect3> - - <sect3> - <title>Selecting Default Allocation Strategy</title> - - <para> - </para> - - <orderedlist> - <listitem> - </listitem> - - <listitem> - </listitem> - - <listitem> - </listitem> - </orderedlist> - </sect3> - - <sect3> - <title>Disabling Memory Caching</title> - - <para> - </para> - - <para> - </para> - </sect3> -</sect2> - -<sect2 id="allocator.using" xreflabel="allocator.using"> -<title>Using</title> - - <para> - </para> -</sect2> - -<sect2 id="allocator.custom" xreflabel="allocator.custom"> -<title>Custom Allocators</title> - - <para> - </para> - - <para> - </para> -</sect2> - -<bibliography id="allocator.biblio" xreflabel="allocator.biblio"> -<title>Bibliography</title> - -<!-- - <biblioentry> - <abbrev> - </abbrev> - - <title> - </title> - - <editor> - <firstname></firstname> - <surname></surname> - </editor> - - <author> - <surname></surname> - <firstname></firstname> - </author> - - <copyright> - <year></year> - <holder></holder> - </copyright> - <pagenums></pagenums> - - <publisher> - <publishername> - </publishername> - </publisher> - - <biblioid> - <ulink url=""> - </ulink> - </biblioid> - - </biblioentry> ---> - - <biblioentry> - </biblioentry> - -</bibliography> - -</sect1>
\ No newline at end of file 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> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/fdl-1.2.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/fdl-1.2.xml deleted file mode 100644 index 8ad3a41c9..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/fdl-1.2.xml +++ /dev/null @@ -1,503 +0,0 @@ -<appendix id="appendix.gfdl-1.2"> - <?dbhtml filename="appendix_gfdl.html"?> - <title>GNU Free Documentation License</title> - <para> - Copyright (C) 2000, 2001, 2002 Free Software Foundation, - <abbrev>Inc.</abbrev> 51 Franklin <abbrev>St</abbrev>, Fifth Floor, - Boston, <abbrev>MA</abbrev> 02110-1301 <abbrev - role="initialism">USA</abbrev>. Everyone is permitted to copy and - distribute verbatim copies of this license document, but changing it is - not allowed. - </para> - <bridgehead id="fdl-1-preamble" renderas="sect1"> - 0. PREAMBLE - </bridgehead> - <para> - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to assure - everyone the effective freedom to copy and redistribute it, with or - without modifying it, either commercially or noncommercially. - Secondarily, this License preserves for the author and publisher a way to - get credit for their work, while not being considered responsible for - modifications made by others. - </para> - <para> - This License is a kind of "copyleft", which means that derivative works of - the document must themselves be free in the same sense. It complements - the GNU General Public License, which is a copyleft license designed for - free software. - </para> - <para> - We have designed this License in order to use it for manuals for free - software, because free software needs free documentation: a free program - should come with manuals providing the same freedoms that the software - does. But this License is not limited to software manuals; it can be used - for any textual work, regardless of subject matter or whether it is - published as a printed book. We recommend this License principally for - works whose purpose is instruction or reference.</para> - <bridgehead id="fdl-1-definitions" renderas="sect1"> - 1. APPLICABILITY AND DEFINITIONS - </bridgehead> - <para> - This License applies to any manual or other work, in any medium, that - contains a notice placed by the copyright holder saying it can be - distributed under the terms of this License. Such a notice grants a - world-wide, royalty-free license, unlimited in duration, to use that work - under the conditions stated herein. The "Document", below, refers to any - such manual or work. Any member of the public is a licensee, and is - addressed as "you". You accept the license if you copy, modify or - distribute the work in a way requiring permission under copyright - law. - </para> - <para> - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with modifications - and/or translated into another language. - </para> - <para> - A "Secondary Section" is a named appendix or a front-matter section of the - Document that deals exclusively with the relationship of the publishers or - authors of the Document to the Document's overall subject (or to related - matters) and contains nothing that could fall directly within that overall - subject. (Thus, if the Document is in part a textbook of mathematics, a - Secondary Section may not explain any mathematics.) The relationship - could be a matter of historical connection with the subject or with - related matters, or of legal, commercial, philosophical, ethical or - political position regarding them. - </para> - <para> - The "Invariant Sections" are certain Secondary Sections whose titles are - designated, as being those of Invariant Sections, in the notice that says - that the Document is released under this License. If a section does not - fit the above definition of Secondary then it is not allowed to be - designated as Invariant. The Document may contain zero Invariant - Sections. If the Document does not identify any Invariant Sections then - there are none. - </para> - <para> - The "Cover Texts" are certain short passages of text that are listed, as - Front-Cover Texts or Back-Cover Texts, in the notice that says that the - Document is released under this License. A Front-Cover Text may be at - most 5 words, and a Back-Cover Text may be at most 25 words. - </para> - <para> - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the general - public, that is suitable for revising the document straightforwardly with - generic text editors or (for images composed of pixels) generic paint - programs or (for drawings) some widely available drawing editor, and that - is suitable for input to text formatters or for automatic translation to a - variety of formats suitable for input to text formatters. A copy made in - an otherwise Transparent file format whose markup, or absence of markup, - has been arranged to thwart or discourage subsequent modification by - readers is not Transparent. An image format is not Transparent if used - for any substantial amount of text. A copy that is not "Transparent" is - called "Opaque". - </para> - <para> - Examples of suitable formats for Transparent copies include plain ASCII - without markup, Texinfo input format, LaTeX input format, SGML or XML - using a publicly available DTD, and standard-conforming simple HTML, - PostScript or PDF designed for human modification. Examples of - transparent image formats include PNG, XCF and JPG. Opaque formats - include proprietary formats that can be read and edited only by - proprietary word processors, SGML or XML for which the DTD and/or - processing tools are not generally available, and the machine-generated - HTML, PostScript or PDF produced by some word processors for output - purposes only. - </para> - <para> - The "Title Page" means, for a printed book, the title page itself, plus - such following pages as are needed to hold, legibly, the material this - License requires to appear in the title page. For works in formats which - do not have any title page as such, "Title Page" means the text near the - most prominent appearance of the work's title, preceding the beginning of - the body of the text. - </para> - <para> - A section "Entitled XYZ" means a named subunit of the Document whose title - either is precisely XYZ or contains XYZ in parentheses following text that - translates XYZ in another language. (Here XYZ stands for a specific - section name mentioned below, such as "Acknowledgements", "Dedications", - "Endorsements", or "History".) To "Preserve the Title" of such a section - when you modify the Document means that it remains a section "Entitled - XYZ" according to this definition. - </para> - <para> - The Document may include Warranty Disclaimers next to the notice which - states that this License applies to the Document. These Warranty - Disclaimers are considered to be included by reference in this License, - but only as regards disclaiming warranties: any other implication that - these Warranty Disclaimers may have is void and has no effect on the - meaning of this License. - </para> - <bridgehead id="VerbatimCopying" renderas="sect1"> - 2. VERBATIM COPYING - </bridgehead> - <para> - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the copyright - notices, and the license notice saying this License applies to the - Document are reproduced in all copies, and that you add no other - conditions whatsoever to those of this License. You may not use technical - measures to obstruct or control the reading or further copying of the - copies you make or distribute. However, you may accept compensation in - exchange for copies. If you distribute a large enough number of copies - you must also follow the conditions in section 3. - </para> - <para> - You may also lend copies, under the same conditions stated above, and you - may publicly display copies. - </para> - <bridgehead id="QuantityCopying" renderas="sect1"> - 3. COPYING IN QUANTITY - </bridgehead> - <para> - If you publish printed copies (or copies in media that commonly have - printed covers) of the Document, numbering more than 100, and the - Document's license notice requires Cover Texts, you must enclose the - copies in covers that carry, clearly and legibly, all these Cover Texts: - Front-Cover Texts on the front cover, and Back-Cover Texts on the back - cover. Both covers must also clearly and legibly identify you as the - publisher of these copies. The front cover must present the full title - with all words of the title equally prominent and visible. You may add - other material on the covers in addition. Copying with changes limited to - the covers, as long as they preserve the title of the Document and satisfy - these conditions, can be treated as verbatim copying in other - respects. - </para> - <para> - If the required texts for either cover are too voluminous to fit legibly, - you should put the first ones listed (as many as fit reasonably) on the - actual cover, and continue the rest onto adjacent pages. - </para> - <para> - If you publish or distribute Opaque copies of the Document numbering more - than 100, you must either include a machine-readable Transparent copy - along with each Opaque copy, or state in or with each Opaque copy a - computer-network location from which the general network-using public has - access to download using public-standard network protocols a complete - Transparent copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you begin - distribution of Opaque copies in quantity, to ensure that this Transparent - copy will remain thus accessible at the stated location until at least one - year after the last time you distribute an Opaque copy (directly or - through your agents or retailers) of that edition to the public. - </para> - <para> - It is requested, but not required, that you contact the authors of the - Document well before redistributing any large number of copies, to give - them a chance to provide you with an updated version of the - Document. - </para> - <bridgehead id="Modifications" renderas="sect1"> - 4. MODIFICATIONS - </bridgehead> - <para> - You may copy and distribute a Modified Version of the Document under the - conditions of sections 2 and 3 above, provided that you release the - Modified Version under precisely this License, with the Modified Version - filling the role of the Document, thus licensing distribution and - modification of the Modified Version to whoever possesses a copy of it. - In addition, you must do these things in the Modified Version: - </para> - <orderedlist numeration="upperalpha"> - <listitem> - <simpara> - Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions (which - should, if there were any, be listed in the History section of the - Document). You may use the same title as a previous version if the - original publisher of that version gives permission. - </simpara> - </listitem> - <listitem> - <simpara> - List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has fewer than five), - unless they release you from this requirement. - </simpara> - </listitem> - <listitem> - <simpara> - State on the Title page the name of the publisher of the Modified - Version, as the publisher. - </simpara> - </listitem> - <listitem> - <simpara> - Preserve all the copyright notices of the Document. - </simpara> - </listitem> - <listitem> - <simpara> - Add an appropriate copyright notice for your modifications adjacent to - the other copyright notices. - </simpara> - </listitem> - <listitem> - <simpara> - Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. - </simpara> - </listitem> - <listitem> - <simpara> - Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. - </simpara> - </listitem> - <listitem> - <simpara> - Include an unaltered copy of this License. - </simpara> - </listitem> - <listitem> - <simpara> - Preserve the section Entitled "History", Preserve its Title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section Entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - </simpara> - </listitem> - <listitem> - <simpara> - Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise the - network locations given in the Document for previous versions it was - based on. These may be placed in the "History" section. You may omit - a network location for a work that was published at least four years - before the Document itself, or if the original publisher of the - version it refers to gives permission. - </simpara> - </listitem> - <listitem> - <simpara> - For any section Entitled "Acknowledgements" or "Dedications", Preserve - the Title of the section, and preserve in the section all the - substance and tone of each of the contributor acknowledgements and/or - dedications given therein. - </simpara> - </listitem> - <listitem> - <simpara> - Preserve all the Invariant Sections of the Document, unaltered in - their text and in their titles. Section numbers or the equivalent are - not considered part of the section titles. - </simpara> - </listitem> - <listitem> - <simpara> - Delete any section Entitled "Endorsements". Such a section may not be - included in the Modified Version. - </simpara> - </listitem> - <listitem> - <simpara> - Do not retitle any existing section to be Entitled "Endorsements" or - to conflict in title with any Invariant Section. - </simpara> - </listitem> - <listitem> - <simpara> - Preserve any Warranty Disclaimers. - </simpara> - </listitem> - </orderedlist> - <para> - If the Modified Version includes new front-matter sections or appendices - that qualify as Secondary Sections and contain no material copied from the - Document, you may at your option designate some or all of these sections - as invariant. To do this, add their titles to the list of Invariant - Sections in the Modified Version's license notice. These titles must be - distinct from any other section titles. - </para> - <para> - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various parties--for - example, statements of peer review or that the text has been approved by - an organization as the authoritative definition of a standard. - </para> - <para> - You may add a passage of up to five words as a Front-Cover Text, and a - passage of up to 25 words as a Back-Cover Text, to the end of the list of - Cover Texts in the Modified Version. Only one passage of Front-Cover Text - and one of Back-Cover Text may be added by (or through arrangements made - by) any one entity. If the Document already includes a cover text for the - same cover, previously added by you or by arrangement made by the same - entity you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous publisher - that added the old one. - </para> - <para> - The author(s) and publisher(s) of the Document do not by this License give - permission to use their names for publicity for or to assert or imply - endorsement of any Modified Version. - </para> - <bridgehead id="Combining" renderas="sect1"> - 5. COMBINING DOCUMENTS - </bridgehead> - <para> - You may combine the Document with other documents released under this - License, under the terms defined in section 4 above for modified versions, - provided that you include in the combination all of the Invariant Sections - of all of the original documents, unmodified, and list them all as - Invariant Sections of your combined work in its license notice, and that - you preserve all their Warranty Disclaimers. - </para> - <para> - The combined work need only contain one copy of this License, and multiple - identical Invariant Sections may be replaced with a single copy. If there - are multiple Invariant Sections with the same name but different contents, - make the title of each such section unique by adding at the end of it, in - parentheses, the name of the original author or publisher of that section - if known, or else a unique number. Make the same adjustment to the - section titles in the list of Invariant Sections in the license notice of - the combined work. - </para> - <para> - In the combination, you must combine any sections Entitled "History" in - the various original documents, forming one section Entitled "History"; - likewise combine any sections Entitled "Acknowledgements", and any - sections Entitled "Dedications". You must delete all sections Entitled - "Endorsements". - </para> - <bridgehead id="Collections" renderas="sect1"> - 6. COLLECTIONS OF DOCUMENTS - </bridgehead> - <para> - You may make a collection consisting of the Document and other documents - released under this License, and replace the individual copies of this - License in the various documents with a single copy that is included in - the collection, provided that you follow the rules of this License for - verbatim copying of each of the documents in all other respects. - </para> - <para> - You may extract a single document from such a collection, and distribute - it individually under this License, provided you insert a copy of this - License into the extracted document, and follow this License in all other - respects regarding verbatim copying of that document. - </para> - <bridgehead id="Aggregation" renderas="sect1"> - 7. AGGREGATION WITH INDEPENDENT WORKS - </bridgehead> - <para> - A compilation of the Document or its derivatives with other separate and - independent documents or works, in or on a volume of a storage or - distribution medium, is called an "aggregate" if the copyright resulting - from the compilation is not used to limit the legal rights of the - compilation's users beyond what the individual works permit. When the - Document is included in an aggregate, this License does not apply to the - other works in the aggregate which are not themselves derivative works of - the Document. - </para> - <para> - If the Cover Text requirement of section 3 is applicable to these copies - of the Document, then if the Document is less than one half of the entire - aggregate, the Document's Cover Texts may be placed on covers that bracket - the Document within the aggregate, or the electronic equivalent of covers - if the Document is in electronic form. Otherwise they must appear on - printed covers that bracket the whole aggregate. - </para> - <bridgehead id="Translation" renderas="sect1"> - 8. TRANSLATION - </bridgehead> - <para> - Translation is considered a kind of modification, so you may distribute - translations of the Document under the terms of section 4. Replacing - Invariant Sections with translations requires special permission from - their copyright holders, but you may include translations of some or all - Invariant Sections in addition to the original versions of these Invariant - Sections. You may include a translation of this License, and all the - license notices in the Document, and any Warranty Disclaimers, provided - that you also include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of this - License or a notice or disclaimer, the original version will prevail. - </para> - <para> - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to Preserve its - Title (section 1) will typically require changing the actual title. - </para> - <bridgehead id="fdl-1-termination" renderas="sect1"> - 9. TERMINATION - </bridgehead> - <para> - You may not copy, modify, sublicense, or distribute the Document except as - expressly provided for under this License. Any other attempt to copy, - modify, sublicense or distribute the Document is void, and will - automatically terminate your rights under this License. However, parties - who have received copies, or rights, from you under this License will not - have their licenses terminated so long as such parties remain in full - compliance. - </para> - <bridgehead id="FutureRevisions" renderas="sect1"> - 10. FUTURE REVISIONS OF THIS LICENSE - </bridgehead> - <para> - The Free Software Foundation may publish new, revised versions of the GNU - Free Documentation License from time to time. Such new versions will be - similar in spirit to the present version, but may differ in detail to - address new problems or concerns. See <ulink - url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>. - </para> - <para> - Each version of the License is given a distinguishing version number. If - the Document specifies that a particular numbered version of this License - "or any later version" applies to it, you have the option of following the - terms and conditions either of that specified version or of any later - version that has been published (not as a draft) by the Free Software - Foundation. If the Document does not specify a version number of this - License, you may choose any version ever published (not as a draft) by the - Free Software Foundation. - </para> - <bridgehead id="HowToUse" renderas="sect1"> - ADDENDUM: How to use this License for your documents - </bridgehead> - <para> - To use this License in a document you have written, include a copy of the - License in the document and put the following copyright and license - notices just after the title page: - </para> - <blockquote> - <para> - Copyright (C) YEAR YOUR NAME. - </para> - <para> - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with no - Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A - copy of the license is included in the section entitled "GNU Free - Documentation License". - </para> - </blockquote> - <para> - If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, - replace the "with...Texts." line with this: - </para> - <blockquote> - <para> - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - </para> - </blockquote> - <para> - If you have Invariant Sections without Cover Texts, or some other - combination of the three, merge those two alternatives to suit the - situation. - </para> - <para> - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of free - software license, such as the GNU General Public License, to permit their - use in free software. - </para> -</appendix> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/gpl-2.0.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/gpl-2.0.xml deleted file mode 100644 index 151a9523f..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/gpl-2.0.xml +++ /dev/null @@ -1,366 +0,0 @@ -<?xml version='1.0' encoding='ISO-8859-1'?> -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<appendix id="appendix.gpl-2.0"> - <appendixinfo> - <title>GNU General Public License</title> - <pubdate>Version 2, June 1991</pubdate> - <copyright> - <year>1989, 1991</year> - <holder>Free Software Foundation, Inc.</holder> - </copyright> - <legalnotice id="gpl-legalnotice"> - <para> - <address>Free Software Foundation, Inc. - <street>51 Franklin Street, Fifth Floor</street>, - <city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode> - <country>USA</country> - </address> - </para> - <para>Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.</para> - </legalnotice> - <releaseinfo>Version 2, June 1991</releaseinfo> - </appendixinfo> - <title>GNU General Public License</title> - <section id="gpl-1"> - <title>Preamble</title> - <para>The licenses for most software are designed to take away your - freedom to share and change it. By contrast, the GNU General Public License is - intended to guarantee your freedom to share and change - free software - to make sure the software is free for all its users. - This General Public License applies to most of the Free Software - Foundation's software and to any other program whose authors commit - to using it. (Some other Free Software Foundation software is covered - by the GNU Library General Public License instead.) You can apply it - to your programs, too.</para> - - <para>When we speak of free software, we are referring to freedom, not price. - Our General Public Licenses are designed to make sure that you have the - freedom to distribute copies of free software (and charge for this - service if you wish), that you receive source code or can get it if you - want it, that you can change the software or use pieces of it in new free - programs; and that you know you can do these things.</para> - - <para>To protect your rights, we need to make restrictions that forbid anyone - to deny you these rights or to ask you to surrender the rights. These - restrictions translate to certain responsibilities for you if you distribute - copies of the software, or if you modify it.</para> - - <para>For example, if you distribute copies of such a program, whether gratis or - for a fee, you must give the recipients all the rights that you have. You - must make sure that they, too, receive or can get the source code. And you - must show them these terms so they know their rights.</para> - - <para>We protect your rights with two steps: - <orderedlist> - <listitem> - <para>copyright the software, and</para> - </listitem> - <listitem> - <para>offer you this license which gives you legal permission to copy, - distribute and/or modify the software.</para> - </listitem> - </orderedlist> - </para> - - <para>Also, for each author's protection and ours, we want to make certain that - everyone understands that there is no warranty for this free software. If - the software is modified by someone else and passed on, we want its - recipients to know that what they have is not the original, so that any - problems introduced by others will not reflect on the original authors' - reputations.</para> - - <para>Finally, any free program is threatened constantly by software patents. - We wish to avoid the danger that redistributors of a free program will - individually obtain patent licenses, in effect making the program - proprietary. To prevent this, we have made it clear that any patent must be - licensed for everyone's free use or not licensed at all.</para> - - <para>The precise terms and conditions for copying, distribution and modification - follow.</para> - </section> - <section id="gpl-2"> - <title>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</title> - <section id="gpl-2-0"> - <title>Section 0</title> - <para>This License applies to any program or other work which contains a notice - placed by the copyright holder saying it may be distributed under the terms - of this General Public License. The <quote>Program</quote>, below, refers to any such - program or work, and a - <quote>work based on the Program</quote> means either - the Program or any derivative work under copyright law: that is to say, a - work containing the Program or a portion of it, either verbatim or with - modifications and/or translated into another language. (Hereinafter, translation - is included without limitation in the term - <quote>modification</quote>.) Each licensee is addressed as <quote>you</quote>.</para> - - <para>Activities other than copying, distribution and modification are not covered by - this License; they are outside its scope. The act of running the Program is not - restricted, and the output from the Program is covered only if its contents - constitute a work based on the Program (independent of having been made by running - the Program). Whether that is true depends on what the Program does.</para> - </section> - <section id="gpl-2-1"> - <title>Section 1</title> - <para>You may copy and distribute verbatim copies of the Program's source code as you - receive it, in any medium, provided that you conspicuously and appropriately - publish on each copy an appropriate copyright notice and disclaimer of warranty; - keep intact all the notices that refer to this License and to the absence of any - warranty; and give any other recipients of the Program a copy of this License - along with the Program.</para> - - <para>You may charge a fee for the physical act of transferring a copy, and you may at - your option offer warranty protection in exchange for a fee.</para> - </section> - <section id="gpl-2-2"> - <title>Section 2</title> - <para>You may modify your copy or copies of the Program or any portion of it, thus - forming a work based on the Program, and copy and distribute such modifications - or work under the terms of - <link linkend="gpl-2-1">Section 1</link> above, provided - that you also meet all of these conditions: - <orderedlist numeration="loweralpha"> - <listitem> - <para>You must cause the modified files to carry prominent notices stating that - you changed the files and the date of any change.</para> - </listitem> - <listitem> - <para>You must cause any work that you distribute or publish, that in whole or - in part contains or is derived from the Program or any part thereof, to be - licensed as a whole at no charge to all third parties under the terms of - this License.</para> - </listitem> - <listitem> - <para>If the modified program normally reads commands interactively when run, you - must cause it, when started running for such interactive use in the most - ordinary way, to print or display an announcement including an appropriate - copyright notice and a notice that there is no warranty (or else, saying - that you provide a warranty) and that users may redistribute the program - under these conditions, and telling the user how to view a copy of this - License. (Exception: If the Program itself is interactive but does not - normally print such an announcement, your work based on the Program is not - required to print an announcement.)</para> - </listitem> - </orderedlist> - </para> - - <para>These requirements apply to the modified work as a whole. If identifiable sections - of that work are not derived from the Program, and can be reasonably considered - independent and separate works in themselves, then this License, and its terms, - do not apply to those sections when you distribute them as separate works. But when - you distribute the same sections as part of a whole which is a work based on the - Program, the distribution of the whole must be on the terms of this License, whose - permissions for other licensees extend to the entire whole, and thus to each and - every part regardless of who wrote it.</para> - - <para>Thus, it is not the intent of this section to claim rights or contest your rights - to work written entirely by you; rather, the intent is to exercise the right to control - the distribution of derivative or collective works based on the Program.</para> - - <para>In addition, mere aggregation of another work not based on the Program with the Program - (or with a work based on the Program) on a volume of a storage or distribution medium - does not bring the other work under the scope of this License.</para> - </section> - <section id="gpl-2-3"> - <title>Section 3</title> - <para>You may copy and distribute the Program (or a work based on it, under - <link linkend="gpl-2-2">Section 2</link> in object code or executable form under the terms of - <link linkend="gpl-2-1">Sections 1</link> and - <link linkend="gpl-2-2">2</link> above provided that you also do one of the following: - <orderedlist numeration="loweralpha"> - <listitem> - <para>Accompany it with the complete corresponding machine-readable source code, which - must be distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or,</para> - </listitem> - <listitem> - <para>Accompany it with a written offer, valid for at least three years, to give any - third party, for a charge no more than your cost of physically performing source - distribution, a complete machine-readable copy of the corresponding source code, - to be distributed under the terms of Sections 1 and 2 above on a medium customarily - used for software interchange; or,</para> - </listitem> - <listitem> - <para>Accompany it with the information you received as to the offer to distribute - corresponding source code. (This alternative is allowed only for noncommercial - distribution and only if you received the program in object code or executable form - with such an offer, in accord with Subsection b above.)</para> - </listitem> - </orderedlist> - </para> - - <para>The source code for a work means the preferred form of the work for making modifications - to it. For an executable work, complete source code means all the source code for all modules - it contains, plus any associated interface definition files, plus the scripts used to control - compilation and installation of the executable. However, as a special exception, the source - code distributed need not include anything that is normally distributed (in either source or - binary form) with the major components (compiler, kernel, and so on) of the operating system - on which the executable runs, unless that component itself accompanies the executable.</para> - - <para>If distribution of executable or object code is made by offering access to copy from a - designated place, then offering equivalent access to copy the source code from the same place - counts as distribution of the source code, even though third parties are not compelled to - copy the source along with the object code.</para> - </section> - <section id="gpl-2-4"> - <title>Section 4</title> - <para>You may not copy, modify, sublicense, or distribute the Program except as expressly provided - under this License. Any attempt otherwise to copy, modify, sublicense or distribute the - Program is void, and will automatically terminate your rights under this License. However, - parties who have received copies, or rights, from you under this License will not have their - licenses terminated so long as such parties remain in full compliance.</para> - </section> - <section id="gpl-2-5"> - <title>Section 5</title> - <para>You are not required to accept this License, since you have not signed it. However, nothing - else grants you permission to modify or distribute the Program or its derivative works. - These actions are prohibited by law if you do not accept this License. Therefore, by modifying - or distributing the Program (or any work based on the Program), you indicate your acceptance - of this License to do so, and all its terms and conditions for copying, distributing or - modifying the Program or works based on it.</para> - </section> - <section id="gpl-2-6"> - <title>Section 6</title> - <para>Each time you redistribute the Program (or any work based on the Program), the recipient - automatically receives a license from the original licensor to copy, distribute or modify - the Program subject to these terms and conditions. You may not impose any further restrictions - on the recipients' exercise of the rights granted herein. You are not responsible for enforcing - compliance by third parties to this License.</para> - </section> - <section id="gpl-2-7"> - <title>Section 7</title> - <para>If, as a consequence of a court judgment or allegation of patent infringement or for any other - reason (not limited to patent issues), conditions are imposed on you (whether by court order, - agreement or otherwise) that contradict the conditions of this License, they do not excuse you - from the conditions of this License. If you cannot distribute so as to satisfy simultaneously - your obligations under this License and any other pertinent obligations, then as a consequence - you may not distribute the Program at all. For example, if a patent license would not permit - royalty-free redistribution of the Program by all those who receive copies directly or - indirectly through you, then the only way you could satisfy both it and this License would be - to refrain entirely from distribution of the Program.</para> - - <para>If any portion of this section is held invalid or unenforceable under any particular circumstance, - the balance of the section is intended to apply and the section as a whole is intended to apply - in other circumstances.</para> - - <para>It is not the purpose of this section to induce you to infringe any patents or other property - right claims or to contest validity of any such claims; this section has the sole purpose of - protecting the integrity of the free software distribution system, which is implemented by public - license practices. Many people have made generous contributions to the wide range of software - distributed through that system in reliance on consistent application of that system; it is up - to the author/donor to decide if he or she is willing to distribute software through any other - system and a licensee cannot impose that choice.</para> - - <para>This section is intended to make thoroughly clear what is believed to be a consequence of the - rest of this License.</para> - </section> - <section id="gpl-2-8"> - <title>Section 8</title> - <para>If the distribution and/or use of the Program is restricted in certain countries either by patents - or by copyrighted interfaces, the original copyright holder who places the Program under this License - may add an explicit geographical distribution limitation excluding those countries, so that - distribution is permitted only in or among countries not thus excluded. In such case, this License - incorporates the limitation as if written in the body of this License.</para> - </section> - <section id="gpl-2-9"> - <title>Section 9</title> - <para>The Free Software Foundation may publish revised and/or new versions of the General Public License - from time to time. Such new versions will be similar in spirit to the present version, but may differ - in detail to address new problems or concerns.</para> - - <para>Each version is given a distinguishing version number. If the Program specifies a version number of - this License which applies to it and <quote>any later version</quote>, you have the option of following the terms - and conditions either of that version or of any later version published by the Free Software - Foundation. If the Program does not specify a version number of this License, you may choose any - version ever published by the Free Software Foundation.</para> - </section> - <section id="gpl-2-10"> - <title>Section 10</title> - <para>If you wish to incorporate parts of the Program into other free programs whose distribution - conditions are different, write to the author to ask for permission. For software which is copyrighted - by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions - for this. Our decision will be guided by the two goals of preserving the free status of all - derivatives of our free software and of promoting the sharing and reuse of software generally.</para> - </section> - <section id="gpl-2-11"> - <title>NO WARRANTY Section 11</title> - <para>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT - PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR - OTHER PARTIES PROVIDE THE PROGRAM <quote>AS IS</quote> WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, - INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE - PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</para> - </section> - <section id="gpl-2-12"> - <title>Section 12</title> - <para>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR - ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU - FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE - USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED - INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH - ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH - DAMAGES.</para> - - <para>END OF TERMS AND CONDITIONS</para> - </section> - </section> - <section id="gpl-3"> - <title>How to Apply These Terms to Your New Programs</title> - <para>If you develop a new program, and you want it to be of the greatest - possible use to the public, the best way to achieve this is to make it - free software which everyone can redistribute and change under these terms.</para> - - <para>To do so, attach the following notices to the program. It is safest - to attach them to the start of each source file to most effectively - convey the exclusion of warranty; and each file should have at least - the <quote>copyright</quote> line and a pointer to where the full notice is found.</para> - - <para><one line to give the program's name and a brief idea of what it does.> - Copyright (C) <year> <name of author></para> - - <para>This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version.</para> - - <para>This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details.</para> - - <para>You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA</para> - - <para>Also add information on how to contact you by electronic and paper mail.</para> - - <para>If the program is interactive, make it output a short notice like this - when it starts in an interactive mode:</para> - - <para>Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type <quote>show w</quote>. - This is free software, and you are welcome to redistribute it - under certain conditions; type <quote>show c</quote> for details.</para> - - <para>The hypothetical commands <quote>show w</quote> and <quote>show c</quote> should - show the appropriate parts of the General Public License. Of course, the commands you - use may be called something other than <quote>show w</quote> and <quote>show c</quote>; - they could even be mouse-clicks or menu items--whatever suits your program.</para> - - <para>You should also get your employer (if you work as a programmer) or your - school, if any, to sign a <quote>copyright disclaimer</quote> for the program, if - necessary. Here is a sample; alter the names:</para> - - <para>Yoyodyne, Inc., hereby disclaims all copyright interest in the program - <quote>Gnomovision</quote> (which makes passes at compilers) written by James Hacker.</para> - - <para><signature of Ty Coon>, 1 April 1989 - Ty Coon, President of Vice</para> - - <para>This General Public License does not permit incorporating your program into - proprietary programs. If your program is a subroutine library, you may - consider it more useful to permit linking proprietary applications with the - library. If this is what you want to do, use the GNU Library General - Public License instead of this License.</para> - </section> -</appendix> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/gpl-3.0.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/gpl-3.0.xml deleted file mode 100644 index 1d9a8c589..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/gnu/gpl-3.0.xml +++ /dev/null @@ -1,837 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<appendix id="appendix.gpl-3.0"> - <?dbhtml filename="appendix_gpl.html"?> - <title> - <acronym>GNU</acronym> General Public License version 3 - </title> - <para> - Version 3, 29 June 2007 - </para> - <para> - Copyright © 2007 Free Software Foundation, Inc. - <ulink url="http://fsf.org/">http://fsf.org/</ulink> - </para> - <para> - Everyone is permitted to copy and distribute verbatim copies of this license - document, but changing it is not allowed. - </para> - <bridgehead id="gpl-3-preamble" renderas="sect1"> - Preamble - </bridgehead> - <para> - The <acronym>GNU</acronym> General Public License is a free, copyleft - license for software and other kinds of works. - </para> - <para> - The licenses for most software and other practical works are designed to - take away your freedom to share and change the works. By contrast, the - <acronym>GNU</acronym> General Public License is intended to guarantee your - freedom to share and change all versions of a program—to make sure it - remains free software for all its users. We, the Free Software Foundation, - use the <acronym>GNU</acronym> General Public License for most of our - software; it applies also to any other work released this way by its - authors. You can apply it to your programs, too. - </para> - <para> - When we speak of free software, we are referring to freedom, not price. Our - General Public Licenses are designed to make sure that you have the freedom - to distribute copies of free software (and charge for them if you wish), - that you receive source code or can get it if you want it, that you can - change the software or use pieces of it in new free programs, and that you - know you can do these things. - </para> - <para> - To protect your rights, we need to prevent others from denying you these - rights or asking you to surrender the rights. Therefore, you have certain - responsibilities if you distribute copies of the software, or if you modify - it: responsibilities to respect the freedom of others. - </para> - <para> - For example, if you distribute copies of such a program, whether gratis or - for a fee, you must pass on to the recipients the same freedoms that you - received. You must make sure that they, too, receive or can get the source - code. And you must show them these terms so they know their rights. - </para> - <para> - Developers that use the <acronym>GNU</acronym> <acronym>GPL</acronym> - protect your rights with two steps: (1) assert copyright on the software, - and (2) offer you this License giving you legal permission to copy, - distribute and/or modify it. - </para> - <para> - For the developers’ and authors’ protection, the - <acronym>GPL</acronym> clearly explains that there is no warranty for this - free software. For both users’ and authors’ sake, the - <acronym>GPL</acronym> requires that modified versions be marked as changed, - so that their problems will not be attributed erroneously to authors of - previous versions. - </para> - <para> - Some devices are designed to deny users access to install or run modified - versions of the software inside them, although the manufacturer can do so. - This is fundamentally incompatible with the aim of protecting users’ - freedom to change the software. The systematic pattern of such abuse occurs - in the area of products for individuals to use, which is precisely where it - is most unacceptable. Therefore, we have designed this version of the - <acronym>GPL</acronym> to prohibit the practice for those products. If such - problems arise substantially in other domains, we stand ready to extend this - provision to those domains in future versions of the <acronym>GPL</acronym>, - as needed to protect the freedom of users. - </para> - <para> - Finally, every program is threatened constantly by software patents. States - should not allow patents to restrict development and use of software on - general-purpose computers, but in those that do, we wish to avoid the - special danger that patents applied to a free program could make it - effectively proprietary. To prevent this, the <acronym>GPL</acronym> - assures that patents cannot be used to render the program non-free. - </para> - <para> - The precise terms and conditions for copying, distribution and modification - follow. - </para> - <bridgehead> - TERMS AND CONDITIONS - </bridgehead> - <bridgehead id="gpl-3-definitions" renderas="sect1"> - 0. Definitions. - </bridgehead> - <para> - “This License” refers to version 3 of the <acronym>GNU</acronym> - General Public License. - </para> - <para> - “Copyright” also means copyright-like laws that apply to other - kinds of works, such as semiconductor masks. - </para> - <para> - “The Program” refers to any copyrightable work licensed under - this License. Each licensee is addressed as “you”. - “Licensees” and “recipients” may be individuals or - organizations. - </para> - <para> - To “modify” a work means to copy from or adapt all or part of - the work in a fashion requiring copyright permission, other than the making - of an exact copy. The resulting work is called a “modified - version” of the earlier work or a work “based on” the - earlier work. - </para> - <para> - A “covered work” means either the unmodified Program or a work - based on the Program. - </para> - <para> - To “propagate” a work means to do anything with it that, without - permission, would make you directly or secondarily liable for infringement - under applicable copyright law, except executing it on a computer or - modifying a private copy. Propagation includes copying, distribution (with - or without modification), making available to the public, and in some - countries other activities as well. - </para> - <para> - To “convey” a work means any kind of propagation that enables - other parties to make or receive copies. Mere interaction with a user - through a computer network, with no transfer of a copy, is not conveying. - </para> - <para> - An interactive user interface displays “Appropriate Legal - Notices” to the extent that it includes a convenient and prominently - visible feature that (1) displays an appropriate copyright notice, and (2) - tells the user that there is no warranty for the work (except to the extent - that warranties are provided), that licensees may convey the work under this - License, and how to view a copy of this License. If the interface presents - a list of user commands or options, such as a menu, a prominent item in the - list meets this criterion. - </para> - <bridgehead id="SourceCode" renderas="sect1"> - 1. Source Code. - </bridgehead> - <para> - The “source code” for a work means the preferred form of the - work for making modifications to it. “Object code” means any - non-source form of a work. - </para> - <para> - A “Standard Interface” means an interface that either is an - official standard defined by a recognized standards body, or, in the case of - interfaces specified for a particular programming language, one that is - widely used among developers working in that language. - </para> - <para> - The “System Libraries” of an executable work include anything, - other than the work as a whole, that (a) is included in the normal form of - packaging a Major Component, but which is not part of that Major Component, - and (b) serves only to enable use of the work with that Major Component, or - to implement a Standard Interface for which an implementation is available - to the public in source code form. A “Major Component”, in this - context, means a major essential component (kernel, window system, and so - on) of the specific operating system (if any) on which the executable work - runs, or a compiler used to produce the work, or an object code interpreter - used to run it. - </para> - <para> - The “Corresponding Source” for a work in object code form means - all the source code needed to generate, install, and (for an executable - work) run the object code and to modify the work, including scripts to - control those activities. However, it does not include the work’s - System Libraries, or general-purpose tools or generally available free - programs which are used unmodified in performing those activities but which - are not part of the work. For example, Corresponding Source includes - interface definition files associated with source files for the work, and - the source code for shared libraries and dynamically linked subprograms that - the work is specifically designed to require, such as by intimate data - communication or control flow between those subprograms and other parts of - the work. - </para> - <para> - The Corresponding Source need not include anything that users can regenerate - automatically from other parts of the Corresponding Source. - </para> - <para> - The Corresponding Source for a work in source code form is that same work. - </para> - <bridgehead id="BasicPermissions" renderas="sect1"> - 2. Basic Permissions. - </bridgehead> - <para> - All rights granted under this License are granted for the term of copyright - on the Program, and are irrevocable provided the stated conditions are met. - This License explicitly affirms your unlimited permission to run the - unmodified Program. The output from running a covered work is covered by - this License only if the output, given its content, constitutes a covered - work. This License acknowledges your rights of fair use or other - equivalent, as provided by copyright law. - </para> - <para> - You may make, run and propagate covered works that you do not convey, - without conditions so long as your license otherwise remains in force. You - may convey covered works to others for the sole purpose of having them make - modifications exclusively for you, or provide you with facilities for - running those works, provided that you comply with the terms of this License - in conveying all material for which you do not control copyright. Those - thus making or running the covered works for you must do so exclusively on - your behalf, under your direction and control, on terms that prohibit them - from making any copies of your copyrighted material outside their - relationship with you. - </para> - <para> - Conveying under any other circumstances is permitted solely under the - conditions stated below. Sublicensing is not allowed; section 10 makes it - unnecessary. - </para> - <bridgehead id="Protecting" renderas="sect1"> - 3. Protecting Users’ Legal Rights From Anti-Circumvention Law. - </bridgehead> - <para> - No covered work shall be deemed part of an effective technological measure - under any applicable law fulfilling obligations under article 11 of the WIPO - copyright treaty adopted on 20 December 1996, or similar laws prohibiting or - restricting circumvention of such measures. - </para> - <para> - When you convey a covered work, you waive any legal power to forbid - circumvention of technological measures to the extent such circumvention is - effected by exercising rights under this License with respect to the covered - work, and you disclaim any intention to limit operation or modification of - the work as a means of enforcing, against the work’s users, your or - third parties’ legal rights to forbid circumvention of technological - measures. - </para> - <bridgehead id="ConveyingVerbatim" renderas="sect1"> - 4. Conveying Verbatim Copies. - </bridgehead> - <para> - You may convey verbatim copies of the Program’s source code as you - receive it, in any medium, provided that you conspicuously and appropriately - publish on each copy an appropriate copyright notice; keep intact all - notices stating that this License and any non-permissive terms added in - accord with section 7 apply to the code; keep intact all notices of the - absence of any warranty; and give all recipients a copy of this License - along with the Program. - </para> - <para> - You may charge any price or no price for each copy that you convey, and you - may offer support or warranty protection for a fee. - </para> - <bridgehead id="ConveyingModified" renderas="sect1"> - 5. Conveying Modified Source Versions. - </bridgehead> - <para> - You may convey a work based on the Program, or the modifications to produce - it from the Program, in the form of source code under the terms of section - 4, provided that you also meet all of these conditions: - </para> - <orderedlist numeration="loweralpha"> - <listitem> - <para> - The work must carry prominent notices stating that you modified it, and - giving a relevant date. - </para> - </listitem> - <listitem> - <para> - The work must carry prominent notices stating that it is released under - this License and any conditions added under section 7. This requirement - modifies the requirement in section 4 to “keep intact all - notices”. - </para> - </listitem> - <listitem> - <para> - You must license the entire work, as a whole, under this License to - anyone who comes into possession of a copy. This License will therefore - apply, along with any applicable section 7 additional terms, to the - whole of the work, and all its parts, regardless of how they are - packaged. This License gives no permission to license the work in any - other way, but it does not invalidate such permission if you have - separately received it. - </para> - </listitem> - <listitem> - <para> - If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has interactive - interfaces that do not display Appropriate Legal Notices, your work need - not make them do so. - </para> - </listitem> - </orderedlist> - <para> - A compilation of a covered work with other separate and independent works, - which are not by their nature extensions of the covered work, and which are - not combined with it such as to form a larger program, in or on a volume of - a storage or distribution medium, is called an “aggregate” if - the compilation and its resulting copyright are not used to limit the access - or legal rights of the compilation’s users beyond what the individual works - permit. Inclusion of a covered work in an aggregate does not cause - this License to apply to the other parts of the aggregate. - </para> - <bridgehead id="ConveyingNonSource" renderas="sect1"> - 6. Conveying Non-Source Forms. - </bridgehead> - <para> - You may convey a covered work in object code form under the terms of - sections 4 and 5, provided that you also convey the machine-readable - Corresponding Source under the terms of this License, in one of these ways: - </para> - <orderedlist numeration="loweralpha"> - <listitem> - <para> - Convey the object code in, or embodied in, a physical product (including - a physical distribution medium), accompanied by the Corresponding Source - fixed on a durable physical medium customarily used for software - interchange. - </para> - </listitem> - <listitem> - <para> - Convey the object code in, or embodied in, a physical product (including - a physical distribution medium), accompanied by a written offer, valid - for at least three years and valid for as long as you offer spare parts - or customer support for that product model, to give anyone who possesses - the object code either (1) a copy of the Corresponding Source for all - the software in the product that is covered by this License, on a - durable physical medium customarily used for software interchange, for a - price no more than your reasonable cost of physically performing this - conveying of source, or (2) access to copy the Corresponding Source from - a network server at no charge. - </para> - </listitem> - <listitem> - <para> - Convey individual copies of the object code with a copy of the written - offer to provide the Corresponding Source. This alternative is allowed - only occasionally and noncommercially, and only if you received the - object code with such an offer, in accord with subsection 6b. - </para> - </listitem> - <listitem> - <para> - Convey the object code by offering access from a designated place - (gratis or for a charge), and offer equivalent access to the - Corresponding Source in the same way through the same place at no - further charge. You need not require recipients to copy the - Corresponding Source along with the object code. If the place to copy - the object code is a network server, the Corresponding Source may be on - a different server (operated by you or a third party) that supports - equivalent copying facilities, provided you maintain clear directions - next to the object code saying where to find the Corresponding Source. - Regardless of what server hosts the Corresponding Source, you remain - obligated to ensure that it is available for as long as needed to - satisfy these requirements. - </para> - </listitem> - <listitem> - <para> - Convey the object code using peer-to-peer transmission, provided you - inform other peers where the object code and Corresponding Source of the - work are being offered to the general public at no charge under - subsection 6d. - </para> - </listitem> - </orderedlist> - <para> - A separable portion of the object code, whose source code is excluded from - the Corresponding Source as a System Library, need not be included in - conveying the object code work. - </para> - <para> - A “User Product” is either (1) a “consumer product”, - which means any tangible personal property which is normally used for - personal, family, or household purposes, or (2) anything designed or sold - for incorporation into a dwelling. In determining whether a product is a - consumer product, doubtful cases shall be resolved in favor of coverage. - For a particular product received by a particular user, “normally - used” refers to a typical or common use of that class of product, - regardless of the status of the particular user or of the way in which the - particular user actually uses, or expects or is expected to use, the - product. A product is a consumer product regardless of whether the product - has substantial commercial, industrial or non-consumer uses, unless such - uses represent the only significant mode of use of the product. - </para> - <para> - “Installation Information” for a User Product means any methods, - procedures, authorization keys, or other information required to install and - execute modified versions of a covered work in that User Product from a - modified version of its Corresponding Source. The information must suffice - to ensure that the continued functioning of the modified object code is in - no case prevented or interfered with solely because modification has been - made. - </para> - <para> - If you convey an object code work under this section in, or with, or - specifically for use in, a User Product, and the conveying occurs as part of - a transaction in which the right of possession and use of the User Product - is transferred to the recipient in perpetuity or for a fixed term - (regardless of how the transaction is characterized), the Corresponding - Source conveyed under this section must be accompanied by the Installation - Information. But this requirement does not apply if neither you nor any - third party retains the ability to install modified object code on the User - Product (for example, the work has been installed in - <acronym>ROM</acronym>). - </para> - <para> - The requirement to provide Installation Information does not include a - requirement to continue to provide support service, warranty, or updates for - a work that has been modified or installed by the recipient, or for the User - Product in which it has been modified or installed. Access to a network may - be denied when the modification itself materially and adversely affects the - operation of the network or violates the rules and protocols for - communication across the network. - </para> - <para> - Corresponding Source conveyed, and Installation Information provided, in - accord with this section must be in a format that is publicly documented - (and with an implementation available to the public in source code form), - and must require no special password or key for unpacking, reading or - copying. - </para> - <bridgehead id="AdditionalTerms" renderas="sect1"> - 7. Additional Terms. - </bridgehead> - <para> - “Additional permissions” are terms that supplement the terms of - this License by making exceptions from one or more of its conditions. - Additional permissions that are applicable to the entire Program shall be - treated as though they were included in this License, to the extent that - they are valid under applicable law. If additional permissions apply only - to part of the Program, that part may be used separately under those - permissions, but the entire Program remains governed by this License - without regard to the additional permissions. - </para> - <para> - When you convey a copy of a covered work, you may at your option remove any - additional permissions from that copy, or from any part of it. (Additional - permissions may be written to require their own removal in certain cases - when you modify the work.) You may place additional permissions on - material, added by you to a covered work, for which you have or can give - appropriate copyright permission. - </para> - <para> - Notwithstanding any other provision of this License, for material you add - to a covered work, you may (if authorized by the copyright holders of that - material) supplement the terms of this License with terms: - </para> - <orderedlist numeration="loweralpha"> - <listitem> - <para> - Disclaiming warranty or limiting liability differently from the terms - of sections 15 and 16 of this License; or - </para> - </listitem> - <listitem> - <para> - Requiring preservation of specified reasonable legal notices or author - attributions in that material or in the Appropriate Legal Notices - displayed by works containing it; or - </para> - </listitem> - <listitem> - <para> - Prohibiting misrepresentation of the origin of that material, or - requiring that modified versions of such material be marked in - reasonable ways as different from the original version; or - </para> - </listitem> - <listitem> - <para> - Limiting the use for publicity purposes of names of licensors or - authors of the material; or - </para> - </listitem> - <listitem> - <para> - Declining to grant rights under trademark law for use of some trade - names, trademarks, or service marks; or - </para> - </listitem> - <listitem> - <para> - Requiring indemnification of licensors and authors of that material by - anyone who conveys the material (or modified versions of it) with - contractual assumptions of liability to the recipient, for any - liability that these contractual assumptions directly impose on those - licensors and authors. - </para> - </listitem> - </orderedlist> - <para> - All other non-permissive additional terms are considered “further - restrictions” within the meaning of section 10. If the Program as - you received it, or any part of it, contains a notice stating that it is - governed by this License along with a term that is a further restriction, - you may remove that term. If a license document contains a further - restriction but permits relicensing or conveying under this License, you - may add to a covered work material governed by the terms of that license - document, provided that the further restriction does not survive such - relicensing or conveying. - </para> - <para> - If you add terms to a covered work in accord with this section, you must - place, in the relevant source files, a statement of the additional terms - that apply to those files, or a notice indicating where to find the - applicable terms. - </para> - <para> - Additional terms, permissive or non-permissive, may be stated in the form - of a separately written license, or stated as exceptions; the above - requirements apply either way. - </para> - <bridgehead id="gpl-3-termination" renderas="sect1"> - 8. Termination. - </bridgehead> - <para> - You may not propagate or modify a covered work except as expressly provided - under this License. Any attempt otherwise to propagate or modify it is - void, and will automatically terminate your rights under this License - (including any patent licenses granted under the third paragraph of section - 11). - </para> - <para> - However, if you cease all violation of this License, then your license from - a particular copyright holder is reinstated (a) provisionally, unless and - until the copyright holder explicitly and finally terminates your license, - and (b) permanently, if the copyright holder fails to notify you of the - violation by some reasonable means prior to 60 days after the cessation. - </para> - <para> - Moreover, your license from a particular copyright holder is reinstated - permanently if the copyright holder notifies you of the violation by some - reasonable means, this is the first time you have received notice of - violation of this License (for any work) from that copyright holder, and - you cure the violation prior to 30 days after your receipt of the notice. - </para> - <para> - Termination of your rights under this section does not terminate the - licenses of parties who have received copies or rights from you under this - License. If your rights have been terminated and not permanently - reinstated, you do not qualify to receive new licenses for the same - material under section 10. - </para> - <bridgehead id="AcceptanceNotRequired" renderas="sect1"> - 9. Acceptance Not Required for Having Copies. - </bridgehead> - <para> - You are not required to accept this License in order to receive or run a - copy of the Program. Ancillary propagation of a covered work occurring - solely as a consequence of using peer-to-peer transmission to receive a - copy likewise does not require acceptance. However, nothing other than - this License grants you permission to propagate or modify any covered work. - These actions infringe copyright if you do not accept this License. - Therefore, by modifying or propagating a covered work, you indicate your - acceptance of this License to do so. - </para> - <bridgehead id="AutomaticDownstream" renderas="sect1"> - 10. Automatic Licensing of Downstream Recipients. - </bridgehead> - <para> - Each time you convey a covered work, the recipient automatically receives a - license from the original licensors, to run, modify and propagate that - work, subject to this License. You are not responsible for enforcing - compliance by third parties with this License. - </para> - <para> - An “entity transaction” is a transaction transferring control - of an organization, or substantially all assets of one, or subdividing an - organization, or merging organizations. If propagation of a covered work - results from an entity transaction, each party to that transaction who - receives a copy of the work also receives whatever licenses to the work the - party’s predecessor in interest had or could give under the previous - paragraph, plus a right to possession of the Corresponding Source of the - work from the predecessor in interest, if the predecessor has it or can get - it with reasonable efforts. - </para> - <para> - You may not impose any further restrictions on the exercise of the rights - granted or affirmed under this License. For example, you may not impose a - license fee, royalty, or other charge for exercise of rights granted under - this License, and you may not initiate litigation (including a cross-claim - or counterclaim in a lawsuit) alleging that any patent claim is infringed - by making, using, selling, offering for sale, or importing the Program or - any portion of it. - </para> - <bridgehead id="Patents" renderas="sect1"> - 11. Patents. - </bridgehead> - <para> - A “contributor” is a copyright holder who authorizes use under - this License of the Program or a work on which the Program is based. The - work thus licensed is called the contributor’s “contributor - version”. - </para> - <para> - A contributor’s “essential patent claims” are all patent - claims owned or controlled by the contributor, whether already acquired or - hereafter acquired, that would be infringed by some manner, permitted by - this License, of making, using, or selling its contributor version, but do - not include claims that would be infringed only as a consequence of further - modification of the contributor version. For purposes of this definition, - “control” includes the right to grant patent sublicenses in a - manner consistent with the requirements of this License. - </para> - <para> - Each contributor grants you a non-exclusive, worldwide, royalty-free patent - license under the contributor’s essential patent claims, to make, use, - sell, offer for sale, import and otherwise run, modify and propagate the - contents of its contributor version. - </para> - <para> - In the following three paragraphs, a “patent license” is any - express agreement or commitment, however denominated, not to enforce a - patent (such as an express permission to practice a patent or covenant not - to sue for patent infringement). To “grant” such a patent - license to a party means to make such an agreement or commitment not to - enforce a patent against the party. - </para> - <para> - If you convey a covered work, knowingly relying on a patent license, and the - Corresponding Source of the work is not available for anyone to copy, free - of charge and under the terms of this License, through a publicly available - network server or other readily accessible means, then you must either (1) - cause the Corresponding Source to be so available, or (2) arrange to deprive - yourself of the benefit of the patent license for this particular work, or - (3) arrange, in a manner consistent with the requirements of this License, - to extend the patent license to downstream recipients. “Knowingly - relying” means you have actual knowledge that, but for the patent - license, your conveying the covered work in a country, or your - recipient’s use of the covered work in a country, would infringe one - or more identifiable patents in that country that you have reason to believe - are valid. - </para> - <para> - If, pursuant to or in connection with a single transaction or arrangement, - you convey, or propagate by procuring conveyance of, a covered work, and - grant a patent license to some of the parties receiving the covered work - authorizing them to use, propagate, modify or convey a specific copy of the - covered work, then the patent license you grant is automatically extended to - all recipients of the covered work and works based on it. - </para> - <para> - A patent license is “discriminatory” if it does not include - within the scope of its coverage, prohibits the exercise of, or is - conditioned on the non-exercise of one or more of the rights that are - specifically granted under this License. You may not convey a covered work - if you are a party to an arrangement with a third party that is in the - business of distributing software, under which you make payment to the third - party based on the extent of your activity of conveying the work, and under - which the third party grants, to any of the parties who would receive the - covered work from you, a discriminatory patent license (a) in connection - with copies of the covered work conveyed by you (or copies made from those - copies), or (b) primarily for and in connection with specific products or - compilations that contain the covered work, unless you entered into that - arrangement, or that patent license was granted, prior to 28 March 2007. - </para> - <para> - Nothing in this License shall be construed as excluding or limiting any - implied license or other defenses to infringement that may otherwise be - available to you under applicable patent law. - </para> - <bridgehead id="NoSurrender" renderas="sect1"> - 12. No Surrender of Others’ Freedom. - </bridgehead> - <para> - If conditions are imposed on you (whether by court order, agreement or - otherwise) that contradict the conditions of this License, they do not - excuse you from the conditions of this License. If you cannot convey a - covered work so as to satisfy simultaneously your obligations under this - License and any other pertinent obligations, then as a consequence you may - not convey it at all. For example, if you agree to terms that obligate you - to collect a royalty for further conveying from those to whom you convey the - Program, the only way you could satisfy both those terms and this License - would be to refrain entirely from conveying the Program. - </para> - <bridgehead id="UsedWithAGPL" renderas="sect1"> - 13. Use with the <acronym>GNU</acronym> Affero General Public License. - </bridgehead> - <para> - Notwithstanding any other provision of this License, you have permission to - link or combine any covered work with a work licensed under version 3 of the - <acronym>GNU</acronym> Affero General Public License into a single combined - work, and to convey the resulting work. The terms of this License will - continue to apply to the part which is the covered work, but the special - requirements of the <acronym>GNU</acronym> Affero General Public License, - section 13, concerning interaction through a network will apply to the - combination as such. - </para> - <bridgehead id="RevisedVersions" renderas="sect1"> - 14. Revised Versions of this License. - </bridgehead> - <para> - The Free Software Foundation may publish revised and/or new versions of the - <acronym>GNU</acronym> General Public License from time to time. Such new - versions will be similar in spirit to the present version, but may differ in - detail to address new problems or concerns. - </para> - <para> - Each version is given a distinguishing version number. If the Program - specifies that a certain numbered version of the <acronym>GNU</acronym> - General Public License “or any later version” applies to it, you - have the option of following the terms and conditions either of that - numbered version or of any later version published by the Free Software - Foundation. If the Program does not specify a version number of the - <acronym>GNU</acronym> General Public License, you may choose any version - ever published by the Free Software Foundation. - </para> - <para> - If the Program specifies that a proxy can decide which future versions of - the <acronym>GNU</acronym> General Public License can be used, that - proxy’s public statement of acceptance of a version permanently - authorizes you to choose that version for the Program. - </para> - <para> - Later license versions may give you additional or different permissions. - However, no additional obligations are imposed on any author or copyright - holder as a result of your choosing to follow a later version. - </para> - <bridgehead id="WarrantyDisclaimer" renderas="sect1"> - 15. Disclaimer of Warranty. - </bridgehead> - <para> - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE - LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR - OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF - ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. - THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH - YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL - NECESSARY SERVICING, REPAIR OR CORRECTION. - </para> - <bridgehead id="LiabilityLimitation" renderas="sect1"> - 16. Limitation of Liability. - </bridgehead> - <para> - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL - ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE - PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY - GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE - OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA - OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD - PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), - EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF - SUCH DAMAGES. - </para> - <bridgehead id="InterpretationSecs1516" renderas="sect1"> - 17. Interpretation of Sections 15 and 16. - </bridgehead> - <para> - If the disclaimer of warranty and limitation of liability provided above - cannot be given local legal effect according to their terms, reviewing - courts shall apply local law that most closely approximates an absolute - waiver of all civil liability in connection with the Program, unless a - warranty or assumption of liability accompanies a copy of the Program in - return for a fee. - </para> - <bridgehead> - END OF TERMS AND CONDITIONS - </bridgehead> - <bridgehead id="HowToApply" renderas="sect1"> - How to Apply These Terms to Your New Programs - </bridgehead> - <para> - If you develop a new program, and you want it to be of the greatest possible - use to the public, the best way to achieve this is to make it free software - which everyone can redistribute and change under these terms. - </para> - <para> - To do so, attach the following notices to the program. It is safest to - attach them to the start of each source file to most effectively state the - exclusion of warranty; and each file should have at least the - “copyright” line and a pointer to where the full notice is - found. - </para> - <screen> -<replaceable>one line to give the program’s name and a brief idea of what it does.</replaceable> -Copyright (C) <replaceable>year</replaceable> <replaceable>name of author</replaceable> - -This program is free software: you can redistribute it and/or modify -it under the terms of the <acronym>GNU</acronym> General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -<acronym>GNU</acronym> General Public License for more details. - -You should have received a copy of the <acronym>GNU</acronym> General Public License -along with this program. If not, see <ulink url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>. - </screen> - <para> - Also add information on how to contact you by electronic and paper mail. - </para> - <para> - If the program does terminal interaction, make it output a short notice like - this when it starts in an interactive mode: - </para> - <screen> -<replaceable>program</replaceable> Copyright (C) <replaceable>year</replaceable> <replaceable>name of author</replaceable> -This program comes with ABSOLUTELY NO WARRANTY; for details type ‘<literal>show w</literal>’. -This is free software, and you are welcome to redistribute it -under certain conditions; type ‘<literal>show c</literal>’ for details. - </screen> - <para> - The hypothetical commands ‘<literal>show w</literal>’ and - ‘<literal>show c</literal>’ should show the appropriate parts of - the General Public License. Of course, your program’s commands might be - different; for a GUI interface, you would use an “about box”. - </para> - <para> - You should also get your employer (if you work as a programmer) or school, - if any, to sign a “copyright disclaimer” for the program, if - necessary. For more information on this, and how to apply and follow the - <acronym>GNU</acronym> <acronym>GPL</acronym>, see - <ulink url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>. - </para> - <para> - The <acronym>GNU</acronym> General Public License does not permit - incorporating your program into proprietary programs. If your program is a - subroutine library, you may consider it more useful to permit linking - proprietary applications with the library. If this is what you want to do, - use the <acronym>GNU</acronym> Lesser General Public License instead of this - License. But first, please read <ulink - url="http://www.gnu.org/philosophy/why-not-lgpl.html">http://www.gnu.org/philosophy/why-not-lgpl.html</ulink>. - </para> -</appendix> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/images/confdeps.dot b/gcc-4.4.3/libstdc++-v3/doc/xml/images/confdeps.dot deleted file mode 100644 index a62d28ce9..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/images/confdeps.dot +++ /dev/null @@ -1,14 +0,0 @@ -# Blatantly ripped out of the graphviz examples and modified. -pme -digraph v3conf { - size="6,6"; - node [color=lightblue2, style=filled]; - "aclocal.m4" -> "acinclude.m4"; - "configure" -> "aclocal.m4"; - "configure" -> "configure.ac"; - "configure" -> "crossconfig.m4"; - "configure" -> "linkage.m4"; - "[*/]Makefile.in" -> "Makefile.am"; - "[*/]Makefile.in" -> "configure.ac"; - "config.h.in" -> "acconfig.h"; - "config.h.in" -> "configure.ac"; -} diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/images/confdeps.png b/gcc-4.4.3/libstdc++-v3/doc/xml/images/confdeps.png Binary files differdeleted file mode 100644 index 5075aa869..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/images/confdeps.png +++ /dev/null diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/abi.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/abi.xml deleted file mode 100644 index d051d3a48..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/abi.xml +++ /dev/null @@ -1,1189 +0,0 @@ -<sect1 id="appendix.porting.abi" xreflabel="abi"> -<?dbhtml filename="abi.html"?> - -<sect1info> - <keywordset> - <keyword> - C++ - </keyword> - <keyword> - ABI - </keyword> - <keyword> - version - </keyword> - <keyword> - dynamic - </keyword> - <keyword> - shared - </keyword> - </keywordset> -</sect1info> - -<title>ABI Policy and Guidelines</title> - -<para> -</para> - -<sect2 id="abi.cxx_interface" xreflabel="abi.cxx_interface"> -<title>The C++ Interface</title> - -<para> - C++ applications often dependent on specific language support - routines, say for throwing exceptions, or catching exceptions, and - perhaps also dependent on features in the C++ Standard Library. -</para> - -<para> - The C++ Standard Library has many include files, types defined in - those include files, specific named functions, and other - behavior. The text of these behaviors, as written in source include - files, is called the Application Programing Interface, or API. -</para> - -<para> - Furthermore, C++ source that is compiled into object files is - transformed by the compiler: it arranges objects with specific - alignment and in a particular layout, mangling names according to a - well-defined algorithm, has specific arrangements for the support of - virtual functions, etc. These details are defined as the compiler - Application Binary Interface, or ABI. The GNU C++ compiler uses an - industry-standard C++ ABI starting with version 3. Details can be - found in the <ulink - url="http://www.codesourcery.com/cxx-abi/abi.html"> ABI - specification</ulink>. -</para> - -<para> - The GNU C++ compiler, g++, has a compiler command line option to - switch between various different C++ ABIs. This explicit version - switch is the flag <code>-fabi-version</code>. In addition, some - g++ command line options may change the ABI as a side-effect of - use. Such flags include <code>-fpack-struct</code> and - <code>-fno-exceptions</code>, but include others: see the complete - list in the GCC manual under the heading <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options - for Code Generation Conventions</ulink>. -</para> - -<para> - The configure options used when building a specific libstdc++ - version may also impact the resulting library ABI. The available - configure options, and their impact on the library ABI, are - documented -<link linkend="manual.intro.setup.configure">here</link>. -</para> - -<para> Putting all of these ideas together results in the C++ Standard -library ABI, which is the compilation of a given library API by a -given compiler ABI. In a nutshell: -</para> - -<para> - <quote> - library API + compiler ABI = library ABI - </quote> -</para> - -<para> - The library ABI is mostly of interest for end-users who have - unresolved symbols and are linking dynamically to the C++ Standard - library, and who thus must be careful to compile their application - with a compiler that is compatible with the available C++ Standard - library binary. In this case, compatible is defined with the equation - above: given an application compiled with a given compiler ABI and - library API, it will work correctly with a Standard C++ Library - created with the same constraints. -</para> - -<para> - To use a specific version of the C++ ABI, one must use a - corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that - implements the C++ ABI in question. -</para> - -</sect2> - -<sect2 id="abi.versioning" xreflabel="abi.versioning"> -<title>Versioning</title> - -<para> The C++ interface has evolved throughout the history of the GNU -C++ toolchain. With each release, various details have been changed so -as to give distinct versions to the C++ interface. -</para> - - <sect3 id="abi.versioning.goals" xreflabel="abi.versioning.goals"> - <title>Goals</title> - -<para>Extending existing, stable ABIs. Versioning gives subsequent -releases of library binaries the ability to add new symbols and add -functionality, all the while retaining compatibility with the previous -releases in the series. Thus, program binaries linked with the initial -release of a library binary will still link correctly if the library -binary is replaced by carefully-managed subsequent library -binaries. This is called forward compatibility. -</para> -<para> -The reverse (backwards compatibility) is not true. It is not possible -to take program binaries linked with the latest version of a library -binary in a release series (with additional symbols added), substitute -in the initial release of the library binary, and remain link -compatible. -</para> - -<para>Allows multiple, incompatible ABIs to coexist at the same time. -</para> - </sect3> - - <sect3 id="abi.versioning.history" xreflabel="abi.versioning.history"> - <title>History</title> - -<para> - How can this complexity be managed? What does C++ versioning mean? - Because library and compiler changes often make binaries compiled - with one version of the GNU tools incompatible with binaries - compiled with other (either newer or older) versions of the same GNU - tools, specific techniques are used to make managing this complexity - easier. -</para> - -<para> - The following techniques are used: -</para> - - <orderedlist> - - <listitem><para>Release versioning on the libgcc_s.so binary. </para> - - <para>This is implemented via file names and the ELF - <constant>DT_SONAME</constant> mechanism (at least on ELF - systems). It is versioned as follows: - </para> - - <itemizedlist> - <listitem><para>gcc-3.0.0: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.0.1: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.0.2: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.0.3: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.0.4: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.1.0: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.1.1: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.2.0: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.2.1: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.2.2: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.2.3: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.3.0: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.3.1: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.3.2: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.3.3: libgcc_s.so.1</para></listitem> - <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: on m68k-linux and - hppa-linux this is either libgcc_s.so.1 (when configuring - <code>--with-sjlj-exceptions</code>) or libgcc_s.so.2. For all - others, this is libgcc_s.so.1. </para> - </listitem> - </itemizedlist> - - </listitem> - - <listitem><para>Symbol versioning on the libgcc_s.so binary.</para> - - <para>It is versioned with the following labels and version - definitions, where the version definition is the maximum for a - particular release. Labels are cumulative. If a particular release - is not listed, it has the same version labels as the preceding - release.</para> - - <para>This corresponds to the mapfile: gcc/libgcc-std.ver</para> - <itemizedlist> - <listitem><para>gcc-3.0.0: GCC_3.0</para></listitem> - <listitem><para>gcc-3.3.0: GCC_3.3</para></listitem> - <listitem><para>gcc-3.3.1: GCC_3.3.1</para></listitem> - <listitem><para>gcc-3.3.2: GCC_3.3.2</para></listitem> - <listitem><para>gcc-3.3.4: GCC_3.3.4</para></listitem> - <listitem><para>gcc-3.4.0: GCC_3.4</para></listitem> - <listitem><para>gcc-3.4.2: GCC_3.4.2</para></listitem> - <listitem><para>gcc-3.4.4: GCC_3.4.4</para></listitem> - <listitem><para>gcc-4.0.0: GCC_4.0.0</para></listitem> - <listitem><para>gcc-4.1.0: GCC_4.1.0</para></listitem> - <listitem><para>gcc-4.2.0: GCC_4.2.0</para></listitem> - <listitem><para>gcc-4.3.0: GCC_4.3.0</para></listitem> - <listitem><para>gcc-4.4.0: GCC_4.4.0</para></listitem> - </itemizedlist> - </listitem> - - <listitem> - <para> - Release versioning on the libstdc++.so binary, implemented in - the same was as the libgcc_s.so binary above. Listed is the - filename: <constant>DT_SONAME</constant> can be deduced from - the filename by removing the last two period-delimited numbers. For - example, filename <filename>libstdc++.so.5.0.4</filename> - corresponds to a <constant>DT_SONAME</constant> of - <constant>libstdc++.so.5</constant>. Binaries with equivalent - <constant>DT_SONAME</constant>s are forward-compatibile: in - the table below, releases incompatible with the previous - one are explicitly noted. - </para> - - <para>It is versioned as follows: - </para> - <itemizedlist> - <listitem><para>gcc-3.0.0: libstdc++.so.3.0.0</para></listitem> - <listitem><para>gcc-3.0.1: libstdc++.so.3.0.1</para></listitem> - <listitem><para>gcc-3.0.2: libstdc++.so.3.0.2</para></listitem> - <listitem><para>gcc-3.0.3: libstdc++.so.3.0.2 (See Note 1)</para></listitem> - <listitem><para>gcc-3.0.4: libstdc++.so.3.0.4</para></listitem> - <listitem><para>gcc-3.1.0: libstdc++.so.4.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem> - <listitem><para>gcc-3.1.1: libstdc++.so.4.0.1</para></listitem> - <listitem><para>gcc-3.2.0: libstdc++.so.5.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem> - <listitem><para>gcc-3.2.1: libstdc++.so.5.0.1</para></listitem> - <listitem><para>gcc-3.2.2: libstdc++.so.5.0.2</para></listitem> - <listitem><para>gcc-3.2.3: libstdc++.so.5.0.3 (See Note 2)</para></listitem> - <listitem><para>gcc-3.3.0: libstdc++.so.5.0.4</para></listitem> - <listitem><para>gcc-3.3.1: libstdc++.so.5.0.5</para></listitem> - <listitem><para>gcc-3.3.2: libstdc++.so.5.0.5</para></listitem> - <listitem><para>gcc-3.3.3: libstdc++.so.5.0.5</para></listitem> - <listitem><para>gcc-3.4.0: libstdc++.so.6.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem> - <listitem><para>gcc-3.4.1: libstdc++.so.6.0.1</para></listitem> - <listitem><para>gcc-3.4.2: libstdc++.so.6.0.2</para></listitem> - <listitem><para>gcc-3.4.3: libstdc++.so.6.0.3</para></listitem> - <listitem><para>gcc-3.4.4: libstdc++.so.6.0.3</para></listitem> - <listitem><para>gcc-3.4.5: libstdc++.so.6.0.3</para></listitem> - <listitem><para>gcc-3.4.6: libstdc++.so.6.0.3</para></listitem> - <listitem><para>gcc-4.0.0: libstdc++.so.6.0.4</para></listitem> - <listitem><para>gcc-4.0.1: libstdc++.so.6.0.5</para></listitem> - <listitem><para>gcc-4.0.2: libstdc++.so.6.0.6</para></listitem> - <listitem><para>gcc-4.0.3: libstdc++.so.6.0.7</para></listitem> - <listitem><para>gcc-4.1.0: libstdc++.so.6.0.7</para></listitem> - <listitem><para>gcc-4.1.1: libstdc++.so.6.0.8</para></listitem> - <listitem><para>gcc-4.1.2: libstdc++.so.6.0.8</para></listitem> - <listitem><para>gcc-4.2.0: libstdc++.so.6.0.9</para></listitem> - <listitem><para>gcc-4.2.1: libstdc++.so.6.0.9 (See Note 3)</para></listitem> - <listitem><para>gcc-4.2.2: libstdc++.so.6.0.9</para></listitem> - <listitem><para>gcc-4.2.3: libstdc++.so.6.0.9</para></listitem> - <listitem><para>gcc-4.2.4: libstdc++.so.6.0.9</para></listitem> - <listitem><para>gcc-4.3.0: libstdc++.so.6.0.10</para></listitem> - <listitem><para>gcc-4.3.1: libstdc++.so.6.0.10</para></listitem> - <listitem><para>gcc-4.3.2: libstdc++.so.6.0.10</para></listitem> - <listitem><para>gcc-4.3.3: libstdc++.so.6.0.10</para></listitem> - <listitem><para>gcc-4.4.0: libstdc++.so.6.0.11</para></listitem> - </itemizedlist> - <para> - Note 1: Error should be libstdc++.so.3.0.3. - </para> - <para> - Note 2: Not strictly required. - </para> - <para> - Note 3: This release (but not previous or subsequent) has one - known incompatibility, see <ulink - url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</ulink> - in the GCC bug database. - </para> - </listitem> - - <listitem><para>Symbol versioning on the libstdc++.so binary.</para> - - <para>mapfile: libstdc++/config/linker-map.gnu</para> - <para>It is versioned with the following labels and version - definitions, where the version definition is the maximum for a - particular release. Note, only symbol which are newly introduced - will use the maximum version definition. Thus, for release series - with the same label, but incremented version definitions, the later - release has both versions. (An example of this would be the - gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and - GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0 - release.) If a particular release is not listed, it has the same - version labels as the preceding release. - </para> - <itemizedlist> - <listitem><para>gcc-3.0.0: (Error, not versioned)</para></listitem> - <listitem><para>gcc-3.0.1: (Error, not versioned)</para></listitem> - <listitem><para>gcc-3.0.2: (Error, not versioned)</para></listitem> - <listitem><para>gcc-3.0.3: (Error, not versioned)</para></listitem> - <listitem><para>gcc-3.0.4: (Error, not versioned)</para></listitem> - <listitem><para>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</para></listitem> - <listitem><para>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</para></listitem> - <listitem><para>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</para></listitem> - <listitem><para>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</para></listitem> - <listitem><para>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem> - <listitem><para>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem> - <listitem><para>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</para></listitem> - <listitem><para>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> - <listitem><para>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> - <listitem><para>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> - <listitem><para>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</para></listitem> - <listitem><para>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</para></listitem> - <listitem><para>gcc-3.4.2: GLIBCXX_3.4.2</para></listitem> - <listitem><para>gcc-3.4.3: GLIBCXX_3.4.3</para></listitem> - <listitem><para>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</para></listitem> - <listitem><para>gcc-4.0.1: GLIBCXX_3.4.5</para></listitem> - <listitem><para>gcc-4.0.2: GLIBCXX_3.4.6</para></listitem> - <listitem><para>gcc-4.0.3: GLIBCXX_3.4.7</para></listitem> - <listitem><para>gcc-4.1.1: GLIBCXX_3.4.8</para></listitem> - <listitem><para>gcc-4.2.0: GLIBCXX_3.4.9</para></listitem> - <listitem><para>gcc-4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</para></listitem> - <listitem><para>gcc-4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</para></listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Incremental bumping of a compiler pre-defined macro, - __GXX_ABI_VERSION. This macro is defined as the version of the - compiler v3 ABI, with g++ 3.0.x being version 100. This macro will - be automatically defined whenever g++ is used (the curious can - test this by invoking g++ with the '-v' flag.) - </para> - - <para> - This macro was defined in the file "lang-specs.h" in the gcc/cp directory. - Later versions defined it in "c-common.c" in the gcc directory, and from - G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the - '-fabi-version' command line option. - </para> - - <para> - It is versioned as follows, where 'n' is given by '-fabi-version=n': - </para> - <itemizedlist> - <listitem><para>gcc-3.0.x: 100</para></listitem> - <listitem><para>gcc-3.1.x: 100 (Error, should be 101)</para></listitem> - <listitem><para>gcc-3.2.x: 102</para></listitem> - <listitem><para>gcc-3.3.x: 102</para></listitem> - <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: 102 (when n=1)</para></listitem> - <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: 1000 + n (when n>1) </para></listitem> - <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: 999999 (when n=0)</para></listitem> - </itemizedlist> - <para></para> - </listitem> - - <listitem> - <para>Changes to the default compiler option for - <code>-fabi-version</code>. - </para> - <para> - It is versioned as follows: - </para> - <itemizedlist> - <listitem><para>gcc-3.0.x: (Error, not versioned) </para></listitem> - <listitem><para>gcc-3.1.x: (Error, not versioned) </para></listitem> - <listitem><para>gcc-3.2.x: <code>-fabi-version=1</code></para></listitem> - <listitem><para>gcc-3.3.x: <code>-fabi-version=1</code></para></listitem> - <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: <code>-fabi-version=2</code> <emphasis>(Incompatible with previous)</emphasis></para></listitem> - </itemizedlist> - <para></para> - </listitem> - - <listitem> - <para>Incremental bumping of a library pre-defined macro. For releases - before 3.4.0, the macro is __GLIBCPP__. For later releases, it's - __GLIBCXX__. (The libstdc++ project generously changed from CPP to - CXX throughout its source to allow the "C" pre-processor the CPP - macro namespace.) These macros are defined as the date the library - was released, in compressed ISO date format, as an unsigned long. - </para> - - <para> - This macro is defined in the file "c++config" in the - "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was - changed every night by an automated script. Since gcc-4.1.0, it is - the same value as gcc/DATESTAMP.) - </para> - <para> - It is versioned as follows: - </para> - <itemizedlist> - <listitem><para>gcc-3.0.0: 20010615</para></listitem> - <listitem><para>gcc-3.0.1: 20010819</para></listitem> - <listitem><para>gcc-3.0.2: 20011023</para></listitem> - <listitem><para>gcc-3.0.3: 20011220</para></listitem> - <listitem><para>gcc-3.0.4: 20020220</para></listitem> - <listitem><para>gcc-3.1.0: 20020514</para></listitem> - <listitem><para>gcc-3.1.1: 20020725</para></listitem> - <listitem><para>gcc-3.2.0: 20020814</para></listitem> - <listitem><para>gcc-3.2.1: 20021119</para></listitem> - <listitem><para>gcc-3.2.2: 20030205</para></listitem> - <listitem><para>gcc-3.2.3: 20030422</para></listitem> - <listitem><para>gcc-3.3.0: 20030513</para></listitem> - <listitem><para>gcc-3.3.1: 20030804</para></listitem> - <listitem><para>gcc-3.3.2: 20031016</para></listitem> - <listitem><para>gcc-3.3.3: 20040214</para></listitem> - <listitem><para>gcc-3.4.0: 20040419</para></listitem> - <listitem><para>gcc-3.4.1: 20040701</para></listitem> - <listitem><para>gcc-3.4.2: 20040906</para></listitem> - <listitem><para>gcc-3.4.3: 20041105</para></listitem> - <listitem><para>gcc-3.4.4: 20050519</para></listitem> - <listitem><para>gcc-3.4.5: 20051201</para></listitem> - <listitem><para>gcc-3.4.6: 20060306</para></listitem> - <listitem><para>gcc-4.0.0: 20050421</para></listitem> - <listitem><para>gcc-4.0.1: 20050707</para></listitem> - <listitem><para>gcc-4.0.2: 20050921</para></listitem> - <listitem><para>gcc-4.0.3: 20060309</para></listitem> - <listitem><para>gcc-4.1.0: 20060228</para></listitem> - <listitem><para>gcc-4.1.1: 20060524</para></listitem> - <listitem><para>gcc-4.1.2: 20070214</para></listitem> - <listitem><para>gcc-4.2.0: 20070514</para></listitem> - <listitem><para>gcc-4.2.1: 20070719</para></listitem> - <listitem><para>gcc-4.2.2: 20071007</para></listitem> - <listitem><para>gcc-4.2.3: 20080201</para></listitem> - <listitem><para>gcc-4.2.4: 20080519</para></listitem> - <listitem><para>gcc-4.3.0: 20080306</para></listitem> - <listitem><para>gcc-4.3.1: 20080606</para></listitem> - <listitem><para>gcc-4.3.2: 20080827</para></listitem> - <listitem><para>gcc-4.3.3: 20090124</para></listitem> - <listitem><para>gcc-4.4.0: 20090421</para></listitem> - </itemizedlist> - <para></para> - </listitem> - - <listitem> - <para> - Incremental bumping of a library pre-defined macro, - _GLIBCPP_VERSION. This macro is defined as the released version of - the library, as a string literal. This is only implemented in - gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it - is called _GLIBCXX_VERSION). - </para> - - <para> - This macro is defined in the file "c++config" in the - "libstdc++/include/bits" directory and is generated - automatically by autoconf as part of the configure-time generation - of config.h. - </para> - - <para> - It is versioned as follows: - </para> - <itemizedlist> - <listitem><para>gcc-3.0.0: "3.0.0"</para></listitem> - <listitem><para>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</para></listitem> - <listitem><para>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</para></listitem> - <listitem><para>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</para></listitem> - <listitem><para>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</para></listitem> - <listitem><para>gcc-3.1.0: "3.1.0"</para></listitem> - <listitem><para>gcc-3.1.1: "3.1.1"</para></listitem> - <listitem><para>gcc-3.2.0: "3.2"</para></listitem> - <listitem><para>gcc-3.2.1: "3.2.1"</para></listitem> - <listitem><para>gcc-3.2.2: "3.2.2"</para></listitem> - <listitem><para>gcc-3.2.3: "3.2.3"</para></listitem> - <listitem><para>gcc-3.3.0: "3.3"</para></listitem> - <listitem><para>gcc-3.3.1: "3.3.1"</para></listitem> - <listitem><para>gcc-3.3.2: "3.3.2"</para></listitem> - <listitem><para>gcc-3.3.3: "3.3.3"</para></listitem> - <listitem><para>gcc-3.4.x: "version-unused"</para></listitem> - <listitem><para>gcc-4.[0-3].x: "version-unused"</para></listitem> - </itemizedlist> - <para></para> - </listitem> - - <listitem> - <para> - Matching each specific C++ compiler release to a specific set of - C++ include files. This is only implemented in gcc-3.1.1 releases - and higher. - </para> - <para> - All C++ includes are installed in include/c++, then nest in a - directory hierarchy corresponding to the C++ compiler's released - version. This version corresponds to the variable "gcc_version" in - "libstdc++/acinclude.m4," and more details can be found in that - file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0). - </para> - <para> - C++ includes are versioned as follows: - </para> - <itemizedlist> - <listitem><para>gcc-3.0.0: include/g++-v3</para></listitem> - <listitem><para>gcc-3.0.1: include/g++-v3</para></listitem> - <listitem><para>gcc-3.0.2: include/g++-v3</para></listitem> - <listitem><para>gcc-3.0.3: include/g++-v3</para></listitem> - <listitem><para>gcc-3.0.4: include/g++-v3</para></listitem> - <listitem><para>gcc-3.1.0: include/g++-v3</para></listitem> - <listitem><para>gcc-3.1.1: include/c++/3.1.1</para></listitem> - <listitem><para>gcc-3.2.0: include/c++/3.2</para></listitem> - <listitem><para>gcc-3.2.1: include/c++/3.2.1</para></listitem> - <listitem><para>gcc-3.2.2: include/c++/3.2.2</para></listitem> - <listitem><para>gcc-3.2.3: include/c++/3.2.3</para></listitem> - <listitem><para>gcc-3.3.0: include/c++/3.3</para></listitem> - <listitem><para>gcc-3.3.1: include/c++/3.3.1</para></listitem> - <listitem><para>gcc-3.3.2: include/c++/3.3.2</para></listitem> - <listitem><para>gcc-3.3.3: include/c++/3.3.3</para></listitem> - <listitem><para>gcc-3.4.0: include/c++/3.4.0</para></listitem> - <listitem><para>gcc-3.4.1: include/c++/3.4.1</para></listitem> - <listitem><para>gcc-3.4.2: include/c++/3.4.2</para></listitem> - <listitem><para>gcc-3.4.3: include/c++/3.4.3</para></listitem> - <listitem><para>gcc-3.4.4: include/c++/3.4.4</para></listitem> - <listitem><para>gcc-3.4.5: include/c++/3.4.5</para></listitem> - <listitem><para>gcc-3.4.6: include/c++/3.4.6</para></listitem> - <listitem><para>gcc-4.0.0: include/c++/4.0.0</para></listitem> - <listitem><para>gcc-4.0.1: include/c++/4.0.1</para></listitem> - <listitem><para>gcc-4.0.2: include/c++/4.0.2</para></listitem> - <listitem><para>gcc-4.0.3: include/c++/4.0.3</para></listitem> - <listitem><para>gcc-4.1.0: include/c++/4.1.0</para></listitem> - <listitem><para>gcc-4.1.1: include/c++/4.1.1</para></listitem> - <listitem><para>gcc-4.1.2: include/c++/4.1.2</para></listitem> - <listitem><para>gcc-4.2.0: include/c++/4.2.0</para></listitem> - <listitem><para>gcc-4.2.1: include/c++/4.2.1</para></listitem> - <listitem><para>gcc-4.2.2: include/c++/4.2.2</para></listitem> - <listitem><para>gcc-4.2.3: include/c++/4.2.3</para></listitem> - <listitem><para>gcc-4.2.4: include/c++/4.2.4</para></listitem> - <listitem><para>gcc-4.3.0: include/c++/4.3.0</para></listitem> - <listitem><para>gcc-4.3.1: include/c++/4.3.1</para></listitem> - <listitem><para>gcc-4.3.3: include/c++/4.3.3</para></listitem> - <listitem><para>gcc-4.4.0: include/c++/4.4.0</para></listitem> - </itemizedlist> - <para></para> - </listitem> - </orderedlist> - -<para> - Taken together, these techniques can accurately specify interface - and implementation changes in the GNU C++ tools themselves. Used - properly, they allow both the GNU C++ tools implementation, and - programs using them, an evolving yet controlled development that - maintains backward compatibility. -</para> - - - </sect3> - - <sect3 id="abi.versioning.prereq" xreflabel="abi.versioning.prereq"> - <title>Prerequisites</title> - <para> - Minimum environment that supports a versioned ABI: A supported - dynamic linker, a GNU linker of sufficient vintage to understand - demangled C++ name globbing (ld), a shared executable compiled - with g++, and shared libraries (libgcc_s, libstdc++) compiled by - a compiler (g++) with a compatible ABI. Phew. - </para> - - <para> - On top of all that, an additional constraint: libstdc++ did not - attempt to version symbols (or age gracefully, really) until - version 3.1.0. - </para> - - <para> - Most modern Linux and BSD versions, particularly ones using - gcc-3.1.x tools and more recent vintages, will meet the - requirements above. - </para> - </sect3> - - <sect3 id="abi.versioning.config" xreflabel="abi.versioning.config"> - <title>Configuring</title> - - <para> - It turns out that most of the configure options that change - default behavior will impact the mangled names of exported - symbols, and thus impact versioning and compatibility. - </para> - - <para> - For more information on configure options, including ABI - impacts, see: - http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html - </para> - - <para> - There is one flag that explicitly deals with symbol versioning: - --enable-symvers. - </para> - - <para> - In particular, libstdc++/acinclude.m4 has a macro called - GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument - passed in via --enable-symvers=foo). At that point, the macro - attempts to make sure that all the requirement for symbol - versioning are in place. For more information, please consult - acinclude.m4. - </para> - </sect3> - - <sect3 id="abi.versioning.active" xreflabel="abi.versioning.active"> - <title>Checking Active</title> - - <para> - When the GNU C++ library is being built with symbol versioning - on, you should see the following at configure time for - libstdc++: - </para> - -<screen> -<computeroutput> - checking versioning on shared library symbols... gnu -</computeroutput> -</screen> - -<para> - If you don't see this line in the configure output, or if this line - appears but the last word is 'no', then you are out of luck. -</para> - -<para> - If the compiler is pre-installed, a quick way to test is to compile - the following (or any) simple C++ file and link it to the shared - libstdc++ library: -</para> - -<programlisting> -#include <iostream> - -int main() -{ std::cout << "hello" << std::endl; return 0; } - -%g++ hello.cc -o hello.out - -%ldd hello.out - libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) - libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) - libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) - libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) - -%nm hello.out -</programlisting> - -<para> -If you see symbols in the resulting output with "GLIBCXX_3" as part -of the name, then the executable is versioned. Here's an example: -</para> - -<para> - <code>U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code> -</para> - - </sect3> -</sect2> - -<sect2 id="abi.changes_allowed" xreflabel="abi.changes_allowed"> -<title>Allowed Changes</title> - -<para> -The following will cause the library minor version number to -increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". -</para> -<orderedlist> - <listitem><para>Adding an exported global or static data member</para></listitem> - <listitem><para>Adding an exported function, static or non-virtual member function</para></listitem> - <listitem><para>Adding an exported symbol or symbols by additional instantiations</para></listitem> -</orderedlist> -<para> -Other allowed changes are possible. -</para> - -</sect2> - -<sect2 id="abi.changes_no" xreflabel="abi.changes_no"> -<title>Prohibited Changes</title> - -<para> -The following non-exhaustive list will cause the library major version -number to increase, say from "libstdc++.so.3.0.4" to -"libstdc++.so.4.0.0". -</para> - -<orderedlist> - <listitem><para>Changes in the gcc/g++ compiler ABI</para></listitem> -<listitem><para>Changing size of an exported symbol</para></listitem> -<listitem><para>Changing alignment of an exported symbol</para></listitem> -<listitem><para>Changing the layout of an exported symbol</para></listitem> -<listitem><para>Changing mangling on an exported symbol</para></listitem> -<listitem><para>Deleting an exported symbol</para></listitem> -<listitem><para>Changing the inheritance properties of a type by adding or removing - base classes</para></listitem> -<listitem><para> - Changing the size, alignment, or layout of types - specified in the C++ standard. These may not necessarily be - instantiated or otherwise exported in the library binary, and - include all the required locale facets, as well as things like - std::basic_streambuf, et al. -</para></listitem> - -<listitem><para> Adding an explicit copy constructor or destructor to a -class that would otherwise have implicit versions. This will change -the way the compiler deals with this class in by-value return -statements or parameters: instead of being passing instances of this -class in registers, the compiler will be forced to use memory. See <ulink url="http://www.codesourcery.com/cxx-abi/abi.html#calls"> this part</ulink> - of the C++ ABI documentation for further details. - </para></listitem> - -</orderedlist> - -</sect2> - - - -<sect2 id="abi.impl" xreflabel="abi.impl"> -<title>Implementation</title> - -<orderedlist> - <listitem> - <para> - Separation of interface and implementation - </para> - <para> - This is accomplished by two techniques that separate the API from - the ABI: forcing undefined references to link against a library - binary for definitions. - </para> - -<variablelist> - <varlistentry> - <term>Include files have declarations, source files have defines</term> - - <listitem> - <para> - For non-templatized types, such as much of <code>class - locale</code>, the appropriate standard C++ include, say - <code>locale</code>, can contain full declarations, while - various source files (say <code> locale.cc, locale_init.cc, - localename.cc</code>) contain definitions. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Extern template on required types</term> - - <listitem> - <para> - For parts of the standard that have an explicit list of - required instantiations, the GNU extension syntax <code> extern - template </code> can be used to control where template - definitions reside. By marking required instantiations as - <code> extern template </code> in include files, and providing - explicit instantiations in the appropriate instantiation files, - non-inlined template functions can be versioned. This technique - is mostly used on parts of the standard that require <code> - char</code> and <code> wchar_t</code> instantiations, and - includes <code> basic_string</code>, the locale facets, and the - types in <code> iostreams</code>. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - In addition, these techniques have the additional benefit that they - reduce binary size, which can increase runtime performance. - </para> - </listitem> - - <listitem> - <para> - Namespaces linking symbol definitions to export mapfiles - </para> - <para> - All symbols in the shared library binary are processed by a - linker script at build time that either allows or disallows - external linkage. Because of this, some symbols, regardless of - normal C/C++ linkage, are not visible. Symbols that are internal - have several appealing characteristics: by not exporting the - symbols, there are no relocations when the shared library is - started and thus this makes for faster runtime loading - performance by the underlying dynamic loading mechanism. In - addition, they have the possibility of changing without impacting - ABI compatibility. - </para> - -<para>The following namespaces are transformed by the mapfile:</para> - -<variablelist> - - <varlistentry> -<term><code>namespace std</code></term> -<listitem><para> Defaults to exporting all symbols in label -<code>GLIBCXX</code> that do not begin with an underscore, i.e., -<code>__test_func</code> would not be exported by default. Select -exceptional symbols are allowed to be visible.</para></listitem> - </varlistentry> - - <varlistentry> -<term><code>namespace __gnu_cxx</code></term> -<listitem><para> Defaults to not exporting any symbols in label -<code>GLIBCXX</code>, select items are allowed to be visible.</para></listitem> - </varlistentry> - - <varlistentry> -<term><code>namespace __gnu_internal</code></term> -<listitem><para> Defaults to not exported, no items are allowed to be visible.</para></listitem> - </varlistentry> - - <varlistentry> -<term><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></term> -<listitem><para> Defaults to not exporting any symbols in label -<code>CXXABI</code>, select items are allowed to be visible.</para></listitem> - </varlistentry> - -</variablelist> -<para> -</para> -</listitem> - - <listitem><para>Freezing the API</para> - <para>Disallowed changes, as above, are not made on a stable release -branch. Enforcement tends to be less strict with GNU extensions that -standard includes.</para> -</listitem> -</orderedlist> - -</sect2> - -<sect2 id="abi.testing" xreflabel="abi.testing"> -<title>Testing</title> - - <sect3 id="abi.testing.single" xreflabel="abi.testing.single"> - <title>Single ABI Testing</title> - - <para> - Testing for GNU C++ ABI changes is composed of two distinct - areas: testing the C++ compiler (g++) for compiler changes, and - testing the C++ library (libstdc++) for library changes. - </para> - - <para> - Testing the C++ compiler ABI can be done various ways. - </para> - - <para> - One. Intel ABI checker. More information can be obtained <ulink - url="http://developer.intel.com/software/products/opensource/">here.</ulink> - </para> - -<para> -Two. -The second is yet unreleased, but has been announced on the gcc -mailing list. It is yet unspecified if these tools will be freely -available, and able to be included in a GNU project. Please contact -Mark Mitchell (mark@codesourcery.com) for more details, and current -status. -</para> - -<para> -Three. -Involves using the vlad.consistency test framework. This has also been -discussed on the gcc mailing lists. -</para> - -<para> -Testing the C++ library ABI can also be done various ways. -</para> - -<para> -One. -(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, -one with a new compiler and an old library, and the other with an old -compiler and a new library, and look for testsuite regressions) -</para> - -<para> -Details on how to set this kind of test up can be found here: -http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html -</para> - -<para> -Two. -Use the 'make check-abi' rule in the libstdc++ Makefile. -</para> - -<para> -This is a proactive check the library ABI. Currently, exported symbol -names that are either weak or defined are checked against a last known -good baseline. Currently, this baseline is keyed off of 3.4.0 -binaries, as this was the last time the .so number was incremented. In -addition, all exported names are demangled, and the exported objects -are checked to make sure they are the same size as the same object in -the baseline. - -Notice that each baseline is relative to a <emphasis>default</emphasis> -configured library and compiler: in particular, if options such as ---enable-clocale, or --with-cpu, in case of multilibs, are used at -configure time, the check may fail, either because of substantive -differences or because of limitations of the current checking -machinery. -</para> - -<para> -This dataset is insufficient, yet a start. Also needed is a -comprehensive check for all user-visible types part of the standard -library for sizeof() and alignof() changes. -</para> - -<para> -Verifying compatible layouts of objects is not even attempted. It -should be possible to use sizeof, alignof, and offsetof to compute -offsets for each structure and type in the standard library, saving to -another datafile. Then, compute this in a similar way for new -binaries, and look for differences. -</para> - -<para> -Another approach might be to use the -fdump-class-hierarchy flag to -get information. However, currently this approach gives insufficient -data for use in library testing, as class data members, their offsets, -and other detailed data is not displayed with this flag. -(See g++/7470 on how this was used to find bugs.) -</para> - -<para> -Perhaps there are other C++ ABI checkers. If so, please notify -us. We'd like to know about them! -</para> - - </sect3> - <sect3 id="abi.testing.multi" xreflabel="abi.testing.multi"> - <title>Multiple ABI Testing</title> -<para> -A "C" application, dynamically linked to two shared libraries, liba, -libb. The dependent library liba is C++ shared library compiled with -gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library -libb is a C++ shared library compiled with gcc-3.4.x, and also uses io, -exceptions, locale, etc. -</para> - -<para> As above, libone is constructed as follows: </para> -<programlisting> -%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc - -%$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0 - -%ln -s libone.so.1.0.0 libone.so - -%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc - -%ar cru libone.a a.o -</programlisting> - -<para> And, libtwo is constructed as follows: </para> - -<programlisting> -%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc - -%$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0 - -%ln -s libtwo.so.1.0.0 libtwo.so - -%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc - -%ar cru libtwo.a b.o -</programlisting> - -<para> ...with the resulting libraries looking like </para> - -<screen> -<computeroutput> -%ldd libone.so.1.0.0 - libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000) - libm.so.6 => /lib/tls/libm.so.6 (0x400fa000) - libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000) - libc.so.6 => /lib/tls/libc.so.6 (0x40125000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) - -%ldd libtwo.so.1.0.0 - libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000) - libm.so.6 => /lib/tls/libm.so.6 (0x400e1000) - libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000) - libc.so.6 => /lib/tls/libc.so.6 (0x4010c000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) -</computeroutput> -</screen> - -<para> - Then, the "C" compiler is used to compile a source file that uses - functions from each library. -</para> -<programlisting> -gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6 -</programlisting> - -<para> - Which gives the expected: -</para> - -<screen> -<computeroutput> -%ldd a.out - libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) - libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000) - libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) - libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) - libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) -</computeroutput> -</screen> - -<para> - This resulting binary, when executed, will be able to safely use - code from both liba, and the dependent libstdc++.so.6, and libb, - with the dependent libstdc++.so.5. -</para> - </sect3> -</sect2> - -<sect2 id="abi.issues" xreflabel="abi.issues"> -<title>Outstanding Issues</title> - -<para> - Some features in the C++ language make versioning especially - difficult. In particular, compiler generated constructs such as - implicit instantiations for templates, typeinfo information, and - virtual tables all may cause ABI leakage across shared library - boundaries. Because of this, mixing C++ ABIs is not recommended at - this time. -</para> - -<para> - For more background on this issue, see these bugzilla entries: -</para> - -<para> -<ulink url="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</ulink> -</para> - -<para> -<ulink url="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</ulink> -</para> - -</sect2> - -<bibliography id="abi.biblio" xreflabel="abi.biblio"> -<title>Bibliography</title> - - <biblioentry> - <title> - ABIcheck, a vague idea of checking ABI compatibility - </title> - - <biblioid> - <ulink url="http://abicheck.sourceforge.net/"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - C++ ABI Reference - </title> - - <biblioid> - <ulink url="http://www.codesourcery.com/cxx-abi"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - Intel® Compilers for Linux* -Compatibility with the GNU Compilers - </title> - - <biblioid> - <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - Intel® Compilers for Linux* -Compatibility with the GNU Compilers - </title> - - <biblioid> - <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386) - </title> - - <biblioid> - <ulink url="http://docs.sun.com/?p=/doc/816-1386&a=load"> - </ulink> - </biblioid> - </biblioentry> - - - <biblioentry> - <title> - Sun Solaris 2.9 : C++ Migration Guide (document 816-2459) - </title> - - <biblioid> - <ulink url="http://docs.sun.com/db/prod/solaris.9"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - ELF Symbol Versioning - </title> - - <author> - <firstname>Ulrich</firstname> - <surname>Drepper</surname> - </author> - - <biblioid> - <ulink url="http://people.redhat.com/drepper/symbol-versioning"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - C++ ABI for the ARM Architecture - </title> - - <biblioid> - <ulink url="http://www.arm.com/miscPDFs/8033.pdf"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - Dynamic Shared Objects: Survey and Issues - </title> - <subtitle> - ISO C++ J16/06-0046 - </subtitle> - - <author> - <firstname>Benjamin</firstname> - <surname>Kosnik</surname> - </author> - - <biblioid> - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - Versioning With Namespaces - </title> - <subtitle> - ISO C++ J16/06-0083 - </subtitle> - - <author> - <firstname>Benjamin</firstname> - <surname>Kosnik</surname> - </author> - - <biblioid> - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html"> - </ulink> - </biblioid> - </biblioentry> - -</bibliography> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/algorithms.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/algorithms.xml deleted file mode 100644 index ead0b8bbe..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/algorithms.xml +++ /dev/null @@ -1,107 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.algorithms" xreflabel="Algorithms"> -<?dbhtml filename="algorithms.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - <keyword> - algorithm - </keyword> - </keywordset> -</partinfo> - -<title> - Algorithms - <indexterm><primary>Algorithms</primary></indexterm> -</title> - -<preface> - <title></title> -<para> - The neatest accomplishment of the algorithms chapter is that all the - work is done via iterators, not containers directly. This means two - important things: -</para> -<orderedlist> - <listitem> - <para> - Anything that behaves like an iterator can be used in one of - these algorithms. Raw pointers make great candidates, thus - built-in arrays are fine containers, as well as your own iterators. - </para> - </listitem> - <listitem> - <para> - The algorithms do not (and cannot) affect the container as a - whole; only the things between the two iterator endpoints. If - you pass a range of iterators only enclosing the middle third of - a container, then anything outside that range is inviolate. - </para> - </listitem> - </orderedlist> - <para> - Even strings can be fed through the algorithms here, although the - string class has specialized versions of many of these functions - (for example, <code>string::find()</code>). Most of the examples - on this page will use simple arrays of integers as a playground - for algorithms, just to keep things simple. The use of - <emphasis>N</emphasis> as a size in the examples is to keep - things easy to read but probably won't be valid code. You can - use wrappers such as those described in the <ulink - url="../23_containers/howto.html">containers chapter</ulink> to - keep real code readable. - </para> - <para> - The single thing that trips people up the most is the definition - of <emphasis>range</emphasis> used with iterators; the famous - "past-the-end" rule that everybody loves to hate. The - <ulink url="../24_iterators/howto.html#2">iterators - chapter</ulink> of this document has a complete explanation of - this simple rule that seems to cause so much confusion. Once you - get <emphasis>range</emphasis> into your head (it's not that - hard, honest!), then the algorithms are a cakewalk. - </para> -</preface> - -<!-- Chapter 01 : Non Modifying --> - -<!-- Chapter 02 : Mutating --> -<chapter id="manual.algorithms.mutating" xreflabel="Mutating"> - <title>Mutating</title> - - <sect1 id="algorithms.mutating.swap" xreflabel="swap"> - <title><function>swap</function></title> - - <sect2 id="algorithms.swap.specializations" xreflabel="Specializations"> - <title>Specializations</title> - - <para>If you call <code> std::swap(x,y); </code> where x and y are standard - containers, then the call will automatically be replaced by a call to - <code> x.swap(y); </code> instead. - </para> - <para>This allows member functions of each container class to take over, and - containers' swap functions should have O(1) complexity according to - the standard. (And while "should" allows implementations to - behave otherwise and remain compliant, this implementation does in - fact use constant-time swaps.) This should not be surprising, since - for two containers of the same type to swap contents, only some - internal pointers to storage need to be exchanged. - </para> - - </sect2> - </sect1> -</chapter> - -<!-- Chapter 03 : Sorting --> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/allocator.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/allocator.xml deleted file mode 100644 index 5aa4f3530..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/allocator.xml +++ /dev/null @@ -1,659 +0,0 @@ -<sect1 id="manual.util.memory.allocator" xreflabel="Allocator"> -<?dbhtml filename="allocator.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - allocator - </keyword> - </keywordset> -</sect1info> - -<title>Allocators</title> - -<para> - Memory management for Standard Library entities is encapsulated in a - class template called <classname>allocator</classname>. The - <classname>allocator</classname> abstraction is used throughout the - library in <classname>string</classname>, container classes, - algorithms, and parts of iostreams. This class, and base classes of - it, are the superset of available free store (<quote>heap</quote>) - management classes. -</para> - -<sect2 id="allocator.req" xreflabel="allocator.req"> -<title>Requirements</title> - - <para> - The C++ standard only gives a few directives in this area: - </para> - <itemizedlist> - <listitem> - <para> - When you add elements to a container, and the container must - allocate more memory to hold them, the container makes the - request via its <type>Allocator</type> template - parameter, which is usually aliased to - <type>allocator_type</type>. This includes adding chars - to the string class, which acts as a regular STL container in - this respect. - </para> - </listitem> - <listitem> - <para> - The default <type>Allocator</type> argument of every - container-of-T is <classname>allocator<T></classname>. - </para> - </listitem> - <listitem> - <para> - The interface of the <classname>allocator<T></classname> class is - extremely simple. It has about 20 public declarations (nested - typedefs, member functions, etc), but the two which concern us most - are: - </para> - <programlisting> - T* allocate (size_type n, const void* hint = 0); - void deallocate (T* p, size_type n); - </programlisting> - - <para> - The <varname>n</varname> arguments in both those - functions is a <emphasis>count</emphasis> of the number of - <type>T</type>'s to allocate space for, <emphasis>not their - total size</emphasis>. - (This is a simplification; the real signatures use nested typedefs.) - </para> - </listitem> - <listitem> - <para> - The storage is obtained by calling <function>::operator - new</function>, but it is unspecified when or how - often this function is called. The use of the - <varname>hint</varname> is unspecified, but intended as an - aid to locality if an implementation so - desires. <constant>[20.4.1.1]/6</constant> - </para> - </listitem> - </itemizedlist> - - <para> - Complete details cam be found in the C++ standard, look in - <constant>[20.4 Memory]</constant>. - </para> - -</sect2> - -<sect2 id="allocator.design_issues" xreflabel="allocator.design_issues"> -<title>Design Issues</title> - - <para> - The easiest way of fulfilling the requirements is to call - <function>operator new</function> each time a container needs - memory, and to call <function>operator delete</function> each time - the container releases memory. This method may be <ulink - url="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</ulink> - than caching the allocations and re-using previously-allocated - memory, but has the advantage of working correctly across a wide - variety of hardware and operating systems, including large - clusters. The <classname>__gnu_cxx::new_allocator</classname> - implements the simple operator new and operator delete semantics, - while <classname>__gnu_cxx::malloc_allocator</classname> - implements much the same thing, only with the C language functions - <function>std::malloc</function> and <function>free</function>. - </para> - - <para> - Another approach is to use intelligence within the allocator - class to cache allocations. This extra machinery can take a variety - of forms: a bitmap index, an index into an exponentially increasing - power-of-two-sized buckets, or simpler fixed-size pooling cache. - The cache is shared among all the containers in the program: when - your program's <classname>std::vector<int></classname> gets - cut in half and frees a bunch of its storage, that memory can be - reused by the private - <classname>std::list<WonkyWidget></classname> brought in from - a KDE library that you linked against. And operators - <function>new</function> and <function>delete</function> are not - always called to pass the memory on, either, which is a speed - bonus. Examples of allocators that use these techniques are - <classname>__gnu_cxx::bitmap_allocator</classname>, - <classname>__gnu_cxx::pool_allocator</classname>, and - <classname>__gnu_cxx::__mt_alloc</classname>. - </para> - - <para> - Depending on the implementation techniques used, the underlying - operating system, and compilation environment, scaling caching - allocators can be tricky. In particular, order-of-destruction and - order-of-creation for memory pools may be difficult to pin down - with certainty, which may create problems when used with plugins - or loading and unloading shared objects in memory. As such, using - caching allocators on systems that do not support - <function>abi::__cxa_atexit</function> is not recommended. - </para> - -</sect2> - -<sect2 id="allocator.impl" xreflabel="allocator.impl"> -<title>Implementation</title> - - <sect3> - <title>Interface Design</title> - - <para> - The only allocator interface that - is support is the standard C++ interface. As such, all STL - containers have been adjusted, and all external allocators have - been modified to support this change. - </para> - - <para> - The class <classname>allocator</classname> just has typedef, - constructor, and rebind members. It inherits from one of the - high-speed extension allocators, covered below. Thus, all - allocation and deallocation depends on the base class. - </para> - - <para> - The base class that <classname>allocator</classname> is derived from - may not be user-configurable. -</para> - - </sect3> - - <sect3> - <title>Selecting Default Allocation Policy</title> - - <para> - It's difficult to pick an allocation strategy that will provide - maximum utility, without excessively penalizing some behavior. In - fact, it's difficult just deciding which typical actions to measure - for speed. - </para> - - <para> - Three synthetic benchmarks have been created that provide data - that is used to compare different C++ allocators. These tests are: - </para> - - <orderedlist> - <listitem> - <para> - Insertion. - </para> - <para> - Over multiple iterations, various STL container - objects have elements inserted to some maximum amount. A variety - of allocators are tested. - Test source for <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup">sequence</ulink> - and <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup">associative</ulink> - containers. - </para> - - </listitem> - - <listitem> - <para> - Insertion and erasure in a multi-threaded environment. - </para> - <para> - This test shows the ability of the allocator to reclaim memory - on a pre-thread basis, as well as measuring thread contention - for memory resources. - Test source - <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup">here</ulink>. - </para> - </listitem> - - <listitem> - <para> - A threaded producer/consumer model. - </para> - <para> - Test source for - <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup">sequence</ulink> - and - <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup">associative</ulink> - containers. - </para> - </listitem> - </orderedlist> - - <para> - The current default choice for - <classname>allocator</classname> is - <classname>__gnu_cxx::new_allocator</classname>. - </para> - - </sect3> - - <sect3> - <title>Disabling Memory Caching</title> - - <para> - In use, <classname>allocator</classname> may allocate and - deallocate using implementation-specified strategies and - heuristics. Because of this, every call to an allocator object's - <function>allocate</function> member function may not actually - call the global operator new. This situation is also duplicated - for calls to the <function>deallocate</function> member - function. - </para> - - <para> - This can be confusing. - </para> - - <para> - In particular, this can make debugging memory errors more - difficult, especially when using third party tools like valgrind or - debug versions of <function>new</function>. - </para> - - <para> - There are various ways to solve this problem. One would be to use - a custom allocator that just called operators - <function>new</function> and <function>delete</function> - directly, for every allocation. (See - <filename>include/ext/new_allocator.h</filename>, for instance.) - However, that option would involve changing source code to use - a non-default allocator. Another option is to force the - default allocator to remove caching and pools, and to directly - allocate with every call of <function>allocate</function> and - directly deallocate with every call of - <function>deallocate</function>, regardless of efficiency. As it - turns out, this last option is also available. - </para> - - - <para> - To globally disable memory caching within the library for the - default allocator, merely set - <constant>GLIBCXX_FORCE_NEW</constant> (with any value) in the - system's environment before running the program. If your program - crashes with <constant>GLIBCXX_FORCE_NEW</constant> in the - environment, it likely means that you linked against objects - built against the older library (objects which might still using the - cached allocations...). - </para> - - </sect3> - -</sect2> - -<sect2 id="allocator.using" xreflabel="allocator.using"> -<title>Using a Specific Allocator</title> - - <para> - You can specify different memory management schemes on a - per-container basis, by overriding the default - <type>Allocator</type> template parameter. For example, an easy - (but non-portable) method of specifying that only <function>malloc</function> or <function>free</function> - should be used instead of the default node allocator is: - </para> - <programlisting> - std::list <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</programlisting> - <para> - Likewise, a debugging form of whichever allocator is currently in use: - </para> - <programlisting> - std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > debug_deque; - </programlisting> -</sect2> - -<sect2 id="allocator.custom" xreflabel="allocator.custom"> -<title>Custom Allocators</title> - - <para> - Writing a portable C++ allocator would dictate that the interface - would look much like the one specified for - <classname>allocator</classname>. Additional member functions, but - not subtractions, would be permissible. - </para> - - <para> - Probably the best place to start would be to copy one of the - extension allocators: say a simple one like - <classname>new_allocator</classname>. - </para> - -</sect2> - -<sect2 id="allocator.ext" xreflabel="allocator.ext"> -<title>Extension Allocators</title> - - <para> - Several other allocators are provided as part of this - implementation. The location of the extension allocators and their - names have changed, but in all cases, functionality is - equivalent. Starting with gcc-3.4, all extension allocators are - standard style. Before this point, SGI style was the norm. Because of - this, the number of template arguments also changed. Here's a simple - chart to track the changes. - </para> - - <para> - More details on each of these extension allocators follows. - </para> - <orderedlist> - <listitem> - <para> - <classname>new_allocator</classname> - </para> - <para> - Simply wraps <function>::operator new</function> - and <function>::operator delete</function>. - </para> - </listitem> - <listitem> - <para> - <classname>malloc_allocator</classname> - </para> - <para> - Simply wraps <function>malloc</function> and - <function>free</function>. There is also a hook for an - out-of-memory handler (for - <function>new</function>/<function>delete</function> this is - taken care of elsewhere). - </para> - </listitem> - <listitem> - <para> - <classname>array_allocator</classname> - </para> - <para> - Allows allocations of known and fixed sizes using existing - global or external storage allocated via construction of - <classname>std::tr1::array</classname> objects. By using this - allocator, fixed size containers (including - <classname>std::string</classname>) can be used without - instances calling <function>::operator new</function> and - <function>::operator delete</function>. This capability - allows the use of STL abstractions without runtime - complications or overhead, even in situations such as program - startup. For usage examples, please consult the testsuite. - </para> - </listitem> - <listitem> - <para> - <classname>debug_allocator</classname> - </para> - <para> - A wrapper around an arbitrary allocator A. It passes on - slightly increased size requests to A, and uses the extra - memory to store size information. When a pointer is passed - to <function>deallocate()</function>, the stored size is - checked, and <function>assert()</function> is used to - guarantee they match. - </para> - </listitem> - <listitem> - <para> - <classname>throw_allocator</classname> - </para> - <para> - Includes memory tracking and marking abilities as well as hooks for - throwing exceptions at configurable intervals (including random, - all, none). - </para> - </listitem> - <listitem> - <para> - <classname>__pool_alloc</classname> - </para> - <para> - A high-performance, single pool allocator. The reusable - memory is shared among identical instantiations of this type. - It calls through <function>::operator new</function> to - obtain new memory when its lists run out. If a client - container requests a block larger than a certain threshold - size, then the pool is bypassed, and the allocate/deallocate - request is passed to <function>::operator new</function> - directly. - </para> - - <para> - Older versions of this class take a boolean template - parameter, called <varname>thr</varname>, and an integer template - parameter, called <varname>inst</varname>. - </para> - - <para> - The <varname>inst</varname> number is used to track additional memory - pools. The point of the number is to allow multiple - instantiations of the classes without changing the semantics at - all. All three of - </para> - - <programlisting> - typedef __pool_alloc<true,0> normal; - typedef __pool_alloc<true,1> private; - typedef __pool_alloc<true,42> also_private; - </programlisting> - <para> - behave exactly the same way. However, the memory pool for each type - (and remember that different instantiations result in different types) - remains separate. - </para> - <para> - The library uses <emphasis>0</emphasis> in all its instantiations. If you - wish to keep separate free lists for a particular purpose, use a - different number. - </para> - <para>The <varname>thr</varname> boolean determines whether the - pool should be manipulated atomically or not. When - <varname>thr</varname> = <constant>true</constant>, the allocator - is is thread-safe, while <varname>thr</varname> = - <constant>false</constant>, and is slightly faster but unsafe for - multiple threads. - </para> - - <para> - For thread-enabled configurations, the pool is locked with a - single big lock. In some situations, this implementation detail - may result in severe performance degradation. - </para> - - <para> - (Note that the GCC thread abstraction layer allows us to provide - safe zero-overhead stubs for the threading routines, if threads - were disabled at configuration time.) - </para> - </listitem> - - <listitem> - <para> - <classname>__mt_alloc</classname> - </para> - <para> - A high-performance fixed-size allocator with - exponentially-increasing allocations. It has its own - documentation, found <link - linkend="manual.ext.allocator.mt">here</link>. - </para> - </listitem> - - <listitem> - <para> - <classname>bitmap_allocator</classname> - </para> - <para> - A high-performance allocator that uses a bit-map to keep track - of the used and unused memory locations. It has its own - documentation, found <link - linkend="manual.ext.allocator.bitmap">here</link>. - </para> - </listitem> - </orderedlist> -</sect2> - - -<bibliography id="allocator.biblio" xreflabel="allocator.biblio"> -<title>Bibliography</title> - - <biblioentry> - <title> - ISO/IEC 14882:1998 Programming languages - C++ - </title> - - <abbrev> - isoc++_1998 - </abbrev> - <pagenums>20.4 Memory</pagenums> - </biblioentry> - - <biblioentry> - <title>The Standard Librarian: What Are Allocators Good - </title> - - <abbrev> - austernm - </abbrev> - - <author> - <firstname>Matt</firstname> - <surname>Austern</surname> - </author> - - <publisher> - <publishername> - C/C++ Users Journal - </publishername> - </publisher> - - <biblioid> - <ulink url="http://www.cuj.com/documents/s=8000/cujcexp1812austern/"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title>The Hoard Memory Allocator</title> - - <abbrev> - emeryb - </abbrev> - - <author> - <firstname>Emery</firstname> - <surname>Berger</surname> - </author> - - <biblioid> - <ulink url="http://www.cs.umass.edu/~emery/hoard/"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title>Reconsidering Custom Memory Allocation</title> - - <abbrev> - bergerzorn - </abbrev> - - <author> - <firstname>Emery</firstname> - <surname>Berger</surname> - </author> - <author> - <firstname>Ben</firstname> - <surname>Zorn</surname> - </author> - <author> - <firstname>Kathryn</firstname> - <surname>McKinley</surname> - </author> - - <copyright> - <year>2002</year> - <holder>OOPSLA</holder> - </copyright> - - <biblioid> - <ulink url="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf"> - </ulink> - </biblioid> - </biblioentry> - - - <biblioentry> - <title>Allocator Types</title> - - <abbrev> - kreftlanger - </abbrev> - - <author> - <firstname>Klaus</firstname> - <surname>Kreft</surname> - </author> - <author> - <firstname>Angelika</firstname> - <surname>Langer</surname> - </author> - - <publisher> - <publishername> - C/C++ Users Journal - </publishername> - </publisher> - - <biblioid> - <ulink url="http://www.langer.camelot.de/Articles/C++Report/Allocators/Allocators.html"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title>The C++ Programming Language</title> - - <abbrev> - tcpl - </abbrev> - - <author> - <firstname>Bjarne</firstname> - <surname>Stroustrup</surname> - </author> - <copyright> - <year>2000</year> - <holder></holder> - </copyright> - <pagenums>19.4 Allocators</pagenums> - - <publisher> - <publishername> - Addison Wesley - </publishername> - </publisher> - </biblioentry> - - <biblioentry> - <title>Yalloc: A Recycling C++ Allocator</title> - - <abbrev> - yenf - </abbrev> - - <author> - <firstname>Felix</firstname> - <surname>Yen</surname> - </author> - <copyright> - <year></year> - <holder></holder> - </copyright> - - <biblioid> - <ulink url="http://home.earthlink.net/~brimar/yalloc/"> - </ulink> - </biblioid> - </biblioentry> -</bibliography> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_contributing.xml deleted file mode 100644 index 1688fa823..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_contributing.xml +++ /dev/null @@ -1,2250 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<appendix id="appendix.contrib" xreflabel="Contributing"> -<?dbhtml filename="appendix_contributing.html"?> - -<appendixinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</appendixinfo> - -<title> - Contributing - <indexterm> - <primary>Appendix</primary> - <secondary>Contributing</secondary> - </indexterm> -</title> - -<para> - The GNU C++ Library follows an open development model. Active - contributors are assigned maintainer-ship responsibility, and given - write access to the source repository. First time contributors - should follow this procedure: -</para> - -<sect1 id="contrib.list" xreflabel="Contributor Checklist"> - <title>Contributor Checklist</title> - - <sect2 id="list.reading" xreflabel="list.reading"> - <title>Reading</title> - - <itemizedlist> - <listitem> - <para> - Get and read the relevant sections of the C++ language - specification. 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 web-site 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> - </listitem> - - <listitem> - <para> - The library working group bugs, and known defects, can - be obtained here: - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink> - </para> - </listitem> - - <listitem> - <para> - The newsgroup dedicated to standardization issues is - comp.std.c++: this FAQ for this group is quite useful and - can be - found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html"> - here </ulink>. - </para> - </listitem> - - <listitem> - <para> - Peruse - the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU - Coding Standards</ulink>, and chuckle when you hit the part - about <quote>Using Languages Other Than C</quote>. - </para> - </listitem> - - <listitem> - <para> - Be familiar with the extensions that preceded these - general GNU rules. These style issues for libstdc++ can be - found <link linkend="contrib.coding_style">here</link>. - </para> - </listitem> - - <listitem> - <para> - And last but certainly not least, read the - library-specific information - found <link linkend="appendix.porting"> here</link>. - </para> - </listitem> - </itemizedlist> - - </sect2> - <sect2 id="list.copyright" xreflabel="list.copyright"> - <title>Assignment</title> - <para> - Small changes can be accepted without a copyright assignment form on - file. New code and additions to the library need completed copyright - assignment form on file at the FSF. Note: your employer may be required - to fill out appropriate disclaimer forms as well. - </para> - - <para> - Historically, the libstdc++ assignment form added the following - question: - </para> - - <para> - <quote> - Which Belgian comic book character is better, Tintin or Asterix, and - why? - </quote> - </para> - - <para> - While not strictly necessary, humoring the maintainers and answering - this question would be appreciated. - </para> - - <para> - For more information about getting a copyright assignment, please see - <ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal - Matters</ulink>. - </para> - - <para> - Please contact Benjamin Kosnik at - <email>bkoz+assign@redhat.com</email> if you are confused - about the assignment or have general licensing questions. When - requesting an assignment form from - <email>mailto:assign@gnu.org</email>, please cc the libstdc++ - maintainer above so that progress can be monitored. - </para> - </sect2> - - <sect2 id="list.getting" xreflabel="list.getting"> - <title>Getting Sources</title> - <para> - <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access - (look for "Write after approval")</ulink> - </para> - </sect2> - - <sect2 id="list.patches" xreflabel="list.patches"> - <title>Submitting Patches</title> - - <para> - Every patch must have several pieces of information before it can be - properly evaluated. Ideally (and to ensure the fastest possible - response from the maintainers) it would have all of these pieces: - </para> - - <itemizedlist> - <listitem> - <para> - A description of the bug and how your patch fixes this - bug. For new features a description of the feature and your - implementation. - </para> - </listitem> - - <listitem> - <para> - A ChangeLog entry as plain text; see the various - ChangeLog files for format and content. If using you are - using emacs as your editor, simply position the insertion - point at the beginning of your change and hit CX-4a to bring - up the appropriate ChangeLog entry. See--magic! Similar - functionality also exists for vi. - </para> - </listitem> - - <listitem> - <para> - A testsuite submission or sample program that will - easily and simply show the existing error or test new - functionality. - </para> - </listitem> - - <listitem> - <para> - The patch itself. If you are accessing the SVN - repository use <command>svn update; svn diff NEW</command>; - else, use <command>diff -cp OLD NEW</command> ... If your - version of diff does not support these options, then get the - latest version of GNU - diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN - Tricks</ulink> wiki page has information on customising the - output of <code>svn diff</code>. - </para> - </listitem> - - <listitem> - <para> - When you have all these pieces, bundle them up in a - mail message and send it to libstdc++@gcc.gnu.org. All - patches and related discussion should be sent to the - libstdc++ mailing list. - </para> - </listitem> - </itemizedlist> - - </sect2> - -</sect1> - -<sect1 id="contrib.organization" xreflabel="Source Organization"> - <?dbhtml filename="source_organization.html"?> - <title>Directory Layout and Source Conventions</title> - - <para> - The unpacked source directory of libstdc++ contains the files - needed to create the GNU C++ Library. - </para> - - <literallayout> -It has subdirectories: - - doc - Files in HTML and text format that document usage, quirks of the - implementation, and contributor checklists. - - include - All header files for the C++ library are within this directory, - modulo specific runtime-related files that are in the libsupc++ - directory. - - include/std - Files meant to be found by #include <name> directives in - standard-conforming user programs. - - include/c - Headers intended to directly include standard C headers. - [NB: this can be enabled via --enable-cheaders=c] - - include/c_global - Headers intended to include standard C headers in - the global namespace, and put select names into the std:: - namespace. [NB: this is the default, and is the same as - --enable-cheaders=c_global] - - include/c_std - Headers intended to include standard C headers - already in namespace std, and put select names into the std:: - namespace. [NB: this is the same as --enable-cheaders=c_std] - - include/bits - Files included by standard headers and by other files in - the bits directory. - - include/backward - Headers provided for backward compatibility, such as <iostream.h>. - They are not used in this library. - - include/ext - Headers that define extensions to the standard library. No - standard header refers to any of them. - - scripts - Scripts that are used during the configure, build, make, or test - process. - - src - Files that are used in constructing the library, but are not - installed. - - testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*] - Test programs are here, and may be used to begin to exercise the - library. Support for "make check" and "make check-install" is - complete, and runs through all the subdirectories here when this - command is issued from the build directory. Please note that - "make check" requires DejaGNU 1.4 or later to be installed. Please - note that "make check-script" calls the script mkcheck, which - requires bash, and which may need the paths to bash adjusted to - work properly, as /bin/bash is assumed. - -Other subdirectories contain variant versions of certain files -that are meant to be copied or linked by the configure script. -Currently these are: - - config/abi - config/cpu - config/io - config/locale - config/os - -In addition, a subdirectory holds the convenience library libsupc++. - - libsupc++ - Contains the runtime library for C++, including exception - handling and memory allocation and deallocation, RTTI, terminate - handlers, etc. - -Note that glibc also has a bits/ subdirectory. We will either -need to be careful not to collide with names in its bits/ -directory; or rename bits to (e.g.) cppbits/. - -In files throughout the system, lines marked with an "XXX" indicate -a bug or incompletely-implemented feature. Lines marked "XXX MT" -indicate a place that may require attention for multi-thread safety. - </literallayout> - -</sect1> - -<sect1 id="contrib.coding_style" xreflabel="Coding Style"> - <?dbhtml filename="source_code_style.html"?> - <title>Coding Style</title> - <para> - </para> - <sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad"> - <title>Bad Identifiers</title> - <para> - Identifiers that conflict and should be avoided. - </para> - - <literallayout> - This is the list of names <quote>reserved to the - implementation</quote> that have been claimed by certain - compilers and system headers of interest, and should not be used - in the library. It will grow, of course. We generally are - interested in names that are not all-caps, except for those like - "_T" - - For Solaris: - _B - _C - _L - _N - _P - _S - _U - _X - _E1 - .. - _E24 - - Irix adds: - _A - _G - - MS adds: - _T - - BSD adds: - __used - __unused - __inline - _Complex - __istype - __maskrune - __tolower - __toupper - __wchar_t - __wint_t - _res - _res_ext - __tg_* - - SPU adds: - __ea - - For GCC: - - [Note that this list is out of date. It applies to the old - name-mangling; in G++ 3.0 and higher a different name-mangling is - used. In addition, many of the bugs relating to G++ interpreting - these names as operators have been fixed.] - - The full set of __* identifiers (combined from gcc/cp/lex.c and - gcc/cplus-dem.c) that are either old or new, but are definitely - recognized by the demangler, is: - - __aa - __aad - __ad - __addr - __adv - __aer - __als - __alshift - __amd - __ami - __aml - __amu - __aor - __apl - __array - __ars - __arshift - __as - __bit_and - __bit_ior - __bit_not - __bit_xor - __call - __cl - __cm - __cn - __co - __component - __compound - __cond - __convert - __delete - __dl - __dv - __eq - __er - __ge - __gt - __indirect - __le - __ls - __lt - __max - __md - __method_call - __mi - __min - __minus - __ml - __mm - __mn - __mult - __mx - __ne - __negate - __new - __nop - __nt - __nw - __oo - __op - __or - __pl - __plus - __postdecrement - __postincrement - __pp - __pt - __rf - __rm - __rs - __sz - __trunc_div - __trunc_mod - __truth_andif - __truth_not - __truth_orif - __vc - __vd - __vn - - SGI badnames: - __builtin_alloca - __builtin_fsqrt - __builtin_sqrt - __builtin_fabs - __builtin_dabs - __builtin_cast_f2i - __builtin_cast_i2f - __builtin_cast_d2ll - __builtin_cast_ll2d - __builtin_copy_dhi2i - __builtin_copy_i2dhi - __builtin_copy_dlo2i - __builtin_copy_i2dlo - __add_and_fetch - __sub_and_fetch - __or_and_fetch - __xor_and_fetch - __and_and_fetch - __nand_and_fetch - __mpy_and_fetch - __min_and_fetch - __max_and_fetch - __fetch_and_add - __fetch_and_sub - __fetch_and_or - __fetch_and_xor - __fetch_and_and - __fetch_and_nand - __fetch_and_mpy - __fetch_and_min - __fetch_and_max - __lock_test_and_set - __lock_release - __lock_acquire - __compare_and_swap - __synchronize - __high_multiply - __unix - __sgi - __linux__ - __i386__ - __i486__ - __cplusplus - __embedded_cplusplus - // long double conversion members mangled as __opr - // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html - _opr - </literallayout> - </sect2> - - <sect2 id="coding_style.example" xreflabel="coding_style.example"> - <title>By Example</title> - <literallayout> - This library is written to appropriate C++ coding standards. As such, - it is intended to precede the recommendations of the GNU Coding - Standard, which can be referenced in full here: - - http://www.gnu.org/prep/standards/standards.html#Formatting - - The rest of this is also interesting reading, but skip the "Design - Advice" part. - - The GCC coding conventions are here, and are also useful: - http://gcc.gnu.org/codingconventions.html - - In addition, because it doesn't seem to be stated explicitly anywhere - else, there is an 80 column source limit. - - ChangeLog entries for member functions should use the - classname::member function name syntax as follows: - - 1999-04-15 Dennis Ritchie <dr@att.com> - - * src/basic_file.cc (__basic_file::open): Fix thinko in - _G_HAVE_IO_FILE_OPEN bits. - - Notable areas of divergence from what may be previous local practice - (particularly for GNU C) include: - - 01. Pointers and references - char* p = "flop"; - char& c = *p; - -NOT- - char *p = "flop"; // wrong - char &c = *p; // wrong - - Reason: In C++, definitions are mixed with executable code. Here, - p is being initialized, not *p. This is near-universal - practice among C++ programmers; it is normal for C hackers - to switch spontaneously as they gain experience. - - 02. Operator names and parentheses - operator==(type) - -NOT- - operator == (type) // wrong - - Reason: The == is part of the function name. Separating - it makes the declaration look like an expression. - - 03. Function names and parentheses - void mangle() - -NOT- - void mangle () // wrong - - Reason: no space before parentheses (except after a control-flow - keyword) is near-universal practice for C++. It identifies the - parentheses as the function-call operator or declarator, as - opposed to an expression or other overloaded use of parentheses. - - 04. Template function indentation - template<typename T> - void - template_function(args) - { } - -NOT- - template<class T> - void template_function(args) {}; - - Reason: In class definitions, without indentation whitespace is - needed both above and below the declaration to distinguish - it visually from other members. (Also, re: "typename" - rather than "class".) T often could be int, which is - not a class. ("class", here, is an anachronism.) - - 05. Template class indentation - template<typename _CharT, typename _Traits> - class basic_ios : public ios_base - { - public: - // Types: - }; - -NOT- - template<class _CharT, class _Traits> - class basic_ios : public ios_base - { - public: - // Types: - }; - -NOT- - template<class _CharT, class _Traits> - class basic_ios : public ios_base - { - public: - // Types: - }; - - 06. Enumerators - enum - { - space = _ISspace, - print = _ISprint, - cntrl = _IScntrl - }; - -NOT- - enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; - - 07. Member initialization lists - All one line, separate from class name. - - gribble::gribble() - : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - -NOT- - gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - - 08. Try/Catch blocks - try - { - // - } - catch (...) - { - // - } - -NOT- - try { - // - } catch(...) { - // - } - - 09. Member functions declarations and definitions - Keywords such as extern, static, export, explicit, inline, etc - go on the line above the function name. Thus - - virtual int - foo() - -NOT- - virtual int foo() - - Reason: GNU coding conventions dictate return types for functions - are on a separate line than the function name and parameter list - for definitions. For C++, where we have member functions that can - be either inline definitions or declarations, keeping to this - standard allows all member function names for a given class to be - aligned to the same margin, increasing readability. - - - 10. Invocation of member functions with "this->" - For non-uglified names, use this->name to call the function. - - this->sync() - -NOT- - sync() - - Reason: Koenig lookup. - - 11. Namespaces - namespace std - { - blah blah blah; - } // namespace std - - -NOT- - - namespace std { - blah blah blah; - } // namespace std - - 12. Spacing under protected and private in class declarations: - space above, none below - i.e. - - public: - int foo; - - -NOT- - public: - - int foo; - - 13. Spacing WRT return statements. - no extra spacing before returns, no parenthesis - i.e. - - } - return __ret; - - -NOT- - } - - return __ret; - - -NOT- - - } - return (__ret); - - - 14. Location of global variables. - All global variables of class type, whether in the "user visible" - space (e.g., cin) or the implementation namespace, must be defined - as a character array with the appropriate alignment and then later - re-initialized to the correct value. - - This is due to startup issues on certain platforms, such as AIX. - For more explanation and examples, see src/globals.cc. All such - variables should be contained in that file, for simplicity. - - 15. Exception abstractions - Use the exception abstractions found in functexcept.h, which allow - C++ programmers to use this library with -fno-exceptions. (Even if - that is rarely advisable, it's a necessary evil for backwards - compatibility.) - - 16. Exception error messages - All start with the name of the function where the exception is - thrown, and then (optional) descriptive text is added. Example: - - __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); - - Reason: The verbose terminate handler prints out exception::what(), - as well as the typeinfo for the thrown exception. As this is the - default terminate handler, by putting location info into the - exception string, a very useful error message is printed out for - uncaught exceptions. So useful, in fact, that non-programmers can - give useful error messages, and programmers can intelligently - speculate what went wrong without even using a debugger. - - 17. The doxygen style guide to comments is a separate document, - see index. - - The library currently has a mixture of GNU-C and modern C++ coding - styles. The GNU C usages will be combed out gradually. - - Name patterns: - - For nonstandard names appearing in Standard headers, we are constrained - to use names that begin with underscores. This is called "uglification". - The convention is: - - Local and argument names: __[a-z].* - - Examples: __count __ix __s1 - - Type names and template formal-argument names: _[A-Z][^_].* - - Examples: _Helper _CharT _N - - Member data and function names: _M_.* - - Examples: _M_num_elements _M_initialize () - - Static data members, constants, and enumerations: _S_.* - - Examples: _S_max_elements _S_default_value - - Don't use names in the same scope that differ only in the prefix, - e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names. - (The most tempting of these seem to be and "_T" and "__sz".) - - Names must never have "__" internally; it would confuse name - unmanglers on some targets. Also, never use "__[0-9]", same reason. - - -------------------------- - - [BY EXAMPLE] - - #ifndef _HEADER_ - #define _HEADER_ 1 - - namespace std - { - class gribble - { - public: - gribble() throw(); - - gribble(const gribble&); - - explicit - gribble(int __howmany); - - gribble& - operator=(const gribble&); - - virtual - ~gribble() throw (); - - // Start with a capital letter, end with a period. - inline void - public_member(const char* __arg) const; - - // In-class function definitions should be restricted to one-liners. - int - one_line() { return 0 } - - int - two_lines(const char* arg) - { return strchr(arg, 'a'); } - - inline int - three_lines(); // inline, but defined below. - - // Note indentation. - template<typename _Formal_argument> - void - public_template() const throw(); - - template<typename _Iterator> - void - other_template(); - - private: - class _Helper; - - int _M_private_data; - int _M_more_stuff; - _Helper* _M_helper; - int _M_private_function(); - - enum _Enum - { - _S_one, - _S_two - }; - - static void - _S_initialize_library(); - }; - - // More-or-less-standard language features described by lack, not presence. - # ifndef _G_NO_LONGLONG - extern long long _G_global_with_a_good_long_name; // avoid globals! - # endif - - // Avoid in-class inline definitions, define separately; - // likewise for member class definitions: - inline int - gribble::public_member() const - { int __local = 0; return __local; } - - class gribble::_Helper - { - int _M_stuff; - - friend class gribble; - }; - } - - // Names beginning with "__": only for arguments and - // local variables; never use "__" in a type name, or - // within any name; never use "__[0-9]". - - #endif /* _HEADER_ */ - - - namespace std - { - template<typename T> // notice: "typename", not "class", no space - long_return_value_type<with_many, args> - function_name(char* pointer, // "char *pointer" is wrong. - char* argument, - const Reference& ref) - { - // int a_local; /* wrong; see below. */ - if (test) - { - nested code - } - - int a_local = 0; // declare variable at first use. - - // char a, b, *p; /* wrong */ - char a = 'a'; - char b = a + 1; - char* c = "abc"; // each variable goes on its own line, always. - - // except maybe here... - for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) { - // ... - } - } - - gribble::gribble() - : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - - inline int - gribble::three_lines() - { - // doesn't fit in one line. - } - } // namespace std - </literallayout> - </sect2> -</sect1> - -<sect1 id="contrib.doc_style" xreflabel="Documentation Style"> - <?dbhtml filename="documentation_style.html"?> - <title>Documentation Style</title> - <sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen"> - <title>Doxygen</title> - <sect3 id="doxygen.prereq" xreflabel="doxygen.prereq"> - <title>Prerequisites</title> - <para> - Prerequisite tools are Bash 2.x, - <ulink url="http://www.doxygen.org/">Doxygen</ulink>, and - the <ulink url="http://www.gnu.org/software/coreutils/">GNU - coreutils</ulink>. (GNU versions of find, xargs, and possibly - sed and grep are used, just because the GNU versions make - things very easy.) - </para> - - <para> - To generate the pretty pictures and hierarchy - graphs, the - <ulink url="http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink> - package will need to be installed. - </para> - </sect3> - - <sect3 id="doxygen.rules" xreflabel="doxygen.rules"> - <title>Generating the Doxygen Files</title> - <para> - The following Makefile rules run Doxygen to generate HTML - docs, XML docs, and the man pages. - </para> - - <para> - <screen><userinput>make doc-html-doxygen</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-xml-doxygen</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-man-doxygen</userinput></screen> - </para> - - <para> - Careful observers will see that the Makefile rules simply call - a script from the source tree, <filename>run_doxygen</filename>, which - does the actual work of running Doxygen and then (most - importantly) massaging the output files. If for some reason - you prefer to not go through the Makefile, you can call this - script directly. (Start by passing <literal>--help</literal>.) - </para> - - <para> - If you wish to tweak the Doxygen settings, do so by editing - <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow - library hackers are written in triple-# comments. - </para> - - </sect3> - - <sect3 id="doxygen.markup" xreflabel="doxygen.markup"> - <title>Markup</title> - - <para> - In general, libstdc++ files should be formatted according to - the rules found in the - <link linkend="contrib.coding_style">Coding Standard</link>. Before - any doxygen-specific formatting tweaks are made, please try to - make sure that the initial formatting is sound. - </para> - - <para> - Adding Doxygen markup to a file (informally called - <quote>doxygenating</quote>) is very simple. The Doxygen manual can be - found - <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>. - We try to use a very-recent version of Doxygen. - </para> - - <para> - For classes, use - <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname> - and <classname>std::pair</classname> as examples. For - functions, see their member functions, and the free functions - in <filename>stl_algobase.h</filename>. Member functions of - other container-like types should read similarly to these - member functions. - </para> - - <para> - These points accompany the first list in section 3.1 of the - Doxygen manual: - </para> - - <orderedlist> - <listitem><para>Use the Javadoc style...</para></listitem> - <listitem> - <para> - ...not the Qt style. The intermediate *'s are preferred. - </para> - </listitem> - <listitem> - <para> - Use the triple-slash style only for one-line comments (the - <quote>brief</quote> mode). Very recent versions of Doxygen permit - full-mode comments in triple-slash blocks, but the - formatting still comes out wonky. - </para> - </listitem> - <listitem> - <para> - This is disgusting. Don't do this. - </para> - </listitem> - </orderedlist> - - <para> - Use the @-style of commands, not the !-style. Please be - careful about whitespace in your markup comments. Most of the - time it doesn't matter; doxygen absorbs most whitespace, and - both HTML and *roff are agnostic about whitespace. However, - in <pre> blocks and @code/@endcode sections, spacing can - have <quote>interesting</quote> effects. - </para> - - <para> - Use either kind of grouping, as - appropriate. <filename>doxygroups.cc</filename> exists for this - purpose. See <filename>stl_iterator.h</filename> for a good example - of the <quote>other</quote> kind of grouping. - </para> - - <para> - Please use markup tags like @p and @a when referring to things - such as the names of function parameters. Use @e for emphasis - when necessary. Use @c to refer to other standard names. - (Examples of all these abound in the present code.) - </para> - - </sect3> - - </sect2> - - <sect2 id="doc_style.docbook" xreflabel="doc_style.docbook"> - <title>Docbook</title> - - <sect3 id="docbook.prereq" xreflabel="docbook.prereq"> - <title>Prerequisites</title> - <para> - Editing the DocBook sources requires an XML editor. Many - exist: some notable options - include <command>emacs</command>, <application>Kate</application>, - or <application>Conglomerate</application>. - </para> - - <para> - Some editors support special <quote>XML Validation</quote> - modes that can validate the file as it is - produced. Recommended is the <command>nXML Mode</command> - for <command>emacs</command>. - </para> - - <para> - Besides an editor, additional DocBook files and XML tools are - also required. - </para> - - <para> - Access to the DocBook stylesheets and DTD is required. The - stylesheets are usually packaged by vendor, in something - like <filename>docbook-style-xsl</filename>. To exactly match - generated output, please use a version of the stylesheets - equivalent - to <filename>docbook-style-xsl-1.74.0-5</filename>. The - installation directory for this package corresponds to - the <literal>XSL_STYLE_DIR</literal> - in <filename>doc/Makefile.am</filename> and defaults - to <filename class="directory">/usr/share/sgml/docbook/xsl-stylesheets</filename>. - </para> - - <para> - For processing XML, an XML processor and some style - sheets are necessary. Defaults are <command>xsltproc</command> - provided by <filename>libxslt</filename>. - </para> - - <para> - For validating the XML document, you'll need - something like <command>xmllint</command> and access to the - DocBook DTD. These are provided - by a vendor package like <filename>libxml2</filename>. - </para> - - <para> - For PDF output, something that transforms valid XML to PDF is - required. Possible solutions include <command>xmlto</command>, - <ulink url="http://xmlgraphics.apache.org/fop/">Apache - FOP</ulink>, or <command>prince</command>. Other options are - listed on the DocBook web <ulink - url="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Please - consult the <email>libstdc++@gcc.gnu.org</email> list when - preparing printed manuals for current best practice and suggestions. - </para> - - <para> - Make sure that the XML documentation and markup is valid for - any change. This can be done easily, with the validation rules - in the <filename>Makefile</filename>, which is equivalent to doing: - </para> - - <screen> - <userinput> -xmllint --noout --valid <filename>xml/index.xml</filename> - </userinput> - </screen> - </sect3> - - <sect3 id="docbook.rules" xreflabel="docbook.rules"> - <title>Generating the DocBook Files</title> - - <para> - The following Makefile rules generate (in order): an HTML - version of all the documentation, a PDF version of the same, a - single XML document, and the result of validating the entire XML - document. - </para> - - <para> - <screen><userinput>make doc-html</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-pdf</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-xml-single</userinput></screen> - </para> - - <para> - <screen><userinput>make doc-xml-validate</userinput></screen> - </para> - - </sect3> - - <sect3 id="docbook.examples" xreflabel="docbook.examples"> - <title>File Organization and Basics</title> - - <literallayout> - <emphasis>Which files are important</emphasis> - - All Docbook files are in the directory - libstdc++-v3/doc/xml - - Inside this directory, the files of importance: - spine.xml - index to documentation set - manual/spine.xml - index to manual - manual/*.xml - individual chapters and sections of the manual - faq.xml - index to FAQ - api.xml - index to source level / API - - All *.txml files are template xml files, i.e., otherwise empty files with - the correct structure, suitable for filling in with new information. - - <emphasis>Canonical Writing Style</emphasis> - - class template - function template - member function template - (via C++ Templates, Vandevoorde) - - class in namespace std: allocator, not std::allocator - - header file: iostream, not <iostream> - - - <emphasis>General structure</emphasis> - - <set> - <book> - </book> - - <book> - <chapter> - </chapter> - </book> - - <book> - <part> - <chapter> - <section> - </section> - - <sect1> - </sect1> - - <sect1> - <sect2> - </sect2> - </sect1> - </chapter> - - <chapter> - </chapter> - </part> - </book> - - </set> - </literallayout> - </sect3> - - <sect3 id="docbook.markup" xreflabel="docbook.markup"> - <title>Markup By Example</title> - -<para> -Complete details on Docbook markup can be found in the DocBook Element -Reference, <ulink url="http://www.docbook.org/tdg/en/html/part2.html">online</ulink>. An -incomplete reference for HTML to Docbook conversion is detailed in the -table below. -</para> - -<table frame='all'> -<title>HTML to Docbook XML markup comparison</title> -<tgroup cols='2' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> - - <thead> - <row> - <entry>HTML</entry> - <entry>XML</entry> - </row> - </thead> - - <tbody> - <row> - <entry><p></entry> - <entry><para></entry> - </row> - <row> - <entry><pre></entry> - <entry><computeroutput>, <programlisting>, - <literallayout></entry> - </row> - <row> - <entry><ul></entry> - <entry><itemizedlist></entry> - </row> - <row> - <entry><ol></entry> - <entry><orderedlist></entry> - </row> - <row> - <entry><il></entry> - <entry><listitem></entry> - </row> - <row> - <entry><dl></entry> - <entry><variablelist></entry> - </row> - <row> - <entry><dt></entry> - <entry><term></entry> - </row> - <row> - <entry><dd></entry> - <entry><listitem></entry> - </row> - - <row> - <entry><a href=""></entry> - <entry><ulink url=""></entry> - </row> - <row> - <entry><code></entry> - <entry><literal>, <programlisting></entry> - </row> - <row> - <entry><strong></entry> - <entry><emphasis></entry> - </row> - <row> - <entry><em></entry> - <entry><emphasis></entry> - </row> - <row> - <entry>"</entry> - <entry><quote></entry> - </row> - </tbody> -</tgroup> -</table> - -<para> - And examples of detailed markup for which there are no real HTML - equivalents are listed in the table below. -</para> - -<table frame='all'> -<title>Docbook XML Element Use</title> -<tgroup cols='2' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> - - <thead> - <row> - <entry>Element</entry> - <entry>Use</entry> - </row> - </thead> - - <tbody> - <row> - <entry><structname></entry> - <entry><structname>char_traits</structname></entry> - </row> - <row> - <entry><classname></entry> - <entry><classname>string</classname></entry> - </row> - <row> - <entry><function></entry> - <entry> - <para><function>clear()</function></para> - <para><function>fs.clear()</function></para> - </entry> - </row> - <row> - <entry><type></entry> - <entry><type>long long</type></entry> - </row> - <row> - <entry><varname></entry> - <entry><varname>fs</varname></entry> - </row> - <row> - <entry><literal></entry> - <entry> - <para><literal>-Weffc++</literal></para> - <para><literal>rel_ops</literal></para> - </entry> - </row> - <row> - <entry><constant></entry> - <entry> - <para><constant>_GNU_SOURCE</constant></para> - <para><constant>3.0</constant></para> - </entry> - </row> - <row> - <entry><command></entry> - <entry><command>g++</command></entry> - </row> - <row> - <entry><errortext></entry> - <entry><errortext>In instantiation of</errortext></entry> - </row> - <row> - <entry><filename></entry> - <entry> - <para><filename class="headerfile">ctype.h</filename></para> - <para><filename class="directory">/home/gcc/build</filename></para> - </entry> - </row> - </tbody> -</tgroup> -</table> - - </sect3> - </sect2> - -</sect1> - -<sect1 id="contrib.design_notes" xreflabel="Design Notes"> - <?dbhtml filename="source_design_notes.html"?> - <title>Design Notes</title> - <para> - </para> - - <literallayout> - - The Library - ----------- - - This paper is covers two major areas: - - - Features and policies not mentioned in the standard that - the quality of the library implementation depends on, including - extensions and "implementation-defined" features; - - - Plans for required but unimplemented library features and - optimizations to them. - - Overhead - -------- - - The standard defines a large library, much larger than the standard - C library. A naive implementation would suffer substantial overhead - in compile time, executable size, and speed, rendering it unusable - in many (particularly embedded) applications. The alternative demands - care in construction, and some compiler support, but there is no - need for library subsets. - - What are the sources of this overhead? There are four main causes: - - - The library is specified almost entirely as templates, which - with current compilers must be included in-line, resulting in - very slow builds as tens or hundreds of thousands of lines - of function definitions are read for each user source file. - Indeed, the entire SGI STL, as well as the dos Reis valarray, - are provided purely as header files, largely for simplicity in - porting. Iostream/locale is (or will be) as large again. - - - The library is very flexible, specifying a multitude of hooks - where users can insert their own code in place of defaults. - When these hooks are not used, any time and code expended to - support that flexibility is wasted. - - - Templates are often described as causing to "code bloat". In - practice, this refers (when it refers to anything real) to several - independent processes. First, when a class template is manually - instantiated in its entirely, current compilers place the definitions - for all members in a single object file, so that a program linking - to one member gets definitions of all. Second, template functions - which do not actually depend on the template argument are, under - current compilers, generated anew for each instantiation, rather - than being shared with other instantiations. Third, some of the - flexibility mentioned above comes from virtual functions (both in - regular classes and template classes) which current linkers add - to the executable file even when they manifestly cannot be called. - - - The library is specified to use a language feature, exceptions, - which in the current gcc compiler ABI imposes a run time and - code space cost to handle the possibility of exceptions even when - they are not used. Under the new ABI (accessed with -fnew-abi), - there is a space overhead and a small reduction in code efficiency - resulting from lost optimization opportunities associated with - non-local branches associated with exceptions. - - What can be done to eliminate this overhead? A variety of coding - techniques, and compiler, linker and library improvements and - extensions may be used, as covered below. Most are not difficult, - and some are already implemented in varying degrees. - - Overhead: Compilation Time - -------------------------- - - Providing "ready-instantiated" template code in object code archives - allows us to avoid generating and optimizing template instantiations - in each compilation unit which uses them. However, the number of such - instantiations that are useful to provide is limited, and anyway this - is not enough, by itself, to minimize compilation time. In particular, - it does not reduce time spent parsing conforming headers. - - Quicker header parsing will depend on library extensions and compiler - improvements. One approach is some variation on the techniques - previously marketed as "pre-compiled headers", now standardized as - support for the "export" keyword. "Exported" template definitions - can be placed (once) in a "repository" -- really just a library, but - of template definitions rather than object code -- to be drawn upon - at link time when an instantiation is needed, rather than placed in - header files to be parsed along with every compilation unit. - - Until "export" is implemented we can put some of the lengthy template - definitions in #if guards or alternative headers so that users can skip - over the full definitions when they need only the ready-instantiated - specializations. - - To be precise, this means that certain headers which define - templates which users normally use only for certain arguments - can be instrumented to avoid exposing the template definitions - to the compiler unless a macro is defined. For example, in - <string>, we might have: - - template <class _CharT, ... > class basic_string { - ... // member declarations - }; - ... // operator declarations - - #ifdef _STRICT_ISO_ - # if _G_NO_TEMPLATE_EXPORT - # include <bits/std_locale.h> // headers needed by definitions - # ... - # include <bits/string.tcc> // member and global template definitions. - # endif - #endif - - Users who compile without specifying a strict-ISO-conforming flag - would not see many of the template definitions they now see, and rely - instead on ready-instantiated specializations in the library. This - technique would be useful for the following substantial components: - string, locale/iostreams, valarray. It would *not* be useful or - usable with the following: containers, algorithms, iterators, - allocator. Since these constitute a large (though decreasing) - fraction of the library, the benefit the technique offers is - limited. - - The language specifies the semantics of the "export" keyword, but - the gcc compiler does not yet support it. When it does, problems - with large template inclusions can largely disappear, given some - minor library reorganization, along with the need for the apparatus - described above. - - Overhead: Flexibility Cost - -------------------------- - - The library offers many places where users can specify operations - to be performed by the library in place of defaults. Sometimes - this seems to require that the library use a more-roundabout, and - possibly slower, way to accomplish the default requirements than - would be used otherwise. - - The primary protection against this overhead is thorough compiler - optimization, to crush out layers of inline function interfaces. - Kuck & Associates has demonstrated the practicality of this kind - of optimization. - - The second line of defense against this overhead is explicit - specialization. By defining helper function templates, and writing - specialized code for the default case, overhead can be eliminated - for that case without sacrificing flexibility. This takes full - advantage of any ability of the optimizer to crush out degenerate - code. - - The library specifies many virtual functions which current linkers - load even when they cannot be called. Some minor improvements to the - compiler and to ld would eliminate any such overhead by simply - omitting virtual functions that the complete program does not call. - A prototype of this work has already been done. For targets where - GNU ld is not used, a "pre-linker" could do the same job. - - The main areas in the standard interface where user flexibility - can result in overhead are: - - - Allocators: Containers are specified to use user-definable - allocator types and objects, making tuning for the container - characteristics tricky. - - - Locales: the standard specifies locale objects used to implement - iostream operations, involving many virtual functions which use - streambuf iterators. - - - Algorithms and containers: these may be instantiated on any type, - frequently duplicating code for identical operations. - - - Iostreams and strings: users are permitted to use these on their - own types, and specify the operations the stream must use on these - types. - - Note that these sources of overhead are _avoidable_. The techniques - to avoid them are covered below. - - Code Bloat - ---------- - - In the SGI STL, and in some other headers, many of the templates - are defined "inline" -- either explicitly or by their placement - in class definitions -- which should not be inline. This is a - source of code bloat. Matt had remarked that he was relying on - the compiler to recognize what was too big to benefit from inlining, - and generate it out-of-line automatically. However, this also can - result in code bloat except where the linker can eliminate the extra - copies. - - Fixing these cases will require an audit of all inline functions - defined in the library to determine which merit inlining, and moving - the rest out of line. This is an issue mainly in chapters 23, 25, and - 27. Of course it can be done incrementally, and we should generally - accept patches that move large functions out of line and into ".tcc" - files, which can later be pulled into a repository. Compiler/linker - improvements to recognize very large inline functions and move them - out-of-line, but shared among compilation units, could make this - work unnecessary. - - Pre-instantiating template specializations currently produces large - amounts of dead code which bloats statically linked programs. The - current state of the static library, libstdc++.a, is intolerable on - this account, and will fuel further confused speculation about a need - for a library "subset". A compiler improvement that treats each - instantiated function as a separate object file, for linking purposes, - would be one solution to this problem. An alternative would be to - split up the manual instantiation files into dozens upon dozens of - little files, each compiled separately, but an abortive attempt at - this was done for <string> and, though it is far from complete, it - is already a nuisance. A better interim solution (just until we have - "export") is badly needed. - - When building a shared library, the current compiler/linker cannot - automatically generate the instantiations needed. This creates a - miserable situation; it means any time something is changed in the - library, before a shared library can be built someone must manually - copy the declarations of all templates that are needed by other parts - of the library to an "instantiation" file, and add it to the build - system to be compiled and linked to the library. This process is - readily automated, and should be automated as soon as possible. - Users building their own shared libraries experience identical - frustrations. - - Sharing common aspects of template definitions among instantiations - can radically reduce code bloat. The compiler could help a great - deal here by recognizing when a function depends on nothing about - a template parameter, or only on its size, and giving the resulting - function a link-name "equate" that allows it to be shared with other - instantiations. Implementation code could take advantage of the - capability by factoring out code that does not depend on the template - argument into separate functions to be merged by the compiler. - - Until such a compiler optimization is implemented, much can be done - manually (if tediously) in this direction. One such optimization is - to derive class templates from non-template classes, and move as much - implementation as possible into the base class. Another is to partial- - specialize certain common instantiations, such as vector<T*>, to share - code for instantiations on all types T. While these techniques work, - they are far from the complete solution that a compiler improvement - would afford. - - Overhead: Expensive Language Features - ------------------------------------- - - The main "expensive" language feature used in the standard library - is exception support, which requires compiling in cleanup code with - static table data to locate it, and linking in library code to use - the table. For small embedded programs the amount of such library - code and table data is assumed by some to be excessive. Under the - "new" ABI this perception is generally exaggerated, although in some - cases it may actually be excessive. - - To implement a library which does not use exceptions directly is - not difficult given minor compiler support (to "turn off" exceptions - and ignore exception constructs), and results in no great library - maintenance difficulties. To be precise, given "-fno-exceptions", - the compiler should treat "try" blocks as ordinary blocks, and - "catch" blocks as dead code to ignore or eliminate. Compiler - support is not strictly necessary, except in the case of "function - try blocks"; otherwise the following macros almost suffice: - - #define throw(X) - #define try if (true) - #define catch(X) else if (false) - - However, there may be a need to use function try blocks in the - library implementation, and use of macros in this way can make - correct diagnostics impossible. Furthermore, use of this scheme - would require the library to call a function to re-throw exceptions - from a try block. Implementing the above semantics in the compiler - is preferable. - - Given the support above (however implemented) it only remains to - replace code that "throws" with a call to a well-documented "handler" - function in a separate compilation unit which may be replaced by - the user. The main source of exceptions that would be difficult - for users to avoid is memory allocation failures, but users can - define their own memory allocation primitives that never throw. - Otherwise, the complete list of such handlers, and which library - functions may call them, would be needed for users to be able to - implement the necessary substitutes. (Fortunately, they have the - source code.) - - Opportunities - ------------- - - The template capabilities of C++ offer enormous opportunities for - optimizing common library operations, well beyond what would be - considered "eliminating overhead". In particular, many operations - done in Glibc with macros that depend on proprietary language - extensions can be implemented in pristine Standard C++. For example, - the chapter 25 algorithms, and even C library functions such as strchr, - can be specialized for the case of static arrays of known (small) size. - - Detailed optimization opportunities are identified below where - the component where they would appear is discussed. Of course new - opportunities will be identified during implementation. - - Unimplemented Required Library Features - --------------------------------------- - - The standard specifies hundreds of components, grouped broadly by - chapter. These are listed in excruciating detail in the CHECKLIST - file. - - 17 general - 18 support - 19 diagnostics - 20 utilities - 21 string - 22 locale - 23 containers - 24 iterators - 25 algorithms - 26 numerics - 27 iostreams - Annex D backward compatibility - - Anyone participating in implementation of the library should obtain - a copy of the standard, ISO 14882. People in the U.S. can obtain an - electronic copy for US$18 from ANSI's web site. Those from other - countries should visit http://www.iso.ch/ to find out the location - of their country's representation in ISO, in order to know who can - sell them a copy. - - The emphasis in the following sections is on unimplemented features - and optimization opportunities. - - Chapter 17 General - ------------------- - - Chapter 17 concerns overall library requirements. - - The standard doesn't mention threads. A multi-thread (MT) extension - primarily affects operators new and delete (18), allocator (20), - string (21), locale (22), and iostreams (27). The common underlying - support needed for this is discussed under chapter 20. - - The standard requirements on names from the C headers create a - lot of work, mostly done. Names in the C headers must be visible - in the std:: and sometimes the global namespace; the names in the - two scopes must refer to the same object. More stringent is that - Koenig lookup implies that any types specified as defined in std:: - really are defined in std::. Names optionally implemented as - macros in C cannot be macros in C++. (An overview may be read at - <http://www.cantrip.org/cheaders.html>). The scripts "inclosure" - and "mkcshadow", and the directories shadow/ and cshadow/, are the - beginning of an effort to conform in this area. - - A correct conforming definition of C header names based on underlying - C library headers, and practical linking of conforming namespaced - customer code with third-party C libraries depends ultimately on - an ABI change, allowing namespaced C type names to be mangled into - type names as if they were global, somewhat as C function names in a - namespace, or C++ global variable names, are left unmangled. Perhaps - another "extern" mode, such as 'extern "C-global"' would be an - appropriate place for such type definitions. Such a type would - affect mangling as follows: - - namespace A { - struct X {}; - extern "C-global" { // or maybe just 'extern "C"' - struct Y {}; - }; - } - void f(A::X*); // mangles to f__FPQ21A1X - void f(A::Y*); // mangles to f__FP1Y - - (It may be that this is really the appropriate semantics for regular - 'extern "C"', and 'extern "C-global"', as an extension, would not be - necessary.) This would allow functions declared in non-standard C headers - (and thus fixable by neither us nor users) to link properly with functions - declared using C types defined in properly-namespaced headers. The - problem this solves is that C headers (which C++ programmers do persist - in using) frequently forward-declare C struct tags without including - the header where the type is defined, as in - - struct tm; - void munge(tm*); - - Without some compiler accommodation, munge cannot be called by correct - C++ code using a pointer to a correctly-scoped tm* value. - - The current C headers use the preprocessor extension "#include_next", - which the compiler complains about when run "-pedantic". - (Incidentally, it appears that "-fpedantic" is currently ignored, - probably a bug.) The solution in the C compiler is to use - "-isystem" rather than "-I", but unfortunately in g++ this seems - also to wrap the whole header in an 'extern "C"' block, so it's - unusable for C++ headers. The correct solution appears to be to - allow the various special include-directory options, if not given - an argument, to affect subsequent include-directory options additively, - so that if one said - - -pedantic -iprefix $(prefix) \ - -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ - -iwithprefix -I g++-v3/ext - - the compiler would search $(prefix)/g++-v3 and not report - pedantic warnings for files found there, but treat files in - $(prefix)/g++-v3/ext pedantically. (The undocumented semantics - of "-isystem" in g++ stink. Can they be rescinded? If not it - must be replaced with something more rationally behaved.) - - All the C headers need the treatment above; in the standard these - headers are mentioned in various chapters. Below, I have only - mentioned those that present interesting implementation issues. - - The components identified as "mostly complete", below, have not been - audited for conformance. In many cases where the library passes - conformance tests we have non-conforming extensions that must be - wrapped in #if guards for "pedantic" use, and in some cases renamed - in a conforming way for continued use in the implementation regardless - of conformance flags. - - The STL portion of the library still depends on a header - stl/bits/stl_config.h full of #ifdef clauses. This apparatus - should be replaced with autoconf/automake machinery. - - The SGI STL defines a type_traits<> template, specialized for - many types in their code including the built-in numeric and - pointer types and some library types, to direct optimizations of - standard functions. The SGI compiler has been extended to generate - specializations of this template automatically for user types, - so that use of STL templates on user types can take advantage of - these optimizations. Specializations for other, non-STL, types - would make more optimizations possible, but extending the gcc - compiler in the same way would be much better. Probably the next - round of standardization will ratify this, but probably with - changes, so it probably should be renamed to place it in the - implementation namespace. - - The SGI STL also defines a large number of extensions visible in - standard headers. (Other extensions that appear in separate headers - have been sequestered in subdirectories ext/ and backward/.) All - these extensions should be moved to other headers where possible, - and in any case wrapped in a namespace (not std!), and (where kept - in a standard header) girded about with macro guards. Some cannot be - moved out of standard headers because they are used to implement - standard features. The canonical method for accommodating these - is to use a protected name, aliased in macro guards to a user-space - name. Unfortunately C++ offers no satisfactory template typedef - mechanism, so very ad-hoc and unsatisfactory aliasing must be used - instead. - - Implementation of a template typedef mechanism should have the highest - priority among possible extensions, on the same level as implementation - of the template "export" feature. - - Chapter 18 Language support - ---------------------------- - - Headers: <limits> <new> <typeinfo> <exception> - C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp> - <ctime> <csignal> <cstdlib> (also 21, 25, 26) - - This defines the built-in exceptions, rtti, numeric_limits<>, - operator new and delete. Much of this is provided by the - compiler in its static runtime library. - - Work to do includes defining numeric_limits<> specializations in - separate files for all target architectures. Values for integer types - except for bool and wchar_t are readily obtained from the C header - <limits.h>, but values for the remaining numeric types (bool, wchar_t, - float, double, long double) must be entered manually. This is - largely dog work except for those members whose values are not - easily deduced from available documentation. Also, this involves - some work in target configuration to identify the correct choice of - file to build against and to install. - - The definitions of the various operators new and delete must be - made thread-safe, which depends on a portable exclusion mechanism, - discussed under chapter 20. Of course there is always plenty of - room for improvements to the speed of operators new and delete. - - <cstdarg>, in Glibc, defines some macros that gcc does not allow to - be wrapped into an inline function. Probably this header will demand - attention whenever a new target is chosen. The functions atexit(), - exit(), and abort() in cstdlib have different semantics in C++, so - must be re-implemented for C++. - - Chapter 19 Diagnostics - ----------------------- - - Headers: <stdexcept> - C headers: <cassert> <cerrno> - - This defines the standard exception objects, which are "mostly complete". - Cygnus has a version, and now SGI provides a slightly different one. - It makes little difference which we use. - - The C global name "errno", which C allows to be a variable or a macro, - is required in C++ to be a macro. For MT it must typically result in - a function call. - - Chapter 20 Utilities - --------------------- - Headers: <utility> <functional> <memory> - C header: <ctime> (also in 18) - - SGI STL provides "mostly complete" versions of all the components - defined in this chapter. However, the auto_ptr<> implementation - is known to be wrong. Furthermore, the standard definition of it - is known to be unimplementable as written. A minor change to the - standard would fix it, and auto_ptr<> should be adjusted to match. - - Multi-threading affects the allocator implementation, and there must - be configuration/installation choices for different users' MT - requirements. Anyway, users will want to tune allocator options - to support different target conditions, MT or no. - - The primitives used for MT implementation should be exposed, as an - extension, for users' own work. We need cross-CPU "mutex" support, - multi-processor shared-memory atomic integer operations, and single- - processor uninterruptible integer operations, and all three configurable - to be stubbed out for non-MT use, or to use an appropriately-loaded - dynamic library for the actual runtime environment, or statically - compiled in for cases where the target architecture is known. - - Chapter 21 String - ------------------ - Headers: <string> - C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27) - <cstdlib> (also in 18, 25, 26) - - We have "mostly-complete" char_traits<> implementations. Many of the - char_traits<char> operations might be optimized further using existing - proprietary language extensions. - - We have a "mostly-complete" basic_string<> implementation. The work - to manually instantiate char and wchar_t specializations in object - files to improve link-time behavior is extremely unsatisfactory, - literally tripling library-build time with no commensurate improvement - in static program link sizes. It must be redone. (Similar work is - needed for some components in chapters 22 and 27.) - - Other work needed for strings is MT-safety, as discussed under the - chapter 20 heading. - - The standard C type mbstate_t from <cwchar> and used in char_traits<> - must be different in C++ than in C, because in C++ the default constructor - value mbstate_t() must be the "base" or "ground" sequence state. - (According to the likely resolution of a recently raised Core issue, - this may become unnecessary. However, there are other reasons to - use a state type not as limited as whatever the C library provides.) - If we might want to provide conversions from (e.g.) internally- - represented EUC-wide to externally-represented Unicode, or vice- - versa, the mbstate_t we choose will need to be more accommodating - than what might be provided by an underlying C library. - - There remain some basic_string template-member functions which do - not overload properly with their non-template brethren. The infamous - hack akin to what was done in vector<> is needed, to conform to - 23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', - or incomplete, are so marked for this reason. - - Replacing the string iterators, which currently are simple character - pointers, with class objects would greatly increase the safety of the - client interface, and also permit a "debug" mode in which range, - ownership, and validity are rigorously checked. The current use of - raw pointers as string iterators is evil. vector<> iterators need the - same treatment. Note that the current implementation freely mixes - pointers and iterators, and that must be fixed before safer iterators - can be introduced. - - Some of the functions in <cstring> are different from the C version. - generally overloaded on const and non-const argument pointers. For - example, in <cstring> strchr is overloaded. The functions isupper - etc. in <cctype> typically implemented as macros in C are functions - in C++, because they are overloaded with others of the same name - defined in <locale>. - - Many of the functions required in <cwctype> and <cwchar> cannot be - implemented using underlying C facilities on intended targets because - such facilities only partly exist. - - Chapter 22 Locale - ------------------ - Headers: <locale> - C headers: <clocale> - - We have a "mostly complete" class locale, with the exception of - code for constructing, and handling the names of, named locales. - The ways that locales are named (particularly when categories - (e.g. LC_TIME, LC_COLLATE) are different) varies among all target - environments. This code must be written in various versions and - chosen by configuration parameters. - - Members of many of the facets defined in <locale> are stubs. Generally, - there are two sets of facets: the base class facets (which are supposed - to implement the "C" locale) and the "byname" facets, which are supposed - to read files to determine their behavior. The base ctype<>, collate<>, - and numpunct<> facets are "mostly complete", except that the table of - bitmask values used for "is" operations, and corresponding mask values, - are still defined in libio and just included/linked. (We will need to - implement these tables independently, soon, but should take advantage - of libio where possible.) The num_put<>::put members for integer types - are "mostly complete". - - A complete list of what has and has not been implemented may be - found in CHECKLIST. However, note that the current definition of - codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write - out the raw bytes representing the wide characters, rather than - trying to convert each to a corresponding single "char" value. - - Some of the facets are more important than others. Specifically, - the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets - are used by other library facilities defined in <string>, <istream>, - and <ostream>, and the codecvt<> facet is used by basic_filebuf<> - in <fstream>, so a conforming iostream implementation depends on - these. - - The "long long" type eventually must be supported, but code mentioning - it should be wrapped in #if guards to allow pedantic-mode compiling. - - Performance of num_put<> and num_get<> depend critically on - caching computed values in ios_base objects, and on extensions - to the interface with streambufs. - - Specifically: retrieving a copy of the locale object, extracting - the needed facets, and gathering data from them, for each call to - (e.g.) operator<< would be prohibitively slow. To cache format - data for use by num_put<> and num_get<> we have a _Format_cache<> - object stored in the ios_base::pword() array. This is constructed - and initialized lazily, and is organized purely for utility. It - is discarded when a new locale with different facets is imbued. - - Using only the public interfaces of the iterator arguments to the - facet functions would limit performance by forbidding "vector-style" - character operations. The streambuf iterator optimizations are - described under chapter 24, but facets can also bypass the streambuf - iterators via explicit specializations and operate directly on the - streambufs, and use extended interfaces to get direct access to the - streambuf internal buffer arrays. These extensions are mentioned - under chapter 27. These optimizations are particularly important - for input parsing. - - Unused virtual members of locale facets can be omitted, as mentioned - above, by a smart linker. - - Chapter 23 Containers - ---------------------- - Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset> - - All the components in chapter 23 are implemented in the SGI STL. - They are "mostly complete"; they include a large number of - nonconforming extensions which must be wrapped. Some of these - are used internally and must be renamed or duplicated. - - The SGI components are optimized for large-memory environments. For - embedded targets, different criteria might be more appropriate. Users - will want to be able to tune this behavior. We should provide - ways for users to compile the library with different memory usage - characteristics. - - A lot more work is needed on factoring out common code from different - specializations to reduce code size here and in chapter 25. The - easiest fix for this would be a compiler/ABI improvement that allows - the compiler to recognize when a specialization depends only on the - size (or other gross quality) of a template argument, and allow the - linker to share the code with similar specializations. In its - absence, many of the algorithms and containers can be partial- - specialized, at least for the case of pointers, but this only solves - a small part of the problem. Use of a type_traits-style template - allows a few more optimization opportunities, more if the compiler - can generate the specializations automatically. - - As an optimization, containers can specialize on the default allocator - and bypass it, or take advantage of details of its implementation - after it has been improved upon. - - Replacing the vector iterators, which currently are simple element - pointers, with class objects would greatly increase the safety of the - client interface, and also permit a "debug" mode in which range, - ownership, and validity are rigorously checked. The current use of - pointers for iterators is evil. - - As mentioned for chapter 24, the deque iterator is a good example of - an opportunity to implement a "staged" iterator that would benefit - from specializations of some algorithms. - - Chapter 24 Iterators - --------------------- - Headers: <iterator> - - Standard iterators are "mostly complete", with the exception of - the stream iterators, which are not yet templatized on the - stream type. Also, the base class template iterator<> appears - to be wrong, so everything derived from it must also be wrong, - currently. - - The streambuf iterators (currently located in stl/bits/std_iterator.h, - but should be under bits/) can be rewritten to take advantage of - friendship with the streambuf implementation. - - Matt Austern has identified opportunities where certain iterator - types, particularly including streambuf iterators and deque - iterators, have a "two-stage" quality, such that an intermediate - limit can be checked much more quickly than the true limit on - range operations. If identified with a member of iterator_traits, - algorithms may be specialized for this case. Of course the - iterators that have this quality can be identified by specializing - a traits class. - - Many of the algorithms must be specialized for the streambuf - iterators, to take advantage of block-mode operations, in order - to allow iostream/locale operations' performance not to suffer. - It may be that they could be treated as staged iterators and - take advantage of those optimizations. - - Chapter 25 Algorithms - ---------------------- - Headers: <algorithm> - C headers: <cstdlib> (also in 18, 21, 26)) - - The algorithms are "mostly complete". As mentioned above, they - are optimized for speed at the expense of code and data size. - - Specializations of many of the algorithms for non-STL types would - give performance improvements, but we must use great care not to - interfere with fragile template overloading semantics for the - standard interfaces. Conventionally the standard function template - interface is an inline which delegates to a non-standard function - which is then overloaded (this is already done in many places in - the library). Particularly appealing opportunities for the sake of - iostream performance are for copy and find applied to streambuf - iterators or (as noted elsewhere) for staged iterators, of which - the streambuf iterators are a good example. - - The bsearch and qsort functions cannot be overloaded properly as - required by the standard because gcc does not yet allow overloading - on the extern-"C"-ness of a function pointer. - - Chapter 26 Numerics - -------------------- - Headers: <complex> <valarray> <numeric> - C headers: <cmath>, <cstdlib> (also 18, 21, 25) - - Numeric components: Gabriel dos Reis's valarray, Drepper's complex, - and the few algorithms from the STL are "mostly done". Of course - optimization opportunities abound for the numerically literate. It - is not clear whether the valarray implementation really conforms - fully, in the assumptions it makes about aliasing (and lack thereof) - in its arguments. - - The C div() and ldiv() functions are interesting, because they are the - only case where a C library function returns a class object by value. - Since the C++ type div_t must be different from the underlying C type - (which is in the wrong namespace) the underlying functions div() and - ldiv() cannot be re-used efficiently. Fortunately they are trivial to - re-implement. - - Chapter 27 Iostreams - --------------------- - Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream> - <iomanip> <sstream> <fstream> - C headers: <cstdio> <cwchar> (also in 21) - - Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>, - ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and - basic_ostream<> are well along, but basic_istream<> has had little work - done. The standard stream objects, <sstream> and <fstream> have been - started; basic_filebuf<> "write" functions have been implemented just - enough to do "hello, world". - - Most of the istream and ostream operators << and >> (with the exception - of the op<<(integer) ones) have not been changed to use locale primitives, - sentry objects, or char_traits members. - - All these templates should be manually instantiated for char and - wchar_t in a way that links only used members into user programs. - - Streambuf is fertile ground for optimization extensions. An extended - interface giving iterator access to its internal buffer would be very - useful for other library components. - - Iostream operations (primarily operators << and >>) can take advantage - of the case where user code has not specified a locale, and bypass locale - operations entirely. The current implementation of op<</num_put<>::put, - for the integer types, demonstrates how they can cache encoding details - from the locale on each operation. There is lots more room for - optimization in this area. - - The definition of the relationship between the standard streams - cout et al. and stdout et al. requires something like a "stdiobuf". - The SGI solution of using double-indirection to actually use a - stdio FILE object for buffering is unsatisfactory, because it - interferes with peephole loop optimizations. - - The <sstream> header work has begun. stringbuf can benefit from - friendship with basic_string<> and basic_string<>::_Rep to use - those objects directly as buffers, and avoid allocating and making - copies. - - The basic_filebuf<> template is a complex beast. It is specified to - use the locale facet codecvt<> to translate characters between native - files and the locale character encoding. In general this involves - two buffers, one of "char" representing the file and another of - "char_type", for the stream, with codecvt<> translating. The process - is complicated by the variable-length nature of the translation, and - the need to seek to corresponding places in the two representations. - For the case of basic_filebuf<char>, when no translation is needed, - a single buffer suffices. A specialized filebuf can be used to reduce - code space overhead when no locale has been imbued. Matt Austern's - work at SGI will be useful, perhaps directly as a source of code, or - at least as an example to draw on. - - Filebuf, almost uniquely (cf. operator new), depends heavily on - underlying environmental facilities. In current releases iostream - depends fairly heavily on libio constant definitions, but it should - be made independent. It also depends on operating system primitives - for file operations. There is immense room for optimizations using - (e.g.) mmap for reading. The shadow/ directory wraps, besides the - standard C headers, the libio.h and unistd.h headers, for use mainly - by filebuf. These wrappings have not been completed, though there - is scaffolding in place. - - The encapsulation of certain C header <cstdio> names presents an - interesting problem. It is possible to define an inline std::fprintf() - implemented in terms of the 'extern "C"' vfprintf(), but there is no - standard vfscanf() to use to implement std::fscanf(). It appears that - vfscanf but be re-implemented in C++ for targets where no vfscanf - extension has been defined. This is interesting in that it seems - to be the only significant case in the C library where this kind of - rewriting is necessary. (Of course Glibc provides the vfscanf() - extension.) (The functions related to exit() must be rewritten - for other reasons.) - - - Annex D - ------- - Headers: <strstream> - - Annex D defines many non-library features, and many minor - modifications to various headers, and a complete header. - It is "mostly done", except that the libstdc++-2 <strstream> - header has not been adopted into the library, or checked to - verify that it matches the draft in those details that were - clarified by the committee. Certainly it must at least be - moved into the std namespace. - - We still need to wrap all the deprecated features in #if guards - so that pedantic compile modes can detect their use. - - Nonstandard Extensions - ---------------------- - Headers: <iostream.h> <strstream.h> <hash> <rbtree> - <pthread_alloc> <stdiobuf> (etc.) - - User code has come to depend on a variety of nonstandard components - that we must not omit. Much of this code can be adopted from - libstdc++-v2 or from the SGI STL. This particularly includes - <iostream.h>, <strstream.h>, and various SGI extensions such - as <hash_map.h>. Many of these are already placed in the - subdirectories ext/ and backward/. (Note that it is better to - include them via "<backward/hash_map.h>" or "<ext/hash_map>" than - to search the subdirectory itself via a "-I" directive. - </literallayout> -</sect1> - -</appendix> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_free.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_free.xml deleted file mode 100644 index c2cf1c157..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_free.xml +++ /dev/null @@ -1,182 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<appendix id="appendix.free" xreflabel="Free"> -<?dbhtml filename="appendix_free.html"?> - -<appendixinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</appendixinfo> - -<title> - Free Software Needs Free Documentation - <indexterm> - <primary>Appendix</primary> - <secondary>Free Documentation</secondary> - </indexterm> -</title> - -<para> -The biggest deficiency in free operating systems is not in the -software--it is the lack of good free manuals that we can include in -these systems. Many of our most important programs do not come with -full manuals. Documentation is an essential part of any software -package; when an important free software package does not come with a -free manual, that is a major gap. We have many such gaps today. -</para> - -<para> -Once upon a time, many years ago, I thought I would learn Perl. I got -a copy of a free manual, but I found it hard to read. When I asked -Perl users about alternatives, they told me that there were better -introductory manuals--but those were not free. -</para> - -<para> -Why was this? The authors of the good manuals had written them for -O'Reilly Associates, which published them with restrictive terms--no -copying, no modification, source files not available--which exclude -them from the free software community. -</para> - -<para> -That wasn't the first time this sort of thing has happened, and (to -our community's great loss) it was far from the last. Proprietary -manual publishers have enticed a great many authors to restrict their -manuals since then. Many times I have heard a GNU user eagerly tell -me about a manual that he is writing, with which he expects to help -the GNU project--and then had my hopes dashed, as he proceeded to -explain that he had signed a contract with a publisher that would -restrict it so that we cannot use it. -</para> - -<para> -Given that writing good English is a rare skill among programmers, we -can ill afford to lose manuals this way. -</para> - -<para> - Free documentation, like free software, is a matter of freedom, -not price. The problem with these manuals was not that O'Reilly -Associates charged a price for printed copies--that in itself is fine. -(The Free Software Foundation <ulink url="http://www.gnu.org/doc/doc.html">sells printed copies</ulink> of -free GNU manuals, too.) But GNU manuals are available in source code -form, while these manuals are available only on paper. GNU manuals -come with permission to copy and modify; the Perl manuals do not. -These restrictions are the problems. -</para> - -<para> -The criterion for a free manual is pretty much the same as for free -software: it is a matter of giving all users certain freedoms. -Redistribution (including commercial redistribution) must be -permitted, so that the manual can accompany every copy of the program, -on-line or on paper. Permission for modification is crucial too. -</para> - -<para> -As a general rule, I don't believe that it is essential for people to -have permission to modify all sorts of articles and books. The issues -for writings are not necessarily the same as those for software. For -example, I don't think you or I are obliged to give permission to -modify articles like this one, which describe our actions and our -views. -</para> - -<para> -But there is a particular reason why the freedom to modify is crucial -for documentation for free software. When people exercise their right -to modify the software, and add or change its features, if they are -conscientious they will change the manual too--so they can provide -accurate and usable documentation with the modified program. A manual -which forbids programmers to be conscientious and finish the job, or -more precisely requires them to write a new manual from scratch if -they change the program, does not fill our community's needs. -</para> - -<para> -While a blanket prohibition on modification is unacceptable, some -kinds of limits on the method of modification pose no problem. For -example, requirements to preserve the original author's copyright -notice, the distribution terms, or the list of authors, are ok. It is -also no problem to require modified versions to include notice that -they were modified, even to have entire sections that may not be -deleted or changed, as long as these sections deal with nontechnical -topics. (Some GNU manuals have them.) -</para> - -<para> -These kinds of restrictions are not a problem because, as a practical -matter, they don't stop the conscientious programmer from adapting the -manual to fit the modified program. In other words, they don't block -the free software community from making full use of the manual. -</para> - -<para> -However, it must be possible to modify all the <emphasis>technical</emphasis> -content of the manual, and then distribute the result in all the usual -media, through all the usual channels; otherwise, the restrictions do -block the community, the manual is not free, and so we need another -manual. -</para> - -<para> -Unfortunately, it is often hard to find someone to write another -manual when a proprietary manual exists. The obstacle is that many -users think that a proprietary manual is good enough--so they don't -see the need to write a free manual. They do not see that the free -operating system has a gap that needs filling. -</para> - -<para> -Why do users think that proprietary manuals are good enough? Some -have not considered the issue. I hope this article will do something -to change that. -</para> - -<para> -Other users consider proprietary manuals acceptable for the same -reason so many people consider proprietary software acceptable: they -judge in purely practical terms, not using freedom as a criterion. -These people are entitled to their opinions, but since those opinions -spring from values which do not include freedom, they are no guide for -those of us who do value freedom. -</para> - -<para> -Please spread the word about this issue. We continue to lose manuals -to proprietary publishing. If we spread the word that proprietary -manuals are not sufficient, perhaps the next person who wants to help -GNU by writing documentation will realize, before it is too late, that -he must above all make it free. -</para> - -<para> -We can also encourage commercial publishers to sell free, copylefted -manuals instead of proprietary ones. One way you can help this is to -check the distribution terms of a manual before you buy it, and -prefer copylefted manuals to non-copylefted ones. -</para> -<para> -[Note: We now maintain a <ulink url="http://www.fsf.org/licensing/doc/other-free-books.html">web page -that lists free books available from other publishers</ulink>]. -</para> - -<para>Copyright © 2004, 2005, 2006, 2007 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA</para> - -<para>Verbatim copying and distribution of this entire article are -permitted worldwide, without royalty, in any medium, provided this -notice is preserved.</para> - -<para>Report any problems or suggestions to <email>webmaster@fsf.org</email>.</para> - -</appendix> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_porting.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_porting.xml deleted file mode 100644 index f565c0e03..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/appendix_porting.xml +++ /dev/null @@ -1,53 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<appendix id="appendix.porting" xreflabel="Porting"> -<?dbhtml filename="appendix_porting.html"?> - -<appendixinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</appendixinfo> - -<title> - Porting and Maintenance - <indexterm> - <primary>Appendix</primary> - <secondary>Porting and Maintenance</secondary> - </indexterm> -</title> - - <!-- Hacking the Build System --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="build_hacking.xml"> - </xi:include> - - <!-- Internals: Porting to New Hardware or Operating Systems --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="internals.xml"> - </xi:include> - - <!-- ABI Policy and Guidelines --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="abi.xml"> - </xi:include> - - <!-- API Evolution and Deprecation History --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="evolution.xml"> - </xi:include> - - <!-- Backwards Compatibility --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="backwards_compatibility.xml"> - </xi:include> - -</appendix> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/auto_ptr.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/auto_ptr.xml deleted file mode 100644 index a7a0e97bc..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/auto_ptr.xml +++ /dev/null @@ -1,133 +0,0 @@ -<sect1 id="manual.util.memory.auto_ptr" xreflabel="auto_ptr"> -<?dbhtml filename="auto_ptr.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - auto_ptr - </keyword> - </keywordset> -</sect1info> - -<title>auto_ptr</title> - -<sect2 id="auto_ptr.limitations" xreflabel="auto_ptr.limitations"> -<title>Limitations</title> - - <para>Explaining all of the fun and delicious things that can - happen with misuse of the <classname>auto_ptr</classname> class - template (called <acronym>AP</acronym> here) would take some - time. Suffice it to say that the use of <acronym>AP</acronym> - safely in the presence of copying has some subtleties. - </para> - <para> - The AP class is a really - nifty idea for a smart pointer, but it is one of the dumbest of - all the smart pointers -- and that's fine. - </para> - <para> - AP is not meant to be a supersmart solution to all resource - leaks everywhere. Neither is it meant to be an effective form - of garbage collection (although it can help, a little bit). - And it can <emphasis>not</emphasis>be used for arrays! - </para> - <para> - <acronym>AP</acronym> is meant to prevent nasty leaks in the - presence of exceptions. That's <emphasis>all</emphasis>. This - code is AP-friendly: - </para> - <programlisting> - // Not a recommend naming scheme, but good for web-based FAQs. - typedef std::auto_ptr<MyClass> APMC; - - extern function_taking_MyClass_pointer (MyClass*); - extern some_throwable_function (); - - void func (int data) - { - APMC ap (new MyClass(data)); - - some_throwable_function(); // this will throw an exception - - function_taking_MyClass_pointer (ap.get()); - } - </programlisting> - <para>When an exception gets thrown, the instance of MyClass that's - been created on the heap will be <function>delete</function>'d as the stack is - unwound past <function>func()</function>. - </para> - <para>Changing that code as follows is not <acronym>AP</acronym>-friendly: - </para> - <programlisting> - APMC ap (new MyClass[22]); - </programlisting> - <para>You will get the same problems as you would without the use - of <acronym>AP</acronym>: - </para> - <programlisting> - char* array = new char[10]; // array new... - ... - delete array; // ...but single-object delete - </programlisting> - <para> - AP cannot tell whether the pointer you've passed at creation points - to one or many things. If it points to many things, you are about - to die. AP is trivial to write, however, so you could write your - own <code>auto_array_ptr</code> for that situation (in fact, this has - been done many times; check the mailing lists, Usenet, Boost, etc). - </para> -</sect2> - -<sect2 id="auto_ptr.using" xreflabel="auto_ptr.using"> -<title>Use in Containers</title> - - <para> - </para> - <para>All of the <ulink url="../23_containers/howto.html">containers</ulink> - described in the standard library require their contained types - to have, among other things, a copy constructor like this: - </para> - <programlisting> - struct My_Type - { - My_Type (My_Type const&); - }; - </programlisting> - <para> - Note the const keyword; the object being copied shouldn't change. - The template class <code>auto_ptr</code> (called AP here) does not - meet this requirement. Creating a new AP by copying an existing - one transfers ownership of the pointed-to object, which means that - the AP being copied must change, which in turn means that the - copy ctors of AP do not take const objects. - </para> - <para> - The resulting rule is simple: <emphasis>Never ever use a - container of auto_ptr objects</emphasis>. The standard says that - <quote>undefined</quote> behavior is the result, but it is - guaranteed to be messy. - </para> - <para> - To prevent you from doing this to yourself, the - <ulink url="../19_diagnostics/howto.html#3">concept checks</ulink> built - in to this implementation will issue an error if you try to - compile code like this: - </para> - <programlisting> - #include <vector> - #include <memory> - - void f() - { - std::vector< std::auto_ptr<int> > vec_ap_int; - } - </programlisting> - <para> -Should you try this with the checks enabled, you will see an error. - </para> -</sect2> - -</sect1>
\ No newline at end of file diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml deleted file mode 100644 index 42a64aa98..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml +++ /dev/null @@ -1,1315 +0,0 @@ -<sect1 id="manual.appendix.porting.backwards" xreflabel="backwards"> -<?dbhtml filename="backwards.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - backwards - </keyword> - </keywordset> -</sect1info> - -<title>Backwards Compatibility</title> - -<sect2 id="backwards.first" xreflabel="backwards.first"> -<title>First</title> - -<para>The first generation GNU C++ library was called libg++. It was a -separate GNU project, although reliably paired with GCC. Rumors imply -that it had a working relationship with at least two kinds of -dinosaur. -</para> - -<para>Some background: libg++ was designed and created when there was no -ISO standard to provide guidance. Classes like linked lists are now -provided for by <classname>list<T></classname> and do not need to be -created by <function>genclass</function>. (For that matter, templates exist -now and are well-supported, whereas genclass (mostly) predates them.) -</para> - -<para>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, the Standards -Committee couldn't include everything, and so a lot of those -<quote>obvious</quote> classes didn't get included. -</para> - -<para>Known Issues include many of the limitations of its immediate ancestor.</para> - -<para>Portability notes and known implementation limitations are as follows.</para> - -<sect3> - <title>No <code>ios_base</code></title> - -<para> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>. -</para> -</sect3> - -<sect3> -<title>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></title> - -<para> - In earlier versions of the standard, - <filename class="headerfile">fstream.h</filename>, - <filename class="headerfile">ostream.h</filename> - and <filename class="headerfile">istream.h</filename> - used to define - <code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include - <filename class="headerfile">iostream</filename> - explicitly to get the required definitions. - </para> -<para> Some include adjustment may be required.</para> - -<para>This project is no longer maintained or supported, and the sources -archived. For the desperate, -the <ulink url="http://gcc.gnu.org/extensions.html">GCC extensions -page</ulink> describes where to find the last libg++ source. The code is -considered replaced and rewritten. -</para> -</sect3> -</sect2> - -<sect2 id="backwards.second" xreflabel="backwards.second"> -<title>Second</title> - -<para> - The second generation GNU C++ library was called libstdc++, or - libstdc++-v2. It spans the time between libg++ and pre-ISO C++ - standardization and is usually associated with the following GCC - releases: egcs 1.x, gcc 2.95, and gcc 2.96. -</para> - -<para> - The STL portions of this library are based on SGI/HP STL release 3.11. -</para> - -<para> - This project is no longer maintained or supported, and the sources - archived. The code is considered replaced and rewritten. -</para> - -<para> - Portability notes and known implementation limitations are as follows. -</para> - -<sect3> - <title>Namespace <code>std::</code> not supported</title> - - <para> - Some care is required to support C++ compiler and or library - implementation that do not have the standard library in - <code>namespace std</code>. - </para> - - <para> - The following sections list some possible solutions to support compilers - that cannot ignore <code>std::</code>-qualified names. - </para> - - <para> - First, see if the compiler has a flag for this. Namespace - back-portability-issues are generally not a problem for g++ - compilers that do not have libstdc++ in <code>std::</code>, as the - compilers use <code>-fno-honor-std</code> (ignore - <code>std::</code>, <code>:: = std::</code>) by default. That is, - the responsibility for enabling or disabling <code>std::</code> is - on the user; the maintainer does not have to care about it. This - probably applies to some other compilers as well. - </para> - - <para> - Second, experiment with a variety of pre-processor tricks. - </para> - - <para> - By defining <code>std</code> as a macro, fully-qualified namespace - calls become global. Volia. - </para> - -<programlisting> -#ifdef WICKEDLY_OLD_COMPILER -# define std -#endif -</programlisting> - - <para> - Thanks to Juergen Heinzl who posted this solution on gnu.gcc.help. - </para> - - <para> - Another pre-processor based approach is to define a macro - <code>NAMESPACE_STD</code>, which is defined to either - <quote> </quote> or <quote>std</quote> based on a compile-type - test. On GNU systems, this can be done with autotools by means of - an autoconf test (see below) for <code>HAVE_NAMESPACE_STD</code>, - then using that to set a value for the <code>NAMESPACE_STD</code> - macro. At that point, one is able to use - <code>NAMESPACE_STD::string</code>, which will evaluate to - <code>std::string</code> or <code>::string</code> (i.e., in the - global namespace on systems that do not put <code>string</code> in - <code>std::</code>). - </para> - -<programlisting> -dnl @synopsis AC_CXX_NAMESPACE_STD -dnl -dnl If the compiler supports namespace std, define -dnl HAVE_NAMESPACE_STD. -dnl -dnl @category Cxx -dnl @author Todd Veldhuizen -dnl @author Luc Maisonobe <luc@spaceroots.org> -dnl @version 2004-02-04 -dnl @license AllPermissive -AC_DEFUN([AC_CXX_NAMESPACE_STD], [ - AC_CACHE_CHECK(if g++ supports namespace std, - ac_cv_cxx_have_std_namespace, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - AC_TRY_COMPILE([#include <iostream> - std::istream& is = std::cin;],, - ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no) - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_have_std_namespace" = yes; then - AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ]) - fi -]) -</programlisting> -</sect3> - -<sect3> -<title>Illegal iterator usage</title> -<para> - The following illustrate implementation-allowed illegal iterator - use, and then correct use. -</para> - -<itemizedlist> - <listitem> - <para> - you cannot do <code>ostream::operator<<(iterator)</code> - to print the address of the iterator => use - <code>operator<< &*iterator</code> instead - </para> - </listitem> - <listitem> - <para> - you cannot clear an iterator's reference (<code>iterator = - 0</code>) => use <code>iterator = iterator_type();</code> - </para> - </listitem> - <listitem> - <para> - <code>if (iterator)</code> won't work any more => use - <code>if (iterator != iterator_type())</code> - </para> - </listitem> -</itemizedlist> -</sect3> - -<sect3> - <title><code>isspace</code> from <filename class="headerfile">cctype</filename> is a macro - </title> - - <para> - Glibc 2.0.x and 2.1.x define <filename - class="headerfile">ctype.h</filename> functionality as macros - (isspace, isalpha etc.). - </para> - - <para> - This implementations of libstdc++, however, keep these functions - as macros, and so it is not back-portable to use fully qualified - names. For example: - </para> - -<programlisting> -#include <cctype> -int main() { std::isspace('X'); } -</programlisting> - -<para> - Results in something like this: -</para> - -<programlisting> -std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; -</programlisting> - -<para> - A solution is to modify a header-file so that the compiler tells - <filename class="headerfile">ctype.h</filename> to define functions - instead of macros: -</para> - -<programlisting> -// This keeps isalnum, et al from being propagated as macros. -#if __linux__ -# define __NO_CTYPE 1 -#endif -</programlisting> - -<para> - Then, include <filename class="headerfile">ctype.h</filename> -</para> - -<para> - Another problem arises if you put a <code>using namespace - std;</code> declaration at the top, and include <filename - class="headerfile">ctype.h</filename>. This will result in - ambiguities between the definitions in the global namespace - (<filename class="headerfile">ctype.h</filename>) and the - definitions in namespace <code>std::</code> - (<code><cctype></code>). -</para> -</sect3> - -<sect3> -<title>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></title> - -<para> - One solution is to add an autoconf-test for this: -</para> - -<programlisting> -AC_MSG_CHECKING(for container::at) -AC_TRY_COMPILE( -[ -#include <vector> -#include <deque> -#include <string> - -using namespace std; -], -[ -deque<int> test_deque(3); -test_deque.at(2); -vector<int> test_vector(2); -test_vector.at(1); -string test_string(<quote>test_string</quote>); -test_string.at(3); -], -[AC_MSG_RESULT(yes) -AC_DEFINE(HAVE_CONTAINER_AT)], -[AC_MSG_RESULT(no)]) -</programlisting> - -<para> - If you are using other (non-GNU) compilers it might be a good idea - to check for <code>string::at</code> separately. -</para> - -</sect3> - -<sect3> -<title>No <code>std::char_traits<char>::eof</code></title> - -<para> - Use some kind of autoconf test, plus this: -</para> - -<programlisting> -#ifdef HAVE_CHAR_TRAITS -#define CPP_EOF std::char_traits<char>::eof() -#else -#define CPP_EOF EOF -#endif -</programlisting> - -</sect3> - -<sect3> -<title>No <code>string::clear</code></title> - -<para> - There are two functions for deleting the contents of a string: - <code>clear</code> and <code>erase</code> (the latter returns the - string). -</para> - -<programlisting> -void -clear() { _M_mutate(0, this->size(), 0); } -</programlisting> - -<programlisting> -basic_string& -erase(size_type __pos = 0, size_type __n = npos) -{ - return this->replace(_M_check(__pos), _M_fold(__pos, __n), - _M_data(), _M_data()); -} -</programlisting> - -<para> - Unfortunately, <code>clear</code> is not implemented in this - version, so you should use <code>erase</code> (which is probably - faster than <code>operator=(charT*)</code>). -</para> -</sect3> - -<sect3> -<title> - Removal of <code>ostream::form</code> and <code>istream::scan</code> - extensions -</title> - -<para> - These are no longer supported. Please use stringstreams instead. -</para> -</sect3> - -<sect3> -<title>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></title> - -<para> - Although the ISO standard <code>i/ostringstream</code>-classes are - provided, (<filename class="headerfile">sstream</filename>), for - compatibility with older implementations the pre-ISO - <code>i/ostrstream</code> (<filename - class="headerfile">strstream</filename>) interface is also provided, - with these caveats: -</para> - -<itemizedlist> - <listitem> - <para> - <code>strstream</code> is considered to be deprecated - </para> - </listitem> - <listitem> - <para> - <code>strstream</code> is limited to <code>char</code> - </para> - </listitem> - <listitem> - <para> - with <code>ostringstream</code> you don't have to take care of - terminating the string or freeing its memory - </para> - </listitem> - <listitem> - <para> - <code>istringstream</code> can be re-filled (clear(); - str(input);) - </para> - </listitem> -</itemizedlist> - -<para> - You can then use output-stringstreams like this: -</para> - -<programlisting> -#ifdef HAVE_SSTREAM -# include <sstream> -#else -# include <strstream> -#endif - -#ifdef HAVE_SSTREAM - std::ostringstream oss; -#else - std::ostrstream oss; -#endif - -oss << <quote>Name=</quote> << m_name << <quote>, number=</quote> << m_number << std::endl; -... -#ifndef HAVE_SSTREAM - oss << std::ends; // terminate the char*-string -#endif - -// str() returns char* for ostrstream and a string for ostringstream -// this also causes ostrstream to think that the buffer's memory -// is yours -m_label.set_text(oss.str()); -#ifndef HAVE_SSTREAM - // let the ostrstream take care of freeing the memory - oss.freeze(false); -#endif -</programlisting> - -<para> - Input-stringstreams can be used similarly: -</para> - -<programlisting> -std::string input; -... -#ifdef HAVE_SSTREAM -std::istringstream iss(input); -#else -std::istrstream iss(input.c_str()); -#endif - -int i; -iss >> i; -</programlisting> - -<para> One (the only?) restriction is that an istrstream cannot be re-filled: -</para> - -<programlisting> -std::istringstream iss(numerator); -iss >> m_num; -// this is not possible with istrstream -iss.clear(); -iss.str(denominator); -iss >> m_den; -</programlisting> - -<para> -If you don't care about speed, you can put these conversions in - a template-function: -</para> -<programlisting> -template <class X> -void fromString(const string& input, X& any) -{ -#ifdef HAVE_SSTREAM -std::istringstream iss(input); -#else -std::istrstream iss(input.c_str()); -#endif -X temp; -iss >> temp; -if (iss.fail()) -throw runtime_error(..) -any = temp; -} -</programlisting> - -<para> - Another example of using stringstreams is in <link - linkend="strings.string.shrink">this howto</link>. -</para> - -<para> There is additional information in the libstdc++-v2 info files, in -particular <quote>info iostream</quote>. -</para> -</sect3> - -<sect3> - <title>Little or no wide character support</title> - <para> - Classes <classname>wstring</classname> and - <classname>char_traits<wchar_t></classname> are - not supported. - </para> -</sect3> - -<sect3> - <title>No templatized iostreams</title> - <para> - Classes <classname>wfilebuf</classname> and - <classname>wstringstream</classname> are not supported. - </para> -</sect3> - -<sect3> -<title>Thread safety issues</title> - - <para> - Earlier GCC releases had a somewhat different approach to - threading configuration and proper compilation. Before GCC 3.0, - configuration of the threading model was dictated by compiler - command-line options and macros (both of which were somewhat - thread-implementation and port-specific). There were no - guarantees related to being able to link code compiled with one - set of options and macro setting with another set. - </para> - - <para> - For GCC 3.0, configuration of the threading model used with - libraries and user-code is performed when GCC is configured and - built using the --enable-threads and --disable-threads options. - The ABI is stable for symbol name-mangling and limited functional - compatibility exists between code compiled under different - threading models. - </para> - - <para> - The libstdc++ library has been designed so that it can be used in - multithreaded applications (with libstdc++-v2 this was only true - of the STL parts.) The first problem is finding a - <emphasis>fast</emphasis> method of implementation portable to - all platforms. Due to historical reasons, some of the library is - written against per-CPU-architecture spinlocks and other parts - against the gthr.h abstraction layer which is provided by gcc. A - minor problem that pops up every so often is different - interpretations of what "thread-safe" means for a - library (not a general program). We currently use the <ulink - url="http://www.sgi.com/tech/stl/thread_safety.html">same - definition that SGI</ulink> uses for their STL subset. However, - the exception for read-only containers only applies to the STL - components. This definition is widely-used and something similar - will be used in the next version of the C++ standard library. - </para> - - <para> - Here is a small link farm to threads (no pun) in the mail - archives that discuss the threading problem. Each link is to the - first relevant message in the thread; from there you can use - "Thread Next" to move down the thread. This farm is in - latest-to-oldest order. - </para> - - <itemizedlist> - <listitem> - <para> - Our threading expert Loren gives a breakdown of <ulink - url="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the - six situations involving threads</ulink> for the 3.0 - release series. - </para> - </listitem> - <listitem> - <para> - <ulink url="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html"> - This message</ulink> inspired a recent updating of issues with - threading and the SGI STL library. It also contains some - example POSIX-multithreaded STL code. - </para> - </listitem> - </itemizedlist> - - <para> - (A large selection of links to older messages has been removed; - many of the messages from 1999 were lost in a disk crash, and the - few people with access to the backup tapes have been too swamped - with work to restore them. Many of the points have been - superseded anyhow.) - </para> -</sect3> - -</sect2> - -<sect2 id="backwards.third" xreflabel="backwards.third"> -<title>Third</title> - -<para> The third generation GNU C++ library is called libstdc++, or -libstdc++-v3. -</para> - - <para>The subset commonly known as the Standard Template Library - (chapters 23 through 25, mostly) is adapted from the final release - of the SGI STL (version 3.3), with extensive changes. - </para> - - <para>A more formal description of the V3 goals can be found in the - official <ulink url="../17_intro/DESIGN">design document</ulink>. - </para> - -<para>Portability notes and known implementation limitations are as follows.</para> - -<sect3> -<title>Pre-ISO headers moved to backwards or removed</title> - -<para> The pre-ISO C++ headers - (<code>iostream.h</code>, <code>defalloc.h</code> etc.) are - available, unlike previous libstdc++ versions, but inclusion - generates a warning that you are using deprecated headers. -</para> - - <para>This compatibility layer is constructed by including the - standard C++ headers, and injecting any items in - <code>std::</code> into the global namespace. - </para> - <para>For those of you new to ISO C++ (welcome, time travelers!), no, - that isn't a typo. Yes, the headers really have new names. - Marshall Cline's C++ FAQ Lite has a good explanation in <ulink url="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item - [27.4]</ulink>. - </para> - -<para> Some include adjustment may be required. What follows is an -autoconf test that defines <code>PRE_STDCXX_HEADERS</code> when they -exist.</para> - -<programlisting> -# AC_HEADER_PRE_STDCXX -AC_DEFUN([AC_HEADER_PRE_STDCXX], [ - AC_CACHE_CHECK(for pre-ISO C++ include files, - ac_cv_cxx_pre_stdcxx, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -Wno-deprecated" - - # Omit defalloc.h, as compilation with newer compilers is problematic. - AC_TRY_COMPILE([ - #include <new.h> - #include <iterator.h> - #include <alloc.h> - #include <set.h> - #include <hashtable.h> - #include <hash_set.h> - #include <fstream.h> - #include <tempbuf.h> - #include <istream.h> - #include <bvector.h> - #include <stack.h> - #include <rope.h> - #include <complex.h> - #include <ostream.h> - #include <heap.h> - #include <iostream.h> - #include <function.h> - #include <multimap.h> - #include <pair.h> - #include <stream.h> - #include <iomanip.h> - #include <slist.h> - #include <tree.h> - #include <vector.h> - #include <deque.h> - #include <multiset.h> - #include <list.h> - #include <map.h> - #include <algobase.h> - #include <hash_map.h> - #include <algo.h> - #include <queue.h> - #include <streambuf.h> - ],, - ac_cv_cxx_pre_stdcxx=yes, ac_cv_cxx_pre_stdcxx=no) - CXXFLAGS="$ac_save_CXXFLAGS" - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_pre_stdcxx" = yes; then - AC_DEFINE(PRE_STDCXX_HEADERS,,[Define if pre-ISO C++ header files are present. ]) - fi -]) -</programlisting> - -<para>Porting between pre-ISO headers and ISO headers is simple: headers -like <filename class="headerfile">vector.h</filename> can be replaced with <filename class="headerfile">vector</filename> and a using -directive <code>using namespace std;</code> can be put at the global -scope. This should be enough to get this code compiling, assuming the -other usage is correct. -</para> -</sect3> - -<sect3> -<title>Extension headers hash_map, hash_set moved to ext or backwards</title> - - <para>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. - </para> -<para> Header files <filename class="headerfile">hash_map</filename> and <filename class="headerfile">hash_set</filename> moved -to <filename class="headerfile">ext/hash_map</filename> and <filename class="headerfile">ext/hash_set</filename>, -respectively. At the same time, all types in these files are enclosed -in <code>namespace __gnu_cxx</code>. Later versions move deprecate -these files, and suggest using TR1's <filename class="headerfile">unordered_map</filename> -and <filename class="headerfile">unordered_set</filename> instead. -</para> - - <para>The extensions are no longer in the global or <code>std</code> - namespaces, instead they are declared in the <code>__gnu_cxx</code> - namespace. For maximum portability, consider defining a namespace - alias to use to talk about extensions, e.g.: - </para> - <programlisting> - #ifdef __GNUC__ - #if __GNUC__ < 3 - #include <hash_map.h> - namespace extension { using ::hash_map; }; // inherit globals - #else - #include <backward/hash_map> - #if __GNUC__ == 3 && __GNUC_MINOR__ == 0 - namespace extension = std; // GCC 3.0 - #else - namespace extension = ::__gnu_cxx; // GCC 3.1 and later - #endif - #endif - #else // ... there are other compilers, right? - namespace extension = std; - #endif - - extension::hash_map<int,int> my_map; - </programlisting> - <para>This is a bit cleaner than defining typedefs for all the - instantiations you might need. - </para> - - -<para>The following autoconf tests check for working HP/SGI hash containers. -</para> - -<programlisting> -# AC_HEADER_EXT_HASH_MAP -AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [ - AC_CACHE_CHECK(for ext/hash_map, - ac_cv_cxx_ext_hash_map, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -Werror" - AC_TRY_COMPILE([#include <ext/hash_map>], [using __gnu_cxx::hash_map;], - ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no) - CXXFLAGS="$ac_save_CXXFLAGS" - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_ext_hash_map" = yes; then - AC_DEFINE(HAVE_EXT_HASH_MAP,,[Define if ext/hash_map is present. ]) - fi -]) -</programlisting> - -<programlisting> -# AC_HEADER_EXT_HASH_SET -AC_DEFUN([AC_HEADER_EXT_HASH_SET], [ - AC_CACHE_CHECK(for ext/hash_set, - ac_cv_cxx_ext_hash_set, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -Werror" - AC_TRY_COMPILE([#include <ext/hash_set>], [using __gnu_cxx::hash_set;], - ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no) - CXXFLAGS="$ac_save_CXXFLAGS" - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_ext_hash_set" = yes; then - AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ]) - fi -]) -</programlisting> -</sect3> - -<sect3> -<title>No <code>ios::nocreate/ios::noreplace</code>. -</title> - -<para> The existence of <code>ios::nocreate</code> being used for -input-streams has been confirmed, most probably because the author -thought it would be more correct to specify nocreate explicitly. So -it can be left out for input-streams. -</para> - -<para>For output streams, <quote>nocreate</quote> is probably the default, -unless you specify <code>std::ios::trunc</code> ? To be safe, you can -open the file for reading, check if it has been opened, and then -decide whether you want to create/replace or not. To my knowledge, -even older implementations support <code>app</code>, <code>ate</code> -and <code>trunc</code> (except for <code>app</code> ?). -</para> -</sect3> - -<sect3> -<title> -No <code>stream::attach(int fd)</code> -</title> - -<para> - Phil Edwards writes: It was considered and rejected for the ISO - standard. Not all environments use file descriptors. Of those - that do, not all of them use integers to represent them. - </para> - -<para> - For a portable solution (among systems which use - file descriptors), you need to implement a subclass of - <code>std::streambuf</code> (or - <code>std::basic_streambuf<..></code>) which opens a file - given a descriptor, and then pass an instance of this to the - stream-constructor. - </para> - -<para> - An extension is available that implements this. - <filename class="headerfile">ext/stdio_filebuf.h</filename> contains a derived class called - <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></ulink>. - This class can be constructed from a C <code>FILE*</code> or a file - descriptor, and provides the <code>fd()</code> function. - </para> - -<para> - For another example of this, refer to - <ulink url="http://www.josuttis.com/cppcode/fdstream.html">fdstream example</ulink> - by Nicolai Josuttis. -</para> -</sect3> - -<sect3> -<title> -Support for C++98 dialect. -</title> - -<para>Check for complete library coverage of the C++1998/2003 standard. -</para> - -<programlisting> -# AC_HEADER_STDCXX_98 -AC_DEFUN([AC_HEADER_STDCXX_98], [ - AC_CACHE_CHECK(for ISO C++ 98 include files, - ac_cv_cxx_stdcxx_98, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - AC_TRY_COMPILE([ - #include <cassert> - #include <cctype> - #include <cerrno> - #include <cfloat> - #include <ciso646> - #include <climits> - #include <clocale> - #include <cmath> - #include <csetjmp> - #include <csignal> - #include <cstdarg> - #include <cstddef> - #include <cstdio> - #include <cstdlib> - #include <cstring> - #include <ctime> - - #include <algorithm> - #include <bitset> - #include <complex> - #include <deque> - #include <exception> - #include <fstream> - #include <functional> - #include <iomanip> - #include <ios> - #include <iosfwd> - #include <iostream> - #include <istream> - #include <iterator> - #include <limits> - #include <list> - #include <locale> - #include <map> - #include <memory> - #include <new> - #include <numeric> - #include <ostream> - #include <queue> - #include <set> - #include <sstream> - #include <stack> - #include <stdexcept> - #include <streambuf> - #include <string> - #include <typeinfo> - #include <utility> - #include <valarray> - #include <vector> - ],, - ac_cv_cxx_stdcxx_98=yes, ac_cv_cxx_stdcxx_98=no) - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_stdcxx_98" = yes; then - AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ]) - fi -]) -</programlisting> -</sect3> - -<sect3> -<title> -Support for C++TR1 dialect. -</title> - -<para>Check for library coverage of the TR1 standard. -</para> - -<programlisting> -# AC_HEADER_STDCXX_TR1 -AC_DEFUN([AC_HEADER_STDCXX_TR1], [ - AC_CACHE_CHECK(for ISO C++ TR1 include files, - ac_cv_cxx_stdcxx_tr1, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - AC_TRY_COMPILE([ - #include <tr1/array> - #include <tr1/ccomplex> - #include <tr1/cctype> - #include <tr1/cfenv> - #include <tr1/cfloat> - #include <tr1/cinttypes> - #include <tr1/climits> - #include <tr1/cmath> - #include <tr1/complex> - #include <tr1/cstdarg> - #include <tr1/cstdbool> - #include <tr1/cstdint> - #include <tr1/cstdio> - #include <tr1/cstdlib> - #include <tr1/ctgmath> - #include <tr1/ctime> - #include <tr1/cwchar> - #include <tr1/cwctype> - #include <tr1/functional> - #include <tr1/memory> - #include <tr1/random> - #include <tr1/regex> - #include <tr1/tuple> - #include <tr1/type_traits> - #include <tr1/unordered_set> - #include <tr1/unordered_map> - #include <tr1/utility> - ],, - ac_cv_cxx_stdcxx_tr1=yes, ac_cv_cxx_stdcxx_tr1=no) - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_stdcxx_tr1" = yes; then - AC_DEFINE(STDCXX_TR1_HEADERS,,[Define if ISO C++ TR1 header files are present. ]) - fi -]) -</programlisting> - -<para>An alternative is to check just for specific TR1 includes, such as <unordered_map> and <unordered_set>. -</para> - -<programlisting> -# AC_HEADER_TR1_UNORDERED_MAP -AC_DEFUN([AC_HEADER_TR1_UNORDERED_MAP], [ - AC_CACHE_CHECK(for tr1/unordered_map, - ac_cv_cxx_tr1_unordered_map, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - AC_TRY_COMPILE([#include <tr1/unordered_map>], [using std::tr1::unordered_map;], - ac_cv_cxx_tr1_unordered_map=yes, ac_cv_cxx_tr1_unordered_map=no) - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_tr1_unordered_map" = yes; then - AC_DEFINE(HAVE_TR1_UNORDERED_MAP,,[Define if tr1/unordered_map is present. ]) - fi -]) -</programlisting> - -<programlisting> -# AC_HEADER_TR1_UNORDERED_SET -AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [ - AC_CACHE_CHECK(for tr1/unordered_set, - ac_cv_cxx_tr1_unordered_set, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - AC_TRY_COMPILE([#include <tr1/unordered_set>], [using std::tr1::unordered_set;], - ac_cv_cxx_tr1_unordered_set=yes, ac_cv_cxx_tr1_unordered_set=no) - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_tr1_unordered_set" = yes; then - AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ]) - fi -]) -</programlisting> -</sect3> - - -<sect3> -<title> -Support for C++0x dialect. -</title> - -<para>Check for baseline language coverage in the compiler for the C++0xstandard. -</para> - -<programlisting> -# AC_COMPILE_STDCXX_OX -AC_DEFUN([AC_COMPILE_STDCXX_0X], [ - AC_CACHE_CHECK(if g++ supports C++0x features without additional flags, - ac_cv_cxx_compile_cxx0x_native, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - AC_TRY_COMPILE([ - template <typename T> - struct check - { - static_assert(sizeof(int) <= sizeof(T), "not big enough"); - }; - - typedef check<check<bool>> right_angle_brackets; - - int a; - decltype(a) b; - - typedef check<int> check_type; - check_type c; - check_type&& cr = c;],, - ac_cv_cxx_compile_cxx0x_native=yes, ac_cv_cxx_compile_cxx0x_native=no) - AC_LANG_RESTORE - ]) - - AC_CACHE_CHECK(if g++ supports C++0x features with -std=c++0x, - ac_cv_cxx_compile_cxx0x_cxx, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -std=c++0x" - AC_TRY_COMPILE([ - template <typename T> - struct check - { - static_assert(sizeof(int) <= sizeof(T), "not big enough"); - }; - - typedef check<check<bool>> right_angle_brackets; - - int a; - decltype(a) b; - - typedef check<int> check_type; - check_type c; - check_type&& cr = c;],, - ac_cv_cxx_compile_cxx0x_cxx=yes, ac_cv_cxx_compile_cxx0x_cxx=no) - CXXFLAGS="$ac_save_CXXFLAGS" - AC_LANG_RESTORE - ]) - - AC_CACHE_CHECK(if g++ supports C++0x features with -std=gnu++0x, - ac_cv_cxx_compile_cxx0x_gxx, - [AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -std=gnu++0x" - AC_TRY_COMPILE([ - template <typename T> - struct check - { - static_assert(sizeof(int) <= sizeof(T), "not big enough"); - }; - - typedef check<check<bool>> right_angle_brackets; - - int a; - decltype(a) b; - - typedef check<int> check_type; - check_type c; - check_type&& cr = c;],, - ac_cv_cxx_compile_cxx0x_gxx=yes, ac_cv_cxx_compile_cxx0x_gxx=no) - CXXFLAGS="$ac_save_CXXFLAGS" - AC_LANG_RESTORE - ]) - - if test "$ac_cv_cxx_compile_cxx0x_native" = yes || - test "$ac_cv_cxx_compile_cxx0x_cxx" = yes || - test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then - AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ]) - fi -]) -</programlisting> - - -<para>Check for library coverage of the C++0xstandard. -</para> - -<programlisting> -# AC_HEADER_STDCXX_0X -AC_DEFUN([AC_HEADER_STDCXX_0X], [ - AC_CACHE_CHECK(for ISO C++ 0x include files, - ac_cv_cxx_stdcxx_0x, - [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) - AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -std=gnu++0x" - - AC_TRY_COMPILE([ - #include <cassert> - #include <ccomplex> - #include <cctype> - #include <cerrno> - #include <cfenv> - #include <cfloat> - #include <cinttypes> - #include <ciso646> - #include <climits> - #include <clocale> - #include <cmath> - #include <csetjmp> - #include <csignal> - #include <cstdarg> - #include <cstdbool> - #include <cstddef> - #include <cstdint> - #include <cstdio> - #include <cstdlib> - #include <cstring> - #include <ctgmath> - #include <ctime> - #include <cwchar> - #include <cwctype> - - #include <algorithm> - #include <array> - #include <bitset> - #include <complex> - #include <deque> - #include <exception> - #include <fstream> - #include <functional> - #include <iomanip> - #include <ios> - #include <iosfwd> - #include <iostream> - #include <istream> - #include <iterator> - #include <limits> - #include <list> - #include <locale> - #include <map> - #include <memory> - #include <new> - #include <numeric> - #include <ostream> - #include <queue> - #include <random> - #include <regex> - #include <set> - #include <sstream> - #include <stack> - #include <stdexcept> - #include <streambuf> - #include <string> - #include <tuple> - #include <typeinfo> - #include <type_traits> - #include <unordered_map> - #include <unordered_set> - #include <utility> - #include <valarray> - #include <vector> - ],, - ac_cv_cxx_stdcxx_0x=yes, ac_cv_cxx_stdcxx_0x=no) - AC_LANG_RESTORE - CXXFLAGS="$ac_save_CXXFLAGS" - ]) - if test "$ac_cv_cxx_stdcxx_0x" = yes; then - AC_DEFINE(STDCXX_0X_HEADERS,,[Define if ISO C++ 0x header files are present. ]) - fi -]) -</programlisting> - -<para>As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For <unordered_map> -</para> - -<programlisting> -# AC_HEADER_UNORDERED_MAP -AC_DEFUN([AC_HEADER_UNORDERED_MAP], [ - AC_CACHE_CHECK(for unordered_map, - ac_cv_cxx_unordered_map, - [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) - AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -std=gnu++0x" - AC_TRY_COMPILE([#include <unordered_map>], [using std::unordered_map;], - ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no) - CXXFLAGS="$ac_save_CXXFLAGS" - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_unordered_map" = yes; then - AC_DEFINE(HAVE_UNORDERED_MAP,,[Define if unordered_map is present. ]) - fi -]) -</programlisting> - -<programlisting> -# AC_HEADER_UNORDERED_SET -AC_DEFUN([AC_HEADER_UNORDERED_SET], [ - AC_CACHE_CHECK(for unordered_set, - ac_cv_cxx_unordered_set, - [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) - AC_LANG_SAVE - AC_LANG_CPLUSPLUS - ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -std=gnu++0x" - AC_TRY_COMPILE([#include <unordered_set>], [using std::unordered_set;], - ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no) - CXXFLAGS="$ac_save_CXXFLAGS" - AC_LANG_RESTORE - ]) - if test "$ac_cv_cxx_unordered_set" = yes; then - AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ]) - fi -]) -</programlisting> -</sect3> - -<sect3> -<title> - Container::iterator_type is not necessarily Container::value_type* -</title> - -<para> - This is a change in behavior from the previous version. Now, most - <type>iterator_type</type> typedefs in container classes are POD - objects, not <type>value_type</type> pointers. -</para> -</sect3> - -</sect2> - -<bibliography id="backwards.biblio" xreflabel="backwards.biblio"> -<title>Bibliography</title> - - <biblioentry> - <abbrev> - kegel41 - </abbrev> - - <title> - Migrating to GCC 4.1 - </title> - - <author> - <firstname>Dan</firstname> - <surname>Kegel</surname> - </author> - - <biblioid> - <ulink url="http://www.kegel.com/gcc/gcc4.html"> - </ulink> - </biblioid> - </biblioentry> - - - <biblioentry> - <abbrev> - kegel41 - </abbrev> - - <title> - Building the Whole Debian Archive with GCC 4.1: A Summary - </title> - - <author> - <firstname>Martin</firstname> - <surname>Michlmayr</surname> - </author> - - <biblioid> - <ulink url="http://lists.debian.org/debian-gcc/2006/03/msg00405.html"> - </ulink> - </biblioid> - </biblioentry> - - - <biblioentry> - <abbrev> - lbl32 - </abbrev> - - <title> - Migration guide for GCC-3.2 - </title> - - <biblioid> - <ulink url="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html"> - </ulink> - </biblioid> - </biblioentry> - -</bibliography> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml deleted file mode 100644 index 1815a39c4..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml +++ /dev/null @@ -1,559 +0,0 @@ -<sect1 id="manual.ext.allocator.bitmap" xreflabel="mt allocator"> -<?dbhtml filename="bitmap_allocator.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - allocator - </keyword> - </keywordset> -</sect1info> - -<title>bitmap_allocator</title> - -<para> -</para> - -<sect2 id="allocator.bitmap.design" xreflabel="allocator.bitmap.design"> -<title>Design</title> - - <para> - As this name suggests, this allocator uses a bit-map to keep track - of the used and unused memory locations for it's book-keeping - purposes. - </para> - <para> - This allocator will make use of 1 single bit to keep track of - whether it has been allocated or not. A bit 1 indicates free, - while 0 indicates allocated. This has been done so that you can - easily check a collection of bits for a free block. This kind of - Bitmapped strategy works best for single object allocations, and - with the STL type parameterized allocators, we do not need to - choose any size for the block which will be represented by a - single bit. This will be the size of the parameter around which - the allocator has been parameterized. Thus, close to optimal - performance will result. Hence, this should be used for node based - containers which call the allocate function with an argument of 1. - </para> - - <para> - The bitmapped allocator's internal pool is exponentially growing. - Meaning that internally, the blocks acquired from the Free List - Store will double every time the bitmapped allocator runs out of - memory. - </para> - - <para> - The macro <literal>__GTHREADS</literal> decides whether to use - Mutex Protection around every allocation/deallocation. The state - of the macro is picked up automatically from the gthr abstraction - layer. - </para> - -</sect2> - -<sect2 id="allocator.bitmap.impl" xreflabel="allocator.bitmap.impl"> -<title>Implementation</title> - -<sect3 id="bitmap.impl.free_list_store" xreflabel="Free List Store"> - <title>Free List Store</title> - - <para> - The Free List Store (referred to as FLS for the remaining part of this - document) is the Global memory pool that is shared by all instances of - the bitmapped allocator instantiated for any type. This maintains a - sorted order of all free memory blocks given back to it by the - bitmapped allocator, and is also responsible for giving memory to the - bitmapped allocator when it asks for more. - </para> - <para> - Internally, there is a Free List threshold which indicates the - Maximum number of free lists that the FLS can hold internally - (cache). Currently, this value is set at 64. So, if there are - more than 64 free lists coming in, then some of them will be given - back to the OS using operator delete so that at any given time the - Free List's size does not exceed 64 entries. This is done because - a Binary Search is used to locate an entry in a free list when a - request for memory comes along. Thus, the run-time complexity of - the search would go up given an increasing size, for 64 entries - however, lg(64) == 6 comparisons are enough to locate the correct - free list if it exists. - </para> - <para> - Suppose the free list size has reached it's threshold, then the - largest block from among those in the list and the new block will - be selected and given back to the OS. This is done because it - reduces external fragmentation, and allows the OS to use the - larger blocks later in an orderly fashion, possibly merging them - later. Also, on some systems, large blocks are obtained via calls - to mmap, so giving them back to free system resources becomes most - important. - </para> - <para> - The function _S_should_i_give decides the policy that determines - whether the current block of memory should be given to the - allocator for the request that it has made. That's because we may - not always have exact fits for the memory size that the allocator - requests. We do this mainly to prevent external fragmentation at - the cost of a little internal fragmentation. Now, the value of - this internal fragmentation has to be decided by this function. I - can see 3 possibilities right now. Please add more as and when you - find better strategies. - </para> - -<orderedlist> - <listitem><para>Equal size check. Return true only when the 2 blocks are of equal -size.</para></listitem> - <listitem><para>Difference Threshold: Return true only when the _block_size is -greater than or equal to the _required_size, and if the _BS is > _RS -by a difference of less than some THRESHOLD value, then return true, -else return false. </para></listitem> - <listitem><para>Percentage Threshold. Return true only when the _block_size is -greater than or equal to the _required_size, and if the _BS is > _RS -by a percentage of less than some THRESHOLD value, then return true, -else return false.</para></listitem> -</orderedlist> - - <para> - Currently, (3) is being used with a value of 36% Maximum wastage per - Super Block. - </para> -</sect3> - -<sect3 id="bitmap.impl.super_block" xreflabel="Super Block"> - <title>Super Block</title> - - <para> - A super block is the block of memory acquired from the FLS from - which the bitmap allocator carves out memory for single objects - and satisfies the user's requests. These super blocks come in - sizes that are powers of 2 and multiples of 32 - (_Bits_Per_Block). Yes both at the same time! That's because the - next super block acquired will be 2 times the previous one, and - also all super blocks have to be multiples of the _Bits_Per_Block - value. - </para> - <para> - How does it interact with the free list store? - </para> - <para> - The super block is contained in the FLS, and the FLS is responsible for - getting / returning Super Bocks to and from the OS using operator new - as defined by the C++ standard. - </para> -</sect3> - -<sect3 id="bitmap.impl.super_block_data" xreflabel="Super Block Data"> - <title>Super Block Data Layout</title> - <para> - Each Super Block will be of some size that is a multiple of the - number of Bits Per Block. Typically, this value is chosen as - Bits_Per_Byte x sizeof(size_t). On an x86 system, this gives the - figure 8 x 4 = 32. Thus, each Super Block will be of size 32 - x Some_Value. This Some_Value is sizeof(value_type). For now, let - it be called 'K'. Thus, finally, Super Block size is 32 x K bytes. - </para> - <para> - This value of 32 has been chosen because each size_t has 32-bits - and Maximum use of these can be made with such a figure. - </para> - <para> - Consider a block of size 64 ints. In memory, it would look like this: - (assume a 32-bit system where, size_t is a 32-bit entity). - </para> - -<table frame='all'> -<title>Bitmap Allocator Memory Map</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<colspec colname='c5'></colspec> - -<tbody> - <row> - <entry>268</entry> - <entry>0</entry> - <entry>4294967295</entry> - <entry>4294967295</entry> - <entry>Data -> Space for 64 ints</entry> - </row> -</tbody> -</tgroup> -</table> - - <para> - The first Column(268) represents the size of the Block in bytes as - seen by the Bitmap Allocator. Internally, a global free list is - used to keep track of the free blocks used and given back by the - bitmap allocator. It is this Free List Store that is responsible - for writing and managing this information. Actually the number of - bytes allocated in this case would be: 4 + 4 + (4x2) + (64x4) = - 272 bytes, but the first 4 bytes are an addition by the Free List - Store, so the Bitmap Allocator sees only 268 bytes. These first 4 - bytes about which the bitmapped allocator is not aware hold the - value 268. - </para> - - <para> - What do the remaining values represent?</para> - <para> - The 2nd 4 in the expression is the sizeof(size_t) because the - Bitmapped Allocator maintains a used count for each Super Block, - which is initially set to 0 (as indicated in the diagram). This is - incremented every time a block is removed from this super block - (allocated), and decremented whenever it is given back. So, when - the used count falls to 0, the whole super block will be given - back to the Free List Store. - </para> - <para> - The value 4294967295 represents the integer corresponding to the bit - representation of all bits set: 11111111111111111111111111111111. - </para> - <para> - The 3rd 4x2 is size of the bitmap itself, which is the size of 32-bits - x 2, - which is 8-bytes, or 2 x sizeof(size_t). - </para> -</sect3> - -<sect3 id="bitmap.impl.max_wasted" xreflabel="Max Wasted Percentage"> - <title>Maximum Wasted Percentage</title> - - <para> - This has nothing to do with the algorithm per-se, - only with some vales that must be chosen correctly to ensure that the - allocator performs well in a real word scenario, and maintains a good - balance between the memory consumption and the allocation/deallocation - speed. - </para> - <para> - The formula for calculating the maximum wastage as a percentage: - </para> - - <para> -(32 x k + 1) / (2 x (32 x k + 1 + 32 x c)) x 100. - </para> - - <para> - where k is the constant overhead per node (e.g., for list, it is - 8 bytes, and for map it is 12 bytes) and c is the size of the - base type on which the map/list is instantiated. Thus, suppose the - type1 is int and type2 is double, they are related by the relation - sizeof(double) == 2*sizeof(int). Thus, all types must have this - double size relation for this formula to work properly. - </para> - <para> - Plugging-in: For List: k = 8 and c = 4 (int and double), we get: - 33.376% - </para> - - <para> -For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524% - </para> - <para> - Thus, knowing these values, and based on the sizeof(value_type), we may - create a function that returns the Max_Wastage_Percentage for us to use. - </para> - -</sect3> - -<sect3 id="bitmap.impl.allocate" xreflabel="Allocate"> - <title><function>allocate</function></title> - - <para> - The allocate function is specialized for single object allocation - ONLY. Thus, ONLY if n == 1, will the bitmap_allocator's - specialized algorithm be used. Otherwise, the request is satisfied - directly by calling operator new. - </para> - <para> - Suppose n == 1, then the allocator does the following: - </para> - <orderedlist> - <listitem> - <para> - Checks to see whether a free block exists somewhere in a region - of memory close to the last satisfied request. If so, then that - block is marked as allocated in the bit map and given to the - user. If not, then (2) is executed. - </para> - </listitem> - <listitem> - <para> - Is there a free block anywhere after the current block right - up to the end of the memory that we have? If so, that block is - found, and the same procedure is applied as above, and - returned to the user. If not, then (3) is executed. - </para> - </listitem> - <listitem> - <para> - Is there any block in whatever region of memory that we own - free? This is done by checking - </para> - <itemizedlist> - <listitem> - <para> - The use count for each super block, and if that fails then - </para> - </listitem> - <listitem> - <para> - The individual bit-maps for each super block. - </para> - </listitem> - </itemizedlist> - - <para> - Note: Here we are never touching any of the memory that the - user will be given, and we are confining all memory accesses - to a small region of memory! This helps reduce cache - misses. If this succeeds then we apply the same procedure on - that bit-map as (1), and return that block of memory to the - user. However, if this process fails, then we resort to (4). - </para> - </listitem> - <listitem> - <para> - This process involves Refilling the internal exponentially - growing memory pool. The said effect is achieved by calling - _S_refill_pool which does the following: - </para> - <itemizedlist> - <listitem> - <para> - Gets more memory from the Global Free List of the Required - size. - </para> - </listitem> - <listitem> - <para> - Adjusts the size for the next call to itself. - </para> - </listitem> - <listitem> - <para> - Writes the appropriate headers in the bit-maps. - </para> - </listitem> - <listitem> - <para> - Sets the use count for that super-block just allocated to 0 - (zero). - </para> - </listitem> - <listitem> - <para> - All of the above accounts to maintaining the basic invariant - for the allocator. If the invariant is maintained, we are - sure that all is well. Now, the same process is applied on - the newly acquired free blocks, which are dispatched - accordingly. - </para> - </listitem> - </itemizedlist> - </listitem> -</orderedlist> - -<para> -Thus, you can clearly see that the allocate function is nothing but a -combination of the next-fit and first-fit algorithm optimized ONLY for -single object allocations. -</para> - -</sect3> - -<sect3 id="bitmap.impl.deallocate" xreflabel="Deallocate"> - <title><function>deallocate</function></title> - <para> - The deallocate function again is specialized for single objects ONLY. - For all n belonging to > 1, the operator delete is called without - further ado, and the deallocate function returns. - </para> - <para> - However for n == 1, a series of steps are performed: - </para> - - <orderedlist> - <listitem><para> - We first need to locate that super-block which holds the memory - location given to us by the user. For that purpose, we maintain - a static variable _S_last_dealloc_index, which holds the index - into the vector of block pairs which indicates the index of the - last super-block from which memory was freed. We use this - strategy in the hope that the user will deallocate memory in a - region close to what he/she deallocated the last time around. If - the check for belongs_to succeeds, then we determine the bit-map - for the given pointer, and locate the index into that bit-map, - and mark that bit as free by setting it. - </para></listitem> - <listitem><para> - If the _S_last_dealloc_index does not point to the memory block - that we're looking for, then we do a linear search on the block - stored in the vector of Block Pairs. This vector in code is - called _S_mem_blocks. When the corresponding super-block is - found, we apply the same procedure as we did for (1) to mark the - block as free in the bit-map. - </para></listitem> - </orderedlist> - - <para> - Now, whenever a block is freed, the use count of that particular - super block goes down by 1. When this use count hits 0, we remove - that super block from the list of all valid super blocks stored in - the vector. While doing this, we also make sure that the basic - invariant is maintained by making sure that _S_last_request and - _S_last_dealloc_index point to valid locations within the vector. - </para> -</sect3> - -<sect3 id="bitmap.impl.questions" xreflabel="Questions"> - <title>Questions</title> - - <sect4 id="bitmap.impl.question.1" xreflabel="Question 1"> - <title>1</title> - <para> -Q1) The "Data Layout" section is -cryptic. I have no idea of what you are trying to say. Layout of what? -The free-list? Each bitmap? The Super Block? - </para> - <para> - The layout of a Super Block of a given -size. In the example, a super block of size 32 x 1 is taken. The -general formula for calculating the size of a super block is -32 x sizeof(value_type) x 2^n, where n ranges from 0 to 32 for 32-bit -systems. - </para> - </sect4> - - <sect4 id="bitmap.impl.question.2" xreflabel="Question 2"> - <title>2</title> - <para> - And since I just mentioned the -term `each bitmap', what in the world is meant by it? What does each -bitmap manage? How does it relate to the super block? Is the Super -Block a bitmap as well? - </para> - <para> - Each bitmap is part of a Super Block which is made up of 3 parts - as I have mentioned earlier. Re-iterating, 1. The use count, - 2. The bit-map for that Super Block. 3. The actual memory that - will be eventually given to the user. Each bitmap is a multiple - of 32 in size. If there are 32 x (2^3) blocks of single objects - to be given, there will be '32 x (2^3)' bits present. Each 32 - bits managing the allocated / free status for 32 blocks. Since - each size_t contains 32-bits, one size_t can manage up to 32 - blocks' status. Each bit-map is made up of a number of size_t, - whose exact number for a super-block of a given size I have just - mentioned. - </para> - </sect4> - - <sect4 id="bitmap.impl.question.3" xreflabel="Question 3"> - <title>3</title> - <para> - How do the allocate and deallocate functions work in regard to - bitmaps? - </para> - <para> - The allocate and deallocate functions manipulate the bitmaps and - have nothing to do with the memory that is given to the user. As - I have earlier mentioned, a 1 in the bitmap's bit field - indicates free, while a 0 indicates allocated. This lets us - check 32 bits at a time to check whether there is at lease one - free block in those 32 blocks by testing for equality with - (0). Now, the allocate function will given a memory block find - the corresponding bit in the bitmap, and will reset it (i.e., - make it re-set (0)). And when the deallocate function is called, - it will again set that bit after locating it to indicate that - that particular block corresponding to this bit in the bit-map - is not being used by anyone, and may be used to satisfy future - requests. - </para> - <para> - e.g.: Consider a bit-map of 64-bits as represented below: - 1111111111111111111111111111111111111111111111111111111111111111 - </para> - - <para> - Now, when the first request for allocation of a single object - comes along, the first block in address order is returned. And - since the bit-maps in the reverse order to that of the address - order, the last bit (LSB if the bit-map is considered as a - binary word of 64-bits) is re-set to 0. - </para> - - <para> - The bit-map now looks like this: - 1111111111111111111111111111111111111111111111111111111111111110 - </para> - </sect4> -</sect3> - -<sect3 id="bitmap.impl.locality" xreflabel="Locality"> - <title>Locality</title> - <para> - Another issue would be whether to keep the all bitmaps in a - separate area in memory, or to keep them near the actual blocks - that will be given out or allocated for the client. After some - testing, I've decided to keep these bitmaps close to the actual - blocks. This will help in 2 ways. - </para> - - <orderedlist> - <listitem><para>Constant time access for the bitmap themselves, since no kind of -look up will be needed to find the correct bitmap list or it's -equivalent.</para></listitem> - <listitem><para>And also this would preserve the cache as far as possible.</para></listitem> - </orderedlist> - - <para> - So in effect, this kind of an allocator might prove beneficial from a - purely cache point of view. But this allocator has been made to try and - roll out the defects of the node_allocator, wherein the nodes get - skewed about in memory, if they are not returned in the exact reverse - order or in the same order in which they were allocated. Also, the - new_allocator's book keeping overhead is too much for small objects and - single object allocations, though it preserves the locality of blocks - very well when they are returned back to the allocator. - </para> -</sect3> - -<sect3 id="bitmap.impl.grow_policy" xreflabel="Grow Policy"> - <title>Overhead and Grow Policy</title> - <para> - Expected overhead per block would be 1 bit in memory. Also, once - the address of the free list has been found, the cost for - allocation/deallocation would be negligible, and is supposed to be - constant time. For these very reasons, it is very important to - minimize the linear time costs, which include finding a free list - with a free block while allocating, and finding the corresponding - free list for a block while deallocating. Therefore, I have - decided that the growth of the internal pool for this allocator - will be exponential as compared to linear for - node_allocator. There, linear time works well, because we are - mainly concerned with speed of allocation/deallocation and memory - consumption, whereas here, the allocation/deallocation part does - have some linear/logarithmic complexity components in it. Thus, to - try and minimize them would be a good thing to do at the cost of a - little bit of memory. - </para> - - <para> - Another thing to be noted is the pool size will double every time - the internal pool gets exhausted, and all the free blocks have - been given away. The initial size of the pool would be - sizeof(size_t) x 8 which is the number of bits in an integer, - which can fit exactly in a CPU register. Hence, the term given is - exponential growth of the internal pool. - </para> -</sect3> - -</sect2> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/build_hacking.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/build_hacking.xml deleted file mode 100644 index 3f47e654f..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/build_hacking.xml +++ /dev/null @@ -1,354 +0,0 @@ -<sect1 id="appendix.porting.build_hacking" xreflabel="build_hacking"> -<?dbhtml filename="build_hacking.html"?> - -<sect1info> - <keywordset> - <keyword> - C++ - </keyword> - <keyword> - BUILD_HACKING - </keyword> - <keyword> - version - </keyword> - <keyword> - dynamic - </keyword> - <keyword> - shared - </keyword> - </keywordset> -</sect1info> - -<title>Configure and Build Hacking</title> - -<sect2 id="build_hacking.prereq" xreflabel="build_hacking.prereq"> - <title>Prerequisites</title> - <para> - As noted <ulink - url="http://gcc.gnu.org/install/prerequisites.html">previously</ulink>, - certain other tools are necessary for hacking on files that - control configure (<code>configure.ac</code>, - <code>acinclude.m4</code>) and make - (<code>Makefile.am</code>). These additional tools - (<code>automake</code>, and <code>autoconf</code>) are further - described in detail in their respective manuals. All the libraries - in GCC try to stay in sync with each other in terms of versions of - the auto-tools used, so please try to play nicely with the - neighbors. - </para> -</sect2> - -<sect2 id="build_hacking.map" xreflabel="build_hacking.map"> - <title>Overview: What Comes from Where</title> - - <screen> - <inlinemediaobject> - <imageobject> - <imagedata fileref="../images/confdeps.png"/> - </imageobject> - <textobject> - <phrase>Dependency Graph Configure to Build Files</phrase> - </textobject> - </inlinemediaobject> - </screen> - - <para> - Regenerate all generated files by using the command sequence - <code>"autoreconf"</code> at the top level of the libstdc++ source - directory. The following will also work, but is much more complex: - <code>"aclocal-1.7 && autoconf-2.59 && - autoheader-2.59 && automake-1.7"</code> The version - numbers may be absent entirely or otherwise vary depending on - <ulink url="http://gcc.gnu.org/install/prerequisites.html">the - current requirements</ulink> and your vendor's choice of - installation names. - </para> -</sect2> - -<sect2 id="build_hacking.scripts" xreflabel="build_hacking.scripts"> - <title>Storing Information in non-AC files (like configure.host)</title> - - <para> - Until that glorious day when we can use AC_TRY_LINK with a - cross-compiler, we have to hardcode the results of what the tests - would have shown if they could be run. So we have an inflexible - mess like crossconfig.m4. - </para> - - <para> - Wouldn't it be nice if we could store that information in files - like configure.host, which can be modified without needing to - regenerate anything, and can even be tweaked without really - knowing how the configury all works? Perhaps break the pieces of - crossconfig.m4 out and place them in their appropriate - config/{cpu,os} directory. - </para> - - <para> - Alas, writing macros like - "<code>AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside - files which are passed through autoconf. Files which are pure - shell script can be source'd at configure time. Files which - contain autoconf macros must be processed with autoconf. We could - still try breaking the pieces out into "config/*/cross.m4" bits, - for instance, but then we would need arguments to aclocal/autoconf - to properly find them all when generating configure. I would - discourage that. -</para> -</sect2> - -<sect2 id="build_hacking.conventions" xreflabel="build_hacking.conventions"> - <title>Coding and Commenting Conventions</title> - - <para> - Most comments should use {octothorpes, shibboleths, hash marks, - pound signs, whatever} rather than "dnl". Nearly all comments in - configure.ac should. Comments inside macros written in ancilliary - .m4 files should. About the only comments which should - <emphasis>not</emphasis> use #, but use dnl instead, are comments - <emphasis>outside</emphasis> our own macros in the ancilliary - files. The difference is that # comments show up in - <code>configure</code> (which is most helpful for debugging), - while dnl'd lines just vanish. Since the macros in ancilliary - files generate code which appears in odd places, their "outside" - comments tend to not be useful while reading - <code>configure</code>. - </para> - - <para> - Do not use any <code>$target*</code> variables, such as - <code>$target_alias</code>. The single exception is in - configure.ac, for automake+dejagnu's sake. - </para> -</sect2> - -<sect2 id="build_hacking.acinclude" xreflabel="build_hacking.acinclude"> - <title>The acinclude.m4 layout</title> - <para> - The nice thing about acinclude.m4/aclocal.m4 is that macros aren't - actually performed/called/expanded/whatever here, just loaded. So - we can arrange the contents however we like. As of this writing, - acinclude.m4 is arranged as follows: - </para> - <programlisting> - GLIBCXX_CHECK_HOST - GLIBCXX_TOPREL_CONFIGURE - GLIBCXX_CONFIGURE - </programlisting> - <para> - All the major variable "discovery" is done here. CXX, multilibs, - etc. - </para> - <programlisting> - fragments included from elsewhere - </programlisting> - <para> - Right now, "fragments" == "the math/linkage bits". - </para> -<programlisting> - GLIBCXX_CHECK_COMPILER_FEATURES - GLIBCXX_CHECK_LINKER_FEATURES - GLIBCXX_CHECK_WCHAR_T_SUPPORT -</programlisting> -<para> - Next come extra compiler/linker feature tests. Wide character - support was placed here because I couldn't think of another place - for it. It will probably get broken apart like the math tests, - because we're still disabling wchars on systems which could actually - support them. -</para> -<programlisting> - GLIBCXX_CHECK_SETRLIMIT_ancilliary - GLIBCXX_CHECK_SETRLIMIT - GLIBCXX_CHECK_S_ISREG_OR_S_IFREG - GLIBCXX_CHECK_POLL - GLIBCXX_CHECK_WRITEV - - GLIBCXX_CONFIGURE_TESTSUITE -</programlisting> -<para> - Feature tests which only get used in one place. Here, things used - only in the testsuite, plus a couple bits used in the guts of I/O. -</para> -<programlisting> - GLIBCXX_EXPORT_INCLUDES - GLIBCXX_EXPORT_FLAGS - GLIBCXX_EXPORT_INSTALL_INFO -</programlisting> -<para> - Installation variables, multilibs, working with the rest of the - compiler. Many of the critical variables used in the makefiles are - set here. -</para> -<programlisting> - GLIBGCC_ENABLE - GLIBCXX_ENABLE_C99 - GLIBCXX_ENABLE_CHEADERS - GLIBCXX_ENABLE_CLOCALE - GLIBCXX_ENABLE_CONCEPT_CHECKS - GLIBCXX_ENABLE_CSTDIO - GLIBCXX_ENABLE_CXX_FLAGS - GLIBCXX_ENABLE_C_MBCHAR - GLIBCXX_ENABLE_DEBUG - GLIBCXX_ENABLE_DEBUG_FLAGS - GLIBCXX_ENABLE_LONG_LONG - GLIBCXX_ENABLE_PCH - GLIBCXX_ENABLE_SJLJ_EXCEPTIONS - GLIBCXX_ENABLE_SYMVERS - GLIBCXX_ENABLE_THREADS -</programlisting> -<para> - All the features which can be controlled with enable/disable - configure options. Note how they're alphabetized now? Keep them - like that. :-) -</para> -<programlisting> - AC_LC_MESSAGES - libtool bits -</programlisting> -<para> - Things which we don't seem to use directly, but just has to be - present otherwise stuff magically goes wonky. -</para> - -</sect2> - -<sect2 id="build_hacking.enable" xreflabel="build_hacking.enable"> - <title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title> - - <para> - All the GLIBCXX_ENABLE_FOO macros use a common helper, - GLIBCXX_ENABLE. (You don't have to use it, but it's easy.) The - helper does two things for us: - </para> - -<orderedlist> - <listitem> - <para> - Builds the call to the AC_ARG_ENABLE macro, with --help text - properly quoted and aligned. (Death to changequote!) - </para> - </listitem> - <listitem> - <para> - Checks the result against a list of allowed possibilities, and - signals a fatal error if there's no match. This means that the - rest of the GLIBCXX_ENABLE_FOO macro doesn't need to test for - strange arguments, nor do we need to protect against - empty/whitespace strings with the <code>"x$foo" = "xbar"</code> - idiom. - </para> - </listitem> -</orderedlist> - -<para>Doing these things correctly takes some extra autoconf/autom4te code, - which made our macros nearly illegible. So all the ugliness is factored - out into this one helper macro. -</para> - -<para>Many of the macros take an argument, passed from when they are expanded - in configure.ac. The argument controls the default value of the - enable/disable switch. Previously, the arguments themselves had defaults. - Now they don't, because that's extra complexity with zero gain for us. -</para> - -<para>There are three "overloaded signatures". When reading the descriptions - below, keep in mind that the brackets are autoconf's quotation characters, - and that they will be stripped. Examples of just about everything occur - in acinclude.m4, if you want to look. -</para> - -<programlisting> - GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) - GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) - GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) -</programlisting> - -<itemizedlist> - <listitem> - <para> - FEATURE is the string that follows --enable. The results of the - test (such as it is) will be in the variable $enable_FEATURE, - where FEATURE has been squashed. Example: - <code>[extra-foo]</code>, controlled by the --enable-extra-foo - option and stored in $enable_extra_foo. - </para> - </listitem> - <listitem> - <para> - DEFAULT is the value to store in $enable_FEATURE if the user does - not pass --enable/--disable. It should be one of the permitted - values passed later. Examples: <code>[yes]</code>, or - <code>[bar]</code>, or <code>[$1]</code> (which passes the - argument given to the GLIBCXX_ENABLE_FOO macro as the - default). - </para> - <para> - For cases where we need to probe for particular models of things, - it is useful to have an undocumented "auto" value here (see - GLIBCXX_ENABLE_CLOCALE for an example). - </para> - </listitem> - <listitem> - <para> - HELP-ARG is any text to append to the option string itself in the - --help output. Examples: <code>[]</code> (i.e., an empty string, - which appends nothing), <code>[=BAR]</code>, which produces - <code>--enable-extra-foo=BAR</code>, and - <code>[@<:@=BAR@:>@]</code>, which produces - <code>--enable-extra-foo[=BAR]</code>. See the difference? See - what it implies to the user? - </para> - <para> - If you're wondering what that line noise in the last example was, - that's how you embed autoconf special characters in output text. - They're called <ulink - url="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_95.html#SEC95"><emphasis>quadrigraphs</emphasis></ulink> - and you should use them whenever necessary. - </para> - </listitem> - <listitem> - <para>HELP-STRING is what you think it is. Do not include the - "default" text like we used to do; it will be done for you by - GLIBCXX_ENABLE. By convention, these are not full English - sentences. Example: [turn on extra foo] - </para> - </listitem> -</itemizedlist> - -<para> - With no other arguments, only the standard autoconf patterns are - allowed: "<code>--{enable,disable}-foo[={yes,no}]</code>" The - $enable_FEATURE variable is guaranteed to equal either "yes" or "no" - after the macro. If the user tries to pass something else, an - explanatory error message will be given, and configure will halt. -</para> - -<para> - The second signature takes a fifth argument, "<code>[permit - a | b | c | ...]</code>" - This allows <emphasis>a</emphasis> or <emphasis>b</emphasis> or - ... after the equals sign in the option, and $enable_FEATURE is - guaranteed to equal one of them after the macro. Note that if you - want to allow plain --enable/--disable with no "=whatever", you must - include "yes" and "no" in the list of permitted values. Also note - that whatever you passed as DEFAULT must be in the list. If the - user tries to pass something not on the list, a semi-explanatory - error message will be given, and configure will halt. Example: - <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> -</para> - -<para> - The third signature takes a fifth argument. It is arbitrary shell - code to execute if the user actually passes the enable/disable - option. (If the user does not, the default is used. Duh.) No - argument checking at all is done in this signature. See - GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error - message. -</para> - -</sect2> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/codecvt.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/codecvt.xml deleted file mode 100644 index c836f9d0a..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/codecvt.xml +++ /dev/null @@ -1,730 +0,0 @@ -<sect1 id="manual.localization.facet.codecvt" xreflabel="codecvt"> -<?dbhtml filename="codecvt.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - codecvt - </keyword> - </keywordset> -</sect1info> - -<title>codecvt</title> - -<para> -The standard class codecvt attempts to address conversions between -different character encoding schemes. In particular, the standard -attempts to detail conversions between the implementation-defined wide -characters (hereafter referred to as wchar_t) and the standard type -char that is so beloved in classic <quote>C</quote> (which can now be -referred to as narrow characters.) This document attempts to describe -how the GNU libstdc++ implementation deals with the conversion between -wide and narrow characters, and also presents a framework for dealing -with the huge number of other encodings that iconv can convert, -including Unicode and UTF8. Design issues and requirements are -addressed, and examples of correct usage for both the required -specializations for wide and narrow characters and the -implementation-provided extended functionality are given. -</para> - -<sect2 id="facet.codecvt.req" xreflabel="facet.codecvt.req"> -<title>Requirements</title> - -<para> -Around page 425 of the C++ Standard, this charming heading comes into view: -</para> - -<blockquote> -<para> -22.2.1.5 - Template class codecvt -</para> -</blockquote> - -<para> -The text around the codecvt definition gives some clues: -</para> - -<blockquote> -<para> -<emphasis> --1- The class codecvt<internT,externT,stateT> is for use when -converting from one codeset to another, such as from wide characters -to multibyte characters, between wide character encodings such as -Unicode and EUC. -</emphasis> -</para> -</blockquote> - -<para> -Hmm. So, in some unspecified way, Unicode encodings and -translations between other character sets should be handled by this -class. -</para> - -<blockquote> -<para> -<emphasis> --2- The stateT argument selects the pair of codesets being mapped between. -</emphasis> -</para> -</blockquote> - -<para> -Ah ha! Another clue... -</para> - -<blockquote> -<para> -<emphasis> --3- The instantiations required in the Table ?? -(lib.locale.category), namely codecvt<wchar_t,char,mbstate_t> and -codecvt<char,char,mbstate_t>, convert the implementation-defined -native character set. codecvt<char,char,mbstate_t> implements a -degenerate conversion; it does not convert at -all. codecvt<wchar_t,char,mbstate_t> converts between the native -character sets for tiny and wide characters. Instantiations on -mbstate_t perform conversion between encodings known to the library -implementor. Other encodings can be converted by specializing on a -user-defined stateT type. The stateT object can contain any state that -is useful to communicate to or from the specialized do_convert member. -</emphasis> -</para> -</blockquote> - -<para> -At this point, a couple points become clear: -</para> - -<para> -One: The standard clearly implies that attempts to add non-required -(yet useful and widely used) conversions need to do so through the -third template parameter, stateT.</para> - -<para> -Two: The required conversions, by specifying mbstate_t as the third -template parameter, imply an implementation strategy that is mostly -(or wholly) based on the underlying C library, and the functions -mcsrtombs and wcsrtombs in particular.</para> -</sect2> - -<sect2 id="facet.codecvt.design" xreflabel="facet.codecvt.design"> -<title>Design</title> - -<sect3 id="codecvt.design.wchar_t_size" xreflabel="codecvt.design.wchar_t_size"> - <title><type>wchar_t</type> Size</title> - - <para> - The simple implementation detail of wchar_t's size seems to - repeatedly confound people. Many systems use a two byte, - unsigned integral type to represent wide characters, and use an - internal encoding of Unicode or UCS2. (See AIX, Microsoft NT, - Java, others.) Other systems, use a four byte, unsigned integral - type to represent wide characters, and use an internal encoding - of UCS4. (GNU/Linux systems using glibc, in particular.) The C - programming language (and thus C++) does not specify a specific - size for the type wchar_t. - </para> - - <para> - Thus, portable C++ code cannot assume a byte size (or endianness) either. - </para> - </sect3> - -<sect3 id="codecvt.design.unicode" xreflabel="codecvt.design.unicode"> - <title>Support for Unicode</title> - <para> - Probably the most frequently asked question about code conversion - is: "So dudes, what's the deal with Unicode strings?" - The dude part is optional, but apparently the usefulness of - Unicode strings is pretty widely appreciated. Sadly, this specific - encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10, - etc etc etc) are not mentioned in the C++ standard. - </para> - - <para> - A couple of comments: - </para> - - <para> - The thought that all one needs to convert between two arbitrary - codesets is two types and some kind of state argument is - unfortunate. In particular, encodings may be stateless. The naming - of the third parameter as stateT is unfortunate, as what is really - needed is some kind of generalized type that accounts for the - issues that abstract encodings will need. The minimum information - that is required includes: - </para> - - <itemizedlist> - <listitem> - <para> - Identifiers for each of the codesets involved in the - conversion. For example, using the iconv family of functions - from the Single Unix Specification (what used to be called - X/Open) hosted on the GNU/Linux operating system allows - bi-directional mapping between far more than the following - tantalizing possibilities: - </para> - - <para> - (An edited list taken from <code>`iconv --list`</code> on a - Red Hat 6.2/Intel system: - </para> - -<blockquote> -<programlisting> -8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7, -ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD, -GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3, -ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, -ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14, -ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4, -ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4, -UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8, -UTF-16, UTF8, UTF16). -</programlisting> -</blockquote> - -<para> -For iconv-based implementations, string literals for each of the -encodings (i.e. "UCS-2" and "UTF-8") are necessary, -although for other, -non-iconv implementations a table of enumerated values or some other -mechanism may be required. -</para> -</listitem> - -<listitem><para> - Maximum length of the identifying string literal. -</para></listitem> - -<listitem><para> - Some encodings require explicit endian-ness. As such, some kind - of endian marker or other byte-order marker will be necessary. See - "Footnotes for C/C++ developers" in Haible for more information on - UCS-2/Unicode endian issues. (Summary: big endian seems most likely, - however implementations, most notably Microsoft, vary.) -</para></listitem> - -<listitem><para> - Types representing the conversion state, for conversions involving - the machinery in the "C" library, or the conversion descriptor, for - conversions using iconv (such as the type iconv_t.) Note that the - conversion descriptor encodes more information than a simple encoding - state type. -</para></listitem> - -<listitem><para> - Conversion descriptors for both directions of encoding. (i.e., both - UCS-2 to UTF-8 and UTF-8 to UCS-2.) -</para></listitem> - -<listitem><para> - Something to indicate if the conversion requested if valid. -</para></listitem> - -<listitem><para> - Something to represent if the conversion descriptors are valid. -</para></listitem> - -<listitem><para> - Some way to enforce strict type checking on the internal and - external types. As part of this, the size of the internal and - external types will need to be known. -</para></listitem> -</itemizedlist> -</sect3> - -<sect3 id="codecvt.design.issues" xreflabel="codecvt.design.issues"> - <title>Other Issues</title> -<para> -In addition, multi-threaded and multi-locale environments also impact -the design and requirements for code conversions. In particular, they -affect the required specialization codecvt<wchar_t, char, mbstate_t> -when implemented using standard "C" functions. -</para> - -<para> -Three problems arise, one big, one of medium importance, and one small. -</para> - -<para> -First, the small: mcsrtombs and wcsrtombs may not be multithread-safe -on all systems required by the GNU tools. For GNU/Linux and glibc, -this is not an issue. -</para> - -<para> -Of medium concern, in the grand scope of things, is that the functions -used to implement this specialization work on null-terminated -strings. Buffers, especially file buffers, may not be null-terminated, -thus giving conversions that end prematurely or are otherwise -incorrect. Yikes! -</para> - -<para> -The last, and fundamental problem, is the assumption of a global -locale for all the "C" functions referenced above. For something like -C++ iostreams (where codecvt is explicitly used) the notion of -multiple locales is fundamental. In practice, most users may not run -into this limitation. However, as a quality of implementation issue, -the GNU C++ library would like to offer a solution that allows -multiple locales and or simultaneous usage with computationally -correct results. In short, libstdc++ is trying to offer, as an -option, a high-quality implementation, damn the additional complexity! -</para> - -<para> -For the required specialization codecvt<wchar_t, char, mbstate_t> , -conversions are made between the internal character set (always UCS4 -on GNU/Linux) and whatever the currently selected locale for the -LC_CTYPE category implements. -</para> - -</sect3> - -</sect2> - -<sect2 id="facet.codecvt.impl" xreflabel="facet.codecvt.impl"> -<title>Implementation</title> - -<para> -The two required specializations are implemented as follows: -</para> - -<para> -<code> -codecvt<char, char, mbstate_t> -</code> -</para> -<para> -This is a degenerate (i.e., does nothing) specialization. Implementing -this was a piece of cake. -</para> - -<para> -<code> -codecvt<char, wchar_t, mbstate_t> -</code> -</para> - -<para> -This specialization, by specifying all the template parameters, pretty -much ties the hands of implementors. As such, the implementation is -straightforward, involving mcsrtombs for the conversions between char -to wchar_t and wcsrtombs for conversions between wchar_t and char. -</para> - -<para> -Neither of these two required specializations deals with Unicode -characters. As such, libstdc++ implements a partial specialization -of the codecvt class with and iconv wrapper class, encoding_state as the -third template parameter. -</para> - -<para> -This implementation should be standards conformant. First of all, the -standard explicitly points out that instantiations on the third -template parameter, stateT, are the proper way to implement -non-required conversions. Second of all, the standard says (in Chapter -17) that partial specializations of required classes are a-ok. Third -of all, the requirements for the stateT type elsewhere in the standard -(see 21.1.2 traits typedefs) only indicate that this type be copy -constructible. -</para> - -<para> -As such, the type encoding_state is defined as a non-templatized, POD -type to be used as the third type of a codecvt instantiation. This -type is just a wrapper class for iconv, and provides an easy interface -to iconv functionality. -</para> - -<para> -There are two constructors for encoding_state: -</para> - -<para> -<code> -encoding_state() : __in_desc(0), __out_desc(0) -</code> -</para> -<para> -This default constructor sets the internal encoding to some default -(currently UCS4) and the external encoding to whatever is returned by -nl_langinfo(CODESET). -</para> - -<para> -<code> -encoding_state(const char* __int, const char* __ext) -</code> -</para> - -<para> -This constructor takes as parameters string literals that indicate the -desired internal and external encoding. There are no defaults for -either argument. -</para> - -<para> -One of the issues with iconv is that the string literals identifying -conversions are not standardized. Because of this, the thought of -mandating and or enforcing some set of pre-determined valid -identifiers seems iffy: thus, a more practical (and non-migraine -inducing) strategy was implemented: end-users can specify any string -(subject to a pre-determined length qualifier, currently 32 bytes) for -encodings. It is up to the user to make sure that these strings are -valid on the target system. -</para> - -<para> -<code> -void -_M_init() -</code> -</para> -<para> -Strangely enough, this member function attempts to open conversion -descriptors for a given encoding_state object. If the conversion -descriptors are not valid, the conversion descriptors returned will -not be valid and the resulting calls to the codecvt conversion -functions will return error. -</para> - -<para> -<code> -bool -_M_good() -</code> -</para> - -<para> -Provides a way to see if the given encoding_state object has been -properly initialized. If the string literals describing the desired -internal and external encoding are not valid, initialization will -fail, and this will return false. If the internal and external -encodings are valid, but iconv_open could not allocate conversion -descriptors, this will also return false. Otherwise, the object is -ready to convert and will return true. -</para> - -<para> -<code> -encoding_state(const encoding_state&) -</code> -</para> - -<para> -As iconv allocates memory and sets up conversion descriptors, the copy -constructor can only copy the member data pertaining to the internal -and external code conversions, and not the conversion descriptors -themselves. -</para> - -<para> -Definitions for all the required codecvt member functions are provided -for this specialization, and usage of codecvt<internal character type, -external character type, encoding_state> is consistent with other -codecvt usage. -</para> - -</sect2> - -<sect2 id="facet.codecvt.use" xreflabel="facet.codecvt.use"> -<title>Use</title> -<para>A conversions involving string literal.</para> - -<programlisting> - typedef codecvt_base::result result; - typedef unsigned short unicode_t; - typedef unicode_t int_type; - typedef char ext_type; - typedef encoding_state state_type; - typedef codecvt<int_type, ext_type, state_type> unicode_codecvt; - - const ext_type* e_lit = "black pearl jasmine tea"; - int size = strlen(e_lit); - int_type i_lit_base[24] = - { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184, - 27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696, - 25856, 24832, 2560 - }; - const int_type* i_lit = i_lit_base; - const ext_type* efrom_next; - const int_type* ifrom_next; - ext_type* e_arr = new ext_type[size + 1]; - ext_type* eto_next; - int_type* i_arr = new int_type[size + 1]; - int_type* ito_next; - - // construct a locale object with the specialized facet. - locale loc(locale::classic(), new unicode_codecvt); - // sanity check the constructed locale has the specialized facet. - VERIFY( has_facet<unicode_codecvt>(loc) ); - const unicode_codecvt& cvt = use_facet<unicode_codecvt>(loc); - // convert between const char* and unicode strings - unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1"); - initialize_state(state01); - result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next, - i_arr, i_arr + size, ito_next); - VERIFY( r1 == codecvt_base::ok ); - VERIFY( !int_traits::compare(i_arr, i_lit, size) ); - VERIFY( efrom_next == e_lit + size ); - VERIFY( ito_next == i_arr + size ); -</programlisting> - -</sect2> - -<sect2 id="facet.codecvt.future" xreflabel="facet.codecvt.future"> -<title>Future</title> -<itemizedlist> -<listitem> - <para> - a. things that are sketchy, or remain unimplemented: - do_encoding, max_length and length member functions - are only weakly implemented. I have no idea how to do - this correctly, and in a generic manner. Nathan? -</para> -</listitem> - -<listitem> - <para> - b. conversions involving std::string - </para> - <itemizedlist> - <listitem><para> - how should operators != and == work for string of - different/same encoding? - </para></listitem> - - <listitem><para> - what is equal? A byte by byte comparison or an - encoding then byte comparison? - </para></listitem> - - <listitem><para> - conversions between narrow, wide, and unicode strings - </para></listitem> - </itemizedlist> -</listitem> -<listitem><para> - c. conversions involving std::filebuf and std::ostream -</para> - <itemizedlist> - <listitem><para> - how to initialize the state object in a - standards-conformant manner? - </para></listitem> - - <listitem><para> - how to synchronize the "C" and "C++" - conversion information? - </para></listitem> - - <listitem><para> - wchar_t/char internal buffers and conversions between - internal/external buffers? - </para></listitem> - </itemizedlist> -</listitem> -</itemizedlist> -</sect2> - - -<bibliography id="facet.codecvt.biblio" xreflabel="facet.codecvt.biblio"> -<title>Bibliography</title> - - <biblioentry> - <title> - The GNU C Library - </title> - - <author> - <surname>McGrath</surname> - <firstname>Roland</firstname> - </author> - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2007</year> - <holder>FSF</holder> - </copyright> - <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums> - - </biblioentry> - - <biblioentry> - <title> - Correspondence - </title> - - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2002</year> - <holder></holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 14882:1998 Programming languages - C++ - </title> - - <copyright> - <year>1998</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 9899:1999 Programming languages - C - </title> - - <copyright> - <year>1999</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) - </title> - - <copyright> - <year>1999</year> - <holder> - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> - </copyright> - - <biblioid> - <ulink url="http://www.opennc.org/austin/docreg.html"> - </ulink> - </biblioid> - - </biblioentry> - - <biblioentry> - <title> - The C++ Programming Language, Special Edition - </title> - - <author> - <surname>Stroustrup</surname> - <firstname>Bjarne</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley, Inc.</holder> - </copyright> - <pagenums>Appendix D</pagenums> - - <publisher> - <publishername> - Addison Wesley - </publishername> - </publisher> - - </biblioentry> - - - <biblioentry> - <title> - Standard C++ IOStreams and Locales - </title> - <subtitle> - Advanced Programmer's Guide and Reference - </subtitle> - - <author> - <surname>Langer</surname> - <firstname>Angelika</firstname> - </author> - - <author> - <surname>Kreft</surname> - <firstname>Klaus</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley Longman, Inc.</holder> - </copyright> - - <publisher> - <publishername> - Addison Wesley Longman - </publishername> - </publisher> - - </biblioentry> - - <biblioentry> - <title> - A brief description of Normative Addendum 1 - </title> - - <author> - <surname>Feather</surname> - <firstname>Clive</firstname> - </author> - - <pagenums>Extended Character Sets</pagenums> - <biblioid> - <ulink url="http://www.lysator.liu.se/c/na1.html"> - </ulink> - </biblioid> - - </biblioentry> - - <biblioentry> - <title> - The Unicode HOWTO - </title> - - <author> - <surname>Haible</surname> - <firstname>Bruno</firstname> - </author> - - <biblioid> - <ulink url="ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html"> - </ulink> - </biblioid> - - </biblioentry> - - <biblioentry> - <title> - UTF-8 and Unicode FAQ for Unix/Linux - </title> - - <author> - <surname>Khun</surname> - <firstname>Markus</firstname> - </author> - - <biblioid> - <ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html"> - </ulink> - </biblioid> - - </biblioentry> - - -</bibliography> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/concurrency.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/concurrency.xml deleted file mode 100644 index 2a676eda3..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/concurrency.xml +++ /dev/null @@ -1,337 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<chapter id="manual.ext.concurrency" xreflabel="Concurrency Extensions"> -<?dbhtml filename="ext_concurrency.html"?> - -<chapterinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</chapterinfo> - -<title>Concurrency</title> - -<sect1 id="manual.ext.concurrency.design" xreflabel="Design"> - <title>Design</title> - - <sect2 id="manual.ext.concurrency.design.threads" xreflabel="Threads API"> - <title>Interface to Locks and Mutexes</title> - -<para>The file <ext/concurrence.h> contains all the higher-level -constructs for playing with threads. In contrast to the atomics layer, -the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>. -</para> - -<para> -These types can be used in a portable manner, regardless of the -specific environment. They are carefully designed to provide optimum -efficiency and speed, abstracting out underlying thread calls and -accesses when compiling for single-threaded situations (even on hosts -that support multiple threads.) -</para> - -<para>The enumerated type <code>_Lock_policy</code> details the set of -available locking -policies: <code>_S_single</code>, <code>_S_mutex</code>, -and <code>_S_atomic</code>. -</para> - -<itemizedlist> -<listitem><para><code>_S_single</code></para> -<para>Indicates single-threaded code that does not need locking. -</para> - -</listitem> -<listitem><para><code>_S_mutex</code></para> -<para>Indicates multi-threaded code using thread-layer abstractions. -</para> -</listitem> -<listitem><para><code>_S_atomic</code></para> -<para>Indicates multi-threaded code using atomic operations. -</para> -</listitem> -</itemizedlist> - -<para>The compile-time constant <code>__default_lock_policy</code> is set -to one of the three values above, depending on characteristics of the -host environment and the current compilation flags. -</para> - -<para>Two more datatypes make up the rest of the -interface: <code>__mutex</code>, and <code>__scoped_lock</code>. -</para> - -<para> -</para> - -<para>The scoped lock idiom is well-discussed within the C++ -community. This version takes a <code>__mutex</code> reference, and -locks it during construction of <code>__scoped_locke</code> and -unlocks it during destruction. This is an efficient way of locking -critical sections, while retaining exception-safety. -</para> - </sect2> - - <sect2 id="manual.ext.concurrency.design.atomics" xreflabel="Atomic API"> - <title>Interface to Atomic Functions</title> - - -<para> -Two functions and one type form the base of atomic support. -</para> - - -<para>The type <code>_Atomic_word</code> is a signed integral type -supporting atomic operations. -</para> - -<para> -The two functions functions are: -</para> - -<programlisting> -_Atomic_word -__exchange_and_add_dispatch(volatile _Atomic_word*, int); - -void -__atomic_add_dispatch(volatile _Atomic_word*, int); -</programlisting> - -<para>Both of these functions are declared in the header file -<ext/atomicity.h>, and are in <code>namespace __gnu_cxx</code>. -</para> - -<itemizedlist> -<listitem><para> -<code> -__exchange_and_add_dispatch -</code> -</para> -<para>Adds the second argument's value to the first argument. Returns the old value. -</para> -</listitem> -<listitem><para> -<code> -__atomic_add_dispatch -</code> -</para> -<para>Adds the second argument's value to the first argument. Has no return value. -</para> -</listitem> -</itemizedlist> - -<para> -These functions forward to one of several specialized helper -functions, depending on the circumstances. For instance, -</para> - -<para> -<code> -__exchange_and_add_dispatch -</code> -</para> - -<para> -Calls through to either of: -</para> - -<itemizedlist> -<listitem><para><code>__exchange_and_add</code> -</para> -<para>Multi-thread version. Inlined if compiler-generated builtin atomics -can be used, otherwise resolved at link time to a non-builtin code -sequence. -</para> -</listitem> - -<listitem><para><code>__exchange_and_add_single</code> -</para> -<para>Single threaded version. Inlined.</para> -</listitem> -</itemizedlist> - -<para>However, only <code>__exchange_and_add_dispatch</code> -and <code>__atomic_add_dispatch</code> should be used. These functions -can be used in a portable manner, regardless of the specific -environment. They are carefully designed to provide optimum efficiency -and speed, abstracting out atomic accesses when they are not required -(even on hosts that support compiler intrinsics for atomic -operations.) -</para> - -<para> -In addition, there are two macros -</para> - -<para> -<code> -_GLIBCXX_READ_MEM_BARRIER -</code> -</para> -<para> -<code> -_GLIBCXX_WRITE_MEM_BARRIER -</code> -</para> - -<para> -Which expand to the appropriate write and read barrier required by the -host hardware and operating system. -</para> - </sect2> - -</sect1> - - -<sect1 id="manual.ext.concurrency.impl" xreflabel="Implementation"> - <title>Implementation</title> - <sect2 id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"> - <title>Using Builtin Atomic Functions</title> - -<para>The functions for atomic operations described above are either -implemented via compiler intrinsics (if the underlying host is -capable) or by library fallbacks.</para> - -<para>Compiler intrinsics (builtins) are always preferred. However, as -the compiler builtins for atomics are not universally implemented, -using them directly is problematic, and can result in undefined -function calls. (An example of an undefined symbol from the use -of <code>__sync_fetch_and_add</code> on an unsupported host is a -missing reference to <code>__sync_fetch_and_add_4</code>.) -</para> - -<para>In addition, on some hosts the compiler intrinsics are enabled -conditionally, via the <code>-march</code> command line flag. This makes -usage vary depending on the target hardware and the flags used during -compile. -</para> - -<para> -If builtins are possible for bool-sized integral types, -<code>_GLIBCXX_ATOMIC_BUILTINS_1</code> will be defined. -If builtins are possible for int-sized integral types, -<code>_GLIBCXX_ATOMIC_BUILTINS_4</code> will be defined. -</para> - - -<para>For the following hosts, intrinsics are enabled by default. -</para> - -<itemizedlist> - <listitem><para>alpha</para></listitem> - <listitem><para>ia64</para></listitem> - <listitem><para>powerpc</para></listitem> - <listitem><para>s390</para></listitem> -</itemizedlist> - -<para>For others, some form of <code>-march</code> may work. On -non-ancient x86 hardware, <code>-march=native</code> usually does the -trick.</para> - -<para> For hosts without compiler intrinsics, but with capable -hardware, hand-crafted assembly is selected. This is the case for the following hosts: -</para> - -<itemizedlist> - <listitem><para>cris</para></listitem> - <listitem><para>hppa</para></listitem> - <listitem><para>i386</para></listitem> - <listitem><para>i486</para></listitem> - <listitem><para>m48k</para></listitem> - <listitem><para>mips</para></listitem> - <listitem><para>sparc</para></listitem> -</itemizedlist> - -<para>And for the rest, a simulated atomic lock via pthreads. -</para> - -<para> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</ulink>. -</para> - -<para> More details on the library fallbacks from the porting <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety">section</ulink>. -</para> - - - </sect2> - <sect2 id="manual.ext.concurrency.impl.thread" xreflabel="Pthread"> - <title>Thread Abstraction</title> - -<para>A thin layer above IEEE 1003.1 (i.e. pthreads) is used to abstract -the thread interface for GCC. This layer is called "gthread," and is -comprised of one header file that wraps the host's default thread layer with -a POSIX-like interface. -</para> - -<para> The file <gthr-default.h> points to the deduced wrapper for -the current host. In libstdc++ implementation files, -<bits/gthr.h> is used to select the proper gthreads file. -</para> - -<para>Within libstdc++ sources, all calls to underlying thread functionality -use this layer. More detail as to the specific interface can be found in the source <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html">documentation</ulink>. -</para> - -<para>By design, the gthread layer is interoperable with the types, -functions, and usage found in the usual <pthread.h> file, -including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>, -etc. -</para> - - </sect2> -</sect1> - -<sect1 id="manual.ext.concurrency.use" xreflabel="Use"> - - <title>Use</title> - -<para>Typical usage of the last two constructs is demonstrated as follows: -</para> - -<programlisting> -#include <ext/concurrence.h> - -namespace -{ - __gnu_cxx::__mutex safe_base_mutex; -} // anonymous namespace - -namespace other -{ - void - foo() - { - __gnu_cxx::__scoped_lock sentry(safe_base_mutex); - for (int i = 0; i < max; ++i) - { - _Safe_iterator_base* __old = __iter; - __iter = __iter-<_M_next; - __old-<_M_detach_single(); - } -} -</programlisting> - -<para>In this sample code, an anonymous namespace is used to keep -the <code>__mutex</code> private to the compilation unit, -and <code>__scoped_lock</code> is used to guard access to the critical -section within the for loop, locking the mutex on creation and freeing -the mutex as control moves out of this block. -</para> - -<para>Several exception classes are used to keep track of -concurrence-related errors. These classes -are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>, -and <code>__concurrence_broadcast_error</code>. -</para> - - -</sect1> - -</chapter> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/configure.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/configure.xml deleted file mode 100644 index 7fa5a1e14..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/configure.xml +++ /dev/null @@ -1,348 +0,0 @@ -<sect1 id="manual.intro.setup.configure" xreflabel="Configuring"> -<?dbhtml filename="configure.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - configure - </keyword> - <keyword> - options - </keyword> - </keywordset> -</sect1info> - -<title>Configure</title> - -<para> - When configuring libstdc++, you'll have to configure the entire - <emphasis>gccsrcdir</emphasis> directory. Consider using the - toplevel gcc configuration option - <literal>--enable-languages=c++</literal>, which saves time by only - building the C++ toolchain. -</para> - -<para> - Here are all of the configure options specific to libstdc++. Keep - in mind that - <!-- This SECnn should be the "Choosing Package Options" section. --> - <ulink url="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_131.html#SEC131">they - all have opposite forms as well</ulink> (enable/disable and - with/without). The defaults are for the <emphasis>current - development sources</emphasis>, which may be different than those - for released versions. -</para> -<para>The canonical way to find out the configure options that are - available for a given set of libstdc++ sources is to go to the - source directory and then type:<command>./configure --help</command>. -</para> - -<variablelist> - <varlistentry><term><code>--enable-multilib</code>[default]</term> - <listitem><para>This is part of the generic multilib support for building cross - compilers. As such, targets like "powerpc-elf" will have - libstdc++ built many different ways: "-msoft-float" - and not, etc. A different libstdc++ will be built for each of - the different multilib versions. This option is on by default. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-sjlj-exceptions</code></term> - <listitem><para>Forces old, set-jump/long-jump exception handling model. If - at all possible, the new, frame unwinding exception handling routines - should be used instead, as they significantly reduce both - runtime memory usage and executable size. This option can - change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-version-specific-runtime-libs</code></term> - <listitem><para>Specify that run-time libraries should be installed in the - compiler-specific subdirectory (i.e., - <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>) - instead of <code>${libdir}</code>. This option is useful if you - intend to use several versions of gcc in parallel. In addition, - libstdc++'s include files will be installed in - <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>, - unless you also specify - <literal>--with-gxx-include-dir=<filename class="directory">dirname</filename></literal> during configuration. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--with-gxx-include-dir=<include-files dir></code></term> - <listitem><para>Adds support for named libstdc++ include directory. For instance, - the following puts all the libstdc++ headers into a directory - called "2.97-20001008" instead of the usual - "c++/(version)". - </para> - <programlisting> - --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008</programlisting> </listitem></varlistentry> - - <varlistentry><term><code>--enable-cstdio</code></term> - <listitem><para>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code> - (described next). This option can change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-cstdio=OPTION</code></term> - <listitem><para>Select a target-specific I/O package. At the moment, the only - choice is to use 'stdio', a generic "C" abstraction. - The default is 'stdio'. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-clocale</code></term> - <listitem><para>This is an abbreviated form of <code>'--enable-clocale=generic'</code> - (described next). This option can change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-clocale=OPTION</code></term> - <listitem><para>Select a target-specific underlying locale package. The - choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix - (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets, - 'gnu' to specify a model based on functionality from the GNU C - library (langinfo/iconv/gettext) (from <ulink url="http://sources.redhat.com/glibc/">glibc</ulink>, the GNU C - library), or 'generic' to use a generic "C" - abstraction which consists of "C" locale info. - </para> - - <para>As part of the configuration process, the "C" library is - probed both for sufficient vintage, and installed locale - data. If either of these elements are not present, the C++ - locale model default to 'generic.' On glibc-based systems of - version 2.2.5 and above with installed locale files, 'gnu' is - automatically selected. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-libstdcxx-allocator</code></term> - <listitem><para>This is an abbreviated form of - <code>'--enable-libstdcxx-allocator=auto'</code> (described - next). This option can change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-libstdcxx-allocator=OPTION </code></term> - <listitem><para>Select a target-specific underlying std::allocator. The - choices are 'new' to specify a wrapper for new, 'malloc' to - specify a wrapper for malloc, 'mt' for a fixed power of two allocator, - 'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator. - This option can change the library ABI. See this page for more information on allocator - <link linkend="allocator.ext">extensions</link> - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-cheaders=OPTION</code></term> - <listitem><para>This allows the user to define the approach taken for C header - compatibility with C++. Options are c, c_std, and c_global. - These correspond to the source directory's include/c, - include/c_std, and include/c_global, and may also include - include/c_compatibility. The default is c_global. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-threads</code></term> - <listitem><para>This is an abbreviated form of <code>'--enable-threads=yes'</code> - (described next). This option can change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-threads=OPTION</code></term> - <listitem><para>Select a threading library. A full description is given in the - general <ulink url="http://gcc.gnu.org/install/configure.html">compiler - configuration instructions</ulink>. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-libstdcxx-debug</code></term> - <listitem><para>Build separate debug libraries in addition to what is normally built. - By default, the debug libraries are compiled with - <code> CXXFLAGS='-g3 -O0 -fno-inline'</code> - , are installed in <code>${libdir}/debug</code>, and have the - same names and versioning information as the non-debug - libraries. This option is off by default. - </para> - <para>Note this make command, executed in - the build directory, will do much the same thing, without the - configuration difference and without building everything twice: - <code>make CXXFLAGS='-g3 -O0 -fno-inline' all</code> - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-libstdcxx-debug-flags=FLAGS</code></term> - - <listitem><para>This option is only valid when <code> --enable-debug </code> - is also specified, and applies to the debug builds only. With - this option, you can pass a specific string of flags to the - compiler to use when building the debug versions of libstdc++. - FLAGS is a quoted string of options, like - </para> - <programlisting> - --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'</programlisting> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-cxx-flags=FLAGS</code></term> - <listitem><para>With this option, you can pass a string of -f (functionality) - flags to the compiler to use when building libstdc++. This - option can change the library ABI. FLAGS is a quoted string of - options, like - </para> - <programlisting> - --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</programlisting> - <para> - Note that the flags don't necessarily have to all be -f flags, - as shown, but usually those are the ones that will make sense - for experimentation and configure-time overriding. - </para> - <para>The advantage of --enable-cxx-flags over setting CXXFLAGS in - the 'make' environment is that, if files are automatically - rebuilt, the same flags will be used when compiling those files - as well, so that everything matches. - </para> - <para>Fun flags to try might include combinations of - </para> - <programlisting> - -fstrict-aliasing - -fno-exceptions - -ffunction-sections - -fvtable-gc</programlisting> - <para>and opposite forms (-fno-) of the same. Tell us (the libstdc++ - mailing list) if you discover more! - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-c99</code></term> - <listitem><para>The "long long" type was introduced in C99, along - with many other functions for wide characters, and math - classification macros, etc. If enabled, all C99 functions not - specified by the C++ standard will be put into <code>namespace - __gnu_cxx</code>, and then all these names will - be injected into namespace std, so that C99 functions can be - used "as if" they were in the C++ standard (as they - will eventually be in some future revision of the standard, - without a doubt). By default, C99 support is on, assuming the - configure probes find all the necessary functions and bits - necessary. This option can change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-wchar_t</code>[default]</term> - <listitem><para>Template specializations for the "wchar_t" type are - required for wide character conversion support. Disabling - wide character specializations may be expedient for initial - porting efforts, but builds only a subset of what is required by - ISO, and is not recommended. By default, this option is on. - This option can change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-long-long </code></term> - <listitem><para>The "long long" type was introduced in C99. It is - provided as a GNU extension to C++98 in g++. This flag builds - support for "long long" into the library (specialized - templates and the like for iostreams). This option is on by default: - if enabled, users will have to either use the new-style "C" - headers by default (i.e., <cmath> not <math.h>) - or add appropriate compile-time flags to all compile lines to - allow "C" visibility of this feature (on GNU/Linux, - the flag is -D_ISOC99_SOURCE, which is added automatically via - CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). - This option can change the library ABI. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-fully-dynamic-string</code></term> - <listitem><para>This option enables a special version of basic_string avoiding - the optimization that allocates empty objects in static memory. - Mostly useful together with shared memory allocators, see PR - libstdc++/16612 for details. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-concept-checks</code></term> - <listitem><para>This turns on additional compile-time checks for instantiated - library templates, in the form of specialized templates, - <link linkend="manual.diagnostics.concept_checking">described here</link>. They - can help users discover when they break the rules of the STL, before - their programs run. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-symvers[=style]</code></term> - - <listitem><para>In 3.1 and later, tries to turn on symbol versioning in the - shared library (if a shared library has been - requested). Values for 'style' that are currently supported - are 'gnu', 'gnu-versioned-namespace', 'darwin', and - 'darwin-export'. Both gnu- options require that a recent - version of the GNU linker be in use. Both darwin options are - equivalent. With no style given, the configure script will try - to guess correct defaults for the host system, probe to see if - additional requirements are necessary and present for - activation, and if so, will turn symbol versioning on. This - option can change the library ABI. - </para> - - </listitem></varlistentry> - - <varlistentry><term><code>--enable-visibility</code></term> - <listitem><para> In 4.2 and later, enables or disables visibility attributes. - If enabled (as by default), and the compiler seems capable of - passing the simple sanity checks thrown at it, adjusts items - in namespace std, namespace std::tr1, and namespace __gnu_cxx - so that -fvisibility options work. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-libstdcxx-pch</code></term> - <listitem><para>In 3.4 and later, tries to turn on the generation of - stdc++.h.gch, a pre-compiled file including all the standard - C++ includes. If enabled (as by default), and the compiler - seems capable of passing the simple sanity checks thrown at - it, try to build stdc++.h.gch as part of the make process. - In addition, this generated file is used later on (by appending <code> - --include bits/stdc++.h </code> to CXXFLAGS) when running the - testsuite. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--disable-hosted-libstdcxx</code></term> - <listitem> - <para> - By default, a complete <emphasis>hosted</emphasis> C++ library is - built. The C++ Standard also describes a - <emphasis>freestanding</emphasis> environment, in which only a - minimal set of headers are provided. This option builds such an - environment. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-clock-gettime</code></term> - <listitem><para>This is an abbreviated form of - <code>'--enable-clock-gettime=yes'</code>(described next). - </para> - </listitem></varlistentry> - - <varlistentry><term><code>--enable-libstdcxx-time=OPTION</code></term> - <listitem><para>Enables link-type checks for the availability of the - clock_gettime clocks, used in the implementation of [time.clock], - and of the nanosleep and sched_yield functions, used in the - implementation of [thread.thread.this] of the current C++0x draft. - The choice OPTION=yes checks for the availability of the facilities - in libc and libposix4. In case of need the latter is also linked - to libstdc++ as part of the build process. OPTION=rt also searches - (and, in case, links) librt. Note that the latter is not always - desirable because, in glibc, for example, in turn it triggers the - linking of libpthread too, which activates locking, a large overhead - for single-thread programs. OPTION=no skips the tests completely. - The default is OPTION=no. - </para> - </listitem></varlistentry> - -</variablelist> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/containers.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/containers.xml deleted file mode 100644 index 2b29ba6fc..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/containers.xml +++ /dev/null @@ -1,450 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.containers" xreflabel="Containers"> -<?dbhtml filename="containers.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Containers - <indexterm><primary>Containers</primary></indexterm> -</title> - -<!-- Chapter 01 : Sequences --> -<chapter id="manual.containers.sequences" xreflabel="Sequences"> -<?dbhtml filename="sequences.html"?> - <title>Sequences</title> - -<sect1 id="containers.sequences.list" xreflabel="list"> -<?dbhtml filename="list.html"?> - <title>list</title> - <sect2 id="sequences.list.size" xreflabel="list::size() is O(n)"> - <title>list::size() is O(n)</title> - <para> - Yes it is, and that's okay. This is a decision that we preserved - when we imported SGI's STL implementation. The following is - quoted from <ulink - url="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</ulink>: - </para> - <blockquote> - <para> - The size() member function, for list and slist, takes time - proportional to the number of elements in the list. This was a - deliberate tradeoff. The only way to get a constant-time - size() for linked lists would be to maintain an extra member - variable containing the list's size. This would require taking - extra time to update that variable (it would make splice() a - linear time operation, for example), and it would also make the - list larger. Many list algorithms don't require that extra - word (algorithms that do require it might do better with - vectors than with lists), and, when it is necessary to maintain - an explicit size count, it's something that users can do - themselves. - </para> - <para> - This choice is permitted by the C++ standard. The standard says - that size() <quote>should</quote> be constant time, and - <quote>should</quote> does not mean the same thing as - <quote>shall</quote>. This is the officially recommended ISO - wording for saying that an implementation is supposed to do - something unless there is a good reason not to. - </para> - <para> - One implication of linear time size(): you should never write - </para> - <programlisting> - if (L.size() == 0) - ... - </programlisting> - - <para> - Instead, you should write - </para> - - <programlisting> - if (L.empty()) - ... - </programlisting> - </blockquote> - </sect2> -</sect1> - -<sect1 id="containers.sequences.vector" xreflabel="vector"> -<?dbhtml filename="vector.html"?> - <title>vector</title> - <para> - </para> - <sect2 id="sequences.vector.management" xreflabel="Space Overhead Management"> - <title>Space Overhead Management</title> - <para> - In <ulink - url="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this - message to the list</ulink>, Daniel Kostecky announced work on an - alternate form of <code>std::vector</code> that would support - hints on the number of elements to be over-allocated. The design - was also described, along with possible implementation choices. - </para> - <para> - The first two alpha releases were announced <ulink - url="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html">here</ulink> - and <ulink - url="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html">here</ulink>. - The releases themselves are available at - <ulink url="http://www.kotelna.sk/dk/sw/caphint/"> - http://www.kotelna.sk/dk/sw/caphint/</ulink>. - </para> - - </sect2></sect1> -</chapter> - -<!-- Chapter 02 : Associative --> -<chapter id="manual.containers.associative" xreflabel="Associative"> -<?dbhtml filename="associative.html"?> - <title>Associative</title> - - <sect1 id="containers.associative.insert_hints" xreflabel="Insertion Hints"> - <title>Insertion Hints</title> - <para> - Section [23.1.2], Table 69, of the C++ standard lists this - function for all of the associative containers (map, set, etc): - </para> - <programlisting> - a.insert(p,t); - </programlisting> - <para> - where 'p' is an iterator into the container 'a', and 't' is the - item to insert. The standard says that <quote><code>t</code> is - inserted as close as possible to the position just prior to - <code>p</code>.</quote> (Library DR #233 addresses this topic, - referring to <ulink - url='http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html'>N1780</ulink>. - Since version 4.2 GCC implements the resolution to DR 233, so - that insertions happen as close as possible to the hint. For - earlier releases the hint was only used as described below. - </para> - <para> - Here we'll describe how the hinting works in the libstdc++ - implementation, and what you need to do in order to take - advantage of it. (Insertions can change from logarithmic - complexity to amortized constant time, if the hint is properly - used.) Also, since the current implementation is based on the - SGI STL one, these points may hold true for other library - implementations also, since the HP/SGI code is used in a lot of - places. - </para> - <para> - In the following text, the phrases <emphasis>greater - than</emphasis> and <emphasis>less than</emphasis> refer to the - results of the strict weak ordering imposed on the container by - its comparison object, which defaults to (basically) - <quote><</quote>. Using those phrases is semantically sloppy, - but I didn't want to get bogged down in syntax. I assume that if - you are intelligent enough to use your own comparison objects, - you are also intelligent enough to assign <quote>greater</quote> - and <quote>lesser</quote> their new meanings in the next - paragraph. *grin* - </para> - <para> - If the <code>hint</code> parameter ('p' above) is equivalent to: - </para> - <itemizedlist> - <listitem> - <para> - <code>begin()</code>, then the item being inserted should - have a key less than all the other keys in the container. - The item will be inserted at the beginning of the container, - becoming the new entry at <code>begin()</code>. - </para> - </listitem> - <listitem> - <para> - <code>end()</code>, then the item being inserted should have - a key greater than all the other keys in the container. The - item will be inserted at the end of the container, becoming - the new entry at <code>end()</code>. - </para> - </listitem> - <listitem> - <para> - neither <code>begin()</code> nor <code>end()</code>, then: - Let <code>h</code> be the entry in the container pointed to - by <code>hint</code>, that is, <code>h = *hint</code>. Then - the item being inserted should have a key less than that of - <code>h</code>, and greater than that of the item preceding - <code>h</code>. The new item will be inserted between - <code>h</code> and <code>h</code>'s predecessor. - </para> - </listitem> - </itemizedlist> - <para> - For <code>multimap</code> and <code>multiset</code>, the - restrictions are slightly looser: <quote>greater than</quote> - should be replaced by <quote>not less than</quote>and <quote>less - than</quote> should be replaced by <quote>not greater - than.</quote> (Why not replace greater with - greater-than-or-equal-to? You probably could in your head, but - the mathematicians will tell you that it isn't the same thing.) - </para> - <para> - If the conditions are not met, then the hint is not used, and the - insertion proceeds as if you had called <code> a.insert(t) - </code> instead. (<emphasis>Note </emphasis> that GCC releases - prior to 3.0.2 had a bug in the case with <code>hint == - begin()</code> for the <code>map</code> and <code>set</code> - classes. You should not use a hint argument in those releases.) - </para> - <para> - This behavior goes well with other containers' - <code>insert()</code> functions which take an iterator: if used, - the new item will be inserted before the iterator passed as an - argument, same as the other containers. - </para> - <para> - <emphasis>Note </emphasis> also that the hint in this - implementation is a one-shot. The older insertion-with-hint - routines check the immediately surrounding entries to ensure that - the new item would in fact belong there. If the hint does not - point to the correct place, then no further local searching is - done; the search begins from scratch in logarithmic time. - </para> - </sect1> - - - <sect1 id="containers.associative.bitset" xreflabel="bitset"> - <?dbhtml filename="bitset.html"?> - <title>bitset</title> - <sect2 id="associative.bitset.size_variable" xreflabel="Variable"> - <title>Size Variable</title> - <para> - No, you cannot write code of the form - </para> - <!-- Careful, the leading spaces in PRE show up directly. --> - <programlisting> - #include <bitset> - - void foo (size_t n) - { - std::bitset<n> bits; - .... - } - </programlisting> - <para> - because <code>n</code> must be known at compile time. Your - compiler is correct; it is not a bug. That's the way templates - work. (Yes, it <emphasis>is</emphasis> a feature.) - </para> - <para> - There are a couple of ways to handle this kind of thing. Please - consider all of them before passing judgement. They include, in - no particular order: - </para> - <itemizedlist> - <listitem><para>A very large N in <code>bitset<N></code>.</para></listitem> - <listitem><para>A container<bool>.</para></listitem> - <listitem><para>Extremely weird solutions.</para></listitem> - </itemizedlist> - <para> - <emphasis>A very large N in - <code>bitset<N></code>. </emphasis> It has been - pointed out a few times in newsgroups that N bits only takes up - (N/8) bytes on most systems, and division by a factor of eight is - pretty impressive when speaking of memory. Half a megabyte given - over to a bitset (recall that there is zero space overhead for - housekeeping info; it is known at compile time exactly how large - the set is) will hold over four million bits. If you're using - those bits as status flags (e.g., - <quote>changed</quote>/<quote>unchanged</quote> flags), that's a - <emphasis>lot</emphasis> of state. - </para> - <para> - You can then keep track of the <quote>maximum bit used</quote> - during some testing runs on representative data, make note of how - many of those bits really need to be there, and then reduce N to - a smaller number. Leave some extra space, of course. (If you - plan to write code like the incorrect example above, where the - bitset is a local variable, then you may have to talk your - compiler into allowing that much stack space; there may be zero - space overhead, but it's all allocated inside the object.) - </para> - <para> - <emphasis>A container<bool>. </emphasis> The - Committee made provision for the space savings possible with that - (N/8) usage previously mentioned, so that you don't have to do - wasteful things like <code>Container<char></code> or - <code>Container<short int></code>. Specifically, - <code>vector<bool></code> is required to be specialized for - that space savings. - </para> - <para> - The problem is that <code>vector<bool></code> doesn't - behave like a normal vector anymore. There have been recent - journal articles which discuss the problems (the ones by Herb - Sutter in the May and July/August 1999 issues of C++ Report cover - it well). Future revisions of the ISO C++ Standard will change - the requirement for <code>vector<bool></code> - specialization. In the meantime, <code>deque<bool></code> - is recommended (although its behavior is sane, you probably will - not get the space savings, but the allocation scheme is different - than that of vector). - </para> - <para> - <emphasis>Extremely weird solutions. </emphasis> If - you have access to the compiler and linker at runtime, you can do - something insane, like figuring out just how many bits you need, - then writing a temporary source code file. That file contains an - instantiation of <code>bitset</code> for the required number of - bits, inside some wrapper functions with unchanging signatures. - Have your program then call the compiler on that file using - Position Independent Code, then open the newly-created object - file and load those wrapper functions. You'll have an - instantiation of <code>bitset<N></code> for the exact - <code>N</code> that you need at the time. Don't forget to delete - the temporary files. (Yes, this <emphasis>can</emphasis> be, and - <emphasis>has been</emphasis>, done.) - </para> - <!-- I wonder if this next paragraph will get me in trouble... --> - <para> - This would be the approach of either a visionary genius or a - raving lunatic, depending on your programming and management - style. Probably the latter. - </para> - <para> - Which of the above techniques you use, if any, are up to you and - your intended application. Some time/space profiling is - indicated if it really matters (don't just guess). And, if you - manage to do anything along the lines of the third category, the - author would love to hear from you... - </para> - <para> - Also note that the implementation of bitset used in libstdc++ has - <ulink url="../ext/sgiexts.html#ch23">some extensions</ulink>. - </para> - - </sect2> - <sect2 id="associative.bitset.type_string" xreflabel="Type String"> - <title>Type String</title> - <para> - </para> - <para> - Bitmasks do not take char* nor const char* arguments in their - constructors. This is something of an accident, but you can read - about the problem: follow the library's <quote>Links</quote> from - the homepage, and from the C++ information <quote>defect - reflector</quote> link, select the library issues list. Issue - number 116 describes the problem. - </para> - <para> - For now you can simply make a temporary string object using the - constructor expression: - </para> - <programlisting> - std::bitset<5> b ( std::string(<quote>10110</quote>) ); - </programlisting> - - <para> - instead of - </para> - - <programlisting> - std::bitset<5> b ( <quote>10110</quote> ); // invalid - </programlisting> - </sect2> - </sect1> - -</chapter> - -<!-- Chapter 03 : Interacting with C --> -<chapter id="manual.containers.c" xreflabel="Interacting with C"> -<?dbhtml filename="containers_and_c.html"?> - <title>Interacting with C</title> - - <sect1 id="containers.c.vs_array" xreflabel="Containers vs. Arrays"> - <title>Containers vs. Arrays</title> - <para> - You're writing some code and can't decide whether to use builtin - arrays or some kind of container. There are compelling reasons - to use one of the container classes, but you're afraid that - you'll eventually run into difficulties, change everything back - to arrays, and then have to change all the code that uses those - data types to keep up with the change. - </para> - <para> - If your code makes use of the standard algorithms, this isn't as - scary as it sounds. The algorithms don't know, nor care, about - the kind of <quote>container</quote> on which they work, since - the algorithms are only given endpoints to work with. For the - container classes, these are iterators (usually - <code>begin()</code> and <code>end()</code>, but not always). - For builtin arrays, these are the address of the first element - and the <ulink - url="../24_iterators/howto.html#2">past-the-end</ulink> element. - </para> - <para> - Some very simple wrapper functions can hide all of that from the - rest of the code. For example, a pair of functions called - <code>beginof</code> can be written, one that takes an array, - another that takes a vector. The first returns a pointer to the - first element, and the second returns the vector's - <code>begin()</code> iterator. - </para> - <para> - The functions should be made template functions, and should also - be declared inline. As pointed out in the comments in the code - below, this can lead to <code>beginof</code> being optimized out - of existence, so you pay absolutely nothing in terms of increased - code size or execution time. - </para> - <para> - The result is that if all your algorithm calls look like - </para> - <programlisting> - std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction); - </programlisting> - <para> - then the type of foo can change from an array of ints to a vector - of ints to a deque of ints and back again, without ever changing - any client code. - </para> - <para> - This author has a collection of such functions, called - <quote>*of</quote> because they all extend the builtin - <quote>sizeof</quote>. It started with some Usenet discussions - on a transparent way to find the length of an array. A - simplified and much-reduced version for easier reading is <ulink - url="wrappers_h.txt">given here</ulink>. - </para> - <para> - Astute readers will notice two things at once: first, that the - container class is still a <code>vector<T></code> instead - of a more general <code>Container<T></code>. This would - mean that three functions for <code>deque</code> would have to be - added, another three for <code>list</code>, and so on. This is - due to problems with getting template resolution correct; I find - it easier just to give the extra three lines and avoid confusion. - </para> - <para> - Second, the line - </para> - <programlisting> - inline unsigned int lengthof (T (&)[sz]) { return sz; } - </programlisting> - <para> - looks just weird! Hint: unused parameters can be left nameless. - </para> - </sect1> - -</chapter> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/ctype.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/ctype.xml deleted file mode 100644 index 58f08fbdb..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/ctype.xml +++ /dev/null @@ -1,259 +0,0 @@ -<sect1 id="manual.localization.facet.ctype" xreflabel="ctype"> -<?dbhtml filename="ctype.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - ctype - </keyword> - </keywordset> -</sect1info> - -<title>ctype</title> - -<sect2 id="facet.ctype.impl" xreflabel="facet.ctype.impl"> -<title>Implementation</title> - - <sect3> - <title>Specializations</title> - -<para> -For the required specialization codecvt<wchar_t, char, mbstate_t> , -conversions are made between the internal character set (always UCS4 -on GNU/Linux) and whatever the currently selected locale for the -LC_CTYPE category implements. -</para> - -<para> -The two required specializations are implemented as follows: -</para> - -<para> -<code> -ctype<char> -</code> -</para> -<para> -This is simple specialization. Implementing this was a piece of cake. -</para> - -<para> -<code> -ctype<wchar_t> -</code> -</para> -<para> -This specialization, by specifying all the template parameters, pretty -much ties the hands of implementors. As such, the implementation is -straightforward, involving mcsrtombs for the conversions between char -to wchar_t and wcsrtombs for conversions between wchar_t and char. -</para> - -<para> -Neither of these two required specializations deals with Unicode -characters. -</para> - - </sect3> -</sect2> - -<sect2 id="facet.ctype.future" xreflabel="facet.ctype.future"> -<title>Future</title> - - -<itemizedlist> - <listitem> - <para> - How to deal with the global locale issue? - </para></listitem> - - <listitem> - <para> - How to deal with different types than char, wchar_t? </para></listitem> - - <listitem><para> - Overlap between codecvt/ctype: narrow/widen - </para></listitem> - - <listitem> - <para> - Mask typedef in codecvt_base, argument types in codecvt. what - is know about this type? - </para></listitem> - - <listitem> - <para> - Why mask* argument in codecvt? - </para></listitem> - - <listitem> - <para> - Can this be made (more) generic? is there a simple way to - straighten out the configure-time mess that is a by-product of - this class? - </para></listitem> - - <listitem> - <para> - Get the ctype<wchar_t>::mask stuff under control. Need to - make some kind of static table, and not do lookup every time - somebody hits the do_is... functions. Too bad we can't just - redefine mask for ctype<wchar_t> - </para></listitem> - - <listitem> - <para> - Rename abstract base class. See if just smash-overriding is a - better approach. Clarify, add sanity to naming. - </para> - </listitem> - -</itemizedlist> - - -</sect2> - - -<bibliography id="facet.ctype.biblio" xreflabel="facet.ctype.biblio"> -<title>Bibliography</title> - - <biblioentry> - <title> - The GNU C Library - </title> - - <author> - <surname>McGrath</surname> - <firstname>Roland</firstname> - </author> - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2007</year> - <holder>FSF</holder> - </copyright> - <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums> - - </biblioentry> - - <biblioentry> - <title> - Correspondence - </title> - - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2002</year> - <holder></holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 14882:1998 Programming languages - C++ - </title> - - <copyright> - <year>1998</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 9899:1999 Programming languages - C - </title> - - <copyright> - <year>1999</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) - </title> - - <copyright> - <year>1999</year> - <holder> - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> - </copyright> - - <biblioid> - <ulink url="http://www.opennc.org/austin/docreg.html"> - </ulink> - </biblioid> - - </biblioentry> - - <biblioentry> - <title> - The C++ Programming Language, Special Edition - </title> - - <author> - <surname>Stroustrup</surname> - <firstname>Bjarne</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley, Inc.</holder> - </copyright> - <pagenums>Appendix D</pagenums> - - <publisher> - <publishername> - Addison Wesley - </publishername> - </publisher> - - </biblioentry> - - - <biblioentry> - <title> - Standard C++ IOStreams and Locales - </title> - <subtitle> - Advanced Programmer's Guide and Reference - </subtitle> - - <author> - <surname>Langer</surname> - <firstname>Angelika</firstname> - </author> - - <author> - <surname>Kreft</surname> - <firstname>Klaus</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley Longman, Inc.</holder> - </copyright> - - <publisher> - <publishername> - Addison Wesley Longman - </publishername> - </publisher> - - </biblioentry> - -</bibliography> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/debug.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/debug.xml deleted file mode 100644 index 2ad542b97..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/debug.xml +++ /dev/null @@ -1,246 +0,0 @@ -<sect1 id="manual.intro.using.debug" xreflabel="Debugging Support"> -<?dbhtml filename="debug.html"?> - -<sect1info> - <keywordset> - <keyword> - C++ - </keyword> - <keyword> - debug - </keyword> - </keywordset> -</sect1info> - -<title>Debugging Support</title> - -<para> - There are numerous things that can be done to improve the ease with - which C++ binaries are debugged when using the GNU tool chain. Here - are some of them. -</para> - -<sect2 id="debug.compiler" xreflabel="debug.compiler"> -<title>Using <command>g++</command></title> - <para> - Compiler flags determine how debug information is transmitted - between compilation and debug or analysis tools. - </para> - - <para> - The default optimizations and debug flags for a libstdc++ build - are <code>-g -O2</code>. However, both debug and optimization - flags can be varied to change debugging characteristics. For - instance, turning off all optimization via the <code>-g -O0 - -fno-inline</code> flags will disable inlining and optimizations, - and add debugging information, so that stepping through all functions, - (including inlined constructors and destructors) is possible. In - addition, <code>-fno-eliminate-unused-debug-types</code> can be - used when additional debug information, such as nested class info, - is desired. -</para> - -<para> - Or, the debug format that the compiler and debugger use to - communicate information about source constructs can be changed via - <code>-gdwarf-2</code> or <code>-gstabs</code> flags: some debugging - formats permit more expressive type and scope information to be - shown in gdb. Expressiveness can be enhanced by flags like - <code>-g3</code>. The default debug information for a particular - platform can be identified via the value set by the - PREFERRED_DEBUGGING_TYPE macro in the gcc sources. -</para> - -<para> - Many other options are available: please see <ulink - url="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options - for Debugging Your Program"</ulink> in Using the GNU Compiler - Collection (GCC) for a complete list. -</para> -</sect2> - -<sect2 id="debug.req" xreflabel="debug.req"> -<title>Debug Versions of Library Binary Files</title> - -<para> - If you would like debug symbols in libstdc++, there are two ways to - build libstdc++ with debug flags. The first is to run make from the - toplevel in a freshly-configured tree with -</para> -<programlisting> - --enable-libstdcxx-debug -</programlisting> -<para>and perhaps</para> -<programlisting> - --enable-libstdcxx-debug-flags='...' -</programlisting> -<para> - to create a separate debug build. Both the normal build and the - debug build will persist, without having to specify - <code>CXXFLAGS</code>, and the debug library will be installed in a - separate directory tree, in <code>(prefix)/lib/debug</code>. For - more information, look at the <link - linkend="manual.intro.setup.configure">configuration</link> section. -</para> - -<para> - A second approach is to use the configuration flags -</para> -<programlisting> - make CXXFLAGS='-g3 -fno-inline -O0' all -</programlisting> - -<para> - This quick and dirty approach is often sufficient for quick - debugging tasks, when you cannot or don't want to recompile your - application to use the <link linkend="manual.ext.debug_mode">debug mode</link>.</para> -</sect2> - -<sect2 id="debug.memory" xreflabel="debug.memory"> -<title>Memory Leak Hunting</title> - -<para> - There are various third party memory tracing and debug utilities - that can be used to provide detailed memory allocation information - about C++ code. An exhaustive list of tools is not going to be - attempted, but includes <code>mtrace</code>, <code>valgrind</code>, - <code>mudflap</code>, and the non-free commercial product - <code>purify</code>. In addition, <code>libcwd</code> has a - replacement for the global new and delete operators that can track - memory allocation and deallocation and provide useful memory - statistics. -</para> - -<para> - Regardless of the memory debugging tool being used, there is one - thing of great importance to keep in mind when debugging C++ code - that uses <code>new</code> and <code>delete</code>: there are - different kinds of allocation schemes that can be used by <code> - std::allocator </code>. For implementation details, see the <link - linkend="manual.ext.allocator.mt">mt allocator</link> documentation and - look specifically for <code>GLIBCXX_FORCE_NEW</code>. -</para> - -<para> - In a nutshell, the default allocator used by <code> - std::allocator</code> is a high-performance pool allocator, and can - give the mistaken impression that in a suspect executable, memory is - being leaked, when in reality the memory "leak" is a pool being used - by the library's allocator and is reclaimed after program - termination. -</para> - -<para> - For valgrind, there are some specific items to keep in mind. First - of all, use a version of valgrind that will work with current GNU - C++ tools: the first that can do this is valgrind 1.0.4, but later - versions should work at least as well. Second of all, use a - completely unoptimized build to avoid confusing valgrind. Third, use - GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from - cluttering debug information. -</para> - -<para> - Fourth, it may be necessary to force deallocation in other libraries - as well, namely the "C" library. On linux, this can be accomplished - with the appropriate use of the <code>__cxa_atexit</code> or - <code>atexit</code> functions. -</para> - -<programlisting> - #include <cstdlib> - - extern "C" void __libc_freeres(void); - - void do_something() { } - - int main() - { - atexit(__libc_freeres); - do_something(); - return 0; - } -</programlisting> - - -<para>or, using <code>__cxa_atexit</code>:</para> - -<programlisting> - extern "C" void __libc_freeres(void); - extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); - - void do_something() { } - - int main() - { - extern void* __dso_handle __attribute__ ((__weak__)); - __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, - &__dso_handle ? __dso_handle : NULL); - do_test(); - return 0; - } -</programlisting> - -<para> - Suggested valgrind flags, given the suggestions above about setting - up the runtime environment, library, and test file, might be: -</para> -<programlisting> - valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out -</programlisting> - -</sect2> - -<sect2 id="debug.gdb" xreflabel="debug.gdb"> -<title>Using <command>gdb</command></title> - <para> - </para> - -<para> - Many options are available for gdb itself: please see <ulink - url="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC125"> - "GDB features for C++" </ulink> in the gdb documentation. Also - recommended: the other parts of this manual. -</para> - -<para> - These settings can either be switched on in at the gdb command line, - or put into a .gdbint file to establish default debugging - characteristics, like so: -</para> - -<programlisting> - set print pretty on - set print object on - set print static-members on - set print vtbl on - set print demangle on - set demangle-style gnu-v3 -</programlisting> -</sect2> - -<sect2 id="debug.exceptions" xreflabel="debug.exceptions"> -<title>Tracking uncaught exceptions</title> -<para> - The <link linkend="support.termination.verbose">verbose - termination handler</link> gives information about uncaught - exceptions which are killing the program. It is described in the - linked-to page. -</para> -</sect2> - -<sect2 id="debug.debug_mode" xreflabel="debug.debug_mode"> -<title>Debug Mode</title> - <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link> - has compile and run-time checks for many containers. - </para> -</sect2> - -<sect2 id="debug.compile_time_checks" xreflabel="debug.compile_time_checks"> -<title>Compile Time Checking</title> - <para> The <link linkend="manual.ext.compile_checks">Compile-Time - Checks</link> Extension has compile-time checks for many algorithms. - </para> -</sect2> - -</sect1>
\ No newline at end of file diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/debug_mode.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/debug_mode.xml deleted file mode 100644 index 223abcf9a..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/debug_mode.xml +++ /dev/null @@ -1,888 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<chapter id="manual.ext.debug_mode" xreflabel="Debug Mode"> -<?dbhtml filename="debug_mode.html"?> - -<chapterinfo> - <keywordset> - <keyword> - C++ - </keyword> - <keyword> - library - </keyword> - <keyword> - debug - </keyword> - </keywordset> -</chapterinfo> - -<title>Debug Mode</title> - -<sect1 id="manual.ext.debug_mode.intro" xreflabel="Intro"> - <title>Intro</title> - <para> - By default, libstdc++ is built with efficiency in mind, and - therefore performs little or no error checking that is not - required by the C++ standard. This means that programs that - incorrectly use the C++ standard library will exhibit behavior - that is not portable and may not even be predictable, because they - tread into implementation-specific or undefined behavior. To - detect some of these errors before they can become problematic, - libstdc++ offers a debug mode that provides additional checking of - library facilities, and will report errors in the use of libstdc++ - as soon as they can be detected by emitting a description of the - problem to standard error and aborting the program. This debug - mode is available with GCC 3.4.0 and later versions. - </para> - - <para> - The libstdc++ debug mode performs checking for many areas of the - C++ standard, but the focus is on checking interactions among - standard iterators, containers, and algorithms, including: - </para> - - <itemizedlist> - <listitem><para><emphasis>Safe iterators</emphasis>: Iterators keep track of the - container whose elements they reference, so errors such as - incrementing a past-the-end iterator or dereferencing an iterator - that points to a container that has been destructed are diagnosed - immediately.</para></listitem> - - <listitem><para><emphasis>Algorithm preconditions</emphasis>: Algorithms attempt to - validate their input parameters to detect errors as early as - possible. For instance, the <code>set_intersection</code> - algorithm requires that its iterator - parameters <code>first1</code> and <code>last1</code> form a valid - iterator range, and that the sequence - [<code>first1</code>, <code>last1</code>) is sorted according to - the same predicate that was passed - to <code>set_intersection</code>; the libstdc++ debug mode will - detect an error if the sequence is not sorted or was sorted by a - different predicate.</para></listitem> - </itemizedlist> - -</sect1> - -<sect1 id="manual.ext.debug_mode.semantics" xreflabel="Semantics"> - <title>Semantics</title> - <para> - </para> - -<para>A program that uses the C++ standard library correctly - will maintain the same semantics under debug mode as it had with - the normal (release) library. All functional and exception-handling - guarantees made by the normal library also hold for the debug mode - library, with one exception: performance guarantees made by the - normal library may not hold in the debug mode library. For - instance, erasing an element in a <code>std::list</code> is a - constant-time operation in normal library, but in debug mode it is - linear in the number of iterators that reference that particular - list. So while your (correct) program won't change its results, it - is likely to execute more slowly.</para> - -<para>libstdc++ includes many extensions to the C++ standard library. In - some cases the extensions are obvious, such as the hashed - associative containers, whereas other extensions give predictable - results to behavior that would otherwise be undefined, such as - throwing an exception when a <code>std::basic_string</code> is - constructed from a NULL character pointer. This latter category also - includes implementation-defined and unspecified semantics, such as - the growth rate of a vector. Use of these extensions is not - considered incorrect, so code that relies on them will not be - rejected by debug mode. However, use of these extensions may affect - the portability of code to other implementations of the C++ standard - library, and is therefore somewhat hazardous. For this reason, the - libstdc++ debug mode offers a "pedantic" mode (similar to - GCC's <code>-pedantic</code> compiler flag) that attempts to emulate - the semantics guaranteed by the C++ standard. For - instance, constructing a <code>std::basic_string</code> with a NULL - character pointer would result in an exception under normal mode or - non-pedantic debug mode (this is a libstdc++ extension), whereas - under pedantic debug mode libstdc++ would signal an error. To enable - the pedantic debug mode, compile your program with - both <code>-D_GLIBCXX_DEBUG</code> - and <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> . - (N.B. In GCC 3.4.x and 4.0.0, due to a bug, - <code>-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has - been fixed in GCC 4.0.1 and later versions.) </para> - -<para>The following library components provide extra debugging - capabilities in debug mode:</para> -<itemizedlist> - <listitem><para><code>std::basic_string</code> (no safe iterators and see note below)</para></listitem> - <listitem><para><code>std::bitset</code></para></listitem> - <listitem><para><code>std::deque</code></para></listitem> - <listitem><para><code>std::list</code></para></listitem> - <listitem><para><code>std::map</code></para></listitem> - <listitem><para><code>std::multimap</code></para></listitem> - <listitem><para><code>std::multiset</code></para></listitem> - <listitem><para><code>std::set</code></para></listitem> - <listitem><para><code>std::vector</code></para></listitem> - <listitem><para><code>std::unordered_map</code></para></listitem> - <listitem><para><code>std::unordered_multimap</code></para></listitem> - <listitem><para><code>std::unordered_set</code></para></listitem> - <listitem><para><code>std::unordered_multiset</code></para></listitem> -</itemizedlist> - -<para>N.B. although there are precondition checks for some string operations, -e.g. <code>operator[]</code>, -they will not always be run when using the <code>char</code> and -<code>wchar_t</code> specialisations (<code>std::string</code> and -<code>std::wstring</code>). This is because libstdc++ uses GCC's -<code>extern template</code> extension to provide explicit instantiations -of <code>std::string</code> and <code>std::wstring</code>, and those -explicit instantiations don't include the debug-mode checks. If the -containing functions are inlined then the checks will run, so compiling -with <code>-O1</code> might be enough to enable them. Alternatively -<code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations -of the explicit instantiations and cause the functions to be instantiated -with the debug-mode checks included, but this is unsupported and not -guaranteed to work. For full debug-mode support you can use the -<code>__gnu_debug::basic_string</code> debugging container directly, -which always works correctly. -</para> - -</sect1> - -<sect1 id="manual.ext.debug_mode.using" xreflabel="Using"> - <title>Using</title> - <para> - </para> -<sect2 id="debug_mode.using.mode" xreflabel="Using Mode"> - <title>Using the Debug Mode</title> - -<para>To use the libstdc++ debug mode, compile your application with the - compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag - changes the sizes and behavior of standard class templates such - as <code>std::vector</code>, and therefore you can only link code - compiled with debug mode and code compiled without debug mode if no - instantiation of a container is passed between the two translation - units.</para> - -<para>By default, error messages are formatted to fit on lines of about - 78 characters. The environment variable - <code>GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a - different length.</para> - -</sect2> - -<sect2 id="debug_mode.using.specific" xreflabel="Using Specific"> - <title>Using a Specific Debug Container</title> -<para>When it is not feasible to recompile your entire application, or - only specific containers need checking, debugging containers are - available as GNU extensions. These debugging containers are - functionally equivalent to the standard drop-in containers used in - debug mode, but they are available in a separate namespace as GNU - extensions and may be used in programs compiled with either release - mode or with debug mode. The - following table provides the names and headers of the debugging - containers: -</para> - -<table frame='all'> -<title>Debugging Containers</title> -<tgroup cols='6' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> - -<thead> - <row> - <entry>Container</entry> - <entry>Header</entry> - <entry>Debug container</entry> - <entry>Debug header</entry> - </row> -</thead> -<tbody> - <row> - <entry><classname>std::bitset</classname></entry> - <entry><filename class="headerfile">bitset</filename></entry> - <entry><classname>__gnu_debug::bitset</classname></entry> - <entry><filename class="headerfile">bitset</filename></entry> - </row> - <row> - <entry><classname>std::deque</classname></entry> - <entry><filename class="headerfile">deque</filename></entry> - <entry><classname>__gnu_debug::deque</classname></entry> - <entry><filename class="headerfile">deque</filename></entry> - </row> - <row> - <entry><classname>std::list</classname></entry> - <entry><filename class="headerfile">list</filename></entry> - <entry><classname>__gnu_debug::list</classname></entry> - <entry><filename class="headerfile">list</filename></entry> - </row> - <row> - <entry><classname>std::map</classname></entry> - <entry><filename class="headerfile">map</filename></entry> - <entry><classname>__gnu_debug::map</classname></entry> - <entry><filename class="headerfile">map</filename></entry> - </row> - <row> - <entry><classname>std::multimap</classname></entry> - <entry><filename class="headerfile">map</filename></entry> - <entry><classname>__gnu_debug::multimap</classname></entry> - <entry><filename class="headerfile">map</filename></entry> - </row> - <row> - <entry><classname>std::multiset</classname></entry> - <entry><filename class="headerfile">set</filename></entry> - <entry><classname>__gnu_debug::multiset</classname></entry> - <entry><filename class="headerfile">set</filename></entry> - </row> - <row> - <entry><classname>std::set</classname></entry> - <entry><filename class="headerfile">set</filename></entry> - <entry><classname>__gnu_debug::set</classname></entry> - <entry><filename class="headerfile">set</filename></entry> - </row> - <row> - <entry><classname>std::string</classname></entry> - <entry><filename class="headerfile">string</filename></entry> - <entry><classname>__gnu_debug::string</classname></entry> - <entry><filename class="headerfile">string</filename></entry> - </row> - <row> - <entry><classname>std::wstring</classname></entry> - <entry><filename class="headerfile">string</filename></entry> - <entry><classname>__gnu_debug::wstring</classname></entry> - <entry><filename class="headerfile">string</filename></entry> - </row> - <row> - <entry><classname>std::basic_string</classname></entry> - <entry><filename class="headerfile">string</filename></entry> - <entry><classname>__gnu_debug::basic_string</classname></entry> - <entry><filename class="headerfile">string</filename></entry> - </row> - <row> - <entry><classname>std::vector</classname></entry> - <entry><filename class="headerfile">vector</filename></entry> - <entry><classname>__gnu_debug::vector</classname></entry> - <entry><filename class="headerfile">vector</filename></entry> - </row> -</tbody> -</tgroup> -</table> - -<para>In addition, when compiling in C++0x mode, these additional -containers have additional debug capability. -</para> - -<table frame='all'> -<title>Debugging Containers C++0x</title> -<tgroup cols='6' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> - -<thead> - <row> - <entry>Container</entry> - <entry>Header</entry> - <entry>Debug container</entry> - <entry>Debug header</entry> - </row> -</thead> -<tbody> - <row> - <entry><classname>std::unordered_map</classname></entry> - <entry><filename class="headerfile">unordered_map</filename></entry> - <entry><classname>__gnu_debug::unordered_map</classname></entry> - <entry><filename class="headerfile">unordered_map</filename></entry> - </row> - <row> - <entry><classname>std::unordered_multimap</classname></entry> - <entry><filename class="headerfile">unordered_map</filename></entry> - <entry><classname>__gnu_debug::unordered_multimap</classname></entry> - <entry><filename class="headerfile">unordered_map</filename></entry> - </row> - <row> - <entry><classname>std::unordered_set</classname></entry> - <entry><filename class="headerfile">unordered_set</filename></entry> - <entry><classname>__gnu_debug::unordered_set</classname></entry> - <entry><filename class="headerfile">unordered_set</filename></entry> - </row> - <row> - <entry><classname>std::unordered_multiset</classname></entry> - <entry><filename class="headerfile">unordered_set</filename></entry> - <entry><classname>__gnu_debug::unordered_multiset</classname></entry> - <entry><filename class="headerfile">unordered_set</filename></entry> - </row> -</tbody> -</tgroup> -</table> -</sect2> -</sect1> - -<sect1 id="manual.ext.debug_mode.design" xreflabel="Design"> - <title>Design</title> - <para> - </para> - <sect2 id="manual.ext.debug_mode.design.goals" xreflabel="Goals"> - <title>Goals</title> - <para> - </para> -<para> The libstdc++ debug mode replaces unsafe (but efficient) standard - containers and iterators with semantically equivalent safe standard - containers and iterators to aid in debugging user programs. The - following goals directed the design of the libstdc++ debug mode:</para> - - <itemizedlist> - - <listitem><para><emphasis>Correctness</emphasis>: the libstdc++ debug mode must not change - the semantics of the standard library for all cases specified in - the ANSI/ISO C++ standard. The essence of this constraint is that - any valid C++ program should behave in the same manner regardless - of whether it is compiled with debug mode or release mode. In - particular, entities that are defined in namespace std in release - mode should remain defined in namespace std in debug mode, so that - legal specializations of namespace std entities will remain - valid. A program that is not valid C++ (e.g., invokes undefined - behavior) is not required to behave similarly, although the debug - mode will abort with a diagnostic when it detects undefined - behavior.</para></listitem> - - <listitem><para><emphasis>Performance</emphasis>: the additional of the libstdc++ debug mode - must not affect the performance of the library when it is compiled - in release mode. Performance of the libstdc++ debug mode is - secondary (and, in fact, will be worse than the release - mode).</para></listitem> - - <listitem><para><emphasis>Usability</emphasis>: the libstdc++ debug mode should be easy to - use. It should be easily incorporated into the user's development - environment (e.g., by requiring only a single new compiler switch) - and should produce reasonable diagnostics when it detects a - problem with the user program. Usability also involves detection - of errors when using the debug mode incorrectly, e.g., by linking - a release-compiled object against a debug-compiled object if in - fact the resulting program will not run correctly.</para></listitem> - - <listitem><para><emphasis>Minimize recompilation</emphasis>: While it is expected that - users recompile at least part of their program to use debug - mode, the amount of recompilation affects the - detect-compile-debug turnaround time. This indirectly affects the - usefulness of the debug mode, because debugging some applications - may require rebuilding a large amount of code, which may not be - feasible when the suspect code may be very localized. There are - several levels of conformance to this requirement, each with its - own usability and implementation characteristics. In general, the - higher-numbered conformance levels are more usable (i.e., require - less recompilation) but are more complicated to implement than - the lower-numbered conformance levels. - <orderedlist> - <listitem><para><emphasis>Full recompilation</emphasis>: The user must recompile his or - her entire application and all C++ libraries it depends on, - including the C++ standard library that ships with the - compiler. This must be done even if only a small part of the - program can use debugging features.</para></listitem> - - <listitem><para><emphasis>Full user recompilation</emphasis>: The user must recompile - his or her entire application and all C++ libraries it depends - on, but not the C++ standard library itself. This must be done - even if only a small part of the program can use debugging - features. This can be achieved given a full recompilation - system by compiling two versions of the standard library when - the compiler is installed and linking against the appropriate - one, e.g., a multilibs approach.</para></listitem> - - <listitem><para><emphasis>Partial recompilation</emphasis>: The user must recompile the - parts of his or her application and the C++ libraries it - depends on that will use the debugging facilities - directly. This means that any code that uses the debuggable - standard containers would need to be recompiled, but code - that does not use them (but may, for instance, use IOStreams) - would not have to be recompiled.</para></listitem> - - <listitem><para><emphasis>Per-use recompilation</emphasis>: The user must recompile the - parts of his or her application and the C++ libraries it - depends on where debugging should occur, and any other code - that interacts with those containers. This means that a set of - translation units that accesses a particular standard - container instance may either be compiled in release mode (no - checking) or debug mode (full checking), but must all be - compiled in the same way; a translation unit that does not see - that standard container instance need not be recompiled. This - also means that a translation unit <emphasis>A</emphasis> that contains a - particular instantiation - (say, <code>std::vector<int></code>) compiled in release - mode can be linked against a translation unit <emphasis>B</emphasis> that - contains the same instantiation compiled in debug mode (a - feature not present with partial recompilation). While this - behavior is technically a violation of the One Definition - Rule, this ability tends to be very important in - practice. The libstdc++ debug mode supports this level of - recompilation. </para></listitem> - - <listitem><para><emphasis>Per-unit recompilation</emphasis>: The user must only - recompile the translation units where checking should occur, - regardless of where debuggable standard containers are - used. This has also been dubbed "<code>-g</code> mode", - because the <code>-g</code> compiler switch works in this way, - emitting debugging information at a per--translation-unit - granularity. We believe that this level of recompilation is in - fact not possible if we intend to supply safe iterators, leave - the program semantics unchanged, and not regress in - performance under release mode because we cannot associate - extra information with an iterator (to form a safe iterator) - without either reserving that space in release mode - (performance regression) or allocating extra memory associated - with each iterator with <code>new</code> (changes the program - semantics).</para></listitem> - </orderedlist> - </para></listitem> - </itemizedlist> - </sect2> - - <sect2 id="manual.ext.debug_mode.design.methods" xreflabel="Methods"> - <title>Methods</title> - <para> - </para> -<para>This section provides an overall view of the design of the - libstdc++ debug mode and details the relationship between design - decisions and the stated design goals.</para> - - <sect3 id="debug_mode.design.methods.wrappers" xreflabel="Method Wrapper"> - <title>The Wrapper Model</title> -<para>The libstdc++ debug mode uses a wrapper model where the debugging - versions of library components (e.g., iterators and containers) form - a layer on top of the release versions of the library - components. The debugging components first verify that the operation - is correct (aborting with a diagnostic if an error is found) and - will then forward to the underlying release-mode container that will - perform the actual work. This design decision ensures that we cannot - regress release-mode performance (because the release-mode - containers are left untouched) and partially enables <ulink url="#mixing">mixing debug and release code</ulink> at link time, - although that will not be discussed at this time.</para> - -<para>Two types of wrappers are used in the implementation of the debug - mode: container wrappers and iterator wrappers. The two types of - wrappers interact to maintain relationships between iterators and - their associated containers, which are necessary to detect certain - types of standard library usage errors such as dereferencing - past-the-end iterators or inserting into a container using an - iterator from a different container.</para> - - <sect4 id="debug_mode.design.methods.safe_iter" xreflabel="Method Safe Iter"> - <title>Safe Iterators</title> -<para>Iterator wrappers provide a debugging layer over any iterator that - is attached to a particular container, and will manage the - information detailing the iterator's state (singular, - dereferenceable, etc.) and tracking the container to which the - iterator is attached. Because iterators have a well-defined, common - interface the iterator wrapper is implemented with the iterator - adaptor class template <code>__gnu_debug::_Safe_iterator</code>, - which takes two template parameters:</para> - -<itemizedlist> - <listitem><para><code>Iterator</code>: The underlying iterator type, which must - be either the <code>iterator</code> or <code>const_iterator</code> - typedef from the sequence type this iterator can reference.</para></listitem> - - <listitem><para><code>Sequence</code>: The type of sequence that this iterator - references. This sequence must be a safe sequence (discussed below) - whose <code>iterator</code> or <code>const_iterator</code> typedef - is the type of the safe iterator.</para></listitem> -</itemizedlist> - </sect4> - - <sect4 id="debug_mode.design.methods.safe_seq" xreflabel="Method Safe Seq"> - <title>Safe Sequences (Containers)</title> - -<para>Container wrappers provide a debugging layer over a particular - container type. Because containers vary greatly in the member - functions they support and the semantics of those member functions - (especially in the area of iterator invalidation), container - wrappers are tailored to the container they reference, e.g., the - debugging version of <code>std::list</code> duplicates the entire - interface of <code>std::list</code>, adding additional semantic - checks and then forwarding operations to the - real <code>std::list</code> (a public base class of the debugging - version) as appropriate. However, all safe containers inherit from - the class template <code>__gnu_debug::_Safe_sequence</code>, - instantiated with the type of the safe container itself (an instance - of the curiously recurring template pattern).</para> - -<para>The iterators of a container wrapper will be - <ulink url="#safe_iterator">safe iterators</ulink> that reference sequences - of this type and wrap the iterators provided by the release-mode - base class. The debugging container will use only the safe - iterators within its own interface (therefore requiring the user to - use safe iterators, although this does not change correct user - code) and will communicate with the release-mode base class with - only the underlying, unsafe, release-mode iterators that the base - class exports.</para> - -<para> The debugging version of <code>std::list</code> will have the - following basic structure:</para> - -<programlisting> -template<typename _Tp, typename _Allocator = allocator<_Tp> - class debug-list : - public release-list<_Tp, _Allocator>, - public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> > - { - typedef release-list<_Tp, _Allocator> _Base; - typedef debug-list<_Tp, _Allocator> _Self; - - public: - typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self> iterator; - typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> const_iterator; - - // duplicate std::list interface with debugging semantics - }; -</programlisting> - </sect4> - </sect3> - - <sect3 id="debug_mode.design.methods.precond" xreflabel="Precondition check"> - <title>Precondition Checking</title> -<para>The debug mode operates primarily by checking the preconditions of - all standard library operations that it supports. Preconditions that - are always checked (regardless of whether or not we are in debug - mode) are checked via the <code>__check_xxx</code> macros defined - and documented in the source - file <code>include/debug/debug.h</code>. Preconditions that may or - may not be checked, depending on the debug-mode - macro <code>_GLIBCXX_DEBUG</code>, are checked via - the <code>__requires_xxx</code> macros defined and documented in the - same source file. Preconditions are validated using any additional - information available at run-time, e.g., the containers that are - associated with a particular iterator, the position of the iterator - within those containers, the distance between two iterators that may - form a valid range, etc. In the absence of suitable information, - e.g., an input iterator that is not a safe iterator, these - precondition checks will silently succeed.</para> - -<para>The majority of precondition checks use the aforementioned macros, - which have the secondary benefit of having prewritten debug - messages that use information about the current status of the - objects involved (e.g., whether an iterator is singular or what - sequence it is attached to) along with some static information - (e.g., the names of the function parameters corresponding to the - objects involved). When not using these macros, the debug mode uses - either the debug-mode assertion - macro <code>_GLIBCXX_DEBUG_ASSERT</code> , its pedantic - cousin <code>_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion - check macro that supports more advance formulation of error - messages, <code>_GLIBCXX_DEBUG_VERIFY</code>. These macros are - documented more thoroughly in the debug mode source code.</para> - </sect3> - - <sect3 id="debug_mode.design.methods.coexistence" xreflabel="Coexistence"> - <title>Release- and debug-mode coexistence</title> -<para>The libstdc++ debug mode is the first debug mode we know of that - is able to provide the "Per-use recompilation" (4) guarantee, that - allows release-compiled and debug-compiled code to be linked and - executed together without causing unpredictable behavior. This - guarantee minimizes the recompilation that users are required to - perform, shortening the detect-compile-debug bug hunting cycle - and making the debug mode easier to incorporate into development - environments by minimizing dependencies.</para> - -<para>Achieving link- and run-time coexistence is not a trivial - implementation task. To achieve this goal we required a small - extension to the GNU C++ compiler (described in the GCC Manual for - C++ Extensions, see <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Strong-Using.html">strong - using</ulink>), and a complex organization of debug- and - release-modes. The end result is that we have achieved per-use - recompilation but have had to give up some checking of the - <code>std::basic_string</code> class template (namely, safe - iterators). -</para> - - <sect4 id="methods.coexistence.compile" xreflabel="Compile"> - <title>Compile-time coexistence of release- and debug-mode components</title> - -<para>Both the release-mode components and the debug-mode - components need to exist within a single translation unit so that - the debug versions can wrap the release versions. However, only one - of these components should be user-visible at any particular - time with the standard name, e.g., <code>std::list</code>. </para> - -<para>In release mode, we define only the release-mode version of the - component with its standard name and do not include the debugging - component at all. The release mode version is defined within the - namespace <code>std</code>. Minus the namespace associations, this - method leaves the behavior of release mode completely unchanged from - its behavior prior to the introduction of the libstdc++ debug - mode. Here's an example of what this ends up looking like, in - C++.</para> - -<programlisting> -namespace std -{ - template<typename _Tp, typename _Alloc = allocator<_Tp> > - class list - { - // ... - }; -} // namespace std -</programlisting> - -<para>In debug mode we include the release-mode container (which is now -defined in in the namespace <code>__norm</code>) and also the -debug-mode container. The debug-mode container is defined within the -namespace <code>__debug</code>, which is associated with namespace -<code>std</code> via the GNU namespace association extension. This -method allows the debug and release versions of the same component to -coexist at compile-time and link-time without causing an unreasonable -maintenance burden, while minimizing confusion. Again, this boils down -to C++ code as follows:</para> - -<programlisting> -namespace std -{ - namespace __norm - { - template<typename _Tp, typename _Alloc = allocator<_Tp> > - class list - { - // ... - }; - } // namespace __gnu_norm - - namespace __debug - { - template<typename _Tp, typename _Alloc = allocator<_Tp> > - class list - : public __norm::list<_Tp, _Alloc>, - public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > - { - // ... - }; - } // namespace __norm - - using namespace __debug __attribute__ ((strong)); -} -</programlisting> - </sect4> - - <sect4 id="methods.coexistence.link" xreflabel="Link"> - <title>Link- and run-time coexistence of release- and - debug-mode components</title> - -<para>Because each component has a distinct and separate release and -debug implementation, there are are no issues with link-time -coexistence: the separate namespaces result in different mangled -names, and thus unique linkage.</para> - -<para>However, components that are defined and used within the C++ -standard library itself face additional constraints. For instance, -some of the member functions of <code> std::moneypunct</code> return -<code>std::basic_string</code>. Normally, this is not a problem, but -with a mixed mode standard library that could be using either -debug-mode or release-mode <code> basic_string</code> objects, things -get more complicated. As the return value of a function is not -encoded into the mangled name, there is no way to specify a -release-mode or a debug-mode string. In practice, this results in -runtime errors. A simplified example of this problem is as follows. -</para> - -<para> Take this translation unit, compiled in debug-mode: </para> -<programlisting> -// -D_GLIBCXX_DEBUG -#include <string> - -std::string test02(); - -std::string test01() -{ - return test02(); -} - -int main() -{ - test01(); - return 0; -} -</programlisting> - -<para> ... and linked to this translation unit, compiled in release mode:</para> - -<programlisting> -#include <string> - -std::string -test02() -{ - return std::string("toast"); -} -</programlisting> - -<para> For this reason we cannot easily provide safe iterators for - the <code>std::basic_string</code> class template, as it is present - throughout the C++ standard library. For instance, locale facets - define typedefs that include <code>basic_string</code>: in a mixed - debug/release program, should that typedef be based on the - debug-mode <code>basic_string</code> or the - release-mode <code>basic_string</code>? While the answer could be - "both", and the difference hidden via renaming a la the - debug/release containers, we must note two things about locale - facets:</para> - -<orderedlist> - <listitem><para>They exist as shared state: one can create a facet in one - translation unit and access the facet via the same type name in a - different translation unit. This means that we cannot have two - different versions of locale facets, because the types would not be - the same across debug/release-mode translation unit barriers.</para></listitem> - - <listitem><para>They have virtual functions returning strings: these functions - mangle in the same way regardless of the mangling of their return - types (see above), and their precise signatures can be relied upon - by users because they may be overridden in derived classes.</para></listitem> -</orderedlist> - -<para>With the design of libstdc++ debug mode, we cannot effectively hide - the differences between debug and release-mode strings from the - user. Failure to hide the differences may result in unpredictable - behavior, and for this reason we have opted to only - perform <code>basic_string</code> changes that do not require ABI - changes. The effect on users is expected to be minimal, as there are - simple alternatives (e.g., <code>__gnu_debug::basic_string</code>), - and the usability benefit we gain from the ability to mix debug- and - release-compiled translation units is enormous.</para> - </sect4> - - <sect4 id="methods.coexistence.alt" xreflabel="Alternatives"> -<title>Alternatives for Coexistence</title> - -<para>The coexistence scheme above was chosen over many alternatives, - including language-only solutions and solutions that also required - extensions to the C++ front end. The following is a partial list of - solutions, with justifications for our rejection of each.</para> - -<itemizedlist> - <listitem><para><emphasis>Completely separate debug/release libraries</emphasis>: This is by - far the simplest implementation option, where we do not allow any - coexistence of debug- and release-compiled translation units in a - program. This solution has an extreme negative affect on usability, - because it is quite likely that some libraries an application - depends on cannot be recompiled easily. This would not meet - our <emphasis>usability</emphasis> or <emphasis>minimize recompilation</emphasis> criteria - well.</para></listitem> - - <listitem><para><emphasis>Add a <code>Debug</code> boolean template parameter</emphasis>: - Partial specialization could be used to select the debug - implementation when <code>Debug == true</code>, and the state - of <code>_GLIBCXX_DEBUG</code> could decide whether the - default <code>Debug</code> argument is <code>true</code> - or <code>false</code>. This option would break conformance with the - C++ standard in both debug <emphasis>and</emphasis> release modes. This would - not meet our <emphasis>correctness</emphasis> criteria. </para></listitem> - - <listitem><para><emphasis>Packaging a debug flag in the allocators</emphasis>: We could - reuse the <code>Allocator</code> template parameter of containers - by adding a sentinel wrapper <code>debug<></code> that - signals the user's intention to use debugging, and pick up - the <code>debug<></code> allocator wrapper in a partial - specialization. However, this has two drawbacks: first, there is a - conformance issue because the default allocator would not be the - standard-specified <code>std::allocator<T></code>. Secondly - (and more importantly), users that specify allocators instead of - implicitly using the default allocator would not get debugging - containers. Thus this solution fails the <emphasis>correctness</emphasis> - criteria.</para></listitem> - - <listitem><para><emphasis>Define debug containers in another namespace, and employ - a <code>using</code> declaration (or directive)</emphasis>: This is an - enticing option, because it would eliminate the need for - the <code>link_name</code> extension by aliasing the - templates. However, there is no true template aliasing mechanism - is C++, because both <code>using</code> directives and using - declarations disallow specialization. This method fails - the <emphasis>correctness</emphasis> criteria.</para></listitem> - - <listitem><para><emphasis> Use implementation-specific properties of anonymous - namespaces. </emphasis> - See <ulink url="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html"> this post - </ulink> - This method fails the <emphasis>correctness</emphasis> criteria.</para></listitem> - - <listitem><para><emphasis>Extension: allow reopening on namespaces</emphasis>: This would - allow the debug mode to effectively alias the - namespace <code>std</code> to an internal namespace, such - as <code>__gnu_std_debug</code>, so that it is completely - separate from the release-mode <code>std</code> namespace. While - this will solve some renaming problems and ensure that - debug- and release-compiled code cannot be mixed unsafely, it ensures that - debug- and release-compiled code cannot be mixed at all. For - instance, the program would have two <code>std::cout</code> - objects! This solution would fails the <emphasis>minimize - recompilation</emphasis> requirement, because we would only be able to - support option (1) or (2).</para></listitem> - - <listitem><para><emphasis>Extension: use link name</emphasis>: This option involves - complicated re-naming between debug-mode and release-mode - components at compile time, and then a g++ extension called <emphasis> - link name </emphasis> to recover the original names at link time. There - are two drawbacks to this approach. One, it's very verbose, - relying on macro renaming at compile time and several levels of - include ordering. Two, ODR issues remained with container member - functions taking no arguments in mixed-mode settings resulting in - equivalent link names, <code> vector::push_back() </code> being - one example. - See <ulink url="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html">link - name</ulink> </para></listitem> -</itemizedlist> - -<para>Other options may exist for implementing the debug mode, many of - which have probably been considered and others that may still be - lurking. This list may be expanded over time to include other - options that we could have implemented, but in all cases the full - ramifications of the approach (as measured against the design goals - for a libstdc++ debug mode) should be considered first. The DejaGNU - testsuite includes some testcases that check for known problems with - some solutions (e.g., the <code>using</code> declaration solution - that breaks user specialization), and additional testcases will be - added as we are able to identify other typical problem cases. These - test cases will serve as a benchmark by which we can compare debug - mode implementations.</para> - </sect4> - </sect3> - </sect2> - - <sect2 id="manual.ext.debug_mode.design.other" xreflabel="Other"> - <title>Other Implementations</title> - <para> - </para> -<para> There are several existing implementations of debug modes for C++ - standard library implementations, although none of them directly - supports debugging for programs using libstdc++. The existing - implementations include:</para> -<itemizedlist> - <listitem><para><ulink url="http://www.mathcs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</ulink>: - SafeSTL was the original debugging version of the Standard Template - Library (STL), implemented by Cay S. Horstmann on top of the - Hewlett-Packard STL. Though it inspired much work in this area, it - has not been kept up-to-date for use with modern compilers or C++ - standard library implementations.</para></listitem> - - <listitem><para><ulink url="http://www.stlport.org/">STLport</ulink>: STLport is a free - implementation of the C++ standard library derived from the <ulink url="http://www.sgi.com/tech/stl/">SGI implementation</ulink>, and - ported to many other platforms. It includes a debug mode that uses a - wrapper model (that in some way inspired the libstdc++ debug mode - design), although at the time of this writing the debug mode is - somewhat incomplete and meets only the "Full user recompilation" (2) - recompilation guarantee by requiring the user to link against a - different library in debug mode vs. release mode.</para></listitem> - - <listitem><para><ulink url="http://www.metrowerks.com/mw/default.htm">Metrowerks - CodeWarrior</ulink>: The C++ standard library that ships with Metrowerks - CodeWarrior includes a debug mode. It is a full debug-mode - implementation (including debugging for CodeWarrior extensions) and - is easy to use, although it meets only the "Full recompilation" (1) - recompilation guarantee.</para></listitem> -</itemizedlist> - - </sect2> -</sect1> - -</chapter> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/diagnostics.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/diagnostics.xml deleted file mode 100644 index ebdc6c7a2..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/diagnostics.xml +++ /dev/null @@ -1,130 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.diagnostics" xreflabel="Diagnostics"> -<?dbhtml filename="diagnostics.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Diagnostics - <indexterm><primary>Diagnostics</primary></indexterm> -</title> - -<chapter id="manual.diagnostics.exceptions" xreflabel="Exceptions"> - <?dbhtml filename="exceptions.html"?> - <title>Exceptions</title> - - <sect1 id="manual.diagnostics.exceptions.hierarchy" xreflabel="Exception Classes"> - <title>Exception Classes</title> - <para> - All exception objects are defined in one of the standard header - files: <filename>exception</filename>, - <filename>stdexcept</filename>, <filename>new</filename>, and - <filename>typeinfo</filename>. - </para> - - <para> - The base exception object is <classname>exception</classname>, - located in <filename>exception</filename>. This object has no - <classname>string</classname> member. - </para> - - <para> - Derived from this are several classes that may have a - <classname>string</classname> member: a full hierarchy can be - found in the <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00233.html">source documentation</ulink>. - </para> - - </sect1> - <sect1 id="manual.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions"> - <title>Adding Data to Exceptions</title> - <para> - The standard exception classes carry with them a single string as - data (usually describing what went wrong or where the 'throw' took - place). It's good to remember that you can add your own data to - these exceptions when extending the hierarchy: - </para> - <programlisting> - struct My_Exception : public std::runtime_error - { - public: - My_Exception (const string& whatarg) - : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { } - int errno_at_time_of_throw() const { return e; } - DBID id_of_thing_that_threw() const { return id; } - protected: - int e; - DBID id; // some user-defined type - }; - </programlisting> - - </sect1> - <sect1 id="manual.diagnostics.exceptions.cancellation" xreflabel="Cancellation"> - <title>Cancellation</title> - <para> - </para> - </sect1> -</chapter> - -<chapter id="manual.diagnostics.concept_checking" xreflabel="Concept Checking"> - <title>Concept Checking</title> - <para> - In 1999, SGI added <quote>concept checkers</quote> to their - implementation of the STL: code which checked the template - parameters of instantiated pieces of the STL, in order to insure - that the parameters being used met the requirements of the - standard. For example, the Standard requires that types passed as - template parameters to <classname>vector</classname> be - "Assignable" (which means what you think it means). The - checking was done during compilation, and none of the code was - executed at runtime. - </para> - <para> - Unfortunately, the size of the compiler files grew significantly - as a result. The checking code itself was cumbersome. And bugs - were found in it on more than one occasion. - </para> - <para> - The primary author of the checking code, Jeremy Siek, had already - started work on a replacement implementation. The new code has been - formally reviewed and accepted into - <ulink url="http://www.boost.org/libs/concept_check/concept_check.htm">the - Boost libraries</ulink>, and we are pleased to incorporate it into the - GNU C++ library. - </para> - <para> - The new version imposes a much smaller space overhead on the generated - object file. The checks are also cleaner and easier to read and - understand. - </para> - - <para> - They are off by default for all versions of GCC. - They can be enabled at configure time with - <ulink url="../configopts.html"><literal>--enable-concept-checks</literal></ulink>. - You can enable them on a per-translation-unit basis with - <literal>-D_GLIBCXX_CONCEPT_CHECKS</literal>. - </para> - - <para> - Please note that the upcoming C++ standard has first-class - support for template parameter constraints based on concepts in the core - language. This will obviate the need for the library-simulated concept - checking described above. - </para> - -</chapter> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/evolution.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/evolution.xml deleted file mode 100644 index 19734312f..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/evolution.xml +++ /dev/null @@ -1,452 +0,0 @@ -<sect1 id="appendix.porting.api" xreflabel="api"> -<?dbhtml filename="api.html"?> - -<sect1info> - <keywordset> - <keyword>ISO C++</keyword> - <keyword>api</keyword> - <keyword>evolution</keyword> - <keyword>deprecation</keyword> - <keyword>history</keyword> - </keywordset> -</sect1info> - -<title>API Evolution and Deprecation History</title> - -<para> -A list of user-visible changes, in chronological order -</para> - -<sect2 id="api.rel_300" xreflabel="api.rel_300"> -<title><constant>3.0</constant></title> - - <para> -Extensions moved to <filename class="directory">include/ext</filename>. - </para> - -<para> -Include files from the SGI/HP sources that pre-date the ISO standard -are added. These files are placed into -the <filename class="directory">include/backward</filename> directory and a deprecated warning -is added that notifies on inclusion (<literal>-Wno-deprecated</literal> -deactivates the warning.) -</para> - -<para>Deprecated include <filename class="headerfile">backward/strstream</filename> added.</para> - -<para>Removal of include <filename class="headerfile">builtinbuf.h</filename>, <filename class="headerfile">indstream.h</filename>, <filename class="headerfile">parsestream.h</filename>, <filename class="headerfile">PlotFile.h</filename>, <filename class="headerfile">SFile.h</filename>, <filename class="headerfile">stdiostream.h</filename>, and <filename class="headerfile">stream.h</filename>. -</para> - - - -</sect2> - -<sect2 id="api.rel_310" xreflabel="api.rel_310"> -<title><constant>3.1</constant></title> - <para> - </para> - -<para> -Extensions from SGI/HP moved from <code>namespace std</code> -to <code>namespace __gnu_cxx</code>. As part of this, the following -new includes are -added: <filename class="headerfile">ext/algorithm</filename>, <filename class="headerfile">ext/functional</filename>, <filename class="headerfile">ext/iterator</filename>, <filename class="headerfile">ext/memory</filename>, and <filename class="headerfile">ext/numeric</filename>. -</para> - -<para> -Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>. -</para> - -<para> -Extensions to tree data structures added in <filename class="headerfile">ext/rb_tree</filename>. -</para> - -<para> -Removal of <filename class="headerfile">ext/tree</filename>, moved to <filename class="headerfile">backward/tree.h</filename>. -</para> - -</sect2> - -<sect2 id="api.rel_320" xreflabel="api.rel_320"> -<title><constant>3.2</constant></title> - <para> - </para> -<para>Symbol versioning introduced for shared library.</para> - -<para>Removal of include <filename class="headerfile">backward/strstream.h</filename>.</para> - -<para>Allocator changes. Change <code>__malloc_alloc</code> to <code>malloc_allocator</code> and <code>__new_alloc</code> to <code>new_allocator</code>. </para> - - <para> For GCC releases from 2.95 through the 3.1 series, defining - <literal>__USE_MALLOC</literal> on the gcc command line would change the - default allocation strategy to instead use <code> malloc</code> and - <function>free</function>. See - <ulink url="../23_containers/howto.html#3">this note</ulink> - for details as to why this was something needing improvement. - </para> - - -<para>Error handling in iostreams cleaned up, made consistent. </para> - - -</sect2> - -<sect2 id="api.rel_330" xreflabel="api.rel_330"> -<title><constant>3.3</constant></title> - <para> - </para> -</sect2> - -<sect2 id="api.rel_340" xreflabel="api.rel_340"> -<title><constant>3.4</constant></title> - <para> - </para> -<para> -Large file support. -</para> - -<para> Extensions for generic characters and <code>char_traits</code> added in <filename class="headerfile">ext/pod_char_traits.h</filename>. -</para> - -<para> -Support for <code>wchar_t</code> specializations of <code>basic_filebuf</code> enhanced to support <code>UTF-8</code> and <code>Unicode</code>, depending on host. More hosts support basic <code>wchar_t</code> functionality. -</para> - -<para> -Support for <code>char_traits</code> beyond builtin types. -</para> - -<para> -Conformant <code>allocator</code> class and usage in containers. As -part of this, the following extensions are -added: <filename class="headerfile">ext/bitmap_allocator.h</filename>, <filename class="headerfile">ext/debug_allocator.h</filename>, <filename class="headerfile">ext/mt_allocator.h</filename>, <filename class="headerfile">ext/malloc_allocator.h</filename>,<filename class="headerfile">ext/new_allocator.h</filename>, <filename class="headerfile">ext/pool_allocator.h</filename>. -</para> - -<para> -This is a change from all previous versions, and may require -source-level changes due to allocator-related changes to structures -names and template parameters, filenames, and file locations. Some, -like <code>__simple_alloc, __allocator, __alloc, </code> and <code> -_Alloc_traits</code> have been removed. -</para> - -<para>Default behavior of <code>std::allocator</code> has changed.</para> - -<para> - Previous versions prior to 3.4 cache allocations in a memory - pool, instead of passing through to call the global allocation - operators (i.e., <classname>__gnu_cxx::pool_allocator</classname>). More - recent versions default to the - simpler <classname>__gnu_cxx::new_allocator</classname>. -</para> - -<para> Previously, all allocators were written to the SGI - style, and all STL containers expected this interface. This - interface had a traits class called <code>_Alloc_traits</code> that - attempted to provide more information for compile-time allocation - selection and optimization. This traits class had another allocator - wrapper, <code>__simple_alloc<T,A></code>, which was a - wrapper around another allocator, A, which itself is an allocator - for instances of T. But wait, there's more: - <code>__allocator<T,A></code> is another adapter. Many of - the provided allocator classes were SGI style: such classes can be - changed to a conforming interface with this wrapper: - <code>__allocator<T, __alloc></code> is thus the same as - <code>allocator<T></code>. - </para> - - <para> The class <classname>allocator</classname> used the typedef - <type>__alloc</type> to select an underlying allocator that - satisfied memory allocation requests. The selection of this - underlying allocator was not user-configurable. - </para> - -<table frame='all'> -<title>Extension Allocators</title> -<tgroup cols='4' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> - - <thead> - <row> - <entry>Allocator (3.4)</entry> - <entry>Header (3.4)</entry> - <entry>Allocator (3.[0-3])</entry> - <entry>Header (3.[0-3])</entry> - </row> - </thead> - - <tbody> - <row> - <entry><classname>__gnu_cxx::new_allocator<T></classname></entry> - <entry><filename class="headerfile">ext/new_allocator.h</filename></entry> - <entry><classname>std::__new_alloc</classname></entry> - <entry><filename class="headerfile">memory</filename></entry> - </row> - <row> - <entry><classname>__gnu_cxx::malloc_allocator<T></classname></entry> - <entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry> - <entry><classname>std::__malloc_alloc_template<int></classname></entry> - <entry><filename class="headerfile">memory</filename></entry> - </row> - <row> - <entry><classname>__gnu_cxx::debug_allocator<T></classname></entry> - <entry><filename class="headerfile">ext/debug_allocator.h</filename></entry> - <entry><classname>std::debug_alloc<T></classname></entry> - <entry><filename class="headerfile">memory</filename></entry> - </row> - <row> - <entry><classname>__gnu_cxx::__pool_alloc<T></classname></entry> - <entry><filename class="headerfile">ext/pool_allocator.h</filename></entry> - <entry><classname>std::__default_alloc_template<bool,int></classname></entry> - <entry><filename class="headerfile">memory</filename></entry> - </row> - <row> - <entry><classname>__gnu_cxx::__mt_alloc<T></classname></entry> - <entry><filename class="headerfile">ext/mt_allocator.h</filename></entry> - <entry> </entry> - <entry> </entry> - </row> - <row> - <entry><classname>__gnu_cxx::bitmap_allocator<T></classname></entry> - <entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry> - <entry> </entry> - <entry> </entry> - </row> - </tbody> -</tgroup> -</table> - - <para> Releases after gcc-3.4 have continued to add to the collection - of available allocators. All of these new allocators are - standard-style. The following table includes details, along with - the first released version of GCC that included the extension allocator. - </para> - -<table frame='all'> -<title>Extension Allocators Continued</title> -<tgroup cols='3' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> - -<thead> - <row> - <entry>Allocator</entry> - <entry>Include</entry> - <entry>Version</entry> - </row> -</thead> - -<tbody> - <row> - <entry><classname>__gnu_cxx::array_allocator<T></classname></entry> - <entry><filename class="headerfile">ext/array_allocator.h</filename></entry> - <entry>4.0.0</entry> - </row> - <row> - <entry><classname>__gnu_cxx::throw_allocator<T></classname></entry> - <entry><filename class="headerfile">ext/throw_allocator.h</filename></entry> - <entry>4.2.0</entry> - </row> -</tbody> -</tgroup> -</table> - - -<para> -Debug mode first appears. -</para> - -<para> -Precompiled header support <acronym>PCH</acronym> support. -</para> - -<para> -Macro guard for changed, from <literal>_GLIBCPP_</literal> to <literal>_GLIBCXX_</literal>. -</para> - -<para> -Extension <filename class="headerfile">ext/stdio_sync_filebuf.h</filename> added. -</para> - -<para> -Extension <filename class="headerfile">ext/demangle.h</filename> added. -</para> - - -</sect2> - -<sect2 id="api.rel_400" xreflabel="api.rel_400"> -<title><constant>4.0</constant></title> - <para> - </para> -<para> -TR1 features first appear. -</para> - -<para> -Extension allocator <filename class="headerfile">ext/array_allocator.h</filename> added. -</para> - -<para> -Extension <code>codecvt</code> specializations moved to <filename class="headerfile">ext/codecvt_specializations.h</filename>. -</para> - -<para> -Removal of <filename class="headerfile">ext/demangle.h</filename>. -</para> - - -</sect2> - -<sect2 id="api.rel_410" xreflabel="api.rel_410"> -<title><constant>4.1</constant></title> - <para> - </para> - - -<para> -Removal of <filename class="headerfile">cassert</filename> from all standard headers: now has to be explicitly included for <code>std::assert</code> calls. -</para> - -<para> Extensions for policy-based data structures first added. New includes, -types, namespace <code>pb_assoc</code>. -</para> - - - -<para> Extensions for typelists added in <filename class="headerfile">ext/typelist.h</filename>. -</para> - -<para> Extension for policy-based <code>basic_string</code> first added: <code>__gnu_cxx::__versa_string</code> in <filename class="headerfile">ext/vstring.h</filename>. -</para> - -</sect2> - -<sect2 id="api.rel_420" xreflabel="api.rel_420"> -<title><constant>4.2</constant></title> - <para> - </para> - - -<para> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>. -</para> - -<para>TR1 <filename class="headerfile">random</filename>, <filename class="headerfile">complex</filename>, and C compatibility headers added.</para> - -<para> Extensions for concurrent programming consolidated -into <filename class="headerfile">ext/concurrence.h</filename> and <filename class="headerfile">ext/atomicity.h</filename>, -including change of namespace to <code>__gnu_cxx</code> in some -cases. Added types -include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</para> - -<para> Extensions for type traits consolidated -into <filename class="headerfile">ext/type_traits.h</filename>. Additional traits are added -(<code>__conditional_type</code>, <code>__enable_if</code>, others.) -</para> - -<para> Extensions for policy-based data structures revised. New includes, -types, namespace moved to <code>__pb_ds</code>. -</para> - -<para> Extensions for debug mode modified: now nested in <code>namespace -std::__debug</code> and extensions in <code>namespace -__gnu_cxx::__debug</code>.</para> - -<para> Extensions added: <filename class="headerfile">ext/typelist.h</filename> -and <filename class="headerfile">ext/throw_allocator.h</filename>. -</para> - -</sect2> - -<sect2 id="api.rel_430" xreflabel="api.rel_430"> -<title><constant>4.3</constant></title> - <para> - </para> - - -<para> -C++0X features first appear. -</para> - -<para>TR1 <filename class="headerfile">regex</filename> and <filename class="headerfile">cmath</filename>'s mathematical special function added.</para> - -<para> -Backward include edit. -</para> -<itemizedlist> - <listitem> - <para>Removed</para> - <para> -<filename class="headerfile">algobase.h</filename> <filename class="headerfile">algo.h</filename> <filename class="headerfile">alloc.h</filename> <filename class="headerfile">bvector.h</filename> <filename class="headerfile">complex.h</filename> -<filename class="headerfile">defalloc.h</filename> <filename class="headerfile">deque.h</filename> <filename class="headerfile">fstream.h</filename> <filename class="headerfile">function.h</filename> <filename class="headerfile">hash_map.h</filename> <filename class="headerfile">hash_set.h</filename> -<filename class="headerfile">hashtable.h</filename> <filename class="headerfile">heap.h</filename> <filename class="headerfile">iomanip.h</filename> <filename class="headerfile">iostream.h</filename> <filename class="headerfile">istream.h</filename> <filename class="headerfile">iterator.h</filename> -<filename class="headerfile">list.h</filename> <filename class="headerfile">map.h</filename> <filename class="headerfile">multimap.h</filename> <filename class="headerfile">multiset.h</filename> <filename class="headerfile">new.h</filename> <filename class="headerfile">ostream.h</filename> <filename class="headerfile">pair.h</filename> <filename class="headerfile">queue.h</filename> <filename class="headerfile">rope.h</filename> <filename class="headerfile">set.h</filename> <filename class="headerfile">slist.h</filename> <filename class="headerfile">stack.h</filename> <filename class="headerfile">streambuf.h</filename> <filename class="headerfile">stream.h</filename> <filename class="headerfile">tempbuf.h</filename> -<filename class="headerfile">tree.h</filename> <filename class="headerfile">vector.h</filename> - </para> - </listitem> - <listitem> - <para>Added</para> - <para> - <filename class="headerfile">hash_map</filename> and <filename class="headerfile">hash_set</filename> - </para> - </listitem> - <listitem> - <para>Added in C++0x</para> - <para> - <filename class="headerfile">auto_ptr.h</filename> and <filename class="headerfile">binders.h</filename> - </para> - </listitem> - -</itemizedlist> - -<para> -Header dependency streamlining. -</para> - -<itemizedlist> - <listitem><para><filename class="headerfile">algorithm</filename> no longer includes <filename class="headerfile">climits</filename>, <filename class="headerfile">cstring</filename>, or <filename class="headerfile">iosfwd</filename> </para></listitem> - <listitem><para><filename class="headerfile">bitset</filename> no longer includes <filename class="headerfile">istream</filename> or <filename class="headerfile">ostream</filename>, adds <filename class="headerfile">iosfwd</filename> </para></listitem> - <listitem><para><filename class="headerfile">functional</filename> no longer includes <filename class="headerfile">cstddef</filename></para></listitem> - <listitem><para><filename class="headerfile">iomanip</filename> no longer includes <filename class="headerfile">istream</filename>, <filename class="headerfile">istream</filename>, or <filename class="headerfile">functional</filename>, adds <filename class="headerfile">ioswd</filename> </para></listitem> - <listitem><para><filename class="headerfile">numeric</filename> no longer includes <filename class="headerfile">iterator</filename></para></listitem> - <listitem><para><filename class="headerfile">string</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">memory</filename></para></listitem> - - <listitem><para><filename class="headerfile">valarray</filename> no longer includes <filename class="headerfile">numeric</filename> or <filename class="headerfile">cstdlib</filename></para></listitem> - <listitem><para><filename class="headerfile">tr1/hashtable</filename> no longer includes <filename class="headerfile">memory</filename> or <filename class="headerfile">functional</filename></para></listitem> - <listitem><para><filename class="headerfile">tr1/memory</filename> no longer includes <filename class="headerfile">algorithm</filename></para></listitem> - <listitem><para><filename class="headerfile">tr1/random</filename> no longer includes <filename class="headerfile">algorithm</filename> or <filename class="headerfile">fstream</filename></para></listitem> -</itemizedlist> - -<para> -Debug mode for <filename class="headerfile">unordered_map</filename> and <filename class="headerfile">unordered_set</filename>. -</para> - -<para> -Parallel mode first appears. -</para> - -<para>Variadic template implementations of items in <filename class="headerfile">tuple</filename> and - <filename class="headerfile">functional</filename>. -</para> - -<para>Default <code>what</code> implementations give more elaborate - exception strings for <code>bad_cast</code>, - <code>bad_typeid</code>, <code>bad_exception</code>, and - <code>bad_alloc</code>. -</para> - -<para> -PCH binary files no longer installed. Instead, the source files are installed. -</para> - -<para> -Namespace pb_ds moved to __gnu_pb_ds. -</para> - -</sect2> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/extensions.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/extensions.xml deleted file mode 100644 index a0e75ccbb..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/extensions.xml +++ /dev/null @@ -1,589 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.ext" xreflabel="Extensions"> -<?dbhtml filename="extensions.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Extensions - <indexterm><primary>Extensions</primary></indexterm> -</title> - -<preface> - <title></title> -<para> - Here we will make an attempt at describing the non-Standard extensions to - the library. Some of these are from SGI's STL, some of these are GNU's, - and some just seemed to appear on the doorstep. -</para> -<para><emphasis>Before</emphasis> you leap in and use any of these -extensions, be aware of two things: -</para> -<orderedlist> - <listitem> - <para> - Non-Standard means exactly that. - </para> - <para> - The behavior, and the very - existence, of these extensions may change with little or no - warning. (Ideally, the really good ones will appear in the next - revision of C++.) Also, other platforms, other compilers, other - versions of g++ or libstdc++ may not recognize these names, or - treat them differently, or... - </para> - </listitem> - <listitem> - <para> - You should know how to <ulink url="XXX">access - these headers properly</ulink>. - </para> - </listitem> -</orderedlist> -</preface> - -<!-- Chapter 01 : Compile Time Checks --> -<chapter id="manual.ext.compile_checks" xreflabel="Compile Time Checks"> -<?dbhtml filename="ext_compile_checks.html"?> - <title>Compile Time Checks</title> - <para> - Also known as concept checking. - </para> - <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation - of the STL: code which checked the template parameters of - instantiated pieces of the STL, in order to insure that the parameters - being used met the requirements of the standard. For example, - the Standard requires that types passed as template parameters to - <code>vector</code> be <quote>Assignable</quote> (which means what you think - it means). The checking was done during compilation, and none of - the code was executed at runtime. - </para> - <para>Unfortunately, the size of the compiler files grew significantly - as a result. The checking code itself was cumbersome. And bugs - were found in it on more than one occasion. - </para> - <para>The primary author of the checking code, Jeremy Siek, had already - started work on a replacement implementation. The new code has been - formally reviewed and accepted into - <ulink url="http://www.boost.org/libs/concept_check/concept_check.htm">the - Boost libraries</ulink>, and we are pleased to incorporate it into the - GNU C++ library. - </para> - <para>The new version imposes a much smaller space overhead on the generated - object file. The checks are also cleaner and easier to read and - understand. - </para> - <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the - latest release at the time of writing). - They can be enabled at configure time with - <ulink url="../configopts.html"><literal>--enable-concept-checks</literal></ulink>. - You can enable them on a per-translation-unit basis with - <code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher - (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions - 3.1, 3.2 and 3.3). - </para> - - <para>Please note that the upcoming C++ standard has first-class - support for template parameter constraints based on concepts in the core - language. This will obviate the need for the library-simulated concept - checking described above. - </para> - -</chapter> - -<!-- Chapter 02 : Debug Mode --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="debug_mode.xml"> -</xi:include> - -<!-- Chapter 03 : Parallel Mode --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="parallel_mode.xml"> -</xi:include> - -<!-- Chapter 04 : Allocators --> -<chapter id="manual.ext.allocator" xreflabel="Allocators"> -<?dbhtml filename="ext_allocators.html"?> - <title>Allocators</title> - - <!-- Section 01 : __mt_alloc --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="mt_allocator.xml"> - </xi:include> - - <!-- Section 02 : bitmap_allocator --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="bitmap_allocator.xml"> - </xi:include> - -</chapter> - -<!-- Chapter 05 : Containers --> -<chapter id="manual.ext.containers" xreflabel="Containers"> -<?dbhtml filename="ext_containers.html"?> - <title>Containers</title> - <para> - </para> - <sect1 id="manual.ext.containers.pbds" xreflabel="Policy Based Data Structures"> - <title>Policy Based Data Structures</title> - <para> - <ulink - url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here</ulink>. - </para> - </sect1> - - <sect1 id="manual.ext.containers.sgi" xreflabel="SGI ext"> - <title>HP/SGI</title> - <para> - </para> - -<para>A few extensions and nods to backwards-compatibility have been made with - containers. Those dealing with older SGI-style allocators are dealt with - elsewhere. The remaining ones all deal with bits: -</para> -<para>The old pre-standard <code>bit_vector</code> class is present for - backwards compatibility. It is simply a typedef for the - <code>vector<bool></code> specialization. -</para> -<para>The <code>bitset</code> class has a number of extensions, described in the - rest of this item. First, we'll mention that this implementation of - <code>bitset<N></code> is specialized for cases where N number of - bits will fit into a single word of storage. If your choice of N is - within that range (<=32 on i686-pc-linux-gnu, for example), then all - of the operations will be faster. -</para> -<para>There are - versions of single-bit test, set, reset, and flip member functions which - do no range-checking. If we call them member functions of an instantiation - of "bitset<N>," then their names and signatures are: -</para> - <programlisting> - bitset<N>& _Unchecked_set (size_t pos); - bitset<N>& _Unchecked_set (size_t pos, int val); - bitset<N>& _Unchecked_reset (size_t pos); - bitset<N>& _Unchecked_flip (size_t pos); - bool _Unchecked_test (size_t pos); - </programlisting> - <para>Note that these may in fact be removed in the future, although we have - no present plans to do so (and there doesn't seem to be any immediate - reason to). -</para> -<para>The semantics of member function <code>operator[]</code> are not specified - in the C++ standard. A long-standing defect report calls for sensible - obvious semantics, which are already implemented here: <code>op[]</code> - on a const bitset returns a bool, and for a non-const bitset returns a - <code>reference</code> (a nested type). However, this implementation does - no range-checking on the index argument, which is in keeping with other - containers' <code>op[]</code> requirements. The defect report's proposed - resolution calls for range-checking to be done. We'll just wait and see... -</para> -<para>Finally, two additional searching functions have been added. They return - the index of the first "on" bit, and the index of the first - "on" bit that is after <code>prev</code>, respectively: -</para> - <programlisting> - size_t _Find_first() const; - size_t _Find_next (size_t prev) const;</programlisting> -<para>The same caveat given for the _Unchecked_* functions applies here also. -</para> - </sect1> - - - <sect1 id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"> - <title>Deprecated HP/SGI</title> - - <para> - The SGI hashing classes <classname>hash_set</classname> and - <classname>hash_set</classname> have been deprecated by the - unordered_set, unordered_multiset, unordered_map, - unordered_multimap containers in TR1 and the upcoming C++0x, and - may be removed in future releases. - </para> - - <para>The SGI headers</para> - <programlisting> - <hash_map> - <hash_set> - <rope> - <slist> - <rb_tree> - </programlisting> - <para>are all here; - <code><hash_map></code> and <code><hash_set></code> - are deprecated but available as backwards-compatible extensions, - as discussed further below. <code><rope></code> is the - SGI specialization for large strings ("rope," - "large strings," get it? Love that geeky humor.) - <code><slist></code> is a singly-linked list, for when the - doubly-linked <code>list<></code> is too much space - overhead, and <code><rb_tree></code> exposes the red-black - tree classes used in the implementation of the standard maps and - sets. - </para> - <para>Each of the associative containers map, multimap, set, and multiset - have a counterpart which uses a - <ulink url="http://www.sgi.com/tech/stl/HashFunction.html">hashing - function</ulink> to do the arranging, instead of a strict weak ordering - function. The classes take as one of their template parameters a - function object that will return the hash value; by default, an - instantiation of - <ulink url="http://www.sgi.com/tech/stl/hash.html">hash</ulink>. - You should specialize this functor for your class, or define your own, - before trying to use one of the hashing classes. - </para> - <para>The hashing classes support all the usual associative container - functions, as well as some extra constructors specifying the number - of buckets, etc. - </para> - <para>Why would you want to use a hashing class instead of the - <quote>normal</quote>implementations? Matt Austern writes: - </para> - <blockquote> - <para> - <emphasis>[W]ith a well chosen hash function, hash tables - generally provide much better average-case performance than - binary search trees, and much worse worst-case performance. So - if your implementation has hash_map, if you don't mind using - nonstandard components, and if you aren't scared about the - possibility of pathological cases, you'll probably get better - performance from hash_map. - </emphasis> - </para> - </blockquote> - - </sect1> -</chapter> - -<!-- Chapter 06 : Utilities --> -<chapter id="manual.ext.util" xreflabel="Utilities"> -<?dbhtml filename="ext_utilities.html"?> - <title>Utilities</title> - <para> - The <functional> header contains many additional functors - and helper functions, extending section 20.3. They are - implemented in the file stl_function.h: - </para> - <itemizedlist> - <listitem> - <para><code>identity_element</code> for addition and multiplication. * - </para> - </listitem> - <listitem> - <para>The functor <code>identity</code>, whose <code>operator()</code> - returns the argument unchanged. * - </para> - </listitem> - <listitem> - <para>Composition functors <code>unary_function</code> and - <code>binary_function</code>, and their helpers <code>compose1</code> - and <code>compose2</code>. * - </para> - </listitem> - <listitem> - <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. * - </para> - </listitem> - <listitem><para><code>project1st</code> and <code>project2nd</code>. * </para></listitem> - <listitem><para>A set of functors/functions which always return the same result. They - are <code>constant_void_fun</code>, <code>constant_binary_fun</code>, - <code>constant_unary_fun</code>, <code>constant0</code>, - <code>constant1</code>, and <code>constant2</code>. * </para></listitem> - <listitem><para>The class <code>subtractive_rng</code>. * </para></listitem> - <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and - <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem> -</itemizedlist> -<para> - 20.4.1 can use several different allocators; they are described on the - main extensions page. -</para> -<para> - 20.4.3 is extended with a special version of - <code>get_temporary_buffer</code> taking a second argument. The - argument is a pointer, which is ignored, but can be used to specify - the template type (instead of using explicit function template - arguments like the standard version does). That is, in addition to -</para> -<programlisting> -get_temporary_buffer<int>(5); -</programlisting> - -<para> -you can also use -</para> - -<programlisting> -get_temporary_buffer(5, (int*)0); -</programlisting> -<para> - A class <code>temporary_buffer</code> is given in stl_tempbuf.h. * -</para> -<para> - The specialized algorithms of section 20.4.4 are extended with - <code>uninitialized_copy_n</code>. * -</para> - -</chapter> - -<!-- Chapter 07 : Algorithms --> -<chapter id="manual.ext.algorithms" xreflabel="Algorithms"> -<?dbhtml filename="ext_algorithms.html"?> - <title>Algorithms</title> -<para>25.1.6 (count, count_if) is extended with two more versions of count - and count_if. The standard versions return their results. The - additional signatures return void, but take a final parameter by - reference to which they assign their results, e.g., -</para> - <programlisting> - void count (first, last, value, n);</programlisting> -<para>25.2 (mutating algorithms) is extended with two families of signatures, - random_sample and random_sample_n. -</para> -<para>25.2.1 (copy) is extended with -</para> - <programlisting> - copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting> -<para>which copies the first 'count' elements at 'first' into 'result'. -</para> -<para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper - predicates. Look in the doxygen-generated pages for notes on these. -</para> - <itemizedlist> - <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem> - <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in - nondescending order.</para></listitem> - </itemizedlist> -<para>25.3.8 (lexicographical_compare) is extended with -</para> - <programlisting> - lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, - _InputIter2 first2, _InputIter2 last2)</programlisting> -<para>which does... what? -</para> - -</chapter> - -<!-- Chapter 08 : Numerics --> -<chapter id="manual.ext.numerics" xreflabel="Numerics"> -<?dbhtml filename="ext_numerics.html"?> - <title>Numerics</title> -<para>26.4, the generalized numeric operations such as accumulate, are extended - with the following functions: -</para> - <programlisting> - power (x, n); - power (x, n, moniod_operation);</programlisting> -<para>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the - case of n == 0, returns the <ulink url="#ch20">identity element</ulink> for the - monoid operation. The two-argument signature uses multiplication (for - a true "power" implementation), but addition is supported as well. - The operation functor must be associative. -</para> -<para>The <code>iota</code> function wins the award for Extension With the - Coolest Name. It "assigns sequentially increasing values to a range. - That is, it assigns value to *first, value + 1 to *(first + 1) and so - on." Quoted from SGI documentation. -</para> - <programlisting> - void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting> -</chapter> - -<!-- Chapter 09 : Iterators --> -<chapter id="manual.ext.iterators" xreflabel="Iterators"> -<?dbhtml filename="ext_iterators.html"?> - <title>Iterators</title> -<para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the - original HP STL implementation (the language wasn't rich enough at the - time). For backwards compatibility, base classes are provided which - declare the same nested typedefs: -</para> - <itemizedlist> - <listitem><para>input_iterator</para></listitem> - <listitem><para>output_iterator</para></listitem> - <listitem><para>forward_iterator</para></listitem> - <listitem><para>bidirectional_iterator</para></listitem> - <listitem><para>random_access_iterator</para></listitem> - </itemizedlist> -<para>24.3.4 describes iterator operation <code>distance</code>, which takes - two iterators and returns a result. It is extended by another signature - which takes two iterators and a reference to a result. The result is - modified, and the function returns nothing. -</para> - -</chapter> - -<!-- Chapter 08 : IO --> -<chapter id="manual.ext.io" xreflabel="IO"> -<?dbhtml filename="ext_io.html"?> - <title>Input and Output</title> - - <para> - Extensions allowing <code>filebuf</code>s to be constructed from - "C" types like FILE*s and file descriptors. - </para> - - <sect1 id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"> - <title>Derived filebufs</title> - - <para>The v2 library included non-standard extensions to construct - <code>std::filebuf</code>s from C stdio types such as - <code>FILE*</code>s and POSIX file descriptors. - Today the recommended way to use stdio types with libstdc++ - IOStreams is via the <code>stdio_filebuf</code> class (see below), - but earlier releases provided slightly different mechanisms. - </para> - <itemizedlist> - <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature: - <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type); - </code> - This comes in very handy in a number of places, such as - attaching Unix sockets, pipes, and anything else which uses file - descriptors, into the IOStream buffering classes. The three - arguments are as follows: - <itemizedlist> - <listitem><para><code>__c_file_type* F </code> - // the __c_file_type typedef usually boils down to stdio's FILE - </para></listitem> - <listitem><para><code>ios_base::openmode M </code> - // same as all the other uses of openmode - </para></listitem> - <listitem><para><code>int_type B </code> - // buffer size, defaults to BUFSIZ if not specified - </para></listitem> - </itemizedlist> - For those wanting to use file descriptors instead of FILE*'s, I - invite you to contemplate the mysteries of C's <code>fdopen()</code>. - </para></listitem> - <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring - back an old extension: the <code>fd()</code> member function. The - integer returned from this function can be used for whatever file - descriptors can be used for on your platform. Naturally, the - library cannot track what you do on your own with a file descriptor, - so if you perform any I/O directly, don't expect the library to be - aware of it. - </para></listitem> - <listitem><para>Beginning with 3.1, the extra <code>filebuf</code> constructor and - the <code>fd()</code> function were removed from the standard - filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains - a derived class called - <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></ulink>. - This class can be constructed from a C <code>FILE*</code> or a file - descriptor, and provides the <code>fd()</code> function. - </para></listitem> - </itemizedlist> - <para>If you want to access a <code>filebuf</code>'s file descriptor to - implement file locking (e.g. using the <code>fcntl()</code> system - call) then you might be interested in Henry Suter's - <ulink url="http://suter.home.cern.ch/suter/RWLock.html">RWLock</ulink> - class. - </para> - - <para> - </para> - </sect1> -</chapter> - -<!-- Chapter 09 : Demangling --> -<chapter id="manual.ext.demangle" xreflabel="Demangling"> -<?dbhtml filename="ext_demangling.html"?> - <title>Demangling</title> - <para> - Transforming C++ ABI identifiers (like RTTI symbols) into the - original C++ source identifiers is called - <quote>demangling.</quote> - </para> - <para> - If you have read the <ulink - url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaceabi.html">source - documentation for <code>namespace abi</code></ulink> then you are - aware of the cross-vendor C++ ABI in use by GCC. One of the - exposed functions is used for demangling, - <code>abi::__cxa_demangle</code>. - </para> - <para> - In programs like <command>c++filt</command>, the linker, and other tools - have the ability to decode C++ ABI names, and now so can you. - </para> - <para> - (The function itself might use different demanglers, but that's the - whole point of abstract interfaces. If we change the implementation, - you won't notice.) - </para> - <para> - Probably the only times you'll be interested in demangling at runtime - are when you're seeing <code>typeid</code> strings in RTTI, or when - you're handling the runtime-support exception classes. For example: - </para> - <programlisting> -#include <exception> -#include <iostream> -#include <cxxabi.h> - -struct empty { }; - -template <typename T, int N> - struct bar { }; - - -int main() -{ - int status; - char *realname; - - // exception classes not in <stdexcept>, thrown by the implementation - // instead of the user - std::bad_exception e; - realname = abi::__cxa_demangle(e.what(), 0, 0, &status); - std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; - free(realname); - - - // typeid - bar<empty,17> u; - const std::type_info &ti = typeid(u); - - realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); - std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; - free(realname); - - return 0; -} - </programlisting> - <para> - This prints - </para> - - <screen> - <computeroutput> - St13bad_exception => std::bad_exception : 0 - 3barI5emptyLi17EE => bar<empty, 17> : 0 - </computeroutput> - </screen> - - <para> - The demangler interface is described in the source documentation - linked to above. It is actually written in C, so you don't need to - be writing C++ in order to demangle C++. (That also means we have to - use crummy memory management facilities, so don't forget to free() - the returned char array.) - </para> -</chapter> - -<!-- Chapter 10 : Concurrency --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="concurrency.xml"> -</xi:include> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/internals.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/internals.xml deleted file mode 100644 index ccde22791..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/internals.xml +++ /dev/null @@ -1,548 +0,0 @@ -<sect1 id="appendix.porting.internals" xreflabel="internals"> -<?dbhtml filename="internals.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - internals - </keyword> - </keywordset> -</sect1info> - -<title>Porting to New Hardware or Operating Systems</title> - -<para> -</para> - - -<para>This document explains how to port libstdc++ (the GNU C++ library) to -a new target. -</para> - - <para>In order to make the GNU C++ library (libstdc++) work with a new -target, you must edit some configuration files and provide some new -header files. Unless this is done, libstdc++ will use generic -settings which may not be correct for your target; even if they are -correct, they will likely be inefficient. - </para> - - <para>Before you get started, make sure that you have a working C library on -your target. The C library need not precisely comply with any -particular standard, but should generally conform to the requirements -imposed by the ANSI/ISO standard. - </para> - - <para>In addition, you should try to verify that the C++ compiler generally -works. It is difficult to test the C++ compiler without a working -library, but you should at least try some minimal test cases. - </para> - - <para>(Note that what we think of as a "target," the library refers to as -a "host." The comment at the top of <code>configure.ac</code> explains why.) - </para> - - -<sect2 id="internals.os" xreflabel="internals.os"> -<title>Operating System</title> - -<para>If you are porting to a new operating system (as opposed to a new chip -using an existing operating system), you will need to create a new -directory in the <code>config/os</code> hierarchy. For example, the IRIX -configuration files are all in <code>config/os/irix</code>. There is no set -way to organize the OS configuration directory. For example, -<code>config/os/solaris/solaris-2.6</code> and -<code>config/os/solaris/solaris-2.7</code> are used as configuration -directories for these two versions of Solaris. On the other hand, both -Solaris 2.7 and Solaris 2.8 use the <code>config/os/solaris/solaris-2.7</code> -directory. The important information is that there needs to be a -directory under <code>config/os</code> to store the files for your operating -system. -</para> - - <para>You might have to change the <code>configure.host</code> file to ensure that -your new directory is activated. Look for the switch statement that sets -<code>os_include_dir</code>, and add a pattern to handle your operating system -if the default will not suffice. The switch statement switches on only -the OS portion of the standard target triplet; e.g., the <code>solaris2.8</code> -in <code>sparc-sun-solaris2.8</code>. If the new directory is named after the -OS portion of the triplet (the default), then nothing needs to be changed. - </para> - - <para>The first file to create in this directory, should be called -<code>os_defines.h</code>. This file contains basic macro definitions -that are required to allow the C++ library to work with your C library. - </para> - - <para>Several libstdc++ source files unconditionally define the macro -<code>_POSIX_SOURCE</code>. On many systems, defining this macro causes -large portions of the C library header files to be eliminated -at preprocessing time. Therefore, you may have to <code>#undef</code> this -macro, or define other macros (like <code>_LARGEFILE_SOURCE</code> or -<code>__EXTENSIONS__</code>). You won't know what macros to define or -undefine at this point; you'll have to try compiling the library and -seeing what goes wrong. If you see errors about calling functions -that have not been declared, look in your C library headers to see if -the functions are declared there, and then figure out what macros you -need to define. You will need to add them to the -<code>CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your -target. It will not work to simply define these macros in -<code>os_defines.h</code>. - </para> - - <para>At this time, there are a few libstdc++-specific macros which may be -defined: - </para> - - <para><code>_GLIBCXX_USE_C99_CHECK</code> may be defined to 1 to check C99 -function declarations (which are not covered by specialization below) -found in system headers against versions found in the library headers -derived from the standard. - </para> - - <para><code>_GLIBCXX_USE_C99_DYNAMIC</code> may be defined to an expression that -yields 0 if and only if the system headers are exposing proper support -for C99 functions (which are not covered by specialization below). If -defined, it must be 0 while bootstrapping the compiler/rebuilding the -library. - </para> - - <para><code>_GLIBCXX_USE_C99_LONG_LONG_CHECK</code> may be defined to 1 to check -the set of C99 long long function declarations found in system headers -against versions found in the library headers derived from the -standard. - - </para> - <para><code>_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC</code> may be defined to an -expression that yields 0 if and only if the system headers are -exposing proper support for the set of C99 long long functions. If -defined, it must be 0 while bootstrapping the compiler/rebuilding the -library. - </para> - <para><code>_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC</code> may be defined to an -expression that yields 0 if and only if the system headers -are exposing proper support for the related set of macros. If defined, -it must be 0 while bootstrapping the compiler/rebuilding the library. - </para> - <para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK</code> may be defined -to 1 to check the related set of function declarations found in system -headers against versions found in the library headers derived from -the standard. - </para> - <para><code>_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC</code> may be defined -to an expression that yields 0 if and only if the system headers -are exposing proper support for the related set of functions. If defined, -it must be 0 while bootstrapping the compiler/rebuilding the library. - </para> - <para>Finally, you should bracket the entire file in an include-guard, like -this: - </para> - -<programlisting> - -#ifndef _GLIBCXX_OS_DEFINES -#define _GLIBCXX_OS_DEFINES -... -#endif -</programlisting> - - <para>We recommend copying an existing <code>os_defines.h</code> to use as a -starting point. - </para> -</sect2> - - -<sect2 id="internals.cpu" xreflabel="internals.cpu"> -<title>CPU</title> - -<para>If you are porting to a new chip (as opposed to a new operating system -running on an existing chip), you will need to create a new directory in the -<code>config/cpu</code> hierarchy. Much like the <link linkend="internals.os">Operating system</link> setup, -there are no strict rules on how to organize the CPU configuration -directory, but careful naming choices will allow the configury to find your -setup files without explicit help. -</para> - - <para>We recommend that for a target triplet <code><CPU>-<vendor>-<OS></code>, you -name your configuration directory <code>config/cpu/<CPU></code>. If you do this, -the configury will find the directory by itself. Otherwise you will need to -edit the <code>configure.host</code> file and, in the switch statement that sets -<code>cpu_include_dir</code>, add a pattern to handle your chip. - </para> - - <para>Note that some chip families share a single configuration directory, for -example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the -<code>config/cpu/alpha</code> directory, and there is an entry in the -<code>configure.host</code> switch statement to handle this. - </para> - - <para>The <code>cpu_include_dir</code> sets default locations for the files controlling -<link linkend="internals.thread_safety">Thread safety</link> and <link linkend="internals.numeric_limits">Numeric limits</link>, if the defaults are not -appropriate for your chip. - </para> - -</sect2> - - -<sect2 id="internals.char_types" xreflabel="internals.char_types"> -<title>Character Types</title> - -<para>The library requires that you provide three header files to implement -character classification, analogous to that provided by the C libraries -<code><ctype.h></code> header. You can model these on the files provided in -<code>config/os/generic</code>. However, these files will almost -certainly need some modification. -</para> - - <para>The first file to write is <code>ctype_base.h</code>. This file provides -some very basic information about character classification. The libstdc++ -library assumes that your C library implements <code><ctype.h></code> by using -a table (indexed by character code) containing integers, where each of -these integers is a bit-mask indicating whether the character is -upper-case, lower-case, alphabetic, etc. The <code>ctype_base.h</code> -file gives the type of the integer, and the values of the various bit -masks. You will have to peer at your own <code><ctype.h></code> to figure out -how to define the values required by this file. - </para> - - <para>The <code>ctype_base.h</code> header file does not need include guards. -It should contain a single <code>struct</code> definition called -<code>ctype_base</code>. This <code>struct</code> should contain two type -declarations, and one enumeration declaration, like this example, taken -from the IRIX configuration: - </para> - -<programlisting> - struct ctype_base - { - typedef unsigned int mask; - typedef int* __to_type; - - enum - { - space = _ISspace, - print = _ISprint, - cntrl = _IScntrl, - upper = _ISupper, - lower = _ISlower, - alpha = _ISalpha, - digit = _ISdigit, - punct = _ISpunct, - xdigit = _ISxdigit, - alnum = _ISalnum, - graph = _ISgraph - }; - }; -</programlisting> - -<para>The <code>mask</code> type is the type of the elements in the table. If your -C library uses a table to map lower-case numbers to upper-case numbers, -and vice versa, you should define <code>__to_type</code> to be the type of the -elements in that table. If you don't mind taking a minor performance -penalty, or if your library doesn't implement <code>toupper</code> and -<code>tolower</code> in this way, you can pick any pointer-to-integer type, -but you must still define the type. -</para> - - <para>The enumeration should give definitions for all the values in the above -example, using the values from your native <code><ctype.h></code>. They can -be given symbolically (as above), or numerically, if you prefer. You do -not have to include <code><ctype.h></code> in this header; it will always be -included before <code>ctype_base.h</code> is included. - </para> - - <para>The next file to write is <code>ctype_noninline.h</code>, which also does -not require include guards. This file defines a few member functions -that will be included in <code>include/bits/locale_facets.h</code>. The first -function that must be written is the <code>ctype<char>::ctype</code> -constructor. Here is the IRIX example: - </para> - -<programlisting> -ctype<char>::ctype(const mask* __table = 0, bool __del = false, - size_t __refs = 0) - : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del), - _M_toupper(NULL), - _M_tolower(NULL), - _M_ctable(NULL), - _M_table(!__table - ? (const mask*) (__libc_attr._ctype_tbl->_class + 1) - : __table) - { } -</programlisting> - -<para>There are two parts of this that you might choose to alter. The first, -and most important, is the line involving <code>__libc_attr</code>. That is -IRIX system-dependent code that gets the base of the table mapping -character codes to attributes. You need to substitute code that obtains -the address of this table on your system. If you want to use your -operating system's tables to map upper-case letters to lower-case, and -vice versa, you should initialize <code>_M_toupper</code> and -<code>_M_tolower</code> with those tables, in similar fashion. -</para> - - <para>Now, you have to write two functions to convert from upper-case to -lower-case, and vice versa. Here are the IRIX versions: - </para> - -<programlisting> - char - ctype<char>::do_toupper(char __c) const - { return _toupper(__c); } - - char - ctype<char>::do_tolower(char __c) const - { return _tolower(__c); } -</programlisting> - -<para>Your C library provides equivalents to IRIX's <code>_toupper</code> and -<code>_tolower</code>. If you initialized <code>_M_toupper</code> and -<code>_M_tolower</code> above, then you could use those tables instead. -</para> - - <para>Finally, you have to provide two utility functions that convert strings -of characters. The versions provided here will always work - but you -could use specialized routines for greater performance if you have -machinery to do that on your system: - </para> - -<programlisting> - const char* - ctype<char>::do_toupper(char* __low, const char* __high) const - { - while (__low < __high) - { - *__low = do_toupper(*__low); - ++__low; - } - return __high; - } - - const char* - ctype<char>::do_tolower(char* __low, const char* __high) const - { - while (__low < __high) - { - *__low = do_tolower(*__low); - ++__low; - } - return __high; - } -</programlisting> - - <para>You must also provide the <code>ctype_inline.h</code> file, which -contains a few more functions. On most systems, you can just copy -<code>config/os/generic/ctype_inline.h</code> and use it on your system. - </para> - - <para>In detail, the functions provided test characters for particular -properties; they are analogous to the functions like <code>isalpha</code> and -<code>islower</code> provided by the C library. - </para> - - <para>The first function is implemented like this on IRIX: - </para> - -<programlisting> - bool - ctype<char>:: - is(mask __m, char __c) const throw() - { return (_M_table)[(unsigned char)(__c)] & __m; } -</programlisting> - -<para>The <code>_M_table</code> is the table passed in above, in the constructor. -This is the table that contains the bitmasks for each character. The -implementation here should work on all systems. -</para> - - <para>The next function is: - </para> - -<programlisting> - const char* - ctype<char>:: - is(const char* __low, const char* __high, mask* __vec) const throw() - { - while (__low < __high) - *__vec++ = (_M_table)[(unsigned char)(*__low++)]; - return __high; - } -</programlisting> - -<para>This function is similar; it copies the masks for all the characters -from <code>__low</code> up until <code>__high</code> into the vector given by -<code>__vec</code>. -</para> - - <para>The last two functions again are entirely generic: - </para> - -<programlisting> - const char* - ctype<char>:: - scan_is(mask __m, const char* __low, const char* __high) const throw() - { - while (__low < __high && !this->is(__m, *__low)) - ++__low; - return __low; - } - - const char* - ctype<char>:: - scan_not(mask __m, const char* __low, const char* __high) const throw() - { - while (__low < __high && this->is(__m, *__low)) - ++__low; - return __low; - } -</programlisting> - -</sect2> - - -<sect2 id="internals.thread_safety" xreflabel="internals.thread_safety"> -<title>Thread Safety</title> - -<para>The C++ library string functionality requires a couple of atomic -operations to provide thread-safety. If you don't take any special -action, the library will use stub versions of these functions that are -not thread-safe. They will work fine, unless your applications are -multi-threaded. -</para> - - <para>If you want to provide custom, safe, versions of these functions, there -are two distinct approaches. One is to provide a version for your CPU, -using assembly language constructs. The other is to use the -thread-safety primitives in your operating system. In either case, you -make a file called <code>atomicity.h</code>, and the variable -<code>ATOMICITYH</code> must point to this file. - </para> - - <para>If you are using the assembly-language approach, put this code in -<code>config/cpu/<chip>/atomicity.h</code>, where chip is the name of -your processor (see <link linkend="internals.cpu">CPU</link>). No additional changes are necessary to -locate the file in this case; <code>ATOMICITYH</code> will be set by default. - </para> - - <para>If you are using the operating system thread-safety primitives approach, -you can also put this code in the same CPU directory, in which case no more -work is needed to locate the file. For examples of this approach, -see the <code>atomicity.h</code> file for IRIX or IA64. - </para> - - <para>Alternatively, if the primitives are more closely related to the OS -than they are to the CPU, you can put the <code>atomicity.h</code> file in -the <link linkend="internals.os">Operating system</link> directory instead. In this case, you must -edit <code>configure.host</code>, and in the switch statement that handles -operating systems, override the <code>ATOMICITYH</code> variable to point to -the appropriate <code>os_include_dir</code>. For examples of this approach, -see the <code>atomicity.h</code> file for AIX. - </para> - - <para>With those bits out of the way, you have to actually write -<code>atomicity.h</code> itself. This file should be wrapped in an -include guard named <code>_GLIBCXX_ATOMICITY_H</code>. It should define one -type, and two functions. - </para> - - <para>The type is <code>_Atomic_word</code>. Here is the version used on IRIX: - </para> - -<programlisting> -typedef long _Atomic_word; -</programlisting> - -<para>This type must be a signed integral type supporting atomic operations. -If you're using the OS approach, use the same type used by your system's -primitives. Otherwise, use the type for which your CPU provides atomic -primitives. -</para> - - <para>Then, you must provide two functions. The bodies of these functions -must be equivalent to those provided here, but using atomic operations: - </para> - -<programlisting> - static inline _Atomic_word - __attribute__ ((__unused__)) - __exchange_and_add (_Atomic_word* __mem, int __val) - { - _Atomic_word __result = *__mem; - *__mem += __val; - return __result; - } - - static inline void - __attribute__ ((__unused__)) - __atomic_add (_Atomic_word* __mem, int __val) - { - *__mem += __val; - } -</programlisting> - -</sect2> - - -<sect2 id="internals.numeric_limits" xreflabel="internals.numeric_limits"> -<title>Numeric Limits</title> - -<para>The C++ library requires information about the fundamental data types, -such as the minimum and maximum representable values of each type. -You can define each of these values individually, but it is usually -easiest just to indicate how many bits are used in each of the data -types and let the library do the rest. For information about the -macros to define, see the top of <code>include/bits/std_limits.h</code>. -</para> - - <para>If you need to define any macros, you can do so in <code>os_defines.h</code>. -However, if all operating systems for your CPU are likely to use the -same values, you can provide a CPU-specific file instead so that you -do not have to provide the same definitions for each operating system. -To take that approach, create a new file called <code>cpu_limits.h</code> in -your CPU configuration directory (see <link linkend="internals.cpu">CPU</link>). - </para> - -</sect2> - - -<sect2 id="internals.libtool" xreflabel="internals.libtool"> -<title>Libtool</title> - -<para>The C++ library is compiled, archived and linked with libtool. -Explaining the full workings of libtool is beyond the scope of this -document, but there are a few, particular bits that are necessary for -porting. -</para> - - <para>Some parts of the libstdc++ library are compiled with the libtool -<code>--tags CXX</code> option (the C++ definitions for libtool). Therefore, -<code>ltcf-cxx.sh</code> in the top-level directory needs to have the correct -logic to compile and archive objects equivalent to the C version of libtool, -<code>ltcf-c.sh</code>. Some libtool targets have definitions for C but not -for C++, or C++ definitions which have not been kept up to date. - </para> - - <para>The C++ run-time library contains initialization code that needs to be -run as the library is loaded. Often, that requires linking in special -object files when the C++ library is built as a shared library, or -taking other system-specific actions. - </para> - - <para>The libstdc++ library is linked with the C version of libtool, even -though it is a C++ library. Therefore, the C version of libtool needs to -ensure that the run-time library initializers are run. The usual way to -do this is to build the library using <code>gcc -shared</code>. - </para> - - <para>If you need to change how the library is linked, look at -<code>ltcf-c.sh</code> in the top-level directory. Find the switch statement -that sets <code>archive_cmds</code>. Here, adjust the setting for your -operating system. - </para> - - -</sect2> - -</sect1>
\ No newline at end of file diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/intro.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/intro.xml deleted file mode 100644 index dca08c2b9..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/intro.xml +++ /dev/null @@ -1,854 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.intro" xreflabel="Introduction"> -<?dbhtml filename="intro.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Introduction - <indexterm><primary>Introduction</primary></indexterm> -</title> -<!-- Chapter 01 : Status --> -<chapter id="manual.intro.status" xreflabel="Status"> - <?dbhtml filename="status.html"?> - <title>Status</title> - - <!-- Section 01 : Implementation Status --> - <sect1 id="manual.intro.status.iso" xreflabel="Status"> - <title>Implementation Status</title> - - <!-- Section 01.1 : Status C++ 1998 --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="status_cxx1998.xml"> - </xi:include> - - <!-- Section 01.2 : Status C++ TR1 --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="status_cxxtr1.xml"> - </xi:include> - - <!-- Section 01.3 : Status C++ 200x --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="status_cxx200x.xml"> - </xi:include> - </sect1> - - <!-- Section 02 : License --> - <sect1 id="manual.intro.status.license" xreflabel="License"> - <?dbhtml filename="license.html"?> - <title>License</title> - <para> - There are two licenses affecting GNU libstdc++: one for the code, - and one for the documentation. - </para> - - <para> - There is a license section in the FAQ regarding common <link - linkend="faq.license">questions</link>. If you have more - questions, ask the FSF or the <ulink - url="http://gcc.gnu.org/lists.html">gcc mailing list</ulink>. - </para> - - <sect2 id="manual.intro.status.license.gpl" xreflabel="License GPL"> - <title>The Code: GPL</title> - - <para> - The source code is distributed under the <link - linkend="appendix.gpl-3.0">GNU General Public License version 3</link>, - with the addition under section 7 of an exception described in - the <quote>GCC Runtime Library Exception, version 3.1</quote> - as follows (or see the file COPYING.RUNTIME): - </para> - - <literallayout> -GCC RUNTIME LIBRARY EXCEPTION - -Version 3.1, 31 March 2009 - -Copyright (C) 2009 <ulink url="http://fsf.org">Free Software Foundation, Inc.</ulink> - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - -This GCC Runtime Library Exception ("Exception") is an additional -permission under section 7 of the GNU General Public License, version -3 ("GPLv3"). It applies to a given file (the "Runtime Library") that -bears a notice placed by the copyright holder of the file stating that -the file is governed by GPLv3 along with this Exception. - -When you use GCC to compile a program, GCC may combine portions of -certain GCC header files and runtime libraries with the compiled -program. The purpose of this Exception is to allow compilation of -non-GPL (including proprietary) programs to use, in this way, the -header files and runtime libraries covered by this Exception. - -0. Definitions. - -A file is an "Independent Module" if it either requires the Runtime -Library for execution after a Compilation Process, or makes use of an -interface provided by the Runtime Library, but is not otherwise based -on the Runtime Library. - -"GCC" means a version of the GNU Compiler Collection, with or without -modifications, governed by version 3 (or a specified later version) of -the GNU General Public License (GPL) with the option of using any -subsequent versions published by the FSF. - -"GPL-compatible Software" is software whose conditions of propagation, -modification and use would permit combination with GCC in accord with -the license of GCC. - -"Target Code" refers to output from any compiler for a real or virtual -target processor architecture, in executable form or suitable for -input to an assembler, loader, linker and/or execution -phase. Notwithstanding that, Target Code does not include data in any -format that is used as a compiler intermediate representation, or used -for producing a compiler intermediate representation. - -The "Compilation Process" transforms code entirely represented in -non-intermediate languages designed for human-written code, and/or in -Java Virtual Machine byte code, into Target Code. Thus, for example, -use of source code generators and preprocessors need not be considered -part of the Compilation Process, since the Compilation Process can be -understood as starting with the output of the generators or -preprocessors. - -A Compilation Process is "Eligible" if it is done using GCC, alone or -with other GPL-compatible software, or if it is done without using any -work based on GCC. For example, using non-GPL-compatible Software to -optimize any GCC intermediate representations would not qualify as an -Eligible Compilation Process. - -1. Grant of Additional Permission. - -You have permission to propagate a work of Target Code formed by -combining the Runtime Library with Independent Modules, even if such -propagation would otherwise violate the terms of GPLv3, provided that -all Target Code was generated by Eligible Compilation Processes. You -may then convey such a combination under terms of your choice, -consistent with the licensing of the Independent Modules. - -2. No Weakening of GCC Copyleft. - -The availability of this Exception does not imply any general -presumption that third-party software is unaffected by the copyleft -requirements of the license of GCC. - </literallayout> - - <para> - Hopefully that text is self-explanatory. If it isn't, you need to speak - to your lawyer, or the Free Software Foundation. - </para> - </sect2> - - <sect2 id="manual.intro.status.license.fdl" xreflabel="License FDL"> - <title>The Documentation: GPL, FDL</title> - - <para> - The documentation shipped with the library and made available over - the web, excluding the pages generated from source comments, are - copyrighted by the Free Software Foundation, and placed under the - <link linkend="appendix.gfdl-1.2"> GNU Free Documentation - License version 1.2</link>. There are no Front-Cover Texts, no - Back-Cover Texts, and no Invariant Sections. - </para> - - <para> - For documentation generated by doxygen or other automated tools - via processing source code comments and markup, the original source - code license applies to the generated files. Thus, the doxygen - documents are licensed <link linkend="appendix.gpl-3.0">GPL</link>. - </para> - - <para> - If you plan on making copies of the documentation, please let us know. - We can probably offer suggestions. - </para> - </sect2> - - </sect1> - - <!-- Section 03 : Known Bugs --> - <sect1 id="manual.intro.status.bugs" xreflabel="Bugs"> - <?dbhtml filename="bugs.html"?> - <title>Bugs</title> - - <sect2 id="manual.intro.status.bugs.impl" xreflabel="Bugs impl"> - <title>Implementation Bugs</title> - <para> - Information on known bugs, details on efforts to fix them, and - fixed bugs are all available as part of the GCC bug tracking - system, <ulink - url="http://gcc.gnu.org/bugzilla">bugzilla</ulink>, with the - category set to <literal>libstdc++</literal>. - </para> - </sect2> - - <sect2 id="manual.intro.status.bugs.iso" xreflabel="Bugs iso"> - <title>Standard Bugs</title> - <para> - Everybody's got issues. Even the C++ Standard Library. - </para> - <para> - The Library Working Group, or LWG, is the ISO subcommittee responsible - for making changes to the library. They periodically publish an - Issues List containing problems and possible solutions. As they reach - a consensus on proposed solutions, we often incorporate the solution. - </para> - <para> - Here are the issues which have resulted in code changes to the library. - The links are to the specific defect reports from a <emphasis>partial - copy</emphasis> of the Issues List. You can read the full version online - at the <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">ISO C++ - Committee homepage</ulink>, linked to on the - <ulink url="http://gcc.gnu.org/readings.html">GCC "Readings" - page</ulink>. If - you spend a lot of time reading the issues, we recommend downloading - the ZIP file and reading them locally. - </para> - <para> - (NB: <emphasis>partial copy</emphasis> means that not all - links within the lwg-*.html pages will work. Specifically, - links to defect reports that have not been accorded full DR - status will probably break. Rather than trying to mirror the - entire issues list on our overworked web server, we recommend - you go to the LWG homepage instead.) - </para> - <para> - If a DR is not listed here, we may simply not have gotten to - it yet; feel free to submit a patch. Search the include/bits - and src directories for appearances of - <constant>_GLIBCXX_RESOLVE_LIB_DEFECTS</constant> for examples - of style. Note that we usually do not make changes to the - code until an issue has reached <ulink url="lwg-active.html#DR">DR</ulink> status. - </para> - - <variablelist> - <varlistentry><term><ulink url="../ext/lwg-defects.html#5">5</ulink>: - <emphasis>string::compare specification questionable</emphasis> - </term> - <listitem><para>This should be two overloaded functions rather than a single function. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#17">17</ulink>: - <emphasis>Bad bool parsing</emphasis> - </term> - <listitem><para>Apparently extracting Boolean values was messed up... - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#19">19</ulink>: - <emphasis>"Noconv" definition too vague</emphasis> - </term> - <listitem><para>If <code>codecvt::do_in</code> returns <code>noconv</code> there are - no changes to the values in <code>[to, to_limit)</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#22">22</ulink>: - <emphasis>Member open vs flags</emphasis> - </term> - <listitem><para>Re-opening a file stream does <emphasis>not</emphasis> clear the state flags. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#23">23</ulink>: - <emphasis>Num_get overflow result</emphasis> - </term> - <listitem><para>Implement the proposed resolution. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#25">25</ulink>: - <emphasis>String operator<< uses width() value wrong</emphasis> - </term> - <listitem><para>Padding issues. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#48">48</ulink>: - <emphasis>Use of non-existent exception constructor</emphasis> - </term> - <listitem><para>An instance of <code>ios_base::failure</code> is constructed instead. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#49">49</ulink>: - <emphasis>Underspecification of ios_base::sync_with_stdio</emphasis> - </term> - <listitem><para>The return type is the <emphasis>previous</emphasis> state of synchronization. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#50">50</ulink>: - <emphasis>Copy constructor and assignment operator of ios_base</emphasis> - </term> - <listitem><para>These members functions are declared <code>private</code> and are - thus inaccessible. Specifying the correct semantics of - "copying stream state" was deemed too complicated. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#60">60</ulink>: - <emphasis>What is a formatted input function?</emphasis> - </term> - <listitem><para>This DR made many widespread changes to <code>basic_istream</code> - and <code>basic_ostream</code> all of which have been implemented. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#63">63</ulink>: - <emphasis>Exception-handling policy for unformatted output</emphasis> - </term> - <listitem><para>Make the policy consistent with that of formatted input, unformatted - input, and formatted output. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#68">68</ulink>: - <emphasis>Extractors for char* should store null at end</emphasis> - </term> - <listitem><para>And they do now. An editing glitch in the last item in the list of - [27.6.1.2.3]/7. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#74">74</ulink>: - <emphasis>Garbled text for codecvt::do_max_length</emphasis> - </term> - <listitem><para>The text of the standard was gibberish. Typos gone rampant. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#75">75</ulink>: - <emphasis>Contradiction in codecvt::length's argument types</emphasis> - </term> - <listitem><para>Change the first parameter to <code>stateT&</code> and implement - the new effects paragraph. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="lwg-defects.html#83">83</ulink>: - <emphasis>string::npos vs. string::max_size()</emphasis> - </term> - <listitem><para>Safety checks on the size of the string should test against - <code>max_size()</code> rather than <code>npos</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#90">90</ulink>: - <emphasis>Incorrect description of operator>> for strings</emphasis> - </term> - <listitem><para>The effect contain <code>isspace(c,getloc())</code> which must be - replaced by <code>isspace(c,is.getloc())</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#91">91</ulink>: - <emphasis>Description of operator>> and getline() for string<> - might cause endless loop</emphasis> - </term> - <listitem><para>They behave as a formatted input function and as an unformatted - input function, respectively (except that <code>getline</code> is - not required to set <code>gcount</code>). - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#103">103</ulink>: - <emphasis>set::iterator is required to be modifiable, but this allows - modification of keys.</emphasis> - </term> - <listitem><para>For associative containers where the value type is the same as - the key type, both <code>iterator</code> and <code>const_iterator - </code> are constant iterators. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#109">109</ulink>: - <emphasis>Missing binders for non-const sequence elements</emphasis> - </term> - <listitem><para>The <code>binder1st</code> and <code>binder2nd</code> didn't have an - <code>operator()</code> taking a non-const parameter. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#110">110</ulink>: - <emphasis>istreambuf_iterator::equal not const</emphasis> - </term> - <listitem><para>This was not a const member function. Note that the DR says to - replace the function with a const one; we have instead provided an - overloaded version with identical contents. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#117">117</ulink>: - <emphasis>basic_ostream uses nonexistent num_put member functions</emphasis> - </term> - <listitem><para><code>num_put::put()</code> was overloaded on the wrong types. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#118">118</ulink>: - <emphasis>basic_istream uses nonexistent num_get member functions</emphasis> - </term> - <listitem><para>Same as 117, but for <code>num_get::get()</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#129">129</ulink>: - <emphasis>Need error indication from seekp() and seekg()</emphasis> - </term> - <listitem><para>These functions set <code>failbit</code> on error now. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#136">136</ulink>: - <emphasis>seekp, seekg setting wrong streams?</emphasis> - </term> - <listitem><para><code>seekp</code> should only set the output stream, and - <code>seekg</code> should only set the input stream. - </para></listitem></varlistentry> - -<!--<varlistentry><term><ulink url="../ext/lwg-defects.html#159">159</ulink>: - <emphasis>Strange use of underflow()</emphasis> - </term> - <listitem><para>In fstream.tcc, the basic_filebuf<>::showmanyc() function - should probably not be calling <code>underflow()</code>. - </para></listitem></varlistentry> --> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#167">167</ulink>: - <emphasis>Improper use of traits_type::length()</emphasis> - </term> - <listitem><para><code>op<<</code> with a <code>const char*</code> was - calculating an incorrect number of characters to write. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#169">169</ulink>: - <emphasis>Bad efficiency of overflow() mandated</emphasis> - </term> - <listitem><para>Grow efficiently the internal array object. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#171">171</ulink>: - <emphasis>Strange seekpos() semantics due to joint position</emphasis> - </term> - <listitem><para>Quite complex to summarize... - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#181">181</ulink>: - <emphasis>make_pair() unintended behavior</emphasis> - </term> - <listitem><para>This function used to take its arguments as reference-to-const, now - it copies them (pass by value). - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#195">195</ulink>: - <emphasis>Should basic_istream::sentry's constructor ever set eofbit?</emphasis> - </term> - <listitem><para>Yes, it can, specifically if EOF is reached while skipping whitespace. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#211">211</ulink>: - <emphasis>operator>>(istream&, string&) doesn't set failbit</emphasis> - </term> - <listitem><para>If nothing is extracted into the string, <code>op>></code> now - sets <code>failbit</code> (which can cause an exception, etc., etc.). - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#214">214</ulink>: - <emphasis>set::find() missing const overload</emphasis> - </term> - <listitem><para>Both <code>set</code> and <code>multiset</code> were missing - overloaded find, lower_bound, upper_bound, and equal_range functions - for const instances. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#231">231</ulink>: - <emphasis>Precision in iostream?</emphasis> - </term> - <listitem><para>For conversion from a floating-point type, <code>str.precision()</code> - is specified in the conversion specification. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#233">233</ulink>: - <emphasis>Insertion hints in associative containers</emphasis> - </term> - <listitem><para>Implement N1780, first check before then check after, insert as close - to hint as possible. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#235">235</ulink>: - <emphasis>No specification of default ctor for reverse_iterator</emphasis> - </term> - <listitem><para>The declaration of <code>reverse_iterator</code> lists a default constructor. - However, no specification is given what this constructor should do. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#241">241</ulink>: - <emphasis>Does unique_copy() require CopyConstructible and Assignable?</emphasis> - </term> - <listitem><para>Add a helper for forward_iterator/output_iterator, fix the existing - one for input_iterator/output_iterator to not rely on Assignability. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#243">243</ulink>: - <emphasis>get and getline when sentry reports failure</emphasis> - </term> - <listitem><para>Store a null character only if the character array has a non-zero size. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#251">251</ulink>: - <emphasis>basic_stringbuf missing allocator_type</emphasis> - </term> - <listitem><para>This nested typedef was originally not specified. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#253">253</ulink>: - <emphasis>valarray helper functions are almost entirely useless</emphasis> - </term> - <listitem><para>Make the copy constructor and copy-assignment operator declarations - public in gslice_array, indirect_array, mask_array, slice_array; provide - definitions. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#265">265</ulink>: - <emphasis>std::pair::pair() effects overly restrictive</emphasis> - </term> - <listitem><para>The default ctor would build its members from copies of temporaries; - now it simply uses their respective default ctors. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#266">266</ulink>: - <emphasis>bad_exception::~bad_exception() missing Effects clause</emphasis> - </term> - <listitem><para>The <code>bad_</code>* classes no longer have destructors (they - are trivial), since no description of them was ever given. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#271">271</ulink>: - <emphasis>basic_iostream missing typedefs</emphasis> - </term> - <listitem><para>The typedefs it inherits from its base classes can't be used, since - (for example) <code>basic_iostream<T>::traits_type</code> is ambiguous. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#275">275</ulink>: - <emphasis>Wrong type in num_get::get() overloads</emphasis> - </term> - <listitem><para>Similar to 118. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#280">280</ulink>: - <emphasis>Comparison of reverse_iterator to const reverse_iterator</emphasis> - </term> - <listitem><para>Add global functions with two template parameters. - (NB: not added for now a templated assignment operator) - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#292">292</ulink>: - <emphasis>Effects of a.copyfmt (a)</emphasis> - </term> - <listitem><para>If <code>(this == &rhs)</code> do nothing. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#300">300</ulink>: - <emphasis>List::merge() specification incomplete</emphasis> - </term> - <listitem><para>If <code>(this == &x)</code> do nothing. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#303">303</ulink>: - <emphasis>Bitset input operator underspecified</emphasis> - </term> - <listitem><para>Basically, compare the input character to - <code>is.widen(0)</code> and <code>is.widen(1)</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#305">305</ulink>: - <emphasis>Default behavior of codecvt<wchar_t, char, - mbstate_t>::length()</emphasis> - </term> - <listitem><para>Do not specify what <code>codecvt<wchar_t, char, - mbstate_t>::do_length</code> must return. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#328">328</ulink>: - <emphasis>Bad sprintf format modifier in - money_put<>::do_put()</emphasis> - </term> - <listitem><para>Change the format string to "%.0Lf". - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#365">365</ulink>: - <emphasis>Lack of const-qualification in clause 27</emphasis> - </term> - <listitem><para>Add const overloads of <code>is_open</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#387">387</ulink>: - <emphasis>std::complex over-encapsulated</emphasis> - </term> - <listitem><para>Add the <code>real(T)</code> and <code>imag(T)</code> - members; in C++0x mode, also adjust the existing - <code>real()</code> and <code>imag()</code> members and - free functions. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#389">389</ulink>: - <emphasis>Const overload of valarray::operator[] returns - by value</emphasis> - </term> - <listitem><para>Change it to return a <code>const T&</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#396">396</ulink>: - <emphasis>what are characters zero and one</emphasis> - </term> - <listitem><para>Implement the proposed resolution. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#402">402</ulink>: - <emphasis>Wrong new expression in [some_]allocator::construct</emphasis> - </term> - <listitem><para>Replace "new" with "::new". - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#409">409</ulink>: - <emphasis>Closing an fstream should clear the error state</emphasis> - </term> - <listitem><para>Have <code>open</code> clear the error flags. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#431">431</ulink>: - <emphasis>Swapping containers with unequal allocators</emphasis> - </term> - <listitem><para>Implement Option 3, as per N1599. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#432">432</ulink>: - <emphasis>stringbuf::overflow() makes only one write position - available</emphasis> - </term> - <listitem><para>Implement the resolution, beyond DR 169. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#434">434</ulink>: - <emphasis>bitset::to_string() hard to use</emphasis> - </term> - <listitem><para>Add three overloads, taking fewer template arguments. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#438">438</ulink>: - <emphasis>Ambiguity in the "do the right thing" clause</emphasis> - </term> - <listitem><para>Implement the resolution, basically cast less. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#453">453</ulink>: - <emphasis>basic_stringbuf::seekoff need not always fail for an empty stream</emphasis> - </term> - <listitem><para>Don't fail if the next pointer is null and newoff is zero. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#455">455</ulink>: - <emphasis>cerr::tie() and wcerr::tie() are overspecified</emphasis> - </term> - <listitem><para>Initialize cerr tied to cout and wcerr tied to wcout. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#464">464</ulink>: - <emphasis>Suggestion for new member functions in standard containers</emphasis> - </term> - <listitem><para>Add <code>data()</code> to <code>std::vector</code> and - <code>at(const key_type&)</code> to <code>std::map</code>. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#508">508</ulink>: - <emphasis>Bad parameters for ranlux64_base_01</emphasis> - </term> - <listitem><para>Fix the parameters. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-closed.html#512">512</ulink>: - <emphasis>Seeding subtract_with_carry_01 from a single unsigned long</emphasis> - </term> - <listitem><para>Construct a <code>linear_congruential</code> engine and seed with it. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-closed.html#526">526</ulink>: - <emphasis>Is it undefined if a function in the standard changes in - parameters?</emphasis> - </term> - <listitem><para>Use &value. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#538">538</ulink>: - <emphasis>241 again: Does unique_copy() require CopyConstructible - and Assignable?</emphasis> - </term> - <listitem><para>In case of input_iterator/output_iterator rely on Assignability of - input_iterator' value_type. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#541">541</ulink>: - <emphasis>shared_ptr template assignment and void</emphasis> - </term> - <listitem><para>Add an auto_ptr<void> specialization. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#543">543</ulink>: - <emphasis>valarray slice default constructor</emphasis> - </term> - <listitem><para>Follow the straightforward proposed resolution. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#550">550</ulink>: - <emphasis>What should the return type of pow(float,int) be?</emphasis> - </term> - <listitem><para>In C++0x mode, remove the pow(float,int), etc., signatures. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#586">586</ulink>: - <emphasis>string inserter not a formatted function</emphasis> - </term> - <listitem><para>Change it to be a formatted output function (i.e. catch exceptions). - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#596">596</ulink>: - <emphasis>27.8.1.3 Table 112 omits "a+" and "a+b" modes</emphasis> - </term> - <listitem><para>Add the missing modes to fopen_mode. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#660">660</ulink>: - <emphasis>Missing bitwise operations</emphasis> - </term> - <listitem><para>Add the missing operations. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#691">691</ulink>: - <emphasis>const_local_iterator cbegin, cend missing from TR1</emphasis> - </term> - <listitem><para>In C++0x mode add cbegin(size_type) and cend(size_type) - to the unordered containers. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#693">693</ulink>: - <emphasis>std::bitset::all() missing</emphasis> - </term> - <listitem><para>Add it, consistently with the discussion. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#695">695</ulink>: - <emphasis>ctype<char>::classic_table() not accessible</emphasis> - </term> - <listitem><para>Make the member functions table and classic_table public. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#761">761</ulink>: - <emphasis>unordered_map needs an at() member function</emphasis> - </term> - <listitem><para>In C++0x mode, add at() and at() const. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#775">775</ulink>: - <emphasis>Tuple indexing should be unsigned?</emphasis> - </term> - <listitem><para>Implement the int -> size_t replacements. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#776">776</ulink>: - <emphasis>Undescribed assign function of std::array</emphasis> - </term> - <listitem><para>In C++0x mode, remove assign, add fill. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-defects.html#781">781</ulink>: - <emphasis>std::complex should add missing C99 functions</emphasis> - </term> - <listitem><para>In C++0x mode, add std::proj. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#809">809</ulink>: - <emphasis>std::swap should be overloaded for array types</emphasis> - </term> - <listitem><para>Add the overload. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#844">844</ulink>: - <emphasis>complex pow return type is ambiguous</emphasis> - </term> - <listitem><para>In C++0x mode, remove the pow(complex<T>, int) signature. - </para></listitem></varlistentry> - - <varlistentry><term><ulink url="../ext/lwg-active.html#853">853</ulink>: - <emphasis>to_string needs updating with zero and one</emphasis> - </term> - <listitem><para>Update / add the signatures. - </para></listitem></varlistentry> - </variablelist> - - </sect2> - </sect1> -</chapter> - - -<!-- Chapter 02 : Setup --> -<chapter id="manual.intro.setup" xreflabel="Setup"> - <?dbhtml filename="setup.html"?> - <title>Setup</title> - - <para>To transform libstdc++ sources into installed include files - and properly built binaries useful for linking to other software is - a multi-step process. Steps include getting the sources, - configuring and building the sources, testing, and installation. - </para> - - <para>The general outline of commands is something like: - </para> - - <programlisting> - <emphasis>get gcc sources</emphasis> - <emphasis>extract into gccsrcdir</emphasis> - mkdir <emphasis>gccbuilddir</emphasis> - cd <emphasis>gccbuilddir</emphasis> - <emphasis>gccsrcdir</emphasis>/configure --prefix=<emphasis>destdir</emphasis> --other-opts... - make - make check - make install - </programlisting> - - <para> - Each step is described in more detail in the following sections. - </para> - - <!-- Section 01 : Prerequisites --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="prerequisites.xml"> - </xi:include> - - <!-- Section 02 : Configure --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="configure.xml"> - </xi:include> - - <!-- Section 03 : Make --> -<sect1 id="manual.intro.setup.make" xreflabel="Make"> - <?dbhtml filename="make.html"?> -<title>Make</title> - <para>If you have never done this before, you should read the basic - <ulink url="http://gcc.gnu.org/install/">GCC Installation - Instructions</ulink> first. Read <emphasis>all of them</emphasis>. - <emphasis>Twice.</emphasis> - </para> - -<para>Then type:<command>make</command>, and congratulations, you're -started to build. -</para> - -</sect1> - - <!-- Section 04 : Test --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="test.xml"> - </xi:include> -</chapter> - - -<!-- Chapter 03 : Using --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="using.xml"> -</xi:include> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/io.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/io.xml deleted file mode 100644 index 8431f6f4d..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/io.xml +++ /dev/null @@ -1,673 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.io" xreflabel="Input and Output"> -<?dbhtml filename="io.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Input and Output - <indexterm><primary>Input and Output</primary></indexterm> -</title> - -<!-- Chapter 01 : Iostream Objects --> -<chapter id="manual.io.objects" xreflabel="IO Objects"> -<?dbhtml filename="iostream_objects.html"?> - <title>Iostream Objects</title> - - <para>To minimize the time you have to wait on the compiler, it's good to - only include the headers you really need. Many people simply include - <iostream> when they don't need to -- and that can <emphasis>penalize - your runtime as well.</emphasis> Here are some tips on which header to use - for which situations, starting with the simplest. - </para> - <para><emphasis><iosfwd></emphasis> should be included whenever you simply - need the <emphasis>name</emphasis> of an I/O-related class, such as - "ofstream" or "basic_streambuf". Like the name - implies, these are forward declarations. (A word to all you fellow - old school programmers: trying to forward declare classes like - "class istream;" won't work. Look in the iosfwd header if - you'd like to know why.) For example, - </para> - <programlisting> - #include <iosfwd> - - class MyClass - { - .... - std::ifstream& input_file; - }; - - extern std::ostream& operator<< (std::ostream&, MyClass&); - </programlisting> - <para><emphasis><ios></emphasis> declares the base classes for the entire - I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the - counting types std::streamoff and std::streamsize, the file - positioning type std::fpos, and the various manipulators like - std::hex, std::fixed, std::noshowbase, and so forth. - </para> - <para>The ios_base class is what holds the format flags, the state flags, - and the functions which change them (setf(), width(), precision(), - etc). You can also store extra data and register callback functions - through ios_base, but that has been historically underused. Anything - which doesn't depend on the type of characters stored is consolidated - here. - </para> - <para>The template class basic_ios is the highest template class in the - hierarchy; it is the first one depending on the character type, and - holds all general state associated with that type: the pointer to the - polymorphic stream buffer, the facet information, etc. - </para> - <para><emphasis><streambuf></emphasis> declares the template class - basic_streambuf, and two standard instantiations, streambuf and - wstreambuf. If you need to work with the vastly useful and capable - stream buffer classes, e.g., to create a new form of storage - transport, this header is the one to include. - </para> - <para><emphasis><istream></emphasis>/<emphasis><ostream></emphasis> are - the headers to include when you are using the >>/<< - interface, or any of the other abstract stream formatting functions. - For example, - </para> - <programlisting> - #include <istream> - - std::ostream& operator<< (std::ostream& os, MyClass& c) - { - return os << c.data1() << c.data2(); - } - </programlisting> - <para>The std::istream and std::ostream classes are the abstract parents of - the various concrete implementations. If you are only using the - interfaces, then you only need to use the appropriate interface header. - </para> - <para><emphasis><iomanip></emphasis> provides "extractors and inserters - that alter information maintained by class ios_base and its derived - classes," such as std::setprecision and std::setw. If you need - to write expressions like <code>os << setw(3);</code> or - <code>is >> setbase(8);</code>, you must include <iomanip>. - </para> - <para><emphasis><sstream></emphasis>/<emphasis><fstream></emphasis> - declare the six stringstream and fstream classes. As they are the - standard concrete descendants of istream and ostream, you will already - know about them. - </para> - <para>Finally, <emphasis><iostream></emphasis> provides the eight standard - global objects (cin, cout, etc). To do this correctly, this header - also provides the contents of the <istream> and <ostream> - headers, but nothing else. The contents of this header look like - </para> - <programlisting> - #include <ostream> - #include <istream> - - namespace std - { - extern istream cin; - extern ostream cout; - .... - - // this is explained below - <emphasis>static ios_base::Init __foo;</emphasis> // not its real name - } - </programlisting> - <para>Now, the runtime penalty mentioned previously: the global objects - must be initialized before any of your own code uses them; this is - guaranteed by the standard. Like any other global object, they must - be initialized once and only once. This is typically done with a - construct like the one above, and the nested class ios_base::Init is - specified in the standard for just this reason. - </para> - <para>How does it work? Because the header is included before any of your - code, the <emphasis>__foo</emphasis> object is constructed before any of - your objects. (Global objects are built in the order in which they - are declared, and destroyed in reverse order.) The first time the - constructor runs, the eight stream objects are set up. - </para> - <para>The <code>static</code> keyword means that each object file compiled - from a source file containing <iostream> will have its own - private copy of <emphasis>__foo</emphasis>. There is no specified order - of construction across object files (it's one of those pesky NP - problems that make life so interesting), so one copy in each object - file means that the stream objects are guaranteed to be set up before - any of your code which uses them could run, thereby meeting the - requirements of the standard. - </para> - <para>The penalty, of course, is that after the first copy of - <emphasis>__foo</emphasis> is constructed, all the others are just wasted - processor time. The time spent is merely for an increment-and-test - inside a function call, but over several dozen or hundreds of object - files, that time can add up. (It's not in a tight loop, either.) - </para> - <para>The lesson? Only include <iostream> when you need to use one of - the standard objects in that source file; you'll pay less startup - time. Only include the header files you need to in general; your - compile times will go down when there's less parsing work to do. - </para> - -</chapter> - -<!-- Chapter 02 : Stream Buffers --> -<chapter id="manual.io.streambufs" xreflabel="Stream Buffers"> -<?dbhtml filename="streambufs.html"?> - <title>Stream Buffers</title> - - <sect1 id="io.streambuf.derived" xreflabel="Derived streambuf Classes"> - <title>Derived streambuf Classes</title> - <para> - </para> - - <para>Creating your own stream buffers for I/O can be remarkably easy. - If you are interested in doing so, we highly recommend two very - excellent books: - <ulink url="http://www.langer.camelot.de/iostreams.html">Standard C++ - IOStreams and Locales</ulink> by Langer and Kreft, ISBN 0-201-18395-1, and - <ulink url="http://www.josuttis.com/libbook/">The C++ Standard Library</ulink> - by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by - Addison-Wesley, who isn't paying us a cent for saying that, honest. - </para> - <para>Here is a simple example, io/outbuf1, from the Josuttis text. It - transforms everything sent through it to uppercase. This version - assumes many things about the nature of the character type being - used (for more information, read the books or the newsgroups): - </para> - <programlisting> - #include <iostream> - #include <streambuf> - #include <locale> - #include <cstdio> - - class outbuf : public std::streambuf - { - protected: - /* central output function - * - print characters in uppercase mode - */ - virtual int_type overflow (int_type c) { - if (c != EOF) { - // convert lowercase to uppercase - c = std::toupper(static_cast<char>(c),getloc()); - - // and write the character to the standard output - if (putchar(c) == EOF) { - return EOF; - } - } - return c; - } - }; - - int main() - { - // create special output buffer - outbuf ob; - // initialize output stream with that output buffer - std::ostream out(&ob); - - out << "31 hexadecimal: " - << std::hex << 31 << std::endl; - return 0; - } - </programlisting> - <para>Try it yourself! More examples can be found in 3.1.x code, in - <code>include/ext/*_filebuf.h</code>, and on - <ulink url="http://www.informatik.uni-konstanz.de/~kuehl/c++/iostream/">Dietmar - Kühl's IOStreams page</ulink>. - </para> - - </sect1> - - <sect1 id="io.streambuf.buffering" xreflabel="Buffering"> - <title>Buffering</title> - <para>First, are you sure that you understand buffering? Particularly - the fact that C++ may not, in fact, have anything to do with it? - </para> - <para>The rules for buffering can be a little odd, but they aren't any - different from those of C. (Maybe that's why they can be a bit - odd.) Many people think that writing a newline to an output - stream automatically flushes the output buffer. This is true only - when the output stream is, in fact, a terminal and not a file - or some other device -- and <emphasis>that</emphasis> may not even be true - since C++ says nothing about files nor terminals. All of that is - system-dependent. (The "newline-buffer-flushing only occurring - on terminals" thing is mostly true on Unix systems, though.) - </para> - <para>Some people also believe that sending <code>endl</code> down an - output stream only writes a newline. This is incorrect; after a - newline is written, the buffer is also flushed. Perhaps this - is the effect you want when writing to a screen -- get the text - out as soon as possible, etc -- but the buffering is largely - wasted when doing this to a file: - </para> - <programlisting> - output << "a line of text" << endl; - output << some_data_variable << endl; - output << "another line of text" << endl; </programlisting> - <para>The proper thing to do in this case to just write the data out - and let the libraries and the system worry about the buffering. - If you need a newline, just write a newline: - </para> - <programlisting> - output << "a line of text\n" - << some_data_variable << '\n' - << "another line of text\n"; </programlisting> - <para>I have also joined the output statements into a single statement. - You could make the code prettier by moving the single newline to - the start of the quoted text on the last line, for example. - </para> - <para>If you do need to flush the buffer above, you can send an - <code>endl</code> if you also need a newline, or just flush the buffer - yourself: - </para> - <programlisting> - output << ...... << flush; // can use std::flush manipulator - output.flush(); // or call a member fn </programlisting> - <para>On the other hand, there are times when writing to a file should - be like writing to standard error; no buffering should be done - because the data needs to appear quickly (a prime example is a - log file for security-related information). The way to do this is - just to turn off the buffering <emphasis>before any I/O operations at - all</emphasis> have been done (note that opening counts as an I/O operation): - </para> - <programlisting> - std::ofstream os; - std::ifstream is; - int i; - - os.rdbuf()->pubsetbuf(0,0); - is.rdbuf()->pubsetbuf(0,0); - - os.open("/foo/bar/baz"); - is.open("/qux/quux/quuux"); - ... - os << "this data is written immediately\n"; - is >> i; // and this will probably cause a disk read </programlisting> - <para>Since all aspects of buffering are handled by a streambuf-derived - member, it is necessary to get at that member with <code>rdbuf()</code>. - Then the public version of <code>setbuf</code> can be called. The - arguments are the same as those for the Standard C I/O Library - function (a buffer area followed by its size). - </para> - <para>A great deal of this is implementation-dependent. For example, - <code>streambuf</code> does not specify any actions for its own - <code>setbuf()</code>-ish functions; the classes derived from - <code>streambuf</code> each define behavior that "makes - sense" for that class: an argument of (0,0) turns off buffering - for <code>filebuf</code> but does nothing at all for its siblings - <code>stringbuf</code> and <code>strstreambuf</code>, and specifying - anything other than (0,0) has varying effects. - User-defined classes derived from <code>streambuf</code> can - do whatever they want. (For <code>filebuf</code> and arguments for - <code>(p,s)</code> other than zeros, libstdc++ does what you'd expect: - the first <code>s</code> bytes of <code>p</code> are used as a buffer, - which you must allocate and deallocate.) - </para> - <para>A last reminder: there are usually more buffers involved than - just those at the language/library level. Kernel buffers, disk - buffers, and the like will also have an effect. Inspecting and - changing those are system-dependent. - </para> - - </sect1> -</chapter> - -<!-- Chapter 03 : Memory-based Streams --> -<chapter id="manual.io.memstreams" xreflabel="Memory Streams"> -<?dbhtml filename="stringstreams.html"?> - <title>Memory Based Streams</title> - <sect1 id="manual.io.memstreams.compat" xreflabel="Compatibility strstream"> - <title>Compatibility With strstream</title> - <para> - </para> - <para>Stringstreams (defined in the header <code><sstream></code>) - are in this author's opinion one of the coolest things since - sliced time. An example of their use is in the Received Wisdom - section for Chapter 21 (Strings), - <ulink url="../21_strings/howto.html#1.1internal"> describing how to - format strings</ulink>. - </para> - <para>The quick definition is: they are siblings of ifstream and ofstream, - and they do for <code>std::string</code> what their siblings do for - files. All that work you put into writing <code><<</code> and - <code>>></code> functions for your classes now pays off - <emphasis>again!</emphasis> Need to format a string before passing the string - to a function? Send your stuff via <code><<</code> to an - ostringstream. You've read a string as input and need to parse it? - Initialize an istringstream with that string, and then pull pieces - out of it with <code>>></code>. Have a stringstream and need to - get a copy of the string inside? Just call the <code>str()</code> - member function. - </para> - <para>This only works if you've written your - <code><<</code>/<code>>></code> functions correctly, though, - and correctly means that they take istreams and ostreams as - parameters, not i<emphasis>f</emphasis>streams and o<emphasis>f</emphasis>streams. If they - take the latter, then your I/O operators will work fine with - file streams, but with nothing else -- including stringstreams. - </para> - <para>If you are a user of the strstream classes, you need to update - your code. You don't have to explicitly append <code>ends</code> to - terminate the C-style character array, you don't have to mess with - "freezing" functions, and you don't have to manage the - memory yourself. The strstreams have been officially deprecated, - which means that 1) future revisions of the C++ Standard won't - support them, and 2) if you use them, people will laugh at you. - </para> - - - </sect1> -</chapter> - -<!-- Chapter 04 : File-based Streams --> -<chapter id="manual.io.filestreams" xreflabel="File Streams"> -<?dbhtml filename="fstreams.html"?> - <title>File Based Streams</title> - - <sect1 id="manual.io.filestreams.copying_a_file" xreflabel="Copying a File"> - <title>Copying a File</title> - <para> - </para> - - <para>So you want to copy a file quickly and easily, and most important, - completely portably. And since this is C++, you have an open - ifstream (call it IN) and an open ofstream (call it OUT): - </para> - <programlisting> - #include <fstream> - - std::ifstream IN ("input_file"); - std::ofstream OUT ("output_file"); </programlisting> - <para>Here's the easiest way to get it completely wrong: - </para> - <programlisting> - OUT << IN;</programlisting> - <para>For those of you who don't already know why this doesn't work - (probably from having done it before), I invite you to quickly - create a simple text file called "input_file" containing - the sentence - </para> - <programlisting> - The quick brown fox jumped over the lazy dog.</programlisting> - <para>surrounded by blank lines. Code it up and try it. The contents - of "output_file" may surprise you. - </para> - <para>Seriously, go do it. Get surprised, then come back. It's worth it. - </para> - <para>The thing to remember is that the <code>basic_[io]stream</code> classes - handle formatting, nothing else. In particular, they break up on - whitespace. The actual reading, writing, and storing of data is - handled by the <code>basic_streambuf</code> family. Fortunately, the - <code>operator<<</code> is overloaded to take an ostream and - a pointer-to-streambuf, in order to help with just this kind of - "dump the data verbatim" situation. - </para> - <para>Why a <emphasis>pointer</emphasis> to streambuf and not just a streambuf? Well, - the [io]streams hold pointers (or references, depending on the - implementation) to their buffers, not the actual - buffers. This allows polymorphic behavior on the part of the buffers - as well as the streams themselves. The pointer is easily retrieved - using the <code>rdbuf()</code> member function. Therefore, the easiest - way to copy the file is: - </para> - <programlisting> - OUT << IN.rdbuf();</programlisting> - <para>So what <emphasis>was</emphasis> happening with OUT<<IN? Undefined - behavior, since that particular << isn't defined by the Standard. - I have seen instances where it is implemented, but the character - extraction process removes all the whitespace, leaving you with no - blank lines and only "Thequickbrownfox...". With - libraries that do not define that operator, IN (or one of IN's - member pointers) sometimes gets converted to a void*, and the output - file then contains a perfect text representation of a hexadecimal - address (quite a big surprise). Others don't compile at all. - </para> - <para>Also note that none of this is specific to o<emphasis>*f*</emphasis>streams. - The operators shown above are all defined in the parent - basic_ostream class and are therefore available with all possible - descendants. - </para> - - </sect1> - - <sect1 id="manual.io.filestreams.binary" xreflabel="Binary Input and Output"> - <title>Binary Input and Output</title> - <para> - </para> - <para>The first and most important thing to remember about binary I/O is - that opening a file with <code>ios::binary</code> is not, repeat - <emphasis>not</emphasis>, the only thing you have to do. It is not a silver - bullet, and will not allow you to use the <code><</>></code> - operators of the normal fstreams to do binary I/O. - </para> - <para>Sorry. Them's the breaks. - </para> - <para>This isn't going to try and be a complete tutorial on reading and - writing binary files (because "binary" - <ulink url="#7">covers a lot of ground)</ulink>, but we will try and clear - up a couple of misconceptions and common errors. - </para> - <para>First, <code>ios::binary</code> has exactly one defined effect, no more - and no less. Normal text mode has to be concerned with the newline - characters, and the runtime system will translate between (for - example) '\n' and the appropriate end-of-line sequence (LF on Unix, - CRLF on DOS, CR on Macintosh, etc). (There are other things that - normal mode does, but that's the most obvious.) Opening a file in - binary mode disables this conversion, so reading a CRLF sequence - under Windows won't accidentally get mapped to a '\n' character, etc. - Binary mode is not supposed to suddenly give you a bitstream, and - if it is doing so in your program then you've discovered a bug in - your vendor's compiler (or some other part of the C++ implementation, - possibly the runtime system). - </para> - <para>Second, using <code><<</code> to write and <code>>></code> to - read isn't going to work with the standard file stream classes, even - if you use <code>skipws</code> during reading. Why not? Because - ifstream and ofstream exist for the purpose of <emphasis>formatting</emphasis>, - not reading and writing. Their job is to interpret the data into - text characters, and that's exactly what you don't want to happen - during binary I/O. - </para> - <para>Third, using the <code>get()</code> and <code>put()/write()</code> member - functions still aren't guaranteed to help you. These are - "unformatted" I/O functions, but still character-based. - (This may or may not be what you want, see below.) - </para> - <para>Notice how all the problems here are due to the inappropriate use - of <emphasis>formatting</emphasis> functions and classes to perform something - which <emphasis>requires</emphasis> that formatting not be done? There are a - seemingly infinite number of solutions, and a few are listed here: - </para> - <itemizedlist> - <listitem> - <para><quote>Derive your own fstream-type classes and write your own - <</>> operators to do binary I/O on whatever data - types you're using.</quote> - </para> - <para> - This is a Bad Thing, because while - the compiler would probably be just fine with it, other humans - are going to be confused. The overloaded bitshift operators - have a well-defined meaning (formatting), and this breaks it. - </para> - </listitem> - <listitem> - <para> - <quote>Build the file structure in memory, then - <code>mmap()</code> the file and copy the - structure. - </quote> - </para> - <para> - Well, this is easy to make work, and easy to break, and is - pretty equivalent to using <code>::read()</code> and - <code>::write()</code> directly, and makes no use of the - iostream library at all... - </para> - </listitem> - <listitem> - <para> - <quote>Use streambufs, that's what they're there for.</quote> - </para> - <para> - While not trivial for the beginner, this is the best of all - solutions. The streambuf/filebuf layer is the layer that is - responsible for actual I/O. If you want to use the C++ - library for binary I/O, this is where you start. - </para> - </listitem> - </itemizedlist> - <para>How to go about using streambufs is a bit beyond the scope of this - document (at least for now), but while streambufs go a long way, - they still leave a couple of things up to you, the programmer. - As an example, byte ordering is completely between you and the - operating system, and you have to handle it yourself. - </para> - <para>Deriving a streambuf or filebuf - class from the standard ones, one that is specific to your data - types (or an abstraction thereof) is probably a good idea, and - lots of examples exist in journals and on Usenet. Using the - standard filebufs directly (either by declaring your own or by - using the pointer returned from an fstream's <code>rdbuf()</code>) - is certainly feasible as well. - </para> - <para>One area that causes problems is trying to do bit-by-bit operations - with filebufs. C++ is no different from C in this respect: I/O - must be done at the byte level. If you're trying to read or write - a few bits at a time, you're going about it the wrong way. You - must read/write an integral number of bytes and then process the - bytes. (For example, the streambuf functions take and return - variables of type <code>int_type</code>.) - </para> - <para>Another area of problems is opening text files in binary mode. - Generally, binary mode is intended for binary files, and opening - text files in binary mode means that you now have to deal with all of - those end-of-line and end-of-file problems that we mentioned before. - An instructive thread from comp.lang.c++.moderated delved off into - this topic starting more or less at - <ulink url="http://groups.google.com/groups?oi=djq&selm=an_436187505">this</ulink> - article and continuing to the end of the thread. (You'll have to - sort through some flames every couple of paragraphs, but the points - made are good ones.) - </para> - - </sect1> - - <sect1 id="manual.io.filestreams.binary2" xreflabel="Binary Input and Output"> - <title>More Binary Input and Output</title> - <para>Towards the beginning of February 2001, the subject of - "binary" I/O was brought up in a couple of places at the - same time. One notable place was Usenet, where James Kanze and - Dietmar Kühl separately posted articles on why attempting - generic binary I/O was not a good idea. (Here are copies of - <ulink url="binary_iostreams_kanze.txt">Kanze's article</ulink> and - <ulink url="binary_iostreams_kuehl.txt">Kühl's article</ulink>.) - </para> - <para>Briefly, the problems of byte ordering and type sizes mean that - the unformatted functions like <code>ostream::put()</code> and - <code>istream::get()</code> cannot safely be used to communicate - between arbitrary programs, or across a network, or from one - invocation of a program to another invocation of the same program - on a different platform, etc. - </para> - <para>The entire Usenet thread is instructive, and took place under the - subject heading "binary iostreams" on both comp.std.c++ - and comp.lang.c++.moderated in parallel. Also in that thread, - Dietmar Kühl mentioned that he had written a pair of stream - classes that would read and write XDR, which is a good step towards - a portable binary format. - </para> - - </sect1> - -</chapter> - -<!-- Chapter 03 : Interacting with C --> -<chapter id="manual.io.c" xreflabel="Interacting with C"> -<?dbhtml filename="io_and_c.html"?> - <title>Interacting with C</title> - - - <sect1 id="manual.io.c.FILE" xreflabel="Using FILE* and file descriptors"> - <title>Using FILE* and file descriptors</title> - <para> - See the <link linkend="manual.ext.io">extensions</link> for using - <type>FILE</type> and <type>file descriptors</type> with - <classname>ofstream</classname> and - <classname>ifstream</classname>. - </para> - </sect1> - - <sect1 id="manual.io.c.sync" xreflabel="Performance Issues"> - <title>Performance</title> - <para> - Pathetic Performance? Ditch C. - </para> - <para>It sounds like a flame on C, but it isn't. Really. Calm down. - I'm just saying it to get your attention. - </para> - <para>Because the C++ library includes the C library, both C-style and - C++-style I/O have to work at the same time. For example: - </para> - <programlisting> - #include <iostream> - #include <cstdio> - - std::cout << "Hel"; - std::printf ("lo, worl"); - std::cout << "d!\n"; - </programlisting> - <para>This must do what you think it does. - </para> - <para>Alert members of the audience will immediately notice that buffering - is going to make a hash of the output unless special steps are taken. - </para> - <para>The special steps taken by libstdc++, at least for version 3.0, - involve doing very little buffering for the standard streams, leaving - most of the buffering to the underlying C library. (This kind of - thing is tricky to get right.) - The upside is that correctness is ensured. The downside is that - writing through <code>cout</code> can quite easily lead to awful - performance when the C++ I/O library is layered on top of the C I/O - library (as it is for 3.0 by default). Some patches have been applied - which improve the situation for 3.1. - </para> - <para>However, the C and C++ standard streams only need to be kept in sync - when both libraries' facilities are in use. If your program only uses - C++ I/O, then there's no need to sync with the C streams. The right - thing to do in this case is to call - </para> - <programlisting> - #include <emphasis>any of the I/O headers such as ios, iostream, etc</emphasis> - - std::ios::sync_with_stdio(false); - </programlisting> - <para>You must do this before performing any I/O via the C++ stream objects. - Once you call this, the C++ streams will operate independently of the - (unused) C streams. For GCC 3.x, this means that <code>cout</code> and - company will become fully buffered on their own. - </para> - <para>Note, by the way, that the synchronization requirement only applies to - the standard streams (<code>cin</code>, <code>cout</code>, - <code>cerr</code>, - <code>clog</code>, and their wide-character counterparts). File stream - objects that you declare yourself have no such requirement and are fully - buffered. - </para> - - - </sect1> -</chapter> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/iterators.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/iterators.xml deleted file mode 100644 index f5e4e065a..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/iterators.xml +++ /dev/null @@ -1,180 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.iterators" xreflabel="Iterators"> -<?dbhtml filename="iterators.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Iterators - <indexterm><primary>Iterators</primary></indexterm> -</title> - -<!-- Chapter 01 : Predefined --> -<chapter id="manual.iterators.predefined" xreflabel="Predefined"> - <title>Predefined</title> - - <sect1 id="iterators.predefined.vs_pointers" xreflabel="Versus Pointers"> - <title>Iterators vs. Pointers</title> - <para><ulink url="../faq/index.html#5_1">FAQ 5.1</ulink> points out that iterators - are not implemented as pointers. They are a generalization of - pointers, but they are implemented in libstdc++ as separate classes. - </para> - <para>Keeping that simple fact in mind as you design your code will - prevent a whole lot of difficult-to-understand bugs. - </para> - <para>You can think of it the other way 'round, even. Since iterators - are a generalization, that means that <emphasis>pointers</emphasis> are - <emphasis>iterators</emphasis>, and that pointers can be used whenever an - iterator would be. All those functions in the Algorithms chapter - of the Standard will work just as well on plain arrays and their - pointers. - </para> - <para>That doesn't mean that when you pass in a pointer, it gets wrapped - into some special delegating iterator-to-pointer class with a layer - of overhead. (If you think that's the case anywhere, you don't - understand templates to begin with...) Oh, no; if you pass - in a pointer, then the compiler will instantiate that template - using T* as a type, and good old high-speed pointer arithmetic as - its operations, so the resulting code will be doing exactly the same - things as it would be doing if you had hand-coded it yourself (for - the 273rd time). - </para> - <para>How much overhead <emphasis>is</emphasis> there when using an iterator class? - Very little. Most of the layering classes contain nothing but - typedefs, and typedefs are "meta-information" that simply - tell the compiler some nicknames; they don't create code. That - information gets passed down through inheritance, so while the - compiler has to do work looking up all the names, your runtime code - does not. (This has been a prime concern from the beginning.) - </para> - - - </sect1> - - <sect1 id="iterators.predefined.end" xreflabel="end() Is One Past the End"> - <title>One Past the End</title> - - <para>This starts off sounding complicated, but is actually very easy, - especially towards the end. Trust me. - </para> - <para>Beginners usually have a little trouble understand the whole - 'past-the-end' thing, until they remember their early algebra classes - (see, they <emphasis>told</emphasis> you that stuff would come in handy!) and - the concept of half-open ranges. - </para> - <para>First, some history, and a reminder of some of the funkier rules in - C and C++ for builtin arrays. The following rules have always been - true for both languages: - </para> - <orderedlist> - <listitem> - <para>You can point anywhere in the array, <emphasis>or to the first element - past the end of the array</emphasis>. A pointer that points to one - past the end of the array is guaranteed to be as unique as a - pointer to somewhere inside the array, so that you can compare - such pointers safely. - </para> - </listitem> - <listitem> - <para>You can only dereference a pointer that points into an array. - If your array pointer points outside the array -- even to just - one past the end -- and you dereference it, Bad Things happen. - </para> - </listitem> - <listitem> - <para>Strictly speaking, simply pointing anywhere else invokes - undefined behavior. Most programs won't puke until such a - pointer is actually dereferenced, but the standards leave that - up to the platform. - </para> - </listitem> - </orderedlist> - <para>The reason this past-the-end addressing was allowed is to make it - easy to write a loop to go over an entire array, e.g., - while (*d++ = *s++);. - </para> - <para>So, when you think of two pointers delimiting an array, don't think - of them as indexing 0 through n-1. Think of them as <emphasis>boundary - markers</emphasis>: - </para> - <programlisting> - - beginning end - | | - | | This is bad. Always having to - | | remember to add or subtract one. - | | Off-by-one bugs very common here. - V V - array of N elements - |---|---|--...--|---|---| - | 0 | 1 | ... |N-2|N-1| - |---|---|--...--|---|---| - - ^ ^ - | | - | | This is good. This is safe. This - | | is guaranteed to work. Just don't - | | dereference 'end'. - beginning end - - </programlisting> - <para>See? Everything between the boundary markers is part of the array. - Simple. - </para> - <para>Now think back to your junior-high school algebra course, when you - were learning how to draw graphs. Remember that a graph terminating - with a solid dot meant, "Everything up through this point," - and a graph terminating with an open dot meant, "Everything up - to, but not including, this point," respectively called closed - and open ranges? Remember how closed ranges were written with - brackets, <emphasis>[a,b]</emphasis>, and open ranges were written with parentheses, - <emphasis>(a,b)</emphasis>? - </para> - <para>The boundary markers for arrays describe a <emphasis>half-open range</emphasis>, - starting with (and including) the first element, and ending with (but - not including) the last element: <emphasis>[beginning,end)</emphasis>. See, I - told you it would be simple in the end. - </para> - <para>Iterators, and everything working with iterators, follows this same - time-honored tradition. A container's <code>begin()</code> method returns - an iterator referring to the first element, and its <code>end()</code> - method returns a past-the-end iterator, which is guaranteed to be - unique and comparable against any other iterator pointing into the - middle of the container. - </para> - <para>Container constructors, container methods, and algorithms, all take - pairs of iterators describing a range of values on which to operate. - All of these ranges are half-open ranges, so you pass the beginning - iterator as the starting parameter, and the one-past-the-end iterator - as the finishing parameter. - </para> - <para>This generalizes very well. You can operate on sub-ranges quite - easily this way; functions accepting a <emphasis>[first,last)</emphasis> range - don't know or care whether they are the boundaries of an entire {array, - sequence, container, whatever}, or whether they only enclose a few - elements from the center. This approach also makes zero-length - sequences very simple to recognize: if the two endpoints compare - equal, then the {array, sequence, container, whatever} is empty. - </para> - <para>Just don't dereference <code>end()</code>. - </para> - - </sect1> -</chapter> - -<!-- Chapter 02 : Stream --> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/locale.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/locale.xml deleted file mode 100644 index 9cb0a17e6..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/locale.xml +++ /dev/null @@ -1,652 +0,0 @@ -<sect1 id="manual.localization.locales.locale" xreflabel="locale"> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - locale - </keyword> - </keywordset> -</sect1info> - -<title>locale</title> - -<para> -Describes the basic locale object, including nested -classes id, facet, and the reference-counted implementation object, -class _Impl. -</para> - -<sect2 id="locales.locale.req" xreflabel="locales.locale.req"> -<title>Requirements</title> - -<para> -Class locale is non-templatized and has two distinct types nested -inside of it: -</para> - -<blockquote> -<para> -<emphasis> -class facet -22.1.1.1.2 Class locale::facet -</emphasis> -</para> -</blockquote> - -<para> -Facets actually implement locale functionality. For instance, a facet -called numpunct is the data objects that can be used to query for the -thousands separator is in the German locale. -</para> - -<para> -Literally, a facet is strictly defined: -</para> - -<itemizedlist> - <listitem> - <para> - Containing the following public data member: - </para> - <para> - <code>static locale::id id;</code> - </para> - </listitem> - - <listitem> - <para> - Derived from another facet: - </para> - <para> - <code>class gnu_codecvt: public std::ctype<user-defined-type></code> - </para> - </listitem> -</itemizedlist> - -<para> -Of interest in this class are the memory management options explicitly -specified as an argument to facet's constructor. Each constructor of a -facet class takes a std::size_t __refs argument: if __refs == 0, the -facet is deleted when the locale containing it is destroyed. If __refs -== 1, the facet is not destroyed, even when it is no longer -referenced. -</para> - -<blockquote> -<para> -<emphasis> -class id -22.1.1.1.3 - Class locale::id -</emphasis> -</para> -</blockquote> - -<para> -Provides an index for looking up specific facets. -</para> -</sect2> - -<sect2 id="locales.locale.design" xreflabel="locales.locale.design"> -<title>Design</title> - -<para> -The major design challenge is fitting an object-orientated and -non-global locale design on top of POSIX and other relevant standards, -which include the Single Unix (nee X/Open.) -</para> - -<para> -Because C and earlier versions of POSIX fall down so completely, -portability is an issue. -</para> - -</sect2> - -<sect2 id="locales.locale.impl" xreflabel="locales.locale.impl"> -<title>Implementation</title> - - <sect3 id="locale.impl.c" xreflabel="locale.impl.c"> - <title>Interacting with "C" locales</title> - -<itemizedlist> - <listitem> - <para> - <code>`locale -a`</code> displays available locales. - </para> -<blockquote> -<programlisting> -af_ZA -ar_AE -ar_AE.utf8 -ar_BH -ar_BH.utf8 -ar_DZ -ar_DZ.utf8 -ar_EG -ar_EG.utf8 -ar_IN -ar_IQ -ar_IQ.utf8 -ar_JO -ar_JO.utf8 -ar_KW -ar_KW.utf8 -ar_LB -ar_LB.utf8 -ar_LY -ar_LY.utf8 -ar_MA -ar_MA.utf8 -ar_OM -ar_OM.utf8 -ar_QA -ar_QA.utf8 -ar_SA -ar_SA.utf8 -ar_SD -ar_SD.utf8 -ar_SY -ar_SY.utf8 -ar_TN -ar_TN.utf8 -ar_YE -ar_YE.utf8 -be_BY -be_BY.utf8 -bg_BG -bg_BG.utf8 -br_FR -bs_BA -C -ca_ES -ca_ES@euro -ca_ES.utf8 -ca_ES.utf8@euro -cs_CZ -cs_CZ.utf8 -cy_GB -da_DK -da_DK.iso885915 -da_DK.utf8 -de_AT -de_AT@euro -de_AT.utf8 -de_AT.utf8@euro -de_BE -de_BE@euro -de_BE.utf8 -de_BE.utf8@euro -de_CH -de_CH.utf8 -de_DE -de_DE@euro -de_DE.utf8 -de_DE.utf8@euro -de_LU -de_LU@euro -de_LU.utf8 -de_LU.utf8@euro -el_GR -el_GR.utf8 -en_AU -en_AU.utf8 -en_BW -en_BW.utf8 -en_CA -en_CA.utf8 -en_DK -en_DK.utf8 -en_GB -en_GB.iso885915 -en_GB.utf8 -en_HK -en_HK.utf8 -en_IE -en_IE@euro -en_IE.utf8 -en_IE.utf8@euro -en_IN -en_NZ -en_NZ.utf8 -en_PH -en_PH.utf8 -en_SG -en_SG.utf8 -en_US -en_US.iso885915 -en_US.utf8 -en_ZA -en_ZA.utf8 -en_ZW -en_ZW.utf8 -es_AR -es_AR.utf8 -es_BO -es_BO.utf8 -es_CL -es_CL.utf8 -es_CO -es_CO.utf8 -es_CR -es_CR.utf8 -es_DO -es_DO.utf8 -es_EC -es_EC.utf8 -es_ES -es_ES@euro -es_ES.utf8 -es_ES.utf8@euro -es_GT -es_GT.utf8 -es_HN -es_HN.utf8 -es_MX -es_MX.utf8 -es_NI -es_NI.utf8 -es_PA -es_PA.utf8 -es_PE -es_PE.utf8 -es_PR -es_PR.utf8 -es_PY -es_PY.utf8 -es_SV -es_SV.utf8 -es_US -es_US.utf8 -es_UY -es_UY.utf8 -es_VE -es_VE.utf8 -et_EE -et_EE.utf8 -eu_ES -eu_ES@euro -eu_ES.utf8 -eu_ES.utf8@euro -fa_IR -fi_FI -fi_FI@euro -fi_FI.utf8 -fi_FI.utf8@euro -fo_FO -fo_FO.utf8 -fr_BE -fr_BE@euro -fr_BE.utf8 -fr_BE.utf8@euro -fr_CA -fr_CA.utf8 -fr_CH -fr_CH.utf8 -fr_FR -fr_FR@euro -fr_FR.utf8 -fr_FR.utf8@euro -fr_LU -fr_LU@euro -fr_LU.utf8 -fr_LU.utf8@euro -ga_IE -ga_IE@euro -ga_IE.utf8 -ga_IE.utf8@euro -gl_ES -gl_ES@euro -gl_ES.utf8 -gl_ES.utf8@euro -gv_GB -gv_GB.utf8 -he_IL -he_IL.utf8 -hi_IN -hr_HR -hr_HR.utf8 -hu_HU -hu_HU.utf8 -id_ID -id_ID.utf8 -is_IS -is_IS.utf8 -it_CH -it_CH.utf8 -it_IT -it_IT@euro -it_IT.utf8 -it_IT.utf8@euro -iw_IL -iw_IL.utf8 -ja_JP.eucjp -ja_JP.utf8 -ka_GE -kl_GL -kl_GL.utf8 -ko_KR.euckr -ko_KR.utf8 -kw_GB -kw_GB.utf8 -lt_LT -lt_LT.utf8 -lv_LV -lv_LV.utf8 -mi_NZ -mk_MK -mk_MK.utf8 -mr_IN -ms_MY -ms_MY.utf8 -mt_MT -mt_MT.utf8 -nl_BE -nl_BE@euro -nl_BE.utf8 -nl_BE.utf8@euro -nl_NL -nl_NL@euro -nl_NL.utf8 -nl_NL.utf8@euro -nn_NO -nn_NO.utf8 -no_NO -no_NO.utf8 -oc_FR -pl_PL -pl_PL.utf8 -POSIX -pt_BR -pt_BR.utf8 -pt_PT -pt_PT@euro -pt_PT.utf8 -pt_PT.utf8@euro -ro_RO -ro_RO.utf8 -ru_RU -ru_RU.koi8r -ru_RU.utf8 -ru_UA -ru_UA.utf8 -se_NO -sk_SK -sk_SK.utf8 -sl_SI -sl_SI.utf8 -sq_AL -sq_AL.utf8 -sr_YU -sr_YU@cyrillic -sr_YU.utf8 -sr_YU.utf8@cyrillic -sv_FI -sv_FI@euro -sv_FI.utf8 -sv_FI.utf8@euro -sv_SE -sv_SE.iso885915 -sv_SE.utf8 -ta_IN -te_IN -tg_TJ -th_TH -th_TH.utf8 -tl_PH -tr_TR -tr_TR.utf8 -uk_UA -uk_UA.utf8 -ur_PK -uz_UZ -vi_VN -vi_VN.tcvn -wa_BE -wa_BE@euro -yi_US -zh_CN -zh_CN.gb18030 -zh_CN.gbk -zh_CN.utf8 -zh_HK -zh_HK.utf8 -zh_TW -zh_TW.euctw -zh_TW.utf8 -</programlisting> -</blockquote> -</listitem> - - <listitem> - <para> - <code>`locale`</code> displays environmental variables that - impact how locale("") will be deduced. - </para> -<blockquote> -<programlisting> -LANG=en_US -LC_CTYPE="en_US" -LC_NUMERIC="en_US" -LC_TIME="en_US" -LC_COLLATE="en_US" -LC_MONETARY="en_US" -LC_MESSAGES="en_US" -LC_PAPER="en_US" -LC_NAME="en_US" -LC_ADDRESS="en_US" -LC_TELEPHONE="en_US" -LC_MEASUREMENT="en_US" -LC_IDENTIFICATION="en_US" -LC_ALL= -</programlisting> -</blockquote> -</listitem> -</itemizedlist> - -<para> -From Josuttis, p. 697-698, which says, that "there is only *one* -relation (of the C++ locale mechanism) to the C locale mechanism: the -global C locale is modified if a named C++ locale object is set as the -global locale" (emphasis Paolo), that is: -</para> - -<programlisting>std::locale::global(std::locale(""));</programlisting> - -<para>affects the C functions as if the following call was made:</para> - -<programlisting>std::setlocale(LC_ALL, "");</programlisting> - -<para> - On the other hand, there is *no* vice versa, that is, calling - setlocale has *no* whatsoever on the C++ locale mechanism, in - particular on the working of locale(""), which constructs the locale - object from the environment of the running program, that is, in - practice, the set of LC_ALL, LANG, etc. variable of the shell. -</para> - - </sect3> -</sect2> - -<sect2 id="locales.locale.future" xreflabel="locales.locale.future"> -<title>Future</title> - -<itemizedlist> - <listitem> - <para> - Locale initialization: at what point does _S_classic, _S_global - get initialized? Can named locales assume this initialization - has already taken place? - </para> - </listitem> - - <listitem> - <para> - Document how named locales error check when filling data - members. I.e., a fr_FR locale that doesn't have - numpunct::truename(): does it use "true"? Or is it a blank - string? What's the convention? - </para> - </listitem> - - <listitem> - <para> - Explain how locale aliasing happens. When does "de_DE" use "de" - information? What is the rule for locales composed of just an - ISO language code (say, "de") and locales with both an ISO - language code and ISO country code (say, "de_DE"). - </para> - </listitem> - - <listitem> - <para> - What should non-required facet instantiations do? If the - generic implementation is provided, then how to end-users - provide specializations? - </para> - </listitem> -</itemizedlist> -</sect2> - -<bibliography id="locales.locale.biblio" xreflabel="locales.locale.biblio"> -<title>Bibliography</title> - - <biblioentry> - <title> - The GNU C Library - </title> - - <author> - <surname>McGrath</surname> - <firstname>Roland</firstname> - </author> - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2007</year> - <holder>FSF</holder> - </copyright> - <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums> - - </biblioentry> - - <biblioentry> - <title> - Correspondence - </title> - - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2002</year> - <holder></holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 14882:1998 Programming languages - C++ - </title> - - <copyright> - <year>1998</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 9899:1999 Programming languages - C - </title> - - <copyright> - <year>1999</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) - </title> - - <copyright> - <year>1999</year> - <holder> - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> - </copyright> - - <biblioid> - <ulink url="http://www.opennc.org/austin/docreg.html"> - </ulink> - </biblioid> - - </biblioentry> - - <biblioentry> - <title> - The C++ Programming Language, Special Edition - </title> - - <author> - <surname>Stroustrup</surname> - <firstname>Bjarne</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley, Inc.</holder> - </copyright> - <pagenums>Appendix D</pagenums> - - <publisher> - <publishername> - Addison Wesley - </publishername> - </publisher> - - </biblioentry> - - - <biblioentry> - <title> - Standard C++ IOStreams and Locales - </title> - <subtitle> - Advanced Programmer's Guide and Reference - </subtitle> - - <author> - <surname>Langer</surname> - <firstname>Angelika</firstname> - </author> - - <author> - <surname>Kreft</surname> - <firstname>Klaus</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley Longman, Inc.</holder> - </copyright> - - <publisher> - <publishername> - Addison Wesley Longman - </publishername> - </publisher> - - </biblioentry> - -</bibliography> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/localization.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/localization.xml deleted file mode 100644 index 475bee186..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/localization.xml +++ /dev/null @@ -1,59 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.localization" xreflabel="Localization"> -<?dbhtml filename="localization.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Localization - <indexterm><primary>Localization</primary></indexterm> -</title> - -<!-- Chapter 01 : Locale --> -<chapter id="manual.localization.locales" xreflabel="Locales"> -<?dbhtml filename="locales.html"?> - <title>Locales</title> - - <!-- Section 01 : locale --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="locale.xml"> - </xi:include> -</chapter> - -<!-- Chapter 02 : Facet --> -<chapter id="manual.localization.facet" xreflabel="facet"> -<?dbhtml filename="facets.html"?> - <title>Facets aka Categories</title> - - <!-- Section 01 : ctype --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="ctype.xml"> - </xi:include> - - <!-- Section 02 : codecvt --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="codecvt.xml"> - </xi:include> - - <!-- Section 03 : messages --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="messages.xml"> - </xi:include> -</chapter> - -<!-- Chapter 03 : Interacting with C --> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/messages.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/messages.xml deleted file mode 100644 index dcb504a35..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/messages.xml +++ /dev/null @@ -1,604 +0,0 @@ -<sect1 id="manual.localization.facet.messages" xreflabel="messages"> -<?dbhtml filename="messages.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - messages - </keyword> - </keywordset> -</sect1info> - -<title>messages</title> - -<para> -The std::messages facet implements message retrieval functionality -equivalent to Java's java.text.MessageFormat .using either GNU gettext -or IEEE 1003.1-200 functions. -</para> - -<sect2 id="facet.messages.req" xreflabel="facet.messages.req"> -<title>Requirements</title> - -<para> -The std::messages facet is probably the most vaguely defined facet in -the standard library. It's assumed that this facility was built into -the standard library in order to convert string literals from one -locale to the other. For instance, converting the "C" locale's -<code>const char* c = "please"</code> to a German-localized <code>"bitte"</code> -during program execution. -</para> - -<blockquote> -<para> -22.2.7.1 - Template class messages [lib.locale.messages] -</para> -</blockquote> - -<para> -This class has three public member functions, which directly -correspond to three protected virtual member functions. -</para> - -<para> -The public member functions are: -</para> - -<para> -<code>catalog open(const string&, const locale&) const</code> -</para> - -<para> -<code>string_type get(catalog, int, int, const string_type&) const</code> -</para> - -<para> -<code>void close(catalog) const</code> -</para> - -<para> -While the virtual functions are: -</para> - -<para> -<code>catalog do_open(const string&, const locale&) const</code> -</para> -<blockquote> -<para> -<emphasis> --1- Returns: A value that may be passed to get() to retrieve a -message, from the message catalog identified by the string name -according to an implementation-defined mapping. The result can be used -until it is passed to close(). Returns a value less than 0 if no such -catalog can be opened. -</emphasis> -</para> -</blockquote> - -<para> -<code>string_type do_get(catalog, int, int, const string_type&) const</code> -</para> -<blockquote> -<para> -<emphasis> --3- Requires: A catalog cat obtained from open() and not yet closed. --4- Returns: A message identified by arguments set, msgid, and dfault, -according to an implementation-defined mapping. If no such message can -be found, returns dfault. -</emphasis> -</para> -</blockquote> - -<para> -<code>void do_close(catalog) const</code> -</para> -<blockquote> -<para> -<emphasis> --5- Requires: A catalog cat obtained from open() and not yet closed. --6- Effects: Releases unspecified resources associated with cat. --7- Notes: The limit on such resources, if any, is implementation-defined. -</emphasis> -</para> -</blockquote> - - -</sect2> - -<sect2 id="facet.messages.design" xreflabel="facet.messages.design"> -<title>Design</title> - -<para> -A couple of notes on the standard. -</para> - -<para> -First, why is <code>messages_base::catalog</code> specified as a typedef -to int? This makes sense for implementations that use -<code>catopen</code>, but not for others. Fortunately, it's not heavily -used and so only a minor irritant. -</para> - -<para> -Second, by making the member functions <code>const</code>, it is -impossible to save state in them. Thus, storing away information used -in the 'open' member function for use in 'get' is impossible. This is -unfortunate. -</para> - -<para> -The 'open' member function in particular seems to be oddly -designed. The signature seems quite peculiar. Why specify a <code>const -string& </code> argument, for instance, instead of just <code>const -char*</code>? Or, why specify a <code>const locale&</code> argument that is -to be used in the 'get' member function? How, exactly, is this locale -argument useful? What was the intent? It might make sense if a locale -argument was associated with a given default message string in the -'open' member function, for instance. Quite murky and unclear, on -reflection. -</para> - -<para> -Lastly, it seems odd that messages, which explicitly require code -conversion, don't use the codecvt facet. Because the messages facet -has only one template parameter, it is assumed that ctype, and not -codecvt, is to be used to convert between character sets. -</para> - -<para> -It is implicitly assumed that the locale for the default message -string in 'get' is in the "C" locale. Thus, all source code is assumed -to be written in English, so translations are always from "en_US" to -other, explicitly named locales. -</para> - -</sect2> - -<sect2 id="facet.messages.impl" xreflabel="facet.messages.impl"> -<title>Implementation</title> - - <sect3 id="messages.impl.models" xreflabel="messages.impl.models"> - <title>Models</title> - <para> - This is a relatively simple class, on the face of it. The standard - specifies very little in concrete terms, so generic - implementations that are conforming yet do very little are the - norm. Adding functionality that would be useful to programmers and - comparable to Java's java.text.MessageFormat takes a bit of work, - and is highly dependent on the capabilities of the underlying - operating system. - </para> - - <para> - Three different mechanisms have been provided, selectable via - configure flags: - </para> - -<itemizedlist> - <listitem> - <para> - generic - </para> - <para> - This model does very little, and is what is used by default. - </para> - </listitem> - - <listitem> - <para> - gnu - </para> - <para> - The gnu model is complete and fully tested. It's based on the - GNU gettext package, which is part of glibc. It uses the - functions <code>textdomain, bindtextdomain, gettext</code> to - implement full functionality. Creating message catalogs is a - relatively straight-forward process and is lightly documented - below, and fully documented in gettext's distributed - documentation. - </para> - </listitem> - - <listitem> - <para> - ieee_1003.1-200x - </para> - <para> - This is a complete, though untested, implementation based on - the IEEE standard. The functions <code>catopen, catgets, - catclose</code> are used to retrieve locale-specific messages - given the appropriate message catalogs that have been - constructed for their use. Note, the script <code> - po2msg.sed</code> that is part of the gettext distribution can - convert gettext catalogs into catalogs that - <code>catopen</code> can use. - </para> - </listitem> -</itemizedlist> - -<para> -A new, standards-conformant non-virtual member function signature was -added for 'open' so that a directory could be specified with a given -message catalog. This simplifies calling conventions for the gnu -model. -</para> - - </sect3> - - <sect3 id="messages.impl.gnu" xreflabel="messages.impl.gnu"> - <title>The GNU Model</title> - - <para> - The messages facet, because it is retrieving and converting - between characters sets, depends on the ctype and perhaps the - codecvt facet in a given locale. In addition, underlying "C" - library locale support is necessary for more than just the - <code>LC_MESSAGES</code> mask: <code>LC_CTYPE</code> is also - necessary. To avoid any unpleasantness, all bits of the "C" mask - (i.e. <code>LC_ALL</code>) are set before retrieving messages. - </para> - - <para> - Making the message catalogs can be initially tricky, but become - quite simple with practice. For complete info, see the gettext - documentation. Here's an idea of what is required: - </para> - -<itemizedlist> - <listitem> - <para> - Make a source file with the required string literals that need - to be translated. See <code>intl/string_literals.cc</code> for - an example. - </para> - </listitem> - - <listitem> - <para> - Make initial catalog (see "4 Making the PO Template File" from - the gettext docs).</para> - <para> - <code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code> - </para> - </listitem> - - <listitem> - <para>Make language and country-specific locale catalogs.</para> - <para> - <code>cp libstdc++.pot fr_FR.po</code> - </para> - <para> - <code>cp libstdc++.pot de_DE.po</code> - </para> - </listitem> - - <listitem> - <para> - Edit localized catalogs in emacs so that strings are - translated. - </para> - <para> - <code>emacs fr_FR.po</code> - </para> - </listitem> - - <listitem> - <para>Make the binary mo files.</para> - <para> - <code>msgfmt fr_FR.po -o fr_FR.mo</code> - </para> - <para> - <code>msgfmt de_DE.po -o de_DE.mo</code> - </para> - </listitem> - - <listitem> - <para>Copy the binary files into the correct directory structure.</para> - <para> - <code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo</code> - </para> - <para> - <code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo</code> - </para> - </listitem> - - <listitem> - <para>Use the new message catalogs.</para> - <para> - <code>locale loc_de("de_DE");</code> - </para> - <para> - <code> - use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); - </code> - </para> - </listitem> -</itemizedlist> - - </sect3> -</sect2> - -<sect2 id="facet.messages.use" xreflabel="facet.messages.use"> -<title>Use</title> - <para> - A simple example using the GNU model of message conversion. - </para> - -<programlisting> -#include <iostream> -#include <locale> -using namespace std; - -void test01() -{ - typedef messages<char>::catalog catalog; - const char* dir = - "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale"; - const locale loc_de("de_DE"); - const messages<char>& mssg_de = use_facet<messages<char> >(loc_de); - - catalog cat_de = mssg_de.open("libstdc++", loc_de, dir); - string s01 = mssg_de.get(cat_de, 0, 0, "please"); - string s02 = mssg_de.get(cat_de, 0, 0, "thank you"); - cout << "please in german:" << s01 << '\n'; - cout << "thank you in german:" << s02 << '\n'; - mssg_de.close(cat_de); -} -</programlisting> - -</sect2> - -<sect2 id="facet.messages.future" xreflabel="facet.messages.future"> -<title>Future</title> - -<itemizedlist> -<listitem> - <para> - Things that are sketchy, or remain unimplemented: - </para> - <itemizedlist> - <listitem> - <para> - _M_convert_from_char, _M_convert_to_char are in flux, - depending on how the library ends up doing character set - conversions. It might not be possible to do a real character - set based conversion, due to the fact that the template - parameter for messages is not enough to instantiate the - codecvt facet (1 supplied, need at least 2 but would prefer - 3). - </para> - </listitem> - - <listitem> - <para> - There are issues with gettext needing the global locale set - to extract a message. This dependence on the global locale - makes the current "gnu" model non MT-safe. Future versions - of glibc, i.e. glibc 2.3.x will fix this, and the C++ library - bits are already in place. - </para> - </listitem> - </itemizedlist> -</listitem> - -<listitem> - <para> - Development versions of the GNU "C" library, glibc 2.3 will allow - a more efficient, MT implementation of std::messages, and will - allow the removal of the _M_name_messages data member. If this is - done, it will change the library ABI. The C++ parts to support - glibc 2.3 have already been coded, but are not in use: once this - version of the "C" library is released, the marked parts of the - messages implementation can be switched over to the new "C" - library functionality. - </para> -</listitem> -<listitem> - <para> - At some point in the near future, std::numpunct will probably use - std::messages facilities to implement truename/falsename - correctly. This is currently not done, but entries in - libstdc++.pot have already been made for "true" and "false" string - literals, so all that remains is the std::numpunct coding and the - configure/make hassles to make the installed library search its - own catalog. Currently the libstdc++.mo catalog is only searched - for the testsuite cases involving messages members. - </para> -</listitem> - -<listitem> - <para> The following member functions:</para> - - <para> - <code> - catalog - open(const basic_string<char>& __s, const locale& __loc) const - </code> - </para> - - <para> - <code> - catalog - open(const basic_string<char>&, const locale&, const char*) const; - </code> - </para> - - <para> - Don't actually return a "value less than 0 if no such catalog - can be opened" as required by the standard in the "gnu" - model. As of this writing, it is unknown how to query to see - if a specified message catalog exists using the gettext - package. - </para> -</listitem> -</itemizedlist> - -</sect2> - -<bibliography id="facet.messages.biblio" xreflabel="facet.messages.biblio"> -<title>Bibliography</title> - - <biblioentry> - <title> - The GNU C Library - </title> - - <author> - <surname>McGrath</surname> - <firstname>Roland</firstname> - </author> - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2007</year> - <holder>FSF</holder> - </copyright> - <pagenums>Chapters 6 Character Set Handling, and 7 Locales and Internationalization - </pagenums> - - </biblioentry> - - <biblioentry> - <title> - Correspondence - </title> - - <author> - <surname>Drepper</surname> - <firstname>Ulrich</firstname> - </author> - - <copyright> - <year>2002</year> - <holder></holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 14882:1998 Programming languages - C++ - </title> - - <copyright> - <year>1998</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - ISO/IEC 9899:1999 Programming languages - C - </title> - - <copyright> - <year>1999</year> - <holder>ISO</holder> - </copyright> - </biblioentry> - - <biblioentry> - <title> - System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) - </title> - - <copyright> - <year>1999</year> - <holder> - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder> - </copyright> - - <biblioid> - <ulink url="http://www.opennc.org/austin/docreg.html"> - </ulink> - </biblioid> - - </biblioentry> - - <biblioentry> - <title> - The C++ Programming Language, Special Edition - </title> - - <author> - <surname>Stroustrup</surname> - <firstname>Bjarne</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley, Inc.</holder> - </copyright> - <pagenums>Appendix D</pagenums> - - <publisher> - <publishername> - Addison Wesley - </publishername> - </publisher> - - </biblioentry> - - - <biblioentry> - <title> - Standard C++ IOStreams and Locales - </title> - <subtitle> - Advanced Programmer's Guide and Reference - </subtitle> - - <author> - <surname>Langer</surname> - <firstname>Angelika</firstname> - </author> - - <author> - <surname>Kreft</surname> - <firstname>Klaus</firstname> - </author> - - <copyright> - <year>2000</year> - <holder>Addison Wesley Longman, Inc.</holder> - </copyright> - - <publisher> - <publishername> - Addison Wesley Longman - </publishername> - </publisher> - - </biblioentry> - - <biblioentry> - <title> - Java 2 Platform, Standard Edition, v 1.3.1 API Specification - </title> - <pagenums>java.util.Properties, java.text.MessageFormat, -java.util.Locale, java.util.ResourceBundle</pagenums> - <biblioid> - <ulink url="http://java.sun.com/j2se/1.3/docs/api"> - </ulink> - </biblioid> - </biblioentry> - - <biblioentry> - <title> - GNU gettext tools, version 0.10.38, Native Language Support -Library and Tools. - </title> - <biblioid> - <ulink url="http://sources.redhat.com/gettext"> - </ulink> - </biblioid> - </biblioentry> - -</bibliography> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/mt_allocator.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/mt_allocator.xml deleted file mode 100644 index 48f5c2fe5..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/mt_allocator.xml +++ /dev/null @@ -1,554 +0,0 @@ -<sect1 id="manual.ext.allocator.mt" xreflabel="mt allocator"> -<?dbhtml filename="mt_allocator.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - allocator - </keyword> - </keywordset> -</sect1info> - -<title>mt_allocator</title> - -<para> -</para> - -<sect2 id="allocator.mt.intro" xreflabel="allocator.mt.intro"> -<title>Intro</title> - -<para> - The mt allocator [hereinafter referred to simply as "the allocator"] - is a fixed size (power of two) allocator that was initially - developed specifically to suit the needs of multi threaded - applications [hereinafter referred to as an MT application]. Over - time the allocator has evolved and been improved in many ways, in - particular it now also does a good job in single threaded - applications [hereinafter referred to as a ST application]. (Note: - In this document, when referring to single threaded applications - this also includes applications that are compiled with gcc without - thread support enabled. This is accomplished using ifdef's on - __GTHREADS). This allocator is tunable, very flexible, and capable - of high-performance. -</para> - -<para> - The aim of this document is to describe - from an application point of - view - the "inner workings" of the allocator. -</para> - -</sect2> - - -<sect2 id="allocator.mt.design_issues" xreflabel="allocator.mt.design_issues"> -<title>Design Issues</title> - -<sect3 id="allocator.mt.overview" xreflabel="allocator.mt.overview"> -<title>Overview</title> - - -<para> There are three general components to the allocator: a datum -describing the characteristics of the memory pool, a policy class -containing this pool that links instantiation types to common or -individual pools, and a class inheriting from the policy class that is -the actual allocator. -</para> - -<para>The datum describing pools characteristics is -</para> -<programlisting> - template<bool _Thread> - class __pool -</programlisting> -<para> This class is parametrized on thread support, and is explicitly -specialized for both multiple threads (with <code>bool==true</code>) -and single threads (via <code>bool==false</code>.) It is possible to -use a custom pool datum instead of the default class that is provided. -</para> - -<para> There are two distinct policy classes, each of which can be used -with either type of underlying pool datum. -</para> - -<programlisting> - template<bool _Thread> - struct __common_pool_policy - - template<typename _Tp, bool _Thread> - struct __per_type_pool_policy -</programlisting> - -<para> The first policy, <code>__common_pool_policy</code>, implements a -common pool. This means that allocators that are instantiated with -different types, say <code>char</code> and <code>long</code> will both -use the same pool. This is the default policy. -</para> - -<para> The second policy, <code>__per_type_pool_policy</code>, implements -a separate pool for each instantiating type. Thus, <code>char</code> -and <code>long</code> will use separate pools. This allows per-type -tuning, for instance. -</para> - -<para> Putting this all together, the actual allocator class is -</para> -<programlisting> - template<typename _Tp, typename _Poolp = __default_policy> - class __mt_alloc : public __mt_alloc_base<_Tp>, _Poolp -</programlisting> -<para> This class has the interface required for standard library allocator -classes, namely member functions <code>allocate</code> and -<code>deallocate</code>, plus others. -</para> - -</sect3> -</sect2> - -<sect2 id="allocator.mt.impl" xreflabel="allocator.mt.impl"> -<title>Implementation</title> - - -<sect3 id="allocator.mt.tune" xreflabel="allocator.mt.tune"> -<title>Tunable Parameters</title> - -<para>Certain allocation parameters can be modified, or tuned. There -exists a nested <code>struct __pool_base::_Tune</code> that contains all -these parameters, which include settings for -</para> - <itemizedlist> - <listitem><para>Alignment</para></listitem> - <listitem><para>Maximum bytes before calling <code>::operator new</code> directly</para></listitem> - <listitem><para>Minimum bytes</para></listitem> - <listitem><para>Size of underlying global allocations</para></listitem> - <listitem><para>Maximum number of supported threads</para></listitem> - <listitem><para>Migration of deallocations to the global free list</para></listitem> - <listitem><para>Shunt for global <code>new</code> and <code>delete</code></para></listitem> - </itemizedlist> -<para>Adjusting parameters for a given instance of an allocator can only -happen before any allocations take place, when the allocator itself is -initialized. For instance: -</para> -<programlisting> -#include <ext/mt_allocator.h> - -struct pod -{ - int i; - int j; -}; - -int main() -{ - typedef pod value_type; - typedef __gnu_cxx::__mt_alloc<value_type> allocator_type; - typedef __gnu_cxx::__pool_base::_Tune tune_type; - - tune_type t_default; - tune_type t_opt(16, 5120, 32, 5120, 20, 10, false); - tune_type t_single(16, 5120, 32, 5120, 1, 10, false); - - tune_type t; - t = allocator_type::_M_get_options(); - allocator_type::_M_set_options(t_opt); - t = allocator_type::_M_get_options(); - - allocator_type a; - allocator_type::pointer p1 = a.allocate(128); - allocator_type::pointer p2 = a.allocate(5128); - - a.deallocate(p1, 128); - a.deallocate(p2, 5128); - - return 0; -} -</programlisting> - -</sect3> - -<sect3 id="allocator.mt.init" xreflabel="allocator.mt.init"> -<title>Initialization</title> - -<para> -The static variables (pointers to freelists, tuning parameters etc) -are initialized as above, or are set to the global defaults. -</para> - -<para> -The very first allocate() call will always call the -_S_initialize_once() function. In order to make sure that this -function is called exactly once we make use of a __gthread_once call -in MT applications and check a static bool (_S_init) in ST -applications. -</para> - -<para> -The _S_initialize() function: -- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool - _S_force_new to true and then returns. This will cause subsequent calls to - allocate() to return memory directly from a new() call, and deallocate will - only do a delete() call. -</para> - -<para> -- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT - applications will: - - Calculate the number of bins needed. A bin is a specific power of two size - of bytes. I.e., by default the allocator will deal with requests of up to - 128 bytes (or whatever the value of _S_max_bytes is when _S_init() is - called). This means that there will be bins of the following sizes - (in bytes): 1, 2, 4, 8, 16, 32, 64, 128. - - - Create the _S_binmap array. All requests are rounded up to the next - "large enough" bin. I.e., a request for 29 bytes will cause a block from - the "32 byte bin" to be returned to the application. The purpose of - _S_binmap is to speed up the process of finding out which bin to use. - I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes). -</para> -<para> - - Create the _S_bin array. This array consists of bin_records. There will be - as many bin_records in this array as the number of bins that we calculated - earlier. I.e., if _S_max_bytes = 128 there will be 8 entries. - Each bin_record is then initialized: - - bin_record->first = An array of pointers to block_records. There will be - as many block_records pointers as there are maximum number of threads - (in a ST application there is only 1 thread, in a MT application there - are _S_max_threads). - This holds the pointer to the first free block for each thread in this - bin. I.e., if we would like to know where the first free block of size 32 - for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ] - - The above created block_record pointers members are now initialized to - their initial values. I.e. _S_bin[ n ].first[ n ] = NULL; -</para> - -<para> -- Additionally a MT application will: - - Create a list of free thread id's. The pointer to the first entry - is stored in _S_thread_freelist_first. The reason for this approach is - that the __gthread_self() call will not return a value that corresponds to - the maximum number of threads allowed but rather a process id number or - something else. So what we do is that we create a list of thread_records. - This list is _S_max_threads long and each entry holds a size_t thread_id - which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads. - Each time a thread calls allocate() or deallocate() we call - _S_get_thread_id() which looks at the value of _S_thread_key which is a - thread local storage pointer. If this is NULL we know that this is a newly - created thread and we pop the first entry from this list and saves the - pointer to this record in the _S_thread_key variable. The next time - we will get the pointer to the thread_record back and we use the - thread_record->thread_id as identification. I.e., the first thread that - calls allocate will get the first record in this list and thus be thread - number 1 and will then find the pointer to its first free 32 byte block - in _S_bin[ 5 ].first[ 1 ] - When we create the _S_thread_key we also define a destructor - (_S_thread_key_destr) which means that when the thread dies, this - thread_record is returned to the front of this list and the thread id - can then be reused if a new thread is created. - This list is protected by a mutex (_S_thread_freelist_mutex) which is only - locked when records are removed or added to the list. -</para> -<para> - - Initialize the free and used counters of each bin_record: - - bin_record->free = An array of size_t. This keeps track of the number - of blocks on a specific thread's freelist in each bin. I.e., if a thread - has 12 32-byte blocks on it's freelists and allocates one of these, this - counter would be decreased to 11. - - - bin_record->used = An array of size_t. This keeps track of the number - of blocks currently in use of this size by this thread. I.e., if a thread - has made 678 requests (and no deallocations...) of 32-byte blocks this - counter will read 678. - - The above created arrays are now initialized with their initial values. - I.e. _S_bin[ n ].free[ n ] = 0; -</para> -<para> - - Initialize the mutex of each bin_record: The bin_record->mutex - is used to protect the global freelist. This concept of a global - freelist is explained in more detail in the section "A multi - threaded example", but basically this mutex is locked whenever a - block of memory is retrieved or returned to the global freelist - for this specific bin. This only occurs when a number of blocks - are grabbed from the global list to a thread specific list or when - a thread decides to return some blocks to the global freelist. -</para> - -</sect3> - -<sect3 id="allocator.mt.deallocation" xreflabel="allocator.mt.deallocation"> -<title>Deallocation Notes</title> - -<para> Notes about deallocation. This allocator does not explicitly -release memory. Because of this, memory debugging programs like -valgrind or purify may notice leaks: sorry about this -inconvenience. Operating systems will reclaim allocated memory at -program termination anyway. If sidestepping this kind of noise is -desired, there are three options: use an allocator, like -<code>new_allocator</code> that releases memory while debugging, use -GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a -custom pool datum that releases resources on destruction. -</para> - -<para> - On systems with the function <code>__cxa_atexit</code>, the -allocator can be forced to free all memory allocated before program -termination with the member function -<code>__pool_type::_M_destroy</code>. However, because this member -function relies on the precise and exactly-conforming ordering of -static destructors, including those of a static local -<code>__pool</code> object, it should not be used, ever, on systems -that don't have the necessary underlying support. In addition, in -practice, forcing deallocation can be tricky, as it requires the -<code>__pool</code> object to be fully-constructed before the object -that uses it is fully constructed. For most (but not all) STL -containers, this works, as an instance of the allocator is constructed -as part of a container's constructor. However, this assumption is -implementation-specific, and subject to change. For an example of a -pool that frees memory, see the following - <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/ext/mt_allocator/deallocate_local-6.cc?view=markup"> - example.</ulink> -</para> - -</sect3> - -</sect2> - -<sect2 id="allocator.mt.example_single" xreflabel="allocator.mt.example_single"> -<title>Single Thread Example</title> - -<para> -Let's start by describing how the data on a freelist is laid out in memory. -This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes): -</para> -<programlisting> -+----------------+ -| next* ---------|--+ (_S_bin[ 3 ].first[ 3 ] points here) -| | | -| | | -| | | -+----------------+ | -| thread_id = 3 | | -| | | -| | | -| | | -+----------------+ | -| DATA | | (A pointer to here is what is returned to the -| | | the application when needed) -| | | -| | | -| | | -| | | -| | | -| | | -+----------------+ | -+----------------+ | -| next* |<-+ (If next == NULL it's the last one on the list) -| | -| | -| | -+----------------+ -| thread_id = 3 | -| | -| | -| | -+----------------+ -| DATA | -| | -| | -| | -| | -| | -| | -| | -+----------------+ -</programlisting> - -<para> -With this in mind we simplify things a bit for a while and say that there is -only one thread (a ST application). In this case all operations are made to -what is referred to as the global pool - thread id 0 (No thread may be -assigned this id since they span from 1 to _S_max_threads in a MT application). -</para> -<para> -When the application requests memory (calling allocate()) we first look at the -requested size and if this is > _S_max_bytes we call new() directly and return. -</para> -<para> -If the requested size is within limits we start by finding out from which -bin we should serve this request by looking in _S_binmap. -</para> -<para> -A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of -this size on the freelist (0). If this is not NULL - fine, just remove the -block that _S_bin[ bin ].first[ 0 ] points to from the list, -update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data. -</para> -<para> -If the freelist is empty (the pointer is NULL) we must get memory from the -system and build us a freelist within this memory. All requests for new memory -is made in chunks of _S_chunk_size. Knowing the size of a block_record and -the bytes that this bin stores we then calculate how many blocks we can create -within this chunk, build the list, remove the first block, update the pointer -(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data. -</para> - -<para> -Deallocation is equally simple; the pointer is casted back to a block_record -pointer, lookup which bin to use based on the size, add the block to the front -of the global freelist and update the pointer as needed -(_S_bin[ bin ].first[ 0 ]). -</para> - -<para> -The decision to add deallocated blocks to the front of the freelist was made -after a set of performance measurements that showed that this is roughly 10% -faster than maintaining a set of "last pointers" as well. -</para> - -</sect2> - -<sect2 id="allocator.mt.example_multi" xreflabel="allocator.mt.example_multi"> -<title>Multiple Thread Example</title> - -<para> -In the ST example we never used the thread_id variable present in each block. -Let's start by explaining the purpose of this in a MT application. -</para> - -<para> -The concept of "ownership" was introduced since many MT applications -allocate and deallocate memory to shared containers from different -threads (such as a cache shared amongst all threads). This introduces -a problem if the allocator only returns memory to the current threads -freelist (I.e., there might be one thread doing all the allocation and -thus obtaining ever more memory from the system and another thread -that is getting a longer and longer freelist - this will in the end -consume all available memory). -</para> - -<para> -Each time a block is moved from the global list (where ownership is -irrelevant), to a threads freelist (or when a new freelist is built -from a chunk directly onto a threads freelist or when a deallocation -occurs on a block which was not allocated by the same thread id as the -one doing the deallocation) the thread id is set to the current one. -</para> - -<para> -What's the use? Well, when a deallocation occurs we can now look at -the thread id and find out if it was allocated by another thread id -and decrease the used counter of that thread instead, thus keeping the -free and used counters correct. And keeping the free and used counters -corrects is very important since the relationship between these two -variables decides if memory should be returned to the global pool or -not when a deallocation occurs. -</para> - -<para> -When the application requests memory (calling allocate()) we first -look at the requested size and if this is >_S_max_bytes we call new() -directly and return. -</para> - -<para> -If the requested size is within limits we start by finding out from which -bin we should serve this request by looking in _S_binmap. -</para> - -<para> -A call to _S_get_thread_id() returns the thread id for the calling thread -(and if no value has been set in _S_thread_key, a new id is assigned and -returned). -</para> - -<para> -A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are -any blocks of this size on the current threads freelist. If this is -not NULL - fine, just remove the block that _S_bin[ bin ].first[ -thread_id ] points to from the list, update _S_bin[ bin ].first[ -thread_id ], update the free and used counters and return a pointer to -that blocks data. -</para> - -<para> -If the freelist is empty (the pointer is NULL) we start by looking at -the global freelist (0). If there are blocks available on the global -freelist we lock this bins mutex and move up to block_count (the -number of blocks of this bins size that will fit into a _S_chunk_size) -or until end of list - whatever comes first - to the current threads -freelist and at the same time change the thread_id ownership and -update the counters and pointers. When the bins mutex has been -unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ] -points to from the list, update _S_bin[ bin ].first[ thread_id ], -update the free and used counters, and return a pointer to that blocks -data. -</para> - -<para> -The reason that the number of blocks moved to the current threads -freelist is limited to block_count is to minimize the chance that a -subsequent deallocate() call will return the excess blocks to the -global freelist (based on the _S_freelist_headroom calculation, see -below). -</para> - -<para> -However if there isn't any memory on the global pool we need to get -memory from the system - this is done in exactly the same way as in a -single threaded application with one major difference; the list built -in the newly allocated memory (of _S_chunk_size size) is added to the -current threads freelist instead of to the global. -</para> - -<para> -The basic process of a deallocation call is simple: always add the -block to the front of the current threads freelist and update the -counters and pointers (as described earlier with the specific check of -ownership that causes the used counter of the thread that originally -allocated the block to be decreased instead of the current threads -counter). -</para> - -<para> -And here comes the free and used counters to service. Each time a -deallocation() call is made, the length of the current threads -freelist is compared to the amount memory in use by this thread. -</para> - -<para> -Let's go back to the example of an application that has one thread -that does all the allocations and one that deallocates. Both these -threads use say 516 32-byte blocks that was allocated during thread -creation for example. Their used counters will both say 516 at this -point. The allocation thread now grabs 1000 32-byte blocks and puts -them in a shared container. The used counter for this thread is now -1516. -</para> - -<para> -The deallocation thread now deallocates 500 of these blocks. For each -deallocation made the used counter of the allocating thread is -decreased and the freelist of the deallocation thread gets longer and -longer. But the calculation made in deallocate() will limit the length -of the freelist in the deallocation thread to _S_freelist_headroom % -of it's used counter. In this case, when the freelist (given that the -_S_freelist_headroom is at it's default value of 10%) exceeds 52 -(516/10) blocks will be returned to the global pool where the -allocating thread may pick them up and reuse them. -</para> - -<para> -In order to reduce lock contention (since this requires this bins -mutex to be locked) this operation is also made in chunks of blocks -(just like when chunks of blocks are moved from the global freelist to -a threads freelist mentioned above). The "formula" used can probably -be improved to further reduce the risk of blocks being "bounced back -and forth" between freelists. -</para> - -</sect2> - -</sect1>
\ No newline at end of file diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/numerics.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/numerics.xml deleted file mode 100644 index 138531464..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/numerics.xml +++ /dev/null @@ -1,149 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.numerics" xreflabel="Numerics"> -<?dbhtml filename="numerics.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Numerics - <indexterm><primary>Numerics</primary></indexterm> -</title> - -<!-- Chapter 01 : Complex --> -<chapter id="manual.numerics.complex" xreflabel="complex"> -<?dbhtml filename="complex.html"?> - <title>Complex</title> - <para> - </para> - <sect1 id="numerics.complex.processing" xreflabel="complex Processing"> - <title>complex Processing</title> - <para> - </para> - <para>Using <code>complex<></code> becomes even more comple- er, sorry, - <emphasis>complicated</emphasis>, with the not-quite-gratuitously-incompatible - addition of complex types to the C language. David Tribble has - compiled a list of C++98 and C99 conflict points; his description of - C's new type versus those of C++ and how to get them playing together - nicely is -<ulink url="http://david.tribble.com/text/cdiffs.htm#C99-complex">here</ulink>. - </para> - <para><code>complex<></code> is intended to be instantiated with a - floating-point type. As long as you meet that and some other basic - requirements, then the resulting instantiation has all of the usual - math operators defined, as well as definitions of <code>op<<</code> - and <code>op>></code> that work with iostreams: <code>op<<</code> - prints <code>(u,v)</code> and <code>op>></code> can read <code>u</code>, - <code>(u)</code>, and <code>(u,v)</code>. - </para> - - </sect1> -</chapter> - -<!-- Chapter 02 : Generalized Operations --> -<chapter id="manual.numerics.generalized_ops" xreflabel="Generalized Ops"> -<?dbhtml filename="generalized_numeric_operations.html"?> - <title>Generalized Operations</title> - <para> - </para> - - <para>There are four generalized functions in the <numeric> header - that follow the same conventions as those in <algorithm>. Each - of them is overloaded: one signature for common default operations, - and a second for fully general operations. Their names are - self-explanatory to anyone who works with numerics on a regular basis: - </para> - <itemizedlist> - <listitem><para><code>accumulate</code></para></listitem> - <listitem><para><code>inner_product</code></para></listitem> - <listitem><para><code>partial_sum</code></para></listitem> - <listitem><para><code>adjacent_difference</code></para></listitem> - </itemizedlist> - <para>Here is a simple example of the two forms of <code>accumulate</code>. - </para> - <programlisting> - int ar[50]; - int someval = somefunction(); - - // ...initialize members of ar to something... - - int sum = std::accumulate(ar,ar+50,0); - int sum_stuff = std::accumulate(ar,ar+50,someval); - int product = std::accumulate(ar,ar+50,1,std::multiplies<int>()); - </programlisting> - <para>The first call adds all the members of the array, using zero as an - initial value for <code>sum</code>. The second does the same, but uses - <code>someval</code> as the starting value (thus, <code>sum_stuff == sum + - someval</code>). The final call uses the second of the two signatures, - and multiplies all the members of the array; here we must obviously - use 1 as a starting value instead of 0. - </para> - <para>The other three functions have similar dual-signature forms. - </para> - -</chapter> - -<!-- Chapter 03 : Interacting with C --> -<chapter id="manual.numerics.c" xreflabel="Interacting with C"> -<?dbhtml filename="numerics_and_c.html"?> - <title>Interacting with C</title> - - <sect1 id="numerics.c.array" xreflabel="Numerics vs. Arrays"> - <title>Numerics vs. Arrays</title> - - <para>One of the major reasons why FORTRAN can chew through numbers so well - is that it is defined to be free of pointer aliasing, an assumption - that C89 is not allowed to make, and neither is C++98. C99 adds a new - keyword, <code>restrict</code>, to apply to individual pointers. The - C++ solution is contained in the library rather than the language - (although many vendors can be expected to add this to their compilers - as an extension). - </para> - <para>That library solution is a set of two classes, five template classes, - and "a whole bunch" of functions. The classes are required - to be free of pointer aliasing, so compilers can optimize the - daylights out of them the same way that they have been for FORTRAN. - They are collectively called <code>valarray</code>, although strictly - speaking this is only one of the five template classes, and they are - designed to be familiar to people who have worked with the BLAS - libraries before. - </para> - - </sect1> - - <sect1 id="numerics.c.c99" xreflabel="C99"> - <title>C99</title> - - <para>In addition to the other topics on this page, we'll note here some - of the C99 features that appear in libstdc++. - </para> - <para>The C99 features depend on the <code>--enable-c99</code> configure flag. - This flag is already on by default, but it can be disabled by the - user. Also, the configuration machinery will disable it if the - necessary support for C99 (e.g., header files) cannot be found. - </para> - <para>As of GCC 3.0, C99 support includes classification functions - such as <code>isnormal</code>, <code>isgreater</code>, - <code>isnan</code>, etc. - The functions used for 'long long' support such as <code>strtoll</code> - are supported, as is the <code>lldiv_t</code> typedef. Also supported - are the wide character functions using 'long long', like - <code>wcstoll</code>. - </para> - - </sect1> -</chapter> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/parallel_mode.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/parallel_mode.xml deleted file mode 100644 index 7cb2a0598..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/parallel_mode.xml +++ /dev/null @@ -1,896 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<chapter id="manual.ext.parallel_mode" xreflabel="Parallel Mode"> -<?dbhtml filename="parallel_mode.html"?> - -<chapterinfo> - <keywordset> - <keyword> - C++ - </keyword> - <keyword> - library - </keyword> - <keyword> - parallel - </keyword> - </keywordset> -</chapterinfo> - -<title>Parallel Mode</title> - -<para> The libstdc++ parallel mode is an experimental parallel -implementation of many algorithms the C++ Standard Library. -</para> - -<para> -Several of the standard algorithms, for instance -<function>std::sort</function>, are made parallel using OpenMP -annotations. These parallel mode constructs and can be invoked by -explicit source declaration or by compiling existing sources with a -specific compiler flag. -</para> - - -<sect1 id="manual.ext.parallel_mode.intro" xreflabel="Intro"> - <title>Intro</title> - -<para>The following library components in the include -<filename class="headerfile">numeric</filename> are included in the parallel mode:</para> -<itemizedlist> - <listitem><para><function>std::accumulate</function></para></listitem> - <listitem><para><function>std::adjacent_difference</function></para></listitem> - <listitem><para><function>std::inner_product</function></para></listitem> - <listitem><para><function>std::partial_sum</function></para></listitem> -</itemizedlist> - -<para>The following library components in the include -<filename class="headerfile">algorithm</filename> are included in the parallel mode:</para> -<itemizedlist> - <listitem><para><function>std::adjacent_find</function></para></listitem> - <listitem><para><function>std::count</function></para></listitem> - <listitem><para><function>std::count_if</function></para></listitem> - <listitem><para><function>std::equal</function></para></listitem> - <listitem><para><function>std::find</function></para></listitem> - <listitem><para><function>std::find_if</function></para></listitem> - <listitem><para><function>std::find_first_of</function></para></listitem> - <listitem><para><function>std::for_each</function></para></listitem> - <listitem><para><function>std::generate</function></para></listitem> - <listitem><para><function>std::generate_n</function></para></listitem> - <listitem><para><function>std::lexicographical_compare</function></para></listitem> - <listitem><para><function>std::mismatch</function></para></listitem> - <listitem><para><function>std::search</function></para></listitem> - <listitem><para><function>std::search_n</function></para></listitem> - <listitem><para><function>std::transform</function></para></listitem> - <listitem><para><function>std::replace</function></para></listitem> - <listitem><para><function>std::replace_if</function></para></listitem> - <listitem><para><function>std::max_element</function></para></listitem> - <listitem><para><function>std::merge</function></para></listitem> - <listitem><para><function>std::min_element</function></para></listitem> - <listitem><para><function>std::nth_element</function></para></listitem> - <listitem><para><function>std::partial_sort</function></para></listitem> - <listitem><para><function>std::partition</function></para></listitem> - <listitem><para><function>std::random_shuffle</function></para></listitem> - <listitem><para><function>std::set_union</function></para></listitem> - <listitem><para><function>std::set_intersection</function></para></listitem> - <listitem><para><function>std::set_symmetric_difference</function></para></listitem> - <listitem><para><function>std::set_difference</function></para></listitem> - <listitem><para><function>std::sort</function></para></listitem> - <listitem><para><function>std::stable_sort</function></para></listitem> - <listitem><para><function>std::unique_copy</function></para></listitem> -</itemizedlist> - -</sect1> - -<sect1 id="manual.ext.parallel_mode.semantics" xreflabel="Semantics"> - <title>Semantics</title> - -<para> The parallel mode STL algorithms are currently not exception-safe, -i.e. user-defined functors must not throw exceptions. -Also, the order of execution is not guaranteed for some functions, of course. -Therefore, user-defined functors should not have any concurrent side effects. -</para> - -<para> Since the current GCC OpenMP implementation does not support -OpenMP parallel regions in concurrent threads, -it is not possible to call parallel STL algorithm in -concurrent threads, either. -It might work with other compilers, though.</para> - -</sect1> - -<sect1 id="manual.ext.parallel_mode.using" xreflabel="Using"> - <title>Using</title> - -<sect2 id="parallel_mode.using.prereq_flags" xreflabel="using.prereq_flags"> - <title>Prerequisite Compiler Flags</title> - -<para> - Any use of parallel functionality requires additional compiler - and runtime support, in particular support for OpenMP. Adding this support is - not difficult: just compile your application with the compiler - flag <literal>-fopenmp</literal>. This will link - in <code>libgomp</code>, the GNU - OpenMP <ulink url="http://gcc.gnu.org/onlinedocs/libgomp/">implementation</ulink>, - whose presence is mandatory. -</para> - -<para> -In addition, hardware that supports atomic operations and a compiler - capable of producing atomic operations is mandatory: GCC defaults to no - support for atomic operations on some common hardware - architectures. Activating atomic operations may require explicit - compiler flags on some targets (like sparc and x86), such - as <literal>-march=i686</literal>, - <literal>-march=native</literal> or <literal>-mcpu=v9</literal>. See - the GCC manual for more information. -</para> - -</sect2> - -<sect2 id="parallel_mode.using.parallel_mode" xreflabel="using.parallel_mode"> - <title>Using Parallel Mode</title> - -<para> - To use the libstdc++ parallel mode, compile your application with - the prerequisite flags as detailed above, and in addition - add <constant>-D_GLIBCXX_PARALLEL</constant>. This will convert all - use of the standard (sequential) algorithms to the appropriate parallel - equivalents. Please note that this doesn't necessarily mean that - everything will end up being executed in a parallel manner, but - rather that the heuristics and settings coded into the parallel - versions will be used to determine if all, some, or no algorithms - will be executed using parallel variants. -</para> - -<para>Note that the <constant>_GLIBCXX_PARALLEL</constant> define may change the - sizes and behavior of standard class templates such as - <function>std::search</function>, and therefore one can only link code - compiled with parallel mode and code compiled without parallel mode - if no instantiation of a container is passed between the two - translation units. Parallel mode functionality has distinct linkage, - and cannot be confused with normal mode symbols. -</para> -</sect2> - -<sect2 id="parallel_mode.using.specific" xreflabel="using.specific"> - <title>Using Specific Parallel Components</title> - -<para>When it is not feasible to recompile your entire application, or - only specific algorithms need to be parallel-aware, individual - parallel algorithms can be made available explicitly. These - parallel algorithms are functionally equivalent to the standard - drop-in algorithms used in parallel mode, but they are available in - a separate namespace as GNU extensions and may be used in programs - compiled with either release mode or with parallel mode. -</para> - - -<para>An example of using a parallel version -of <function>std::sort</function>, but no other parallel algorithms, is: -</para> - -<programlisting> -#include <vector> -#include <parallel/algorithm> - -int main() -{ - std::vector<int> v(100); - - // ... - - // Explicitly force a call to parallel sort. - __gnu_parallel::sort(v.begin(), v.end()); - return 0; -} -</programlisting> - -<para> -Then compile this code with the prerequisite compiler flags -(<literal>-fopenmp</literal> and any necessary architecture-specific -flags for atomic operations.) -</para> - -<para> The following table provides the names and headers of all the - parallel algorithms that can be used in a similar manner: -</para> - -<table frame='all'> -<title>Parallel Algorithms</title> -<tgroup cols='4' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> - -<thead> - <row> - <entry>Algorithm</entry> - <entry>Header</entry> - <entry>Parallel algorithm</entry> - <entry>Parallel header</entry> - </row> -</thead> - -<tbody> - <row> - <entry><function>std::accumulate</function></entry> - <entry><filename class="headerfile">numeric</filename></entry> - <entry><function>__gnu_parallel::accumulate</function></entry> - <entry><filename class="headerfile">parallel/numeric</filename></entry> - </row> - <row> - <entry><function>std::adjacent_difference</function></entry> - <entry><filename class="headerfile">numeric</filename></entry> - <entry><function>__gnu_parallel::adjacent_difference</function></entry> - <entry><filename class="headerfile">parallel/numeric</filename></entry> - </row> - <row> - <entry><function>std::inner_product</function></entry> - <entry><filename class="headerfile">numeric</filename></entry> - <entry><function>__gnu_parallel::inner_product</function></entry> - <entry><filename class="headerfile">parallel/numeric</filename></entry> - </row> - <row> - <entry><function>std::partial_sum</function></entry> - <entry><filename class="headerfile">numeric</filename></entry> - <entry><function>__gnu_parallel::partial_sum</function></entry> - <entry><filename class="headerfile">parallel/numeric</filename></entry> - </row> - <row> - <entry><function>std::adjacent_find</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::adjacent_find</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::count</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::count</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::count_if</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::count_if</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::equal</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::equal</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::find</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::find</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::find_if</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::find_if</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::find_first_of</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::find_first_of</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::for_each</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::for_each</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::generate</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::generate</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::generate_n</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::generate_n</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::lexicographical_compare</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::lexicographical_compare</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::mismatch</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::mismatch</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::search</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::search</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::search_n</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::search_n</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::transform</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::transform</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::replace</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::replace</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::replace_if</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::replace_if</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::max_element</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::max_element</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::merge</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::merge</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::min_element</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::min_element</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::nth_element</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::nth_element</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::partial_sort</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::partial_sort</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::partition</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::partition</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::random_shuffle</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::random_shuffle</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::set_union</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::set_union</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::set_intersection</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::set_intersection</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::set_symmetric_difference</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::set_symmetric_difference</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::set_difference</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::set_difference</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::sort</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::sort</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::stable_sort</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::stable_sort</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> - - <row> - <entry><function>std::unique_copy</function></entry> - <entry><filename class="headerfile">algorithm</filename></entry> - <entry><function>__gnu_parallel::unique_copy</function></entry> - <entry><filename class="headerfile">parallel/algorithm</filename></entry> - </row> -</tbody> -</tgroup> -</table> - -</sect2> - -</sect1> - -<sect1 id="manual.ext.parallel_mode.design" xreflabel="Design"> - <title>Design</title> - <para> - </para> -<sect2 id="manual.ext.parallel_mode.design.intro" xreflabel="Intro"> - <title>Interface Basics</title> - -<para> -All parallel algorithms are intended to have signatures that are -equivalent to the ISO C++ algorithms replaced. For instance, the -<function>std::adjacent_find</function> function is declared as: -</para> -<programlisting> -namespace std -{ - template<typename _FIter> - _FIter - adjacent_find(_FIter, _FIter); -} -</programlisting> - -<para> -Which means that there should be something equivalent for the parallel -version. Indeed, this is the case: -</para> - -<programlisting> -namespace std -{ - namespace __parallel - { - template<typename _FIter> - _FIter - adjacent_find(_FIter, _FIter); - - ... - } -} -</programlisting> - -<para>But.... why the ellipses? -</para> - -<para> The ellipses in the example above represent additional overloads -required for the parallel version of the function. These additional -overloads are used to dispatch calls from the ISO C++ function -signature to the appropriate parallel function (or sequential -function, if no parallel functions are deemed worthy), based on either -compile-time or run-time conditions. -</para> - -<para> The available signature options are specific for the different -algorithms/algorithm classes.</para> - -<para> The general view of overloads for the parallel algorithms look like this: -</para> -<itemizedlist> - <listitem><para>ISO C++ signature</para></listitem> - <listitem><para>ISO C++ signature + sequential_tag argument</para></listitem> - <listitem><para>ISO C++ signature + algorithm-specific tag type - (several signatures)</para></listitem> -</itemizedlist> - -<para> Please note that the implementation may use additional functions -(designated with the <code>_switch</code> suffix) to dispatch from the -ISO C++ signature to the correct parallel version. Also, some of the -algorithms do not have support for run-time conditions, so the last -overload is therefore missing. -</para> - - -</sect2> - -<sect2 id="manual.ext.parallel_mode.design.tuning" xreflabel="Tuning"> - <title>Configuration and Tuning</title> - - -<sect3 id="parallel_mode.design.tuning.omp" xreflabel="OpenMP Environment"> - <title>Setting up the OpenMP Environment</title> - -<para> -Several aspects of the overall runtime environment can be manipulated -by standard OpenMP function calls. -</para> - -<para> -To specify the number of threads to be used for the algorithms globally, -use the function <function>omp_set_num_threads</function>. An example: -</para> - -<programlisting> -#include <stdlib.h> -#include <omp.h> - -int main() -{ - // Explicitly set number of threads. - const int threads_wanted = 20; - omp_set_dynamic(false); - omp_set_num_threads(threads_wanted); - - // Call parallel mode algorithms. - - return 0; -} -</programlisting> - -<para> - Some algorithms allow the number of threads being set for a particular call, - by augmenting the algorithm variant. - See the next section for further information. -</para> - -<para> -Other parts of the runtime environment able to be manipulated include -nested parallelism (<function>omp_set_nested</function>), schedule kind -(<function>omp_set_schedule</function>), and others. See the OpenMP -documentation for more information. -</para> - -</sect3> - -<sect3 id="parallel_mode.design.tuning.compile" xreflabel="Compile Switches"> - <title>Compile Time Switches</title> - -<para> -To force an algorithm to execute sequentially, even though parallelism -is switched on in general via the macro <constant>_GLIBCXX_PARALLEL</constant>, -add <classname>__gnu_parallel::sequential_tag()</classname> to the end -of the algorithm's argument list. -</para> - -<para> -Like so: -</para> - -<programlisting> -std::sort(v.begin(), v.end(), __gnu_parallel::sequential_tag()); -</programlisting> - -<para> -Some parallel algorithm variants can be excluded from compilation by -preprocessor defines. See the doxygen documentation on -<code>compiletime_settings.h</code> and <code>features.h</code> for details. -</para> - -<para> -For some algorithms, the desired variant can be chosen at compile-time by -appending a tag object. The available options are specific to the particular -algorithm (class). -</para> - -<para> -For the "embarrassingly parallel" algorithms, there is only one "tag object -type", the enum _Parallelism. -It takes one of the following values, -<code>__gnu_parallel::parallel_tag</code>, -<code>__gnu_parallel::balanced_tag</code>, -<code>__gnu_parallel::unbalanced_tag</code>, -<code>__gnu_parallel::omp_loop_tag</code>, -<code>__gnu_parallel::omp_loop_static_tag</code>. -This means that the actual parallelization strategy is chosen at run-time. -(Choosing the variants at compile-time will come soon.) -</para> - -<para> -For the following algorithms in general, we have -<code>__gnu_parallel::parallel_tag</code> and -<code>__gnu_parallel::default_parallel_tag</code>, in addition to -<code>__gnu_parallel::sequential_tag</code>. -<code>__gnu_parallel::default_parallel_tag</code> chooses the default -algorithm at compiletime, as does omitting the tag. -<code>__gnu_parallel::parallel_tag</code> postpones the decision to runtime -(see next section). -For all tags, the number of threads desired for this call can optionally be -passed to the respective tag's constructor. -</para> - -<para> -The <code>multiway_merge</code> algorithm comes with the additional choices, -<code>__gnu_parallel::exact_tag</code> and -<code>__gnu_parallel::sampling_tag</code>. -Exact and sampling are the two available splitting strategies. -</para> - -<para> -For the <code>sort</code> and <code>stable_sort</code> algorithms, there are -several additional choices, namely -<code>__gnu_parallel::multiway_mergesort_tag</code>, -<code>__gnu_parallel::multiway_mergesort_exact_tag</code>, -<code>__gnu_parallel::multiway_mergesort_sampling_tag</code>, -<code>__gnu_parallel::quicksort_tag</code>, and -<code>__gnu_parallel::balanced_quicksort_tag</code>. -Multiway mergesort comes with the two splitting strategies for multi-way -merging. The quicksort options cannot be used for <code>stable_sort</code>. -</para> - -</sect3> - -<sect3 id="parallel_mode.design.tuning.settings" xreflabel="_Settings"> - <title>Run Time Settings and Defaults</title> - -<para> -The default parallelization strategy, the choice of specific algorithm -strategy, the minimum threshold limits for individual parallel -algorithms, and aspects of the underlying hardware can be specified as -desired via manipulation -of <classname>__gnu_parallel::_Settings</classname> member data. -</para> - -<para> -First off, the choice of parallelization strategy: serial, parallel, -or heuristically deduced. This corresponds -to <code>__gnu_parallel::_Settings::algorithm_strategy</code> and is a -value of enum <type>__gnu_parallel::_AlgorithmStrategy</type> -type. Choices -include: <type>heuristic</type>, <type>force_sequential</type>, -and <type>force_parallel</type>. The default is <type>heuristic</type>. -</para> - - -<para> -Next, the sub-choices for algorithm variant, if not fixed at compile-time. -Specific algorithms like <function>find</function> or <function>sort</function> -can be implemented in multiple ways: when this is the case, -a <classname>__gnu_parallel::_Settings</classname> member exists to -pick the default strategy. For -example, <code>__gnu_parallel::_Settings::sort_algorithm</code> can -have any values of -enum <type>__gnu_parallel::_SortAlgorithm</type>: <type>MWMS</type>, <type>QS</type>, -or <type>QS_BALANCED</type>. -</para> - -<para> -Likewise for setting the minimal threshold for algorithm -parallelization. Parallelism always incurs some overhead. Thus, it is -not helpful to parallelize operations on very small sets of -data. Because of this, measures are taken to avoid parallelizing below -a certain, pre-determined threshold. For each algorithm, a minimum -problem size is encoded as a variable in the -active <classname>__gnu_parallel::_Settings</classname> object. This -threshold variable follows the following naming scheme: -<code>__gnu_parallel::_Settings::[algorithm]_minimal_n</code>. So, -for <function>fill</function>, the threshold variable -is <code>__gnu_parallel::_Settings::fill_minimal_n</code>, -</para> - -<para> -Finally, hardware details like L1/L2 cache size can be hardwired -via <code>__gnu_parallel::_Settings::L1_cache_size</code> and friends. -</para> - -<para> -</para> - -<para> -All these configuration variables can be changed by the user, if -desired. -There exists one global instance of the class <classname>_Settings</classname>, -i. e. it is a singleton. It can be read and written by calling -<code>__gnu_parallel::_Settings::get</code> and -<code>__gnu_parallel::_Settings::set</code>, respectively. -Please note that the first call return a const object, so direct manipulation -is forbidden. -See <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00640.html"> - <filename class="headerfile">settings.h</filename></ulink> -for complete details. -</para> - -<para> -A small example of tuning the default: -</para> - -<programlisting> -#include <parallel/algorithm> -#include <parallel/settings.h> - -int main() -{ - __gnu_parallel::_Settings s; - s.algorithm_strategy = __gnu_parallel::force_parallel; - __gnu_parallel::_Settings::set(s); - - // Do work... all algorithms will be parallelized, always. - - return 0; -} -</programlisting> - -</sect3> - -</sect2> - -<sect2 id="manual.ext.parallel_mode.design.impl" xreflabel="Impl"> - <title>Implementation Namespaces</title> - -<para> One namespace contain versions of code that are always -explicitly sequential: -<code>__gnu_serial</code>. -</para> - -<para> Two namespaces contain the parallel mode: -<code>std::__parallel</code> and <code>__gnu_parallel</code>. -</para> - -<para> Parallel implementations of standard components, including -template helpers to select parallelism, are defined in <code>namespace -std::__parallel</code>. For instance, <function>std::transform</function> from <filename class="headerfile">algorithm</filename> has a parallel counterpart in -<function>std::__parallel::transform</function> from <filename class="headerfile">parallel/algorithm</filename>. In addition, these parallel -implementations are injected into <code>namespace -__gnu_parallel</code> with using declarations. -</para> - -<para> Support and general infrastructure is in <code>namespace -__gnu_parallel</code>. -</para> - -<para> More information, and an organized index of types and functions -related to the parallel mode on a per-namespace basis, can be found in -the generated source documentation. -</para> - -</sect2> - -</sect1> - -<sect1 id="manual.ext.parallel_mode.test" xreflabel="Testing"> - <title>Testing</title> - - <para> - Both the normal conformance and regression tests and the - supplemental performance tests work. - </para> - - <para> - To run the conformance and regression tests with the parallel mode - active, - </para> - - <screen> - <userinput>make check-parallel</userinput> - </screen> - - <para> - The log and summary files for conformance testing are in the - <filename class="directory">testsuite/parallel</filename> directory. - </para> - - <para> - To run the performance tests with the parallel mode active, - </para> - - <screen> - <userinput>make check-performance-parallel</userinput> - </screen> - - <para> - The result file for performance testing are in the - <filename class="directory">testsuite</filename> directory, in the file - <filename>libstdc++_performance.sum</filename>. In addition, the - policy-based containers have their own visualizations, which have - additional software dependencies than the usual bare-boned text - file, and can be generated by using the <code>make - doc-performance</code> rule in the testsuite's Makefile. -</para> -</sect1> - -<bibliography id="parallel_mode.biblio" xreflabel="parallel_mode.biblio"> -<title>Bibliography</title> - - <biblioentry> - <title> - Parallelization of Bulk Operations for STL Dictionaries - </title> - - <author> - <firstname>Johannes</firstname> - <surname>Singler</surname> - </author> - <author> - <firstname>Leonor</firstname> - <surname>Frias</surname> - </author> - - <copyright> - <year>2007</year> - <holder></holder> - </copyright> - - <publisher> - <publishername> - Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS) - </publishername> - </publisher> - </biblioentry> - - <biblioentry> - <title> - The Multi-Core Standard Template Library - </title> - - <author> - <firstname>Johannes</firstname> - <surname>Singler</surname> - </author> - <author> - <firstname>Peter</firstname> - <surname>Sanders</surname> - </author> - <author> - <firstname>Felix</firstname> - <surname>Putze</surname> - </author> - - <copyright> - <year>2007</year> - <holder></holder> - </copyright> - - <publisher> - <publishername> - Euro-Par 2007: Parallel Processing. (LNCS 4641) - </publishername> - </publisher> - </biblioentry> - -</bibliography> - -</chapter> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/prerequisites.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/prerequisites.xml deleted file mode 100644 index 20a047865..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/prerequisites.xml +++ /dev/null @@ -1,158 +0,0 @@ -<sect1 id="manual.intro.setup.prereq" xreflabel="Prerequisites"> -<?dbhtml filename="prerequisites.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - Prerequisites - </keyword> - </keywordset> -</sect1info> - -<title>Prerequisites</title> - -<para> - Because libstdc++ is part of GCC, the primary source for - installation instructions is - <ulink url="http://gcc.gnu.org/install/">the GCC install page</ulink>. - In particular, list of prerequisite software needed to build the library - <ulink url="http://gcc.gnu.org/install/prerequisites.html"> - starts with those requirements.</ulink> The same pages also list - the tools you will need if you wish to modify the source. -</para> - - <para> - Additional data is given here only where it applies to libstdc++. - </para> - - <para>As of GCC 4.0.1 the minimum version of binutils required to build - libstdc++ is <code>2.15.90.0.1.1</code>. You can get snapshots - (as well as releases) of binutils from - <ulink url="ftp://sources.redhat.com/pub/binutils"> - ftp://sources.redhat.com/pub/binutils</ulink>. - Older releases of libstdc++ do not require such a recent version, - but to take full advantage of useful space-saving features and - bug-fixes you should use a recent binutils whenever possible. - The configure process will automatically detect and use these - features if the underlying support is present. - </para> - - <para> - Finally, a few system-specific requirements: - </para> - - <variablelist> - <varlistentry> - <term>linux</term> - - <listitem> - <para> - If gcc 3.1.0 or later on is being used on linux, an attempt - will be made to use "C" library functionality necessary for - C++ named locale support. For gcc 3.2.1 and later, this - means that glibc 2.2.5 or later is required and the "C" - library de_DE locale information must be installed. - </para> - - <para> - Note however that the sanity checks involving the de_DE - locale are skipped when an explicit --enable-clocale=gnu - configure option is used: only the basic checks are carried - out, defending against misconfigurations. - </para> - - <para> - If the 'gnu' locale model is being used, the following - locales are used and tested in the libstdc++ testsuites. - The first column is the name of the locale, the second is - the character set it is expected to use. - </para> -<programlisting> -de_DE ISO-8859-1 -de_DE@euro ISO-8859-15 -en_HK ISO-8859-1 -en_PH ISO-8859-1 -en_US ISO-8859-1 -en_US.ISO-8859-1 ISO-8859-1 -en_US.ISO-8859-15 ISO-8859-15 -en_US.UTF-8 UTF-8 -es_ES ISO-8859-1 -es_MX ISO-8859-1 -fr_FR ISO-8859-1 -fr_FR@euro ISO-8859-15 -is_IS UTF-8 -it_IT ISO-8859-1 -ja_JP.eucjp EUC-JP -se_NO.UTF-8 UTF-8 -ta_IN UTF-8 -zh_TW BIG5 -</programlisting> - - <para>Failure to have the underlying "C" library locale - information installed will mean that C++ named locales for the - above regions will not work: because of this, the libstdc++ - testsuite will skip the named locale tests. If this isn't an - issue, don't worry about it. If named locales are needed, the - underlying locale information must be installed. Note that - rebuilding libstdc++ after the "C" locales are installed is not - necessary. - </para> - - <para> - To install support for locales, do only one of the following: - </para> - - <itemizedlist> - <listitem> - <para>install all locales</para> - <itemizedlist> - <listitem> - <para>with RedHat Linux: - </para> - <para> <code> export LC_ALL=C </code> - </para> - <para> <code> rpm -e glibc-common --nodeps </code> - </para> - <para> - <code> rpm -i --define "_install_langs all" - glibc-common-2.2.5-34.i386.rpm - </code> - </para> - </listitem> - <listitem> - <para> - Instructions for other operating systems solicited. - </para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para>install just the necessary locales</para> - <itemizedlist> - <listitem> - <para>with Debian Linux:</para> - <para> Add the above list, as shown, to the file - <code>/etc/locale.gen</code> </para> - <para> run <code>/usr/sbin/locale-gen</code> </para> - </listitem> - <listitem> - <para>on most Unix-like operating systems:</para> - <para><code> localedef -i de_DE -f ISO-8859-1 de_DE </code></para> - <para>(repeat for each entry in the above list) </para> - </listitem> - <listitem> - <para> - Instructions for other operating systems solicited. - </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> - -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/shared_ptr.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/shared_ptr.xml deleted file mode 100644 index cd517f125..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/shared_ptr.xml +++ /dev/null @@ -1,580 +0,0 @@ -<sect1 id="manual.util.memory.shared_ptr" xreflabel="shared_ptr"> -<?dbhtml filename="shared_ptr.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - shared_ptr - </keyword> - </keywordset> -</sect1info> - -<title>shared_ptr</title> - -<para> -The shared_ptr class template stores a pointer, usually obtained via new, -and implements shared ownership semantics. -</para> - -<sect2 id="shared_ptr.req" xreflabel="shared_ptr.req"> -<title>Requirements</title> - - <para> - </para> - - <para> - The standard deliberately doesn't require a reference-counted - implementation, allowing other techniques such as a - circular-linked-list. - </para> - - <para> - At the time of writing the C++0x working paper doesn't mention how - threads affect shared_ptr, but it is likely to follow the existing - practice set by <classname>boost::shared_ptr</classname>. The - shared_ptr in libstdc++ is derived from Boost's, so the same rules - apply. - </para> - - <para> - </para> -</sect2> - -<sect2 id="shared_ptr.design_issues" xreflabel="shared_ptr.design_issues"> -<title>Design Issues</title> - - - <para> -The <classname>shared_ptr</classname> code is kindly donated to GCC by the Boost -project and the original authors of the code. The basic design and -algorithms are from Boost, the notes below describe details specific to -the GCC implementation. Names have been uglified in this implementation, -but the design should be recognisable to anyone familiar with the Boost -1.32 shared_ptr. - </para> - - <para> -The basic design is an abstract base class, <code>_Sp_counted_base</code> that -does the reference-counting and calls virtual functions when the count -drops to zero. -Derived classes override those functions to destroy resources in a context -where the correct dynamic type is known. This is an application of the -technique known as type erasure. - </para> - -</sect2> - -<sect2 id="shared_ptr.impl" xreflabel="shared_ptr.impl"> -<title>Implementation</title> - - <sect3> - <title>Class Hierarchy</title> - - <para> -A <classname>shared_ptr<T></classname> contains a pointer of -type <type>T*</type> and an object of type -<classname>__shared_count</classname>. The shared_count contains a -pointer of type <type>_Sp_counted_base*</type> which points to the -object that maintains the reference-counts and destroys the managed -resource. - </para> - -<variablelist> - -<varlistentry> - <term><classname>_Sp_counted_base<Lp></classname></term> - <listitem> - <para> -The base of the hierarchy is parameterized on the lock policy alone. -_Sp_counted_base doesn't depend on the type of pointer being managed, -it only maintains the reference counts and calls virtual functions when -the counts drop to zero. The managed object is destroyed when the last -strong reference is dropped, but the _Sp_counted_base itself must exist -until the last weak reference is dropped. - </para> - </listitem> -</varlistentry> - -<varlistentry> - <term><classname>_Sp_counted_base_impl<Ptr, Deleter, Lp></classname></term> - <listitem> - <para> -Inherits from _Sp_counted_base and stores a pointer of type <type>Ptr</type> -and a deleter of type <code>Deleter</code>. <code>_Sp_deleter</code> is -used when the user doesn't supply a custom deleter. Unlike Boost's, this -default deleter is not "checked" because GCC already issues a warning if -<function>delete</function> is used with an incomplete type. -This is the only derived type used by <classname>shared_ptr<Ptr></classname> -and it is never used by <classname>shared_ptr</classname>, which uses one of -the following types, depending on how the shared_ptr is constructed. - </para> - </listitem> -</varlistentry> - -<varlistentry> - <term><classname>_Sp_counted_ptr<Ptr, Lp></classname></term> - <listitem> - <para> -Inherits from _Sp_counted_base and stores a pointer of type <type>Ptr</type>, -which is passed to <function>delete</function> when the last reference is dropped. -This is the simplest form and is used when there is no custom deleter or -allocator. - </para> - </listitem> -</varlistentry> - -<varlistentry> - <term><classname>_Sp_counted_deleter<Ptr, Deleter, Alloc></classname></term> - <listitem> - <para> -Inherits from _Sp_counted_ptr and adds support for custom deleter and -allocator. Empty Base Optimization is used for the allocator. This class -is used even when the user only provides a custom deleter, in which case -<classname>allocator</classname> is used as the allocator. - </para> - </listitem> -</varlistentry> - -<varlistentry> - <term><classname>_Sp_counted_ptr_inplace<Tp, Alloc, Lp></classname></term> - <listitem> - <para> -Used by <code>allocate_shared</code> and <code>make_shared</code>. -Contains aligned storage to hold an object of type <type>Tp</type>, -which is constructed in-place with placement <function>new</function>. -Has a variadic template constructor allowing any number of arguments to -be forwarded to <type>Tp</type>'s constructor. -Unlike the other <classname>_Sp_counted_*</classname> classes, this one is parameterized on the -type of object, not the type of pointer; this is purely a convenience -that simplifies the implementation slightly. - </para> - </listitem> -</varlistentry> - -</variablelist> - - </sect3> - - <sect3> - <title>Thread Safety</title> - - <para> -The interface of <classname>tr1::shared_ptr</classname> was extended for C++0x -with support for rvalue-references and the other features from -N2351. As with other libstdc++ headers shared by TR1 and C++0x, -boost_shared_ptr.h uses conditional compilation, based on the macros -<constant>_GLIBCXX_INCLUDE_AS_CXX0X</constant> and -<constant>_GLIBCXX_INCLUDE_AS_TR1</constant>, to enable and disable -features. - </para> - - <para> -C++0x-only features are: rvalue-ref/move support, allocator support, -aliasing constructor, make_shared & allocate_shared. Additionally, -the constructors taking <classname>auto_ptr</classname> parameters are -deprecated in C++0x mode. - </para> - -<para> -The -<ulink url="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread -Safety</ulink> section of the Boost shared_ptr documentation says "shared_ptr -objects offer the same level of thread safety as built-in types." -The implementation must ensure that concurrent updates to separate shared_ptr -instances are correct even when those instances share a reference count e.g. -</para> - -<programlisting> -shared_ptr<A> a(new A); -shared_ptr<A> b(a); - -// Thread 1 // Thread 2 - a.reset(); b.reset(); -</programlisting> - -<para> -The dynamically-allocated object must be destroyed by exactly one of the -threads. Weak references make things even more interesting. -The shared state used to implement shared_ptr must be transparent to the -user and invariants must be preserved at all times. -The key pieces of shared state are the strong and weak reference counts. -Updates to these need to be atomic and visible to all threads to ensure -correct cleanup of the managed resource (which is, after all, shared_ptr's -job!) -On multi-processor systems memory synchronisation may be needed so that -reference-count updates and the destruction of the managed resource are -race-free. -</para> - -<para> -The function <function>_Sp_counted_base::_M_add_ref_lock()</function>, called when -obtaining a shared_ptr from a weak_ptr, has to test if the managed -resource still exists and either increment the reference count or throw -<classname>bad_weak_ptr</classname>. -In a multi-threaded program there is a potential race condition if the last -reference is dropped (and the managed resource destroyed) between testing -the reference count and incrementing it, which could result in a shared_ptr -pointing to invalid memory. -</para> -<para> -The Boost shared_ptr (as used in GCC) features a clever lock-free -algorithm to avoid the race condition, but this relies on the -processor supporting an atomic <emphasis>Compare-And-Swap</emphasis> -instruction. For other platforms there are fall-backs using mutex -locks. Boost (as of version 1.35) includes several different -implementations and the preprocessor selects one based on the -compiler, standard library, platform etc. For the version of -shared_ptr in libstdc++ the compiler and library are fixed, which -makes things much simpler: we have an atomic CAS or we don't, see Lock -Policy below for details. -</para> - - </sect3> - - <sect3> - <title>Selecting Lock Policy</title> - - <para> - </para> - - <para> -There is a single <classname>_Sp_counted_base</classname> class, -which is a template parameterized on the enum -<type>__gnu_cxx::_Lock_policy</type>. The entire family of classes is -parameterized on the lock policy, right up to -<classname>__shared_ptr</classname>, <classname>__weak_ptr</classname> and -<classname>__enable_shared_from_this</classname>. The actual -<classname>std::shared_ptr</classname> class inherits from -<classname>__shared_ptr</classname> with the lock policy parameter -selected automatically based on the thread model and platform that -libstdc++ is configured for, so that the best available template -specialization will be used. This design is necessary because it would -not be conforming for <classname>shared_ptr</classname> to have an -extra template parameter, even if it had a default value. The -available policies are: - </para> - - <orderedlist> - <listitem> - <para> - <type>_S_Atomic</type> - </para> - <para> -Selected when GCC supports a builtin atomic compare-and-swap operation -on the target processor (see <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Atomic -Builtins</ulink>.) The reference counts are maintained using a lock-free -algorithm and GCC's atomic builtins, which provide the required memory -synchronisation. - </para> - </listitem> - - <listitem> - <para> - <type>_S_Mutex</type> - </para> - <para> -The _Sp_counted_base specialization for this policy contains a mutex, -which is locked in add_ref_lock(). This policy is used when GCC's atomic -builtins aren't available so explicit memory barriers are needed in places. - </para> - </listitem> - - <listitem> - <para> - <type>_S_Single</type> - </para> - <para> -This policy uses a non-reentrant add_ref_lock() with no locking. It is -used when libstdc++ is built without <literal>--enable-threads</literal>. - </para> - </listitem> - - </orderedlist> - <para> - For all three policies, reference count increments and - decrements are done via the functions in - <filename>ext/atomicity.h</filename>, which detect if the program - is multi-threaded. If only one thread of execution exists in - the program then less expensive non-atomic operations are used. - </para> - </sect3> - - <sect3> - <title>Dual C++0x and TR1 Implementation</title> - -<para> -The classes derived from <classname>_Sp_counted_base</classname> (see Class Hierarchy -below) and <classname>__shared_count</classname> are implemented separately for C++0x -and TR1, in <filename>bits/boost_sp_shared_count.h</filename> and -<filename>tr1/boost_sp_shared_count.h</filename> respectively. All other classes -including <classname>_Sp_counted_base</classname> are shared by both implementations. -</para> - -<para> -The TR1 implementation is considered relatively stable, so is unlikely to -change unless bug fixes require it. If the code that is common to both -C++0x and TR1 modes needs to diverge further then it might be necessary to -duplicate additional classes and only make changes to the C++0x versions. -</para> -</sect3> - -<sect3> -<title>Related functions and classes</title> - -<variablelist> - -<varlistentry> - <term><code>dynamic_pointer_cast</code>, <code>static_pointer_cast</code>, -<code>const_pointer_cast</code></term> - <listitem> - <para> -As noted in N2351, these functions can be implemented non-intrusively using -the alias constructor. However the aliasing constructor is only available -in C++0x mode, so in TR1 mode these casts rely on three non-standard -constructors in shared_ptr and __shared_ptr. -In C++0x mode these constructors and the related tag types are not needed. - </para> - </listitem> -</varlistentry> - -<varlistentry> - <term><code>enable_shared_from_this</code></term> - <listitem> - <para> -The clever overload to detect a base class of type -<code>enable_shared_from_this</code> comes straight from Boost. -There is an extra overload for <code>__enable_shared_from_this</code> to -work smoothly with <code>__shared_ptr<Tp, Lp></code> using any lock -policy. - </para> - </listitem> -</varlistentry> - -<varlistentry> - <term><code>make_shared</code>, <code>allocate_shared</code></term> - <listitem> - <para> -<code>make_shared</code> simply forwards to <code>allocate_shared</code> -with <code>std::allocator</code> as the allocator. -Although these functions can be implemented non-intrusively using the -alias constructor, if they have access to the implementation then it is -possible to save storage and reduce the number of heap allocations. The -newly constructed object and the _Sp_counted_* can be allocated in a single -block and the standard says implementations are "encouraged, but not required," -to do so. This implementation provides additional non-standard constructors -(selected with the type <code>_Sp_make_shared_tag</code>) which create an -object of type <code>_Sp_counted_ptr_inplace</code> to hold the new object. -The returned <code>shared_ptr<A></code> needs to know the address of the -new <code>A</code> object embedded in the <code>_Sp_counted_ptr_inplace</code>, -but it has no way to access it. -This implementation uses a "covert channel" to return the address of the -embedded object when <code>get_deleter<_Sp_make_shared_tag>()</code> -is called. Users should not try to use this. -As well as the extra constructors, this implementation also needs some -members of _Sp_counted_deleter to be protected where they could otherwise -be private. - </para> - </listitem> -</varlistentry> - -</variablelist> - -</sect3> - -</sect2> - -<!--- XXX - <listitem> - <type>_Sp_counted_base<Lp></type> - <para> -The base of the hierarchy is parameterized on the lock policy alone. -_Sp_counted_base doesn't depend on the type of pointer being managed, -it only maintains the reference counts and calls virtual functions when -the counts drop to zero. The managed object is destroyed when the last -strong reference is dropped, but the _Sp_counted_base itself must exist -until the last weak reference is dropped. - </para> - </listitem> - - <listitem> - <type>_Sp_counted_base_impl<Ptr, Deleter, Lp></type> - <para> -Inherits from _Sp_counted_base and stores a pointer of type <code>Ptr</code> -and a deleter of type <code>Deleter</code>. <code>_Sp_deleter</code> is -used when the user doesn't supply a custom deleter. Unlike Boost's, this -default deleter is not "checked" because GCC already issues a warning if -<code>delete</code> is used with an incomplete type. -This is the only derived type used by <code>tr1::shared_ptr<Ptr></code> -and it is never used by <code>std::shared_ptr</code>, which uses one of -the following types, depending on how the shared_ptr is constructed. - </para> - </listitem> ---> - -<sect2 id="shared_ptr.using" xreflabel="shared_ptr.using"> -<title>Use</title> - - <sect3> - <title>Examples</title> - <para> - Examples of use can be found in the testsuite, under - <filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>. - </para> - </sect3> - - <sect3> - <title>Unresolved Issues</title> - <para> - The resolution to C++ Standard Library issue <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#674">674</ulink>, - "shared_ptr interface changes for consistency with N1856" will - need to be implemented after it is accepted into the working - paper. Issue <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#743">743</ulink> - might also require changes. - </para> - - <para> - The <type>_S_single</type> policy uses atomics when used in MT - code, because it uses the same dispatcher functions that check - <function>__gthread_active_p()</function>. This could be - addressed by providing template specialisations for some members - of <classname>_Sp_counted_base<_S_single></classname>. - </para> - - <para> - Unlike Boost, this implementation does not use separate classes - for the pointer+deleter and pointer+deleter+allocator cases in - C++0x mode, combining both into _Sp_counted_deleter and using - <classname>allocator</classname> when the user doesn't specify - an allocator. If it was found to be beneficial an additional - class could easily be added. With the current implementation, - the _Sp_counted_deleter and __shared_count constructors taking a - custom deleter but no allocator are technically redundant and - could be removed, changing callers to always specify an - allocator. If a separate pointer+deleter class was added the - __shared_count constructor would be needed, so it has been kept - for now. - </para> - - <para> - The hack used to get the address of the managed object from - <function>_Sp_counted_ptr_inplace::_M_get_deleter()</function> - is accessible to users. This could be prevented if - <function>get_deleter<_Sp_make_shared_tag>()</function> - always returned NULL, since the hack only needs to work at a - lower level, not in the public API. This wouldn't be difficult, - but hasn't been done since there is no danger of accidental - misuse: users already know they are relying on unsupported - features if they refer to implementation details such as - _Sp_make_shared_tag. - </para> - - <para> - tr1::_Sp_deleter could be a private member of tr1::__shared_count but it - would alter the ABI. - </para> - - <para> - Exposing the alias constructor in TR1 mode could simplify the - *_pointer_cast functions. Constructor could be private in TR1 - mode, with the cast functions as friends. - </para> - </sect3> - -</sect2> - -<sect2 id="shared_ptr.ack" xreflabel="shared_ptr.ack"> -<title>Acknowledgments</title> - - <para> - The original authors of the Boost shared_ptr, which is really nice - code to work with, Peter Dimov in particular for his help and - invaluable advice on thread safety. Phillip Jordan and Paolo - Carlini for the lock policy implementation. - </para> - -</sect2> - -<bibliography id="shared_ptr.biblio" xreflabel="shared_ptr.biblio"> -<title>Bibliography</title> - - <biblioentry> - <abbrev> - n2351 - </abbrev> - - <title> - Improving shared_ptr for C++0x, Revision 2 - </title> - <subtitle> - N2351 - </subtitle> - - <biblioid> - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm"> - </ulink> - </biblioid> - </biblioentry> - - - <biblioentry> - <abbrev> - n2456 - </abbrev> - - <title> - C++ Standard Library Active Issues List (Revision R52) - </title> - <subtitle> - N2456 - </subtitle> - - <biblioid> - <ulink url="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html"> - </ulink> - </biblioid> - </biblioentry> - - - <biblioentry> - <abbrev> - n2461 - </abbrev> - - <title> - Working Draft, Standard for Programming Language C++ - </title> - <subtitle> - N2461 - </subtitle> - - <biblioid> - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf"> - </ulink> - </biblioid> - </biblioentry> - - - <biblioentry> - <abbrev> - boostshared_ptr - </abbrev> - - <title> - Boost C++ Libraries documentation - shared_ptr class template - </title> - <subtitle> - N2461 - </subtitle> - - <biblioid> - <ulink url="http://boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr - </ulink> - </biblioid> - </biblioentry> - -</bibliography> - -</sect1>
\ No newline at end of file diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/spine.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/spine.xml deleted file mode 100644 index 0d9a89cba..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/spine.xml +++ /dev/null @@ -1,114 +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 id="manual-index" xreflabel="manual-index"> -<?dbhtml dir="manual"?> -<?dbhtml filename="spine.html"?> -<title>The GNU C++ Library</title> - -<bookinfo> - <copyright> - <year>2009</year> - <holder> - <ulink url="http://fsf.org">FSF</ulink> - </holder> - </copyright> - <legalnotice> - <para> - <link linkend="manual.intro.status.license">License</link> - </para> - </legalnotice> -</bookinfo> - -<!-- Part 01 : Intro --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="intro.xml"> -</xi:include> - -<!-- Part 02 : Support --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="support.xml"> -</xi:include> - -<!-- Part 03 : Diagnostics --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="diagnostics.xml"> -</xi:include> - -<!-- Part 04 : Utilities --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="utilities.xml"> -</xi:include> - -<!-- Part 05 : Strings --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="strings.xml"> -</xi:include> - -<!-- Part 06 : Localization --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="localization.xml"> -</xi:include> - -<!-- Part 07 : Containers --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="containers.xml"> -</xi:include> - -<!-- Part 08 : Iterators --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="iterators.xml"> -</xi:include> - -<!-- Part 09 : Algorithms --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="algorithms.xml"> -</xi:include> - -<!-- Part 10 : Numerics --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="numerics.xml"> -</xi:include> - -<!-- Part 11 : Input Output --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="io.xml"> -</xi:include> - -<!-- Part 12 : Extensions --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="extensions.xml"> -</xi:include> - - -<!-- Appendix A --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="appendix_contributing.xml"> -</xi:include> - -<!-- Appendix B --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="appendix_porting.xml"> -</xi:include> - -<!-- Appendix C --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="appendix_free.xml"> -</xi:include> - -<!-- Appendix D --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="../gnu/gpl-3.0.xml"> -</xi:include> - -<!-- Appendix E --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="../gnu/fdl-1.2.xml"> -</xi:include> - -<!-- Index --> -<index/> - -</book> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxx1998.xml deleted file mode 100644 index d163f8a69..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxx1998.xml +++ /dev/null @@ -1,1162 +0,0 @@ -<sect2 id="status.iso.1998" xreflabel="ISO C++ 1998"> -<?dbhtml filename="status_iso_cxx1998.html"?> - -<sect2info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - 1998 - </keyword> - </keywordset> -</sect2info> - -<title>C++ 1998/2003</title> - -<sect3 id="iso.1998.status" xreflabel="Implementation Status"> - <title>Implementation Status</title> - -<para> -This status table is based on the table of contents of ISO/IEC 14882:2003. -</para> - -<para> -This page describes the C++0x support in mainline GCC SVN, not in any -particular release. -</para> - -<!-- Status is Yes or No, Broken/Partial--> -<!-- - Yes - - No - <?dbhtml bgcolor="#C8B0B0" ?> - Broken/Partial - <?dbhtml bgcolor="#B0B0B0" ?> ---> -<table frame='all'> -<title>C++ 1998/2003 Implementation Status</title> -<tgroup cols='4' align='left' colsep='0' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> - <thead> - <row> - <entry>Section</entry> - <entry>Description</entry> - <entry>Status</entry> - <entry>Comments</entry> - </row> - </thead> - - <tbody> - <row> - <entry> - <emphasis>18</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Language support</emphasis> - </entry> - </row> - - <row> - <entry>18.1</entry> - <entry>Types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.2</entry> - <entry>Implementation properties</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.2.1</entry> - <entry>Numeric Limits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.2.1.1</entry> - <entry>Class template <code>numeric_limits</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.2.1.2</entry> - <entry><code>numeric_limits</code> members</entry> - <entry>Y</entry> - </row> - <row> - <entry>18.2.1.3</entry> - <entry><code>float_round_style</code></entry> - <entry>Y</entry> - </row> - <row> - <entry>18.2.1.4</entry> - <entry><code>float_denorm_style</code></entry> - <entry>Y</entry> - </row> - <row> - <entry>18.2.1.5</entry> - <entry><code>numeric_limits</code> specializations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.2.2</entry> - <entry>C Library</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.3</entry> - <entry>Start and termination</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.4</entry> - <entry>Dynamic memory management</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.5</entry> - <entry>Type identification</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.5.1</entry> - <entry>Class type_info</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.5.2</entry> - <entry>Class bad_cast</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.5.3</entry> - <entry>Class bad_typeid</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.6</entry> - <entry>Exception handling</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.6.1</entry> - <entry>Class exception</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.6.2</entry> - <entry>Violation exception-specifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.6.3</entry> - <entry>Abnormal termination</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.6.4</entry> - <entry><code>uncaught_exception</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.7</entry> - <entry>Other runtime support</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>19</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Diagnostics</emphasis> - </entry> - </row> - <row> - <entry>19.1</entry> - <entry>Exception classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>19.2</entry> - <entry>Assertions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>19.3</entry> - <entry>Error numbers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>20</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>General utilities</emphasis> - </entry> - </row> - <row> - <entry>20.1</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.2</entry> - <entry>Utility components</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.2.1</entry> - <entry>Operators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.2.2</entry> - <entry><code>pair</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3</entry> - <entry>Function objects</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.3.1</entry> - <entry>Base</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.2</entry> - <entry>Arithmetic operation</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.3</entry> - <entry>Comparisons</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.4</entry> - <entry>Logical operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.5</entry> - <entry>Negators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.6</entry> - <entry>Binders</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.7</entry> - <entry>Adaptors for pointers to functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.8</entry> - <entry>Adaptors for pointers to members</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4</entry> - <entry>Memory</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.4.1</entry> - <entry>The default allocator</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.2</entry> - <entry>Raw storage iterator</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.3</entry> - <entry>Temporary buffers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.4</entry> - <entry>Specialized algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.4.1</entry> - <entry><code>uninitialized_copy</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.4.2</entry> - <entry><code>uninitialized_fill</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.4.3</entry> - <entry><code>uninitialized_fill_n</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.5</entry> - <entry>Class template <code>auto_ptr</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.6</entry> - <entry>C library</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>21</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Strings</emphasis> - </entry> - </row> - <row> - <entry>21.1</entry> - <entry>Character traits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>21.1.1</entry> - <entry>Character traits requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.1.2</entry> - <entry>traits typedef</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.1.3</entry> - <entry><code>char_traits</code> specializations</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>21.1.3.1</entry> - <entry>struct <code>char_traits<char></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.1.3.2</entry> - <entry>struct <code>char_traits<wchar_t></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.2</entry> - <entry>String classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.3</entry> - <entry>Class template <code>basic_string</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.4</entry> - <entry>Null-terminated sequence utilities</entry> - <entry>Y</entry> - <entry>C library dependency</entry> - </row> - <row> - <entry> - <emphasis>22</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Localization</emphasis> - </entry> - </row> - <row> - <entry>22.1</entry> - <entry>Locales</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.1.1</entry> - <entry>Class <code>locale</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.1.2</entry> - <entry><code>locale</code> globals</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.1.3</entry> - <entry>Convenience interfaces</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.1.3.1</entry> - <entry>Character classification</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.1.3.2</entry> - <entry>Character conversions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2</entry> - <entry>Standard locale categories</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.2.1</entry> - <entry><code>ctype</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.2</entry> - <entry>Numeric</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.2.2.1</entry> - <entry><code>num_get</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.2.2</entry> - <entry><code>num_put</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.3</entry> - <entry><code>num_punct</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.4</entry> - <entry><code>collate</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.5</entry> - <entry>Time</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.2.5.1</entry> - <entry><code>time_get</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.5.2</entry> - <entry><code>time_get_byname</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.5.3</entry> - <entry><code>time_put</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.5.3</entry> - <entry><code>time_put_byname</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.6</entry> - <entry>Monetary</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.2.6.1</entry> - <entry><code>money_get</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.6.2</entry> - <entry><code>money_put</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.6.3</entry> - <entry><code>money_punct</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.6.4</entry> - <entry><code>money_punct_byname</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.7</entry> - <entry><code>messages</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2.8</entry> - <entry>Program-defined facets</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.3</entry> - <entry>C Library Locales</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>23</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Containers</emphasis> - </entry> - </row> - <row> - <entry>23.1</entry> - <entry>Container requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.2</entry> - <entry>Sequence containers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>23.2.1</entry> - <entry>Class template <code>deque</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.2.2</entry> - <entry>Class template <code>list</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.2.3</entry> - <entry>Adaptors</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>23.2.3.1</entry> - <entry>Class template <code>queue</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.2.3.2</entry> - <entry>Class template <code>priority_queue</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.2.3.3</entry> - <entry>Class template <code>stack</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.2.4</entry> - <entry>Class template <code>vector</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.2.5</entry> - <entry>Class <code>vector<bool></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3</entry> - <entry>Associative containers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>23.3.1</entry> - <entry>Class template <code>map</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.2</entry> - <entry>Class template <code>multimap</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.3</entry> - <entry>Class template <code>set</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.4</entry> - <entry>Class template <code>multiset</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>24</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Iterators</emphasis> - </entry> - </row> - <row> - <entry>24.1</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.2</entry> - <entry>Header <code><iterator></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.3</entry> - <entry>Iterator primitives</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.4</entry> - <entry>Predefined iterators and Iterator adaptors</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>24.4.1</entry> - <entry>Reverse iterators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.4.2</entry> - <entry>Insert iterators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.5</entry> - <entry>Stream iterators</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>24.5.1</entry> - <entry>Class template <code>istream_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.5.2</entry> - <entry>Class template <code>ostream_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.5.3</entry> - <entry>Class template <code>istreambuf_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.5.4</entry> - <entry>Class template <code>ostreambuf_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>25</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Algorithms</emphasis> - </entry> - </row> - <row> - <entry>25.1</entry> - <entry>Non-modifying sequence operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>25.2</entry> - <entry>Mutating sequence operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>25.3</entry> - <entry>Sorting and related operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>25.4</entry> - <entry>C library algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>26</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Numerics</emphasis> - </entry> - </row> - <row> - <entry>26.1</entry> - <entry>Numeric type requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.2</entry> - <entry>Complex numbers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3</entry> - <entry>Numeric arrays</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>26.3.1</entry> - <entry>Header <code><valarray></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.2</entry> - <entry>Class template <code>valarray</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.3</entry> - <entry><code>valarray</code> non-member operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.4</entry> - <entry>Class <code>slice</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.5</entry> - <entry>Class template <code>slice_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.6</entry> - <entry>Class <code>gslice</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.7</entry> - <entry>Class template <code>gslice_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.8</entry> - <entry>Class template <code>mask_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3.9</entry> - <entry>Class template <code>indirect_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.4</entry> - <entry>Generalized numeric operations</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>26.4.1</entry> - <entry><code>accumulate</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.4.2</entry> - <entry><code>inner_product</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.4.3</entry> - <entry><code>partial_sum</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.4.4</entry> - <entry><code>adjacent_difference</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.4.5</entry> - <entry>iota</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.5</entry> - <entry>C Library</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>27</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Input/output</emphasis> - </entry> - </row> - <row> - <entry>27.1</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.2</entry> - <entry>Forward declarations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.3</entry> - <entry>Standard iostream objects</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.3.1</entry> - <entry>Narrow stream objects</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.3.2</entry> - <entry>Wide stream objects</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.4</entry> - <entry>Iostreams base classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.5</entry> - <entry>Stream buffers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.6</entry> - <entry>Formatting and manipulators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.7</entry> - <entry>String-based streams</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.8</entry> - <entry>File-based streams</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>Appendix D</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Compatibility features</emphasis> - </entry> - </row> - <row> - <entry>D.1</entry> - <entry>Increment operator with bool operand</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.2</entry> - <entry><code>static</code> keyword</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.3</entry> - <entry>Access declarations</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.4</entry> - <entry>Implicit conversion from const strings</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.5</entry> - <entry>C standard library headers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.6</entry> - <entry>Old iostreams members</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.7</entry> - <entry>char* streams</entry> - <entry></entry> - <entry></entry> - </row> - - </tbody> -</tgroup> -</table> -</sect3> - -<sect3 id="iso.1998.specific" xreflabel="Implementation Specific"> - <title>Implementation Specific Behavior</title> - - <para> - The ISO standard defines the following phrase: - </para> - <blockquote> - <variablelist> - <varlistentry> - <term> - <code>[1.3.5] implementation-defined behavior</code> - </term> - <listitem> - <para> - Behavior, for a well-formed program construct and correct data, that - depends on the implementation <emphasis>and that each implementation - shall document</emphasis>. - </para> - </listitem> - </varlistentry> - </variablelist> - </blockquote> - <para> - We do so here, for the C++ library only. Behavior of the - compiler, linker, runtime loader, and other elements of "the - implementation" are documented elsewhere. Everything listed - in Annex B, Implementation Qualities, are also part of the - compiler, not the library. - </para> - <para> - For each entry, we give the section number of the standard, when - applicable. This list is probably incomplet and inkorrekt. - </para> - <para> - <emphasis>[1.9]/11 #3</emphasis> If <code>isatty(3)</code> is true, then - interactive stream support is implied. - </para> - <para> - <emphasis>[17.4.4.5]</emphasis> Non-reentrant functions are probably best - discussed in the various sections on multithreading (see above). - </para> - <!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec - can throw whatever we want; see also its footnote. Let's list those - in the sections where the function itself occurs. - --> - <para><emphasis>[18.1]/4</emphasis> The type of <code>NULL</code> is described - <ulink url="../18_support/howto.html#1">here</ulink>. - </para> - <para><emphasis>[18.3]/8</emphasis> Even though it's listed in the library - sections, libstdc++ has zero control over what the cleanup code hands - back to the runtime loader. Talk to the compiler people. :-) - </para> - <para><emphasis>[18.4.2.1]/5</emphasis> (bad_alloc), - <emphasis>[18.5.2]/5</emphasis> (bad_cast), - <emphasis>[18.5.3]/5</emphasis> (bad_typeid), - <emphasis>[18.6.1]/8</emphasis> (exception), - <emphasis>[18.6.2.1]/5</emphasis> (bad_exception): The <code>what()</code> - member function of class <code>std::exception</code>, and these other - classes publicly derived from it, simply returns the name of the - class. But they are the <emphasis>mangled</emphasis> names; you will need to call - <code>c++filt</code> and pass the names as command-line parameters to - demangle them, or call a - <ulink url="../18_support/howto.html#5">runtime demangler function</ulink>. - (The classes in <code><stdexcept></code> have constructors which - require an argument to use later for <code>what()</code> calls, so the - problem of <code>what()</code>'s value does not arise in most - user-defined exceptions.) - </para> - <para><emphasis>[18.5.1]/7</emphasis> The return value of - <code>std::type_info::name()</code> is the mangled type name (see the - previous entry for more). - </para> - <para><emphasis>[20.1.5]/5</emphasis> <emphasis>"Implementors are encouraged to - supply libraries that can accept allocators that encapsulate more - general memory models and that support non-equal instances. In such - implementations, any requirements imposed on allocators by containers - beyond those requirements that appear in Table 32, and the semantics - of containers and algorithms when allocator instances compare - non-equal, are implementation-defined."</emphasis> As yet we don't - have any allocators which compare non-equal, so we can't describe how - they behave. - </para> - <para><emphasis>[21.1.3.1]/3,4</emphasis>, - <emphasis>[21.1.3.2]/2</emphasis>, - <emphasis>[23.*]'s foo::iterator</emphasis>, - <emphasis>[27.*]'s foo::*_type</emphasis>, - <emphasis>others...</emphasis> - Nope, these types are called implementation-defined because you - shouldn't be taking advantage of their underlying types. Listing them - here would defeat the purpose. :-) - </para> - <para><emphasis>[21.1.3.1]/5</emphasis> I don't really know about the mbstate_t - stuff... see the <ulink url="../22_locale/howto.html">chapter 22 notes</ulink> - for what does exist. - </para> - <para><emphasis>[22.*]</emphasis> Anything and everything we have on locale - implementation will be described - <ulink url="../22_locale/howto.html">over here</ulink>. - </para> - <para><emphasis>[26.2.8]/9</emphasis> I have no idea what - <code>complex<T></code>'s pow(0,0) returns. - </para> - <para><emphasis>[27.4.2.4]/2</emphasis> Calling - <code>std::ios_base::sync_with_stdio</code> after I/O has already been - performed on the standard stream objects will - flush the buffers, and <!-- this line might go away --> - destroy and recreate the underlying buffer instances. Whether or not - the previously-written I/O is destroyed in this process depends mostly - on the --enable-libio choice: for stdio, if the written data is - already in the stdio buffer, the data may be completely safe! - </para> - <para><emphasis>[27.6.1.1.2]</emphasis>, - <emphasis>[27.6.2.3]</emphasis> The I/O sentry ctor and dtor can perform - additional work than the minimum required. We are not currently taking - advantage of this yet. - </para> - <para><emphasis>[27.7.1.3]/16</emphasis>, - <emphasis>[27.8.1.4]/10</emphasis> - The effects of <code>pubsetbuf/setbuf</code> are described - <ulink url="../27_io/howto.html#2">in this chapter</ulink>. - </para> - <para><emphasis>[27.8.1.4]/16</emphasis> Calling <code>fstream::sync</code> when - a get area exists will... whatever <code>fflush()</code> does, I think. - </para> - -</sect3> - -</sect2> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxx200x.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxx200x.xml deleted file mode 100644 index 2fc1921a3..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxx200x.xml +++ /dev/null @@ -1,2572 +0,0 @@ -<sect2 id="status.iso.200x" xreflabel="Status C++ 200x"> -<?dbhtml filename="status_iso_cxx200x.html"?> - -<sect2info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - 200x - </keyword> - </keywordset> -</sect2info> - -<title>C++ 200x</title> - -<para> -This table is based on the table of contents of ISO/IEC -Doc No: N2857=09-0047 Date: 2009-03-23 -Working Draft, Standard for Programming Language C++ -</para> - -<para> -In this implementation <literal>-std=gnu++0x</literal> or -<literal>-std=c++0x</literal> flags must be used to enable language and -library features. The pre-defined symbol -<constant>__GXX_EXPERIMENTAL_CXX0X__</constant> is used to check for the -presence of the required flag. -</para> - -<para> -This page describes the C++0x support in mainline GCC SVN, not in any -particular release. -</para> - -<!-- Status is Yes or No, Broken/Partial--> -<!-- - Yes - - No - <?dbhtml bgcolor="#C8B0B0" ?> - Broken/Partial - <?dbhtml bgcolor="#B0B0B0" ?> ---> -<table frame='all'> -<title>C++ 200x Implementation Status</title> -<tgroup cols='4' align='left' colsep='0' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> - <thead> - <row> - <entry>Section</entry> - <entry>Description</entry> - <entry>Status</entry> - <entry>Comments</entry> - </row> - </thead> - - <tbody> - <row> - <entry> - <emphasis>18</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Language support</emphasis> - </entry> - </row> - - <row> - <entry>18.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>18.2</entry> - <entry>Types</entry> - <entry>Partial</entry> - <entry>Missing offsetof, max_align_t, nullptr_t</entry> - </row> - <row> - <entry>18.3</entry> - <entry>Implementation properties</entry> - <entry></entry> - <entry></entry> - </row> - - <row> - <entry>18.3.1</entry> - <entry>Numeric Limits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.3.1.1</entry> - <entry>Class template <code>numeric_limits</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>18.3.1.2</entry> - <entry><code>numeric_limits</code> members</entry> - <entry>Partial</entry> - <entry>Missing constexpr</entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>18.3.1.3</entry> - <entry><code>float_round_style</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>18.3.1.4</entry> - <entry><code>float_denorm_style</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>18.3.1.5</entry> - <entry><code>numeric_limits</code> specializations</entry> - <entry>Y</entry> - <entry></entry> - </row> - - <row> - <entry>18.3.2</entry> - <entry>C Library</entry> - <entry>Y</entry> - <entry></entry> - </row> - - <row> - <entry>18.4</entry> - <entry>Integer types</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.4.1</entry> - <entry>Header <code><cstdint></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>18.4.2</entry> - <entry>The header <code><stdint.h></code></entry> - <entry>Partial</entry> - <entry>May use configure-generated stdint.h via GCC_HEADER_STDINT</entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>18.5</entry> - <entry>Start and termination</entry> - <entry>Partial</entry> - <entry>Missing quick_exit, at_quick_exit</entry> - </row> - <row> - <entry>18.6</entry> - <entry>Dynamic memory management</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.7</entry> - <entry>Type identification</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.7.1</entry> - <entry>Class type_info</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>18.7.2</entry> - <entry>Class type_index</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>18.7.3</entry> - <entry>Class bad_cast</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.7.4</entry> - <entry>Class bad_typeid</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.8</entry> - <entry>Exception handling</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.8.1</entry> - <entry>Class exception</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.8.2</entry> - <entry>Violation exception-specifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.8.3</entry> - <entry>Abnormal termination</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.8.4</entry> - <entry><code>uncaught_exception</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.8.5</entry> - <entry>Propagation</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>18.8.6</entry> - <entry>Class <code>nested_exception</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>18.9</entry> - <entry>Initializer lists</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>18.9.1</entry> - <entry>Initializer list constructors</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>18.9.2</entry> - <entry>Initializer list access</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>18.9.3</entry> - <entry>Initializer list concept maps</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>18.10</entry> - <entry>Other runtime support</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>19</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Diagnostics</emphasis> - </entry> - </row> - <row> - <entry>19.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>19.2</entry> - <entry>Exception classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>19.3</entry> - <entry>Assertions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>19.4</entry> - <entry>Error numbers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>19.5</entry> - <entry>System error support</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>19.5.1</entry> - <entry>Class <code>error_category</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>19.5.2</entry> - <entry>Class <code>error_code</code></entry> - <entry>Partial</entry> - <entry>Missing concept ErrorCodeEnum</entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>19.5.3</entry> - <entry>Class <code>error_condition</code></entry> - <entry>Partial</entry> - <entry>Missing concept ErrorConditionEnum</entry> - </row> - <row> - <entry>19.5.4</entry> - <entry>Comparison operators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>19.5.5</entry> - <entry>Class <code>system_error</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>20</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>General utilities</emphasis> - </entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>20.1</entry> - <entry>General</entry> - <entry>Partial</entry> - <entry>Missing all concepts</entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.2</entry> - <entry>Concepts</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.3</entry> - <entry>Utility components</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.3.1</entry> - <entry>Operators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.2</entry> - <entry><code>forward</code> and <code>move</code> helpers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.3</entry> - <entry><code>pair</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.3.4</entry> - <entry>tuple-like access to <code>pair</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.3.5</entry> - <entry>Range concept maps for <code>pair</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.3.6</entry> - <entry>Class template <code>bitset</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4</entry> - <entry>Compile-time rational arithmetic</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.4.1</entry> - <entry>Class template <code>ratio</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.2</entry> - <entry>Arithmetic on <code>ratio</code> types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.3</entry> - <entry>Comparison of <code>ratio</code> types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.4.4</entry> - <entry>SI types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.5</entry> - <entry>Tuples</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.5.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>20.5.2</entry> - <entry>Class template <code>tuple</code></entry> - <entry>Partial</entry> - <entry>Missing range concept maps</entry> - </row> - <row> - <entry>20.6</entry> - <entry>Metaprogramming and type traits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.6.1</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>20.6.2</entry> - <entry>Header <code><type_traits></code> synopsis</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.6.3</entry> - <entry>Helper classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.6.4</entry> - <entry>Unary Type Traits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.6.4.1</entry> - <entry>Primary type categories</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.6.4.2</entry> - <entry>Composite type traits</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>20.6.4.3</entry> - <entry>Type properties</entry> - <entry>Partial</entry> - <entry>Missing is_system_layout</entry> - </row> - <row> - <entry>20.6.5</entry> - <entry>Relationships between types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.6.6</entry> - <entry>Transformations between types</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.6.6.1</entry> - <entry>Const-volatile modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.6.6.2</entry> - <entry>Reference modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.6.6.3</entry> - <entry>Sign modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.6.6.4</entry> - <entry>Array modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.6.6.5</entry> - <entry>Pointer modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>20.6.7</entry> - <entry>Other transformations</entry> - <entry>Partial</entry> - <entry>Missing decay</entry> - </row> - <row> - <entry>20.7</entry> - <entry>Function objects</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.7.1</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.3</entry> - <entry>Base</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.4</entry> - <entry>Function object return types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.5</entry> - <entry>Class template <code>reference_wrapper</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.7.6</entry> - <entry>Identity operation</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.7.7</entry> - <entry>Arithmetic operation</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.8</entry> - <entry>Comparisons</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.9</entry> - <entry>Logical operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.10</entry> - <entry>Bitwise operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.11</entry> - <entry>Negators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.12</entry> - <entry>Template <code>function</code> and function template <code>bind</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.13</entry> - <entry>Adaptors for pointers to functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.14</entry> - <entry>Adaptors for pointers to members</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.15</entry> - <entry>Function template <code>mem_fn</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.16</entry> - <entry>Polymorphic function wrappers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.7.16.1</entry> - <entry>Class <code>bad_function_call</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.16.2</entry> - <entry>Class template <code>function</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.7.17</entry> - <entry>Class template <code>hash</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.7.18</entry> - <entry>Class template <code>reference_closure</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.8</entry> - <entry>Memory</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.01</entry> - <entry>Allocator argument tag</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.8.02</entry> - <entry>Allocators</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.8.02.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.02.2</entry> - <entry>Allocator concept</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.02.3</entry> - <entry>Support for legacy allocators</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.02.4</entry> - <entry>Allocator and Legacy Allocator members</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.03</entry> - <entry>Allocator-related element concepts</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.04</entry> - <entry>Allocator propagation traits</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.05</entry> - <entry>Allocator propagation map</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.8.06</entry> - <entry>The default allocator</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.07</entry> - <entry>Scoped allocator adaptor</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.07.1</entry> - <entry><code>scoped_allocator_adaptor_base</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.07.2</entry> - <entry><code>scoped_allocator_adaptor constructors</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.07.3</entry> - <entry><code>scoped_allocator_adaptor2</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.07.3</entry> - <entry>scoped_allocator_adaptor members</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.07.4</entry> - <entry><code>scoped_allocator_adaptor globals</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.8.08</entry> - <entry>Raw storage iterator</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.09</entry> - <entry>Temporary buffers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.10</entry> - <entry><code>construct_element</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.8.11</entry> - <entry>Specialized algorithms</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.11.1</entry> - <entry><code>addressof</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.8.11.2</entry> - <entry><code>uninitialized_copy</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.11.3</entry> - <entry><code>uninitialized_fill</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.11.4</entry> - <entry><code>uninitialized_fill_n</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.12</entry> - <entry>Class template <code>unique_ptr</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.13</entry> - <entry>Smart pointers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.8.13.1</entry> - <entry>Class <code>bad_weak_ptr</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.13.2</entry> - <entry>Class template <code>shared_ptr</code></entry> - <entry>Y</entry> - <entry> - <para> - Uses code from - <ulink url="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</ulink>. - </para> - </entry> - </row> - <row> - <entry>20.8.13.3</entry> - <entry>Class template <code>weak_ptr</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.13.4</entry> - <entry>Class template <code>owner_less</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.8.13.5</entry> - <entry>Class template <code>emable_shared_from_this</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>20.8.13.6</entry> - <entry><code>shared_ptr</code> atomic access</entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>20.8.13.7</entry> - <entry>Pointer safety</entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>20.8.14</entry> - <entry>Align</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>20.8.15</entry> - <entry>C library</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9</entry> - <entry>Time utilities</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.9.1</entry> - <entry>Clock requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.2</entry> - <entry>Time-related traits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.9.2.1</entry> - <entry><code>treat_as_floating_point</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.2.2</entry> - <entry><code>duration_values</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.2.3</entry> - <entry>Specializations of <code>common_type</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.3</entry> - <entry>Class template <code>duration</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.4</entry> - <entry>Class template <code>time_point</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.5</entry> - <entry>Clocks</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>20.9.5.1</entry> - <entry>Class <code>system_clock</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.5.2</entry> - <entry>Class <code>monotonic_clock</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.9.5.3</entry> - <entry>Class <code>high_resolution_clock</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>20.10</entry> - <entry>Date and time functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>21</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Strings</emphasis> - </entry> - </row> - <row> - <entry>21.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.2</entry> - <entry>Character traits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>21.2.1</entry> - <entry>Character traits requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.2.2</entry> - <entry>traits typedef</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.2.3</entry> - <entry><code>char_traits</code> specializations</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>21.2.3.1</entry> - <entry>struct <code>char_traits<char></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.2.3.2</entry> - <entry>struct <code>char_traits<char16_t></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.2.3.3</entry> - <entry>struct <code>char_traits<char32_t></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.2.3.4</entry> - <entry>struct <code>char_traits<wchar_t></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.3</entry> - <entry>String classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.4</entry> - <entry>Class template <code>basic_string</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.5</entry> - <entry>Numeric Conversions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>21.6</entry> - <entry>Null-terminated sequence utilities</entry> - <entry>Y</entry> - <entry>C library dependency</entry> - </row> - <row> - <entry> - <emphasis>22</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Localization</emphasis> - </entry> - </row> - <row> - <entry>22.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.2</entry> - <entry>Header <code><locale></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.3</entry> - <entry>Locales</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.3.1</entry> - <entry>Class <code>locale</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.3.2</entry> - <entry><code>locale</code> globals</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.3.3</entry> - <entry>Convenience interfaces</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.3.3.1</entry> - <entry>Character classification</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.3.3.2</entry> - <entry>Conversions</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.3.3.2.1</entry> - <entry>Character</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>22.3.3.2.2</entry> - <entry>String</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>22.3.3.2.3</entry> - <entry>Buffer</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>22.4</entry> - <entry>Standard locale categories</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.4.1</entry> - <entry><code>ctype</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.2</entry> - <entry>Numeric</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.4.2.1</entry> - <entry><code>num_get</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.2.2</entry> - <entry><code>num_put</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.3</entry> - <entry><code>num_punct</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.4</entry> - <entry><code>collate</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.5</entry> - <entry>Time</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.4.5.1</entry> - <entry><code>time_get</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.5.2</entry> - <entry><code>time_get_byname</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.5.3</entry> - <entry><code>time_put</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.5.3</entry> - <entry><code>time_put_byname</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.6</entry> - <entry>Monetary</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>22.4.6.1</entry> - <entry><code>money_get</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.6.2</entry> - <entry><code>money_put</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.6.3</entry> - <entry><code>money_punct</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.6.4</entry> - <entry><code>money_punct_byname</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.7</entry> - <entry><code>messages</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>22.4.8</entry> - <entry>Program-defined facets</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>22.5</entry> - <entry>Standard code conversion facets</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>22.6</entry> - <entry>C Library Locales</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>23</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Containers</emphasis> - </entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>23.1</entry> - <entry>General</entry> - <entry>Partial</entry> - <entry>Missing concepts</entry> - </row> - <row> - <entry>23.2</entry> - <entry>Container requirements</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>23.2.1</entry> - <entry>General requirements</entry> - <entry>Partial</entry> - <entry>Missing construct_element</entry> - </row> - <row> - <entry>23.2.2</entry> - <entry>Data races</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3</entry> - <entry>Sequence containers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>23.3.1</entry> - <entry>Class template <code>array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.2</entry> - <entry>Class template <code>deque</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.3</entry> - <entry>Class template <code>forward_list</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.4</entry> - <entry>Class template <code>list</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.5</entry> - <entry>Adaptors</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>23.3.5.1</entry> - <entry>Class template <code>queue</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.5.2</entry> - <entry>Class template <code>priority_queue</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.5.3</entry> - <entry>Class template <code>stack</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.6</entry> - <entry>Class template <code>vector</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.3.7</entry> - <entry>Class <code>vector<bool></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.4</entry> - <entry>Associative containers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>23.4.1</entry> - <entry>Class template <code>map</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.4.2</entry> - <entry>Class template <code>multimap</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.4.3</entry> - <entry>Class template <code>set</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.4.4</entry> - <entry>Class template <code>multiset</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.5</entry> - <entry>Unordered associative containers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>23.5.1</entry> - <entry>Class template <code>unordered_map</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.5.2</entry> - <entry>Class template <code>unordered_multimap</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.5.3</entry> - <entry>Class template <code>unordered_set</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>23.5.4</entry> - <entry>Class template <code>unordered_multiset</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>24</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Iterators</emphasis> - </entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>24.1</entry> - <entry>General</entry> - <entry>Partial</entry> - <entry>Missing concepts</entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>24.2</entry> - <entry>Iterator concepts</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>24.3</entry> - <entry>Header <code><iterator></code> synopsis</entry> - <entry>Partial</entry> - <entry>Missing concepts</entry> - </row> - <row> - <entry>24.4</entry> - <entry>Iterator operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.5</entry> - <entry>Predefined iterators and Iterator adaptors</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>24.5.1</entry> - <entry>Reverse iterators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.5.2</entry> - <entry>Insert iterators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.5.3</entry> - <entry>Move iterators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.6</entry> - <entry>Stream iterators</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>24.6.1</entry> - <entry>Class template <code>istream_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.6.2</entry> - <entry>Class template <code>ostream_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.6.3</entry> - <entry>Class template <code>istreambuf_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.6.4</entry> - <entry>Class template <code>ostreambuf_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.7</entry> - <entry>Insert iterators</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>24.7.1</entry> - <entry>Class template <code>back_insert_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.7.3</entry> - <entry>Class template <code>front_insert_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>24.7.5</entry> - <entry>Class template <code>insert_iterator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>25</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Algorithms</emphasis> - </entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>25.1</entry> - <entry>General</entry> - <entry>Partial</entry> - <entry>Missing concepts</entry> - </row> - <row> - <entry>25.2</entry> - <entry>Header <code><algorithm></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>25.3</entry> - <entry>Non-modifying sequence operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>25.4</entry> - <entry>Mutating sequence operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>25.5</entry> - <entry>Sorting and related operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>25.6</entry> - <entry>C library algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>26</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Numerics</emphasis> - </entry> - </row> - <row> - <entry>26.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.2</entry> - <entry>Numeric type requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.3</entry> - <entry>The floating-point environment</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.4</entry> - <entry>Complex numbers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.5</entry> - <entry>Random number generation</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>26.5.1</entry> - <entry>Header <code><random></code> synopsis</entry> - <entry>Partial</entry> - <entry>Missing concepts, based on TR1</entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.2</entry> - <entry>Concepts and related requirements</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.3</entry> - <entry>Random number engines</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.3.1</entry> - <entry>Class template <code>linear_congruential_engine</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.3.2</entry> - <entry>Class template <code>mersenne_twister_engine</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.3.3</entry> - <entry>Class template <code>subtract_with_carry_engine</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.4</entry> - <entry>Random number engine adaptors</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.4.1</entry> - <entry>Class template <code>discard_block_engine</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.4.2</entry> - <entry>Class template <code>independent_bits_engine</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.4.3</entry> - <entry>Class template <code>shuffle_order_engine</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.5</entry> - <entry>Engines and engine adaptors with predefined parameters</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.6</entry> - <entry>Class <code>random_device</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.7</entry> - <entry>Utilities</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.7.1</entry> - <entry>Class <code>seed_seq</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.7.2</entry> - <entry>Function template generate_canonical</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.8</entry> - <entry>Random number distributions</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>26.5.8.1</entry> - <entry>Uniform distributions</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.1.1</entry> - <entry>Class template <code>uniform_int_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.1.2</entry> - <entry>Class template <code>uniform_real_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.8.2</entry> - <entry>Bernoulli distributions</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.2.1</entry> - <entry>Class <code>bernoulli_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.2.2</entry> - <entry>Class template <code>binomial_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.2.3</entry> - <entry>Class template <code>geometric_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.2.4</entry> - <entry>Class template <code>negative_binomial_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.8.3</entry> - <entry>Poisson distributions</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.3.1</entry> - <entry>Class template <code>poisson_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.3.2</entry> - <entry>Class template <code>exponential_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.3.3</entry> - <entry>Class template <code>gamma_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.3.4</entry> - <entry>Class template <code>weibull_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.3.5</entry> - <entry>Class template <code>extreme_value_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.8.4</entry> - <entry>Normal distributions</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.4.1</entry> - <entry>Class template <code>normal_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.4.2</entry> - <entry>Class template <code>lognormal_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.4.3</entry> - <entry>Class template <code>chi_squared_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.4.4</entry> - <entry>Class template <code>cauchy_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.4.5</entry> - <entry>Class template <code>fisher_f_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.4.6</entry> - <entry>Class template <code>student_t_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.5.8.5</entry> - <entry>Sampling distributions</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.5.1</entry> - <entry>Class template <code>discrete_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.5.2</entry> - <entry>Class template <code>piecewise_constant_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>26.5.8.5.3</entry> - <entry>Class template <code>piecewise_linear_distribution</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>26.6</entry> - <entry>Numeric arrays</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>26.6.1</entry> - <entry>Header <code><valarray></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.2</entry> - <entry>Class template <code>valarray</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.3</entry> - <entry><code>valarray</code> non-member operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.4</entry> - <entry>Class <code>slice</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.5</entry> - <entry>Class template <code>slice_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.6</entry> - <entry>Class <code>gslice</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.7</entry> - <entry>Class template <code>gslice_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.8</entry> - <entry>Class template <code>mask_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.6.9</entry> - <entry>Class template <code>indirect_array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.7</entry> - <entry>Generalized numeric operations</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>26.7.1</entry> - <entry><code>accumulate</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.7.2</entry> - <entry><code>inner_product</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.7.3</entry> - <entry><code>partial_sum</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.7.4</entry> - <entry><code>adjacent_difference</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.7.5</entry> - <entry>iota</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>26.8</entry> - <entry>C Library</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>27</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Input/output</emphasis> - </entry> - </row> - <row> - <entry>27.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.2</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.2.1</entry> - <entry>Imbue limitations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.2.2</entry> - <entry>Positioning type limitations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>27.2.3</entry> - <entry>Thread safety</entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <entry>27.3</entry> - <entry>Forward declarations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.4</entry> - <entry>Standard iostream objects</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.4.1</entry> - <entry>Narrow stream objects</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.4.2</entry> - <entry>Wide stream objects</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.5</entry> - <entry>Iostreams base classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.6</entry> - <entry>Stream buffers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.7</entry> - <entry>Formatting and manipulators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.8</entry> - <entry>String-based streams</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>27.9</entry> - <entry>File-based streams</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>28</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Regular expressions</emphasis> - </entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.01</entry> - <entry>General</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.02</entry> - <entry>Definitions</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.03</entry> - <entry>Requirements</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.04</entry> - <entry>Regular expressions summary</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.05</entry> - <entry>Header <code><regex></code> synopsis</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>28.06</entry> - <entry>Namespace <code>std::regex_constants</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>28.07</entry> - <entry>Class <code>regex_error</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>28.08</entry> - <entry>Class template <code>regex_traits</code></entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>28.09</entry> - <entry>Class template <code>basic_regex</code></entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>28.10</entry> - <entry>Class template <code>sub_match</code></entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>28.11</entry> - <entry>Class template <code>match_results</code></entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.12</entry> - <entry>Regular expression algorithms</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.13</entry> - <entry>Regular expression Iterators</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>28.14</entry> - <entry>Modified ECMAScript regular expression grammar</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>29</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Atomic operations</emphasis> - </entry> - </row> - <row> - <entry>29.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>29.2</entry> - <entry>Header <code><cstdatomic></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>29.3</entry> - <entry>Order and consistency</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>29.4</entry> - <entry>Lock-free property</entry> - <entry>Y</entry> - <entry>Based on _GLIBCXX_ATOMIC_PROPERTY</entry> - </row> - <row> - <entry>29.5</entry> - <entry>Atomic types</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>29.5.1</entry> - <entry>Integral types</entry> - <entry>Y</entry> - <entry>Missing constexpr</entry> - </row> - <row> - <entry>29.5.2</entry> - <entry>Address types</entry> - <entry>Y</entry> - <entry>Missing constexpr</entry> - </row> - <row> - <entry>29.5.3</entry> - <entry>Generic types</entry> - <entry>Y</entry> - <entry>Missing constexpr</entry> - </row> - <row> - <entry>29.6</entry> - <entry>Operations on atomic types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>29.7</entry> - <entry>Flag Type and operations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>29.8</entry> - <entry>Fences</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>30</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Thread support</emphasis> - </entry> - </row> - <row> - <entry>30.1</entry> - <entry>General</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.2</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.3</entry> - <entry>Threads</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>30.3.1</entry> - <entry>Class <code>thread</code></entry> - <entry>Partial</entry> - <entry>Missing futures</entry> - </row> - <row> - <entry>30.3.2</entry> - <entry>Namespace <code>this_thread</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4</entry> - <entry>Mutual exclusion</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>30.4.1</entry> - <entry>Mutex requirements</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>30.4.1.1</entry> - <entry>Class <code>mutex</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.1.2</entry> - <entry>Class <code>recursive_mutex</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.2</entry> - <entry>Timed mutex requirements</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>30.4.2.1</entry> - <entry>Class <code>timed_mutex</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.2.2</entry> - <entry>Class <code>recursive_timed_mutex</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.3</entry> - <entry>Locks</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>30.4.3.1</entry> - <entry>Class template <code>lock_guard</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.3.2</entry> - <entry>Class template <code>unique_lock</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.4</entry> - <entry>Generic locking algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.5</entry> - <entry>Call once</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>30.4.5.1</entry> - <entry><code>once_flag</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.4.5.2</entry> - <entry><code>call_once</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>30.5</entry> - <entry>Condition variables</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>30.5.1</entry> - <entry>Class <code>condition_variable</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#B0B0B0" ?> - <entry>30.5.2</entry> - <entry>Class <code>condition_variable_any</code></entry> - <entry>Partial</entry> - <entry></entry> - </row> - <row> - <entry>30.6</entry> - <entry>Futures</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.1</entry> - <entry>Overview</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.2</entry> - <entry>Error handling</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.3</entry> - <entry>Class <code>future_error</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.4</entry> - <entry>Class template <code>unique_future</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.5</entry> - <entry>Class template <code>shared_future</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.6</entry> - <entry>Class template <code>promise</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.7</entry> - <entry>Allocator templates</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>30.6.8</entry> - <entry>Class template <code>packaged_task</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry> - <emphasis>Appendix D</emphasis> - </entry> - <entry namest="c2" nameend="c4" align="left"> - <emphasis>Compatibility features</emphasis> - </entry> - </row> - <row> - <entry>D.1</entry> - <entry>Increment operator with bool operand</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.2</entry> - <entry><code>static</code> keyword</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.3</entry> - <entry>Access declarations</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.4</entry> - <entry>Implicit conversion from const strings</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.5</entry> - <entry>C standard library headers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.6</entry> - <entry>Old iostreams members</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.7</entry> - <entry>char* streams</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.8</entry> - <entry>Binders</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.9</entry> - <entry><code>auto_ptr</code></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>D.10</entry> - <entry>Iterator primitives</entry> - <entry></entry> - <entry></entry> - </row> - - </tbody> -</tgroup> -</table> - - -</sect2> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml deleted file mode 100644 index 10ca06d13..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml +++ /dev/null @@ -1,1782 +0,0 @@ -<sect2 id="status.iso.tr1" xreflabel="Status C++ TR1"> -<?dbhtml filename="status_iso_cxxtr1.html"?> - -<sect2info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - tr1 - </keyword> - </keywordset> -</sect2info> - -<title>C++ TR1</title> - -<para> -This table is based on the table of contents of ISO/IEC DTR 19768 -Doc No: N1836=05-0096 Date: 2005-06-24 -Draft Technical Report on C++ Library Extensions -</para> - -<para> -In this implementation the header names are prefixed by -<code>tr1/</code>, for instance <code><tr1/functional></code>, -<code><tr1/memory></code>, and so on. -</para> - -<para> -This page describes the TR1 support in mainline GCC SVN, not in any particular -release. -</para> - -<!-- Status is Yes or No, Broken/Partial--> -<!-- - Yes - - No - <?dbhtml bgcolor="#C8B0B0" ?> - Broken/Partial - <?dbhtml bgcolor="#B0B0B0" ?> ---> -<table frame='all'> -<title>C++ TR1 Implementation Status</title> -<tgroup cols='4' align='left' colsep='0' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> - - <thead> - <row> - <entry>Section</entry> - <entry>Description</entry> - <entry>Status</entry> - <entry>Comments</entry> - </row> - </thead> - <tbody> - <row> - <entry><emphasis>2</emphasis></entry> - <entry namest="c2" nameend="c4" align="left"><emphasis>General Utilities</emphasis></entry> - </row> - <row> - <entry>2.1</entry> - <entry>Reference wrappers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>2.1.1</entry> - <entry>Additions to header <code><functional></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.1.2</entry> - <entry>Class template <code>reference_wrapper</code></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>2.1.2.1</entry> - <entry><code>reference_wrapper</code> construct/copy/destroy</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.1.2.2</entry> - <entry><code>reference_wrapper</code> assignment</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.1.2.3</entry> - <entry><code>reference_wrapper</code> access</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.1.2.4</entry> - <entry><code>reference_wrapper</code> invocation</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.1.2.5</entry> - <entry><code>reference_wrapper</code> helper functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2</entry> - <entry>Smart pointers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>2.2.1</entry> - <entry>Additions to header <code><memory></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.2</entry> - <entry>Class <code>bad_weak_ptr</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3</entry> - <entry>Class template <code>shared_ptr</code></entry> - <entry></entry> - <entry> - <para> - Uses code from - <ulink url="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</ulink>. - </para> - </entry> - </row> - <row> - <entry>2.2.3.1</entry> - <entry><code>shared_ptr</code> constructors</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.2</entry> - <entry><code>shared_ptr</code> destructor</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.3</entry> - <entry><code>shared_ptr</code> assignment</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.4</entry> - <entry><code>shared_ptr</code> modifiers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.5</entry> - <entry><code>shared_ptr</code> observers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.6</entry> - <entry><code>shared_ptr</code> comparison</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.7</entry> - <entry><code>shared_ptr</code> I/O</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.8</entry> - <entry><code>shared_ptr</code> specialized algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.9</entry> - <entry><code>shared_ptr</code> casts</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.3.10</entry> - <entry><code>get_deleter</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.4</entry> - <entry>Class template <code>weak_ptr</code></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>2.2.4.1</entry> - <entry><code>weak_ptr</code> constructors</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.4.2</entry> - <entry><code>weak_ptr</code> destructor</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.4.3</entry> - <entry><code>weak_ptr</code> assignment</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.4.4</entry> - <entry><code>weak_ptr</code> modifiers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.4.5</entry> - <entry><code>weak_ptr</code> observers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.4.6</entry> - <entry><code>weak_ptr</code> comparison</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.4.7</entry> - <entry><code>weak_ptr</code> specialized algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>2.2.5</entry> - <entry>Class template <code>enable_shared_from_this</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry><emphasis>3</emphasis></entry> - <entry namest="c2" nameend="c4" align="left"><emphasis>Function Objects</emphasis></entry> - </row> - <row> - <entry>3.1</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.2</entry> - <entry>Additions to <code><functional> synopsis</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.3</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.4</entry> - <entry>Function return types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.5</entry> - <entry>Function template <code>mem_fn</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.6</entry> - <entry>Function object binders</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>3.6.1</entry> - <entry>Class template <code>is_bind_expression</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.6.2</entry> - <entry>Class template <code>is_placeholder</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.6.3</entry> - <entry>Function template <code>bind</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.6.4</entry> - <entry>Placeholders</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7</entry> - <entry>Polymorphic function wrappers</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>3.7.1</entry> - <entry>Class <code>bad_function_call<code></code></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.1.1</entry> - <entry><code>bad_function_call</code> constructor</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2</entry> - <entry>Class template <code>function</code></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.1</entry> - <entry><code>function</code> construct/copy/destroy</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.2</entry> - <entry><code>function</code> modifiers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.3</entry> - <entry><code>function</code> capacity</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.4</entry> - <entry><code>function</code> invocation</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.5</entry> - <entry><code>function</code> target access</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.6</entry> - <entry>undefined operators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.7</entry> - <entry>null pointer comparison operators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>3.7.2.8</entry> - <entry>specialized algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry><emphasis>4</emphasis></entry> - <entry namest="c2" nameend="c4" align="left"><emphasis>Metaprogramming and type traits</emphasis></entry> - </row> - <row> - <entry>4.1</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.2</entry> - <entry>Header <code><type_traits></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.3</entry> - <entry>Helper classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.4</entry> - <entry>General Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.5</entry> - <entry>Unary Type Traits</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>4.5.1</entry> - <entry>Primary Type Categories</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.5.2</entry> - <entry>Composite type traits</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.5.3</entry> - <entry>Type properties</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.6</entry> - <entry>Relationships between types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.7</entry> - <entry>Transformations between types</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>4.7.1</entry> - <entry>Const-volatile modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.7.2</entry> - <entry>Reference modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.7.3</entry> - <entry>Array modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.7.4</entry> - <entry>Pointer modifications</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.8</entry> - <entry>Other transformations</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>4.9</entry> - <entry>Implementation requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry><emphasis>5</emphasis></entry> - <entry namest="c2" nameend="c4" align="left"><emphasis>Numerical Facilities</emphasis></entry> - </row> - <row> - <entry>5.1</entry> - <entry>Random number generation</entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry>5.1.1</entry> - <entry>Requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.2</entry> - <entry>Header <code><random></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.3</entry> - <entry>Class template <code>variate_generator</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.4</entry> - <entry>Random number engine class templates</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.4.1</entry> - <entry>Class template <code>linear_congruential</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.4.2</entry> - <entry>Class template <code>mersenne_twister</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.4.3</entry> - <entry>Class template <code>subtract_with_carry</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.4.4</entry> - <entry>Class template <code>subtract_with_carry_01</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.4.5</entry> - <entry>Class template <code>discard_block</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.4.6</entry> - <entry>Class template <code>xor_combine</code></entry> - <entry>Y</entry> - <entry>operator()() per N2079</entry> - </row> - <row> - <entry>5.1.5</entry> - <entry>Engines with predefined parameters</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.6</entry> - <entry>Class <code>random_device</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7</entry> - <entry>Random distribution class templates</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.1</entry> - <entry>Class template <code>uniform_int</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.2</entry> - <entry>Class <code>bernoulli_distribution</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.3</entry> - <entry>Class template <code>geometric_distribution</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.4</entry> - <entry>Class template <code>poisson_distribution</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.5</entry> - <entry>Class template <code>binomial_distribution</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.6</entry> - <entry>Class template <code>uniform_real</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.7</entry> - <entry>Class template <code>exponential_distribution</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.8</entry> - <entry>Class template <code>normal_distribution</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.1.7.9</entry> - <entry>Class template <code>gamma_distribution</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2</entry> - <entry>Mathematical special functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1</entry> - <entry>Additions to header <code><cmath></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.1</entry> - <entry>associated Laguerre polynomials</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.2</entry> - <entry>associated Legendre functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.3</entry> - <entry>beta function</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.4</entry> - <entry>(complete) elliptic integral of the first kind</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.5</entry> - <entry>(complete) elliptic integral of the second kind</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.6</entry> - <entry>(complete) elliptic integral of the third kind</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.7</entry> - <entry>confluent hypergeometric functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.8</entry> - <entry>regular modified cylindrical Bessel functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.9</entry> - <entry>cylindrical Bessel functions (of the first kind)</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.10</entry> - <entry>irregular modified cylindrical Bessel functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.11</entry> - <entry>cylindrical Neumann functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.12</entry> - <entry>(incomplete) elliptic integral of the first kind</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.13</entry> - <entry>(incomplete) elliptic integral of the second kind</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.14</entry> - <entry>(incomplete) elliptic integral of the third kind</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.15</entry> - <entry>exponential integral</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.16</entry> - <entry>Hermite polynomials</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.17</entry> - <entry>hypergeometric functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.18</entry> - <entry>Laguerre polynomials</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.19</entry> - <entry>Legendre polynomials</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.20</entry> - <entry>Riemann zeta function</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.21</entry> - <entry>spherical Bessel functions (of the first kind)</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.22</entry> - <entry>spherical associated Legendre functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.1.23</entry> - <entry>spherical Neumann functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>5.2.2</entry> - <entry>Additions to header <code><math.h></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry><emphasis>6</emphasis></entry> - <entry namest="c2" nameend="c4" align="left"><emphasis>Containers</emphasis></entry> - </row> - <row> - <entry>6.1</entry> - <entry>Tuple types</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.1</entry> - <entry>Header <code><tuple></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.2</entry> - <entry>Additions to header <code><utility></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.3</entry> - <entry>Class template <code>tuple</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.3.1</entry> - <entry>Construction</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.3.2</entry> - <entry>Tuple creation functions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.3.3</entry> - <entry>Tuple helper classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.3.4</entry> - <entry>Element access</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.3.5</entry> - <entry>Relational operators</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.1.4</entry> - <entry>Pairs</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.2</entry> - <entry>Fixed size array</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.2.1</entry> - <entry>Header <code><array></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.2.2</entry> - <entry>Class template <code>array</code></entry> - <entry>Y</entry> - - <entry></entry> - </row> - <row> - <entry>6.2.2.1</entry> - <entry><code>array</code> constructors, copy, and assignment</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.2.2.2</entry> - <entry><code>array</code> specialized algorithms</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.2.2.3</entry> - <entry><code>array</code> size</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.2.2.4</entry> - <entry>Zero sized <code>array</code>s</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.2.2.5</entry> - <entry>Tuple interface to class template <code>array</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3</entry> - <entry>Unordered associative containers</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.1</entry> - <entry>Unordered associative container requirements</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.1.1</entry> - <entry>Exception safety guarantees</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.2</entry> - <entry>Additions to header <code><functional></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.3</entry> - <entry>Class template <code>hash</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4</entry> - <entry>Unordered associative container classes</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.1</entry> - <entry>Header <code><unordered_set></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.2</entry> - <entry>Header <code><unordered_map></code> synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.3</entry> - <entry>Class template <code>unordered_set</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.3.1</entry> - <entry><code>unordered_set</code> constructors</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.3.2</entry> - <entry><code>unordered_set</code> swap</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.4</entry> - <entry>Class template <code>unordered_map</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.4.1</entry> - <entry><code>unordered_map</code> constructors</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.4.2</entry> - <entry><code>unordered_map</code> element access</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.4.3</entry> - <entry><code>unordered_map</code> swap</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.5</entry> - <entry>Class template <code>unordered_multiset<code></code></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.5.1</entry> - <entry><code>unordered_multiset</code> constructors</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.5.2</entry> - <entry><code>unordered_multiset</code> swap</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.6</entry> - <entry>Class template <code>unordered_multimap</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.6.1</entry> - <entry><code>unordered_multimap</code> constructors</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>6.3.4.6.2</entry> - <entry><code>unordered_multimap</code> swap</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry><emphasis>7</emphasis></entry> - <entry namest="c2" nameend="c4" align="left"><emphasis>Regular Expressions</emphasis></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.1</entry> - <entry>Definitions</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.2</entry> - <entry>Requirements</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.3</entry> - <entry>Regular expressions summary</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.4</entry> - <entry>Header <code><regex></code> synopsis</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.5</entry> - <entry>Namespace <code>tr1::regex_constants</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.5.1</entry> - <entry>Bitmask Type <code>syntax_option_type</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.5.2</entry> - <entry>Bitmask Type <code>regex_constants::match_flag_type</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.5.3</entry> - <entry>Implementation defined <code>error_type</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.6</entry> - <entry>Class <code>regex_error</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.7</entry> - <entry>Class template <code>regex_traits</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8</entry> - <entry>Class template <code>basic_regex</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.1</entry> - <entry><code>basic_regex</code> constants</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.2</entry> - <entry><code>basic_regex</code> constructors</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.3</entry> - <entry><code>basic_regex</code> assign</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.4</entry> - <entry><code>basic_regex</code> constant operations</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.5</entry> - <entry><code>basic_regex</code> locale</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.6</entry> - <entry><code>basic_regex</code> swap</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.7</entry> - <entry><code>basic_regex</code> non-member functions</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.8.7.1</entry> - <entry><code>basic_regex</code> non-member swap</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.9</entry> - <entry>Class template <code>sub_match</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.9.1</entry> - <entry><code>sub_match</code> members</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.9.2</entry> - <entry><code>sub_match</code> non-member operators</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.10</entry> - <entry>Class template <code>match_results</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.10.1</entry> - <entry><code>match_results</code> constructors</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.10.2</entry> - <entry><code>match_results</code> size</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.10.3</entry> - <entry><code>match_results</code> element access</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.10.4</entry> - <entry><code>match_results</code> formatting</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.10.5</entry> - <entry><code>match_results</code> allocator</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.10.6</entry> - <entry><code>match_results</code> swap</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.11</entry> - <entry>Regular expression algorithms</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.11.1</entry> - <entry>exceptions</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.11.2</entry> - <entry><code>regex_match</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.11.3</entry> - <entry><code>regex_search</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.11.4</entry> - <entry><code>regex_replace</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12</entry> - <entry>Regular expression Iterators</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.1</entry> - <entry>Class template <code>regex_iterator</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.1.1</entry> - <entry><code>regex_iterator</code> constructors</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.1.2</entry> - <entry><code>regex_iterator</code> comparisons</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.1.3</entry> - <entry><code>regex_iterator</code> dereference</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.1.4</entry> - <entry><code>regex_iterator</code> increment</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.2</entry> - <entry>Class template <code>regex_token_iterator</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.2.1</entry> - <entry><code>regex_token_iterator</code> constructors</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.2.2</entry> - <entry><code>regex_token_iterator</code> comparisons</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.2.3</entry> - <entry><code>regex_token_iterator</code> dereference</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.12.2.4</entry> - <entry><code>regex_token_iterator</code> increment</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>7.13</entry> - <entry>Modified ECMAScript regular expression grammar</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry><emphasis>8</emphasis></entry> - <entry namest="c2" nameend="c4" align="left"><emphasis>C Compatibility</emphasis></entry> - </row> - <row> - <entry>8.1</entry> - <entry>Additions to header <code><complex></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.2</entry> - <entry>Function <code>acos</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.3</entry> - <entry>Function <code>asin</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.4</entry> - <entry>Function <code>atan</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.5</entry> - <entry>Function <code>acosh</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.6</entry> - <entry>Function <code>asinh</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.7</entry> - <entry>Function <code>atanh</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.8</entry> - <entry>Function <code>fabs</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.1.9</entry> - <entry>Additional Overloads</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>8.2</entry> - <entry>Header <code><ccomplex></code></entry> - <entry>N</entry> - <entry>DR 551</entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>8.3</entry> - <entry>Header <code><complex.h></code></entry> - <entry>N</entry> - <entry>DR 551</entry> - </row> - <row> - <entry>8.4</entry> - <entry>Additions to header <code><cctype></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.4.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.4.2</entry> - <entry>Function <code>isblank</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.5</entry> - <entry>Additions to header <code><ctype.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.6</entry> - <entry>Header <code><cfenv></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.6.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.6.2</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.7</entry> - <entry>Header <code><fenv.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.8</entry> - <entry>Additions to header <code><cfloat></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.9</entry> - <entry>Additions to header <code><float.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>8.10</entry> - <entry>Additions to header <code><ios></code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>8.10.1</entry> - <entry>Synopsis</entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>8.10.2</entry> - <entry>Function <code>hexfloat</code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>8.11</entry> - <entry>Header <code><cinttypes></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.11.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry>DR 557</entry> - </row> - <row> - <entry>8.11.2</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.12</entry> - <entry>Header <code><inttypes.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.13</entry> - <entry>Additions to header <code><climits></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.14</entry> - <entry>Additions to header <code><limits.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <?dbhtml bgcolor="#C8B0B0" ?> - <entry>8.15</entry> - <entry>Additions to header <code><locale></code></entry> - <entry>N</entry> - <entry></entry> - </row> - <row> - <entry>8.16</entry> - <entry>Additions to header <code><cmath></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.16.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.16.2</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.16.3</entry> - <entry>Function template definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.16.4</entry> - <entry>Additional overloads</entry> - <entry>Y</entry> - <entry>DR 568; DR 550</entry> - </row> - <row> - <entry>8.17</entry> - <entry>Additions to header <code><math.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.18</entry> - <entry>Additions to header <code><cstdarg></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.19</entry> - <entry>Additions to header <code><stdarg.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.20</entry> - <entry>The header <code><cstdbool></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.21</entry> - <entry>The header <code><stdbool.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.22</entry> - <entry>The header <code><cstdint></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.22.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.22.2</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.23</entry> - <entry>The header <code><stdint.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.24</entry> - <entry>Additions to header <code><cstdio></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.24.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.24.2</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.24.3</entry> - <entry>Additional format specifiers</entry> - <entry>Y</entry> - <entry>C library dependency</entry> - </row> - <row> - <entry>8.24.4</entry> - <entry>Additions to header <code><stdio.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.25</entry> - <entry>Additions to header <code><cstdlib></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.25.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.25.2</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.25.3</entry> - <entry>Function <code>abs</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.25.4</entry> - <entry>Function <code>div</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.26</entry> - <entry>Additions to header <code><stdlib.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.27</entry> - <entry>Header <code><ctgmath></code></entry> - <entry>Y</entry> - <entry>DR 551</entry> - </row> - <row> - <entry>8.28</entry> - <entry>Header <code><tgmath.h></code></entry> - <entry>Y</entry> - <entry>DR 551</entry> - </row> - <row> - <entry>8.29</entry> - <entry>Additions to header <code><ctime></code></entry> - <entry>Y</entry> - <entry>C library dependency</entry> - </row> - <row> - <entry>8.30</entry> - <entry>Additions to header <code><cwchar></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.30.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.30.2</entry> - <entry>Definitions</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.30.3</entry> - <entry>Additional wide format specifiers</entry> - <entry>Y</entry> - <entry>C library dependency</entry> - </row> - <row> - <entry>8.31</entry> - <entry>Additions to header <code><wchar.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.32</entry> - <entry>Additions to header <code><cwctype></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.32.1</entry> - <entry>Synopsis</entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.32.2</entry> - <entry>Function <code>iswblank</code></entry> - <entry>Y</entry> - <entry></entry> - </row> - <row> - <entry>8.33</entry> - <entry>Additions to header <code><wctype.h></code></entry> - <entry>Y</entry> - <entry></entry> - </row> - </tbody> -</tgroup> -</table> - -</sect2> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/strings.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/strings.xml deleted file mode 100644 index 2ea3da20e..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/strings.xml +++ /dev/null @@ -1,498 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.strings" xreflabel="Strings"> -<?dbhtml filename="strings.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Strings - <indexterm><primary>Strings</primary></indexterm> -</title> - -<!-- Chapter 01 : Character Traits --> - -<!-- Chapter 02 : String Classes --> -<chapter id="manual.strings.string" xreflabel="string"> - <title>String Classes</title> - - <sect1 id="strings.string.simple" xreflabel="Simple Transformations"> - <title>Simple Transformations</title> - <para> - Here are Standard, simple, and portable ways to perform common - transformations on a <code>string</code> instance, such as - "convert to all upper case." The word transformations - is especially apt, because the standard template function - <code>transform<></code> is used. - </para> - <para> - This code will go through some iterations. Here's a simple - version: - </para> - <programlisting> - #include <string> - #include <algorithm> - #include <cctype> // old <ctype.h> - - struct ToLower - { - char operator() (char c) const { return std::tolower(c); } - }; - - struct ToUpper - { - char operator() (char c) const { return std::toupper(c); } - }; - - int main() - { - std::string s ("Some Kind Of Initial Input Goes Here"); - - // Change everything into upper case - std::transform (s.begin(), s.end(), s.begin(), ToUpper()); - - // Change everything into lower case - std::transform (s.begin(), s.end(), s.begin(), ToLower()); - - // Change everything back into upper case, but store the - // result in a different string - std::string capital_s; - capital_s.resize(s.size()); - std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper()); - } - </programlisting> - <para> - <emphasis>Note</emphasis> that these calls all - involve the global C locale through the use of the C functions - <code>toupper/tolower</code>. This is absolutely guaranteed to work -- - but <emphasis>only</emphasis> if the string contains <emphasis>only</emphasis> characters - from the basic source character set, and there are <emphasis>only</emphasis> - 96 of those. Which means that not even all English text can be - represented (certain British spellings, proper names, and so forth). - So, if all your input forevermore consists of only those 96 - characters (hahahahahaha), then you're done. - </para> - <para><emphasis>Note</emphasis> that the - <code>ToUpper</code> and <code>ToLower</code> function objects - are needed because <code>toupper</code> and <code>tolower</code> - are overloaded names (declared in <code><cctype></code> and - <code><locale></code>) so the template-arguments for - <code>transform<></code> cannot be deduced, as explained in - <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html">this - message</ulink>. - <!-- section 14.8.2.4 clause 16 in ISO 14882:1998 --> - At minimum, you can write short wrappers like - </para> - <programlisting> - char toLower (char c) - { - return std::tolower(c); - } </programlisting> - <para>The correct method is to use a facet for a particular locale - and call its conversion functions. These are discussed more in - Chapter 22; the specific part is - <ulink url="../22_locale/howto.html#7">Correct Transformations</ulink>, - which shows the final version of this code. (Thanks to James Kanze - for assistance and suggestions on all of this.) - </para> - <para>Another common operation is trimming off excess whitespace. Much - like transformations, this task is trivial with the use of string's - <code>find</code> family. These examples are broken into multiple - statements for readability: - </para> - <programlisting> - std::string str (" \t blah blah blah \n "); - - // trim leading whitespace - string::size_type notwhite = str.find_first_not_of(" \t\n"); - str.erase(0,notwhite); - - // trim trailing whitespace - notwhite = str.find_last_not_of(" \t\n"); - str.erase(notwhite+1); </programlisting> - <para>Obviously, the calls to <code>find</code> could be inserted directly - into the calls to <code>erase</code>, in case your compiler does not - optimize named temporaries out of existence. - </para> - - </sect1> - <sect1 id="strings.string.case" xreflabel="Case Sensitivity"> - <title>Case Sensitivity</title> - <para> - </para> - - <para>The well-known-and-if-it-isn't-well-known-it-ought-to-be - <ulink url="http://www.gotw.ca/gotw/">Guru of the Week</ulink> - discussions held on Usenet covered this topic in January of 1998. - Briefly, the challenge was, <quote>write a 'ci_string' class which - is identical to the standard 'string' class, but is - case-insensitive in the same way as the (common but nonstandard) - C function stricmp()</quote>. - </para> - <programlisting> - ci_string s( "AbCdE" ); - - // case insensitive - assert( s == "abcde" ); - assert( s == "ABCDE" ); - - // still case-preserving, of course - assert( strcmp( s.c_str(), "AbCdE" ) == 0 ); - assert( strcmp( s.c_str(), "abcde" ) != 0 ); </programlisting> - - <para>The solution is surprisingly easy. The original answer was - posted on Usenet, and a revised version appears in Herb Sutter's - book <emphasis>Exceptional C++</emphasis> and on his website as <ulink url="http://www.gotw.ca/gotw/029.htm">GotW 29</ulink>. - </para> - <para>See? Told you it was easy!</para> - <para> - <emphasis>Added June 2000:</emphasis> The May 2000 issue of C++ - Report contains a fascinating <ulink - url="http://lafstern.org/matt/col2_new.pdf"> article</ulink> by - Matt Austern (yes, <emphasis>the</emphasis> Matt Austern) on why - case-insensitive comparisons are not as easy as they seem, and - why creating a class is the <emphasis>wrong</emphasis> way to go - about it in production code. (The GotW answer mentions one of - the principle difficulties; his article mentions more.) - </para> - <para>Basically, this is "easy" only if you ignore some things, - things which may be too important to your program to ignore. (I chose - to ignore them when originally writing this entry, and am surprised - that nobody ever called me on it...) The GotW question and answer - remain useful instructional tools, however. - </para> - <para><emphasis>Added September 2000:</emphasis> James Kanze provided a link to a - <ulink url="http://www.unicode.org/unicode/reports/tr21/">Unicode - Technical Report discussing case handling</ulink>, which provides some - very good information. - </para> - - </sect1> - <sect1 id="strings.string.character_types" xreflabel="Arbitrary Characters"> - <title>Arbitrary Character Types</title> - <para> - </para> - - <para>The <code>std::basic_string</code> is tantalizingly general, in that - it is parameterized on the type of the characters which it holds. - In theory, you could whip up a Unicode character class and instantiate - <code>std::basic_string<my_unicode_char></code>, or assuming - that integers are wider than characters on your platform, maybe just - declare variables of type <code>std::basic_string<int></code>. - </para> - <para>That's the theory. Remember however that basic_string has additional - type parameters, which take default arguments based on the character - type (called <code>CharT</code> here): - </para> - <programlisting> - template <typename CharT, - typename Traits = char_traits<CharT>, - typename Alloc = allocator<CharT> > - class basic_string { .... };</programlisting> - <para>Now, <code>allocator<CharT></code> will probably Do The Right - Thing by default, unless you need to implement your own allocator - for your characters. - </para> - <para>But <code>char_traits</code> takes more work. The char_traits - template is <emphasis>declared</emphasis> but not <emphasis>defined</emphasis>. - That means there is only - </para> - <programlisting> - template <typename CharT> - struct char_traits - { - static void foo (type1 x, type2 y); - ... - };</programlisting> - <para>and functions such as char_traits<CharT>::foo() are not - actually defined anywhere for the general case. The C++ standard - permits this, because writing such a definition to fit all possible - CharT's cannot be done. - </para> - <para>The C++ standard also requires that char_traits be specialized for - instantiations of <code>char</code> and <code>wchar_t</code>, and it - is these template specializations that permit entities like - <code>basic_string<char,char_traits<char>></code> to work. - </para> - <para>If you want to use character types other than char and wchar_t, - such as <code>unsigned char</code> and <code>int</code>, you will - need suitable specializations for them. For a time, in earlier - versions of GCC, there was a mostly-correct implementation that - let programmers be lazy but it broke under many situations, so it - was removed. GCC 3.4 introduced a new implementation that mostly - works and can be specialized even for <code>int</code> and other - built-in types. - </para> - <para>If you want to use your own special character class, then you have - <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html">a lot - of work to do</ulink>, especially if you with to use i18n features - (facets require traits information but don't have a traits argument). - </para> - <para>Another example of how to specialize char_traits was given <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">on the - mailing list</ulink> and at a later date was put into the file <code> - include/ext/pod_char_traits.h</code>. We agree - that the way it's used with basic_string (scroll down to main()) - doesn't look nice, but that's because <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html">the - nice-looking first attempt</ulink> turned out to <ulink url="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html">not - be conforming C++</ulink>, due to the rule that CharT must be a POD. - (See how tricky this is?) - </para> - - </sect1> - - <sect1 id="strings.string.token" xreflabel="Tokenizing"> - <title>Tokenizing</title> - <para> - </para> - <para>The Standard C (and C++) function <code>strtok()</code> leaves a lot to - be desired in terms of user-friendliness. It's unintuitive, it - destroys the character string on which it operates, and it requires - you to handle all the memory problems. But it does let the client - code decide what to use to break the string into pieces; it allows - you to choose the "whitespace," so to speak. - </para> - <para>A C++ implementation lets us keep the good things and fix those - annoyances. The implementation here is more intuitive (you only - call it once, not in a loop with varying argument), it does not - affect the original string at all, and all the memory allocation - is handled for you. - </para> - <para>It's called stringtok, and it's a template function. Sources are - as below, in a less-portable form than it could be, to keep this - example simple (for example, see the comments on what kind of - string it will accept). - </para> - -<programlisting> -#include <string> -template <typename Container> -void -stringtok(Container &container, string const &in, - const char * const delimiters = " \t\n") -{ - const string::size_type len = in.length(); - string::size_type i = 0; - - while (i < len) - { - // Eat leading whitespace - i = in.find_first_not_of(delimiters, i); - if (i == string::npos) - return; // Nothing left but white space - - // Find the end of the token - string::size_type j = in.find_first_of(delimiters, i); - - // Push token - if (j == string::npos) - { - container.push_back(in.substr(i)); - return; - } - else - container.push_back(in.substr(i, j-i)); - - // Set up for next loop - i = j + 1; - } -} -</programlisting> - - - <para> - The author uses a more general (but less readable) form of it for - parsing command strings and the like. If you compiled and ran this - code using it: - </para> - - - <programlisting> - std::list<string> ls; - stringtok (ls, " this \t is\t\n a test "); - for (std::list<string>const_iterator i = ls.begin(); - i != ls.end(); ++i) - { - std::cerr << ':' << (*i) << ":\n"; - } </programlisting> - <para>You would see this as output: - </para> - <programlisting> - :this: - :is: - :a: - :test: </programlisting> - <para>with all the whitespace removed. The original <code>s</code> is still - available for use, <code>ls</code> will clean up after itself, and - <code>ls.size()</code> will return how many tokens there were. - </para> - <para>As always, there is a price paid here, in that stringtok is not - as fast as strtok. The other benefits usually outweigh that, however. - <ulink url="stringtok_std_h.txt">Another version of stringtok is given - here</ulink>, suggested by Chris King and tweaked by Petr Prikryl, - and this one uses the - transformation functions mentioned below. If you are comfortable - with reading the new function names, this version is recommended - as an example. - </para> - <para><emphasis>Added February 2001:</emphasis> Mark Wilden pointed out that the - standard <code>std::getline()</code> function can be used with standard - <ulink url="../27_io/howto.html">istringstreams</ulink> to perform - tokenizing as well. Build an istringstream from the input text, - and then use std::getline with varying delimiters (the three-argument - signature) to extract tokens into a string. - </para> - - - </sect1> - <sect1 id="strings.string.shrink" xreflabel="Shrink to Fit"> - <title>Shrink to Fit</title> - <para> - </para> - <para>From GCC 3.4 calling <code>s.reserve(res)</code> on a - <code>string s</code> with <code>res < s.capacity()</code> will - reduce the string's capacity to <code>std::max(s.size(), res)</code>. - </para> - <para>This behaviour is suggested, but not required by the standard. Prior - to GCC 3.4 the following alternative can be used instead - </para> - <programlisting> - std::string(str.data(), str.size()).swap(str); - </programlisting> - <para>This is similar to the idiom for reducing a <code>vector</code>'s - memory usage (see <ulink url='../faq/index.html#5_9'>FAQ 5.9</ulink>) but - the regular copy constructor cannot be used because libstdc++'s - <code>string</code> is Copy-On-Write. - </para> - - - </sect1> - - <sect1 id="strings.string.Cstring" xreflabel="CString (MFC)"> - <title>CString (MFC)</title> - <para> - </para> - - <para>A common lament seen in various newsgroups deals with the Standard - string class as opposed to the Microsoft Foundation Class called - CString. Often programmers realize that a standard portable - answer is better than a proprietary nonportable one, but in porting - their application from a Win32 platform, they discover that they - are relying on special functions offered by the CString class. - </para> - <para>Things are not as bad as they seem. In - <ulink url="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this - message</ulink>, Joe Buck points out a few very important things: - </para> - <itemizedlist> - <listitem><para>The Standard <code>string</code> supports all the operations - that CString does, with three exceptions. - </para></listitem> - <listitem><para>Two of those exceptions (whitespace trimming and case - conversion) are trivial to implement. In fact, we do so - on this page. - </para></listitem> - <listitem><para>The third is <code>CString::Format</code>, which allows formatting - in the style of <code>sprintf</code>. This deserves some mention: - </para></listitem> - </itemizedlist> - <para> - The old libg++ library had a function called form(), which did much - the same thing. But for a Standard solution, you should use the - stringstream classes. These are the bridge between the iostream - hierarchy and the string class, and they operate with regular - streams seamlessly because they inherit from the iostream - hierarchy. An quick example: - </para> - <programlisting> - #include <iostream> - #include <string> - #include <sstream> - - string f (string& incoming) // incoming is "foo N" - { - istringstream incoming_stream(incoming); - string the_word; - int the_number; - - incoming_stream >> the_word // extract "foo" - >> the_number; // extract N - - ostringstream output_stream; - output_stream << "The word was " << the_word - << " and 3*N was " << (3*the_number); - - return output_stream.str(); - } </programlisting> - <para>A serious problem with CString is a design bug in its memory - allocation. Specifically, quoting from that same message: - </para> - <programlisting> - CString suffers from a common programming error that results in - poor performance. Consider the following code: - - CString n_copies_of (const CString& foo, unsigned n) - { - CString tmp; - for (unsigned i = 0; i < n; i++) - tmp += foo; - return tmp; - } - - This function is O(n^2), not O(n). The reason is that each += - causes a reallocation and copy of the existing string. Microsoft - applications are full of this kind of thing (quadratic performance - on tasks that can be done in linear time) -- on the other hand, - we should be thankful, as it's created such a big market for high-end - ix86 hardware. :-) - - If you replace CString with string in the above function, the - performance is O(n). - </programlisting> - <para>Joe Buck also pointed out some other things to keep in mind when - comparing CString and the Standard string class: - </para> - <itemizedlist> - <listitem><para>CString permits access to its internal representation; coders - who exploited that may have problems moving to <code>string</code>. - </para></listitem> - <listitem><para>Microsoft ships the source to CString (in the files - MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation - bug and rebuild your MFC libraries. - <emphasis><emphasis>Note:</emphasis> It looks like the CString shipped - with VC++6.0 has fixed this, although it may in fact have been - one of the VC++ SPs that did it.</emphasis> - </para></listitem> - <listitem><para><code>string</code> operations like this have O(n) complexity - <emphasis>if the implementors do it correctly</emphasis>. The libstdc++ - implementors did it correctly. Other vendors might not. - </para></listitem> - <listitem><para>While parts of the SGI STL are used in libstdc++, their - string class is not. The SGI <code>string</code> is essentially - <code>vector<char></code> and does not do any reference - counting like libstdc++'s does. (It is O(n), though.) - So if you're thinking about SGI's string or rope classes, - you're now looking at four possibilities: CString, the - libstdc++ string, the SGI string, and the SGI rope, and this - is all before any allocator or traits customizations! (More - choices than you can shake a stick at -- want fries with that?) - </para></listitem> - </itemizedlist> - - </sect1> -</chapter> - -<!-- Chapter 03 : Interacting with C --> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/support.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/support.xml deleted file mode 100644 index 6e0f75af9..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/support.xml +++ /dev/null @@ -1,455 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.support" xreflabel="Support"> -<?dbhtml filename="support.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Support - <indexterm><primary>Support</primary></indexterm> -</title> - -<preface> - <title></title> - <para> - This part deals with the functions called and objects created - automatically during the course of a program's existence. - </para> - - <para> - While we can't reproduce the contents of the Standard here (you - need to get your own copy from your nation's member body; see our - homepage for help), we can mention a couple of changes in what - kind of support a C++ program gets from the Standard Library. - </para> -</preface> - -<chapter id="manual.support.types" xreflabel="Types"> - <?dbhtml filename="fundamental_types.html"?> - <title>Types</title> - <sect1 id="manual.support.types.fundamental" xreflabel="Fundamental Types"> - <title>Fundamental Types</title> - <para> - C++ has the following builtin types: - </para> - <itemizedlist> - <listitem><para> - char - </para></listitem> - <listitem><para> - signed char - </para></listitem> - <listitem><para> - unsigned char - </para></listitem> - <listitem><para> - signed short - </para></listitem> - <listitem><para> - signed int - </para></listitem> - <listitem><para> - signed long - </para></listitem> - <listitem><para> - unsigned short - </para></listitem> - <listitem><para> - unsigned int - </para></listitem> - <listitem><para> - unsigned long - </para></listitem> - <listitem><para> - bool - </para></listitem> - <listitem><para> - wchar_t - </para></listitem> - <listitem><para> - float - </para></listitem> - <listitem><para> - double - </para></listitem> - <listitem><para> - long double - </para></listitem> - </itemizedlist> - - <para> - These fundamental types are always available, without having to - include a header file. These types are exactly the same in - either C++ or in C. - </para> - - <para> - Specializing parts of the library on these types is prohibited: - instead, use a POD. - </para> - - </sect1> - <sect1 id="manual.support.types.numeric_limits" xreflabel="Numeric Properties"> - <title>Numeric Properties</title> - - - <para> - The header <filename class="headerfile">limits</filename> defines - traits classes to give access to various implementation - defined-aspects of the fundamental types. The traits classes -- - fourteen in total -- are all specializations of the template class - <classname>numeric_limits</classname>, documented <ulink - url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/structstd_1_1numeric__limits.html">here</ulink> - and defined as follows: - </para> - - <programlisting> - template<typename T> - struct class - { - static const bool is_specialized; - static T max() throw(); - static T min() throw(); - - static const int digits; - static const int digits10; - static const bool is_signed; - static const bool is_integer; - static const bool is_exact; - static const int radix; - static T epsilon() throw(); - static T round_error() throw(); - - static const int min_exponent; - static const int min_exponent10; - static const int max_exponent; - static const int max_exponent10; - - static const bool has_infinity; - static const bool has_quiet_NaN; - static const bool has_signaling_NaN; - static const float_denorm_style has_denorm; - static const bool has_denorm_loss; - static T infinity() throw(); - static T quiet_NaN() throw(); - static T denorm_min() throw(); - - static const bool is_iec559; - static const bool is_bounded; - static const bool is_modulo; - - static const bool traps; - static const bool tinyness_before; - static const float_round_style round_style; - }; - </programlisting> - </sect1> - - <sect1 id="manual.support.types.null" xreflabel="NULL"> - <title>NULL</title> - <para> - The only change that might affect people is the type of - <constant>NULL</constant>: while it is required to be a macro, - the definition of that macro is <emphasis>not</emphasis> allowed - to be <constant>(void*)0</constant>, which is often used in C. - </para> - - <para> - For <command>g++</command>, <constant>NULL</constant> is - <programlisting>#define</programlisting>'d to be - <constant>__null</constant>, a magic keyword extension of - <command>g++</command>. - </para> - - <para> - The biggest problem of #defining <constant>NULL</constant> to be - something like <quote>0L</quote> is that the compiler will view - that as a long integer before it views it as a pointer, so - overloading won't do what you expect. (This is why - <command>g++</command> has a magic extension, so that - <constant>NULL</constant> is always a pointer.) - </para> - - <para>In his book <ulink - url="http://www.awprofessional.com/titles/0-201-92488-9/"><emphasis>Effective - C++</emphasis></ulink>, Scott Meyers points out that the best way - to solve this problem is to not overload on pointer-vs-integer - types to begin with. He also offers a way to make your own magic - <constant>NULL</constant> that will match pointers before it - matches integers. - </para> - <para>See - <ulink url="http://www.awprofessional.com/titles/0-201-31015-5/">the - Effective C++ CD example</ulink> - </para> - </sect1> - -</chapter> - -<chapter id="manual.support.memory" xreflabel="Dynamic Memory"> - <?dbhtml filename="dynamic_memory.html"?> - <title>Dynamic Memory</title> - <para> - There are six flavors each of <function>new</function> and - <function>delete</function>, so make certain that you're using the right - ones. Here are quickie descriptions of <function>new</function>: - </para> - <itemizedlist> - <listitem><para> - single object form, throwing a - <classname>bad_alloc</classname> on errors; this is what most - people are used to using - </para></listitem> - <listitem><para> - Single object "nothrow" form, returning NULL on errors - </para></listitem> - <listitem><para> - Array <function>new</function>, throwing - <classname>bad_alloc</classname> on errors - </para></listitem> - <listitem><para> - Array nothrow <function>new</function>, returning - <constant>NULL</constant> on errors - </para></listitem> - <listitem><para> - Placement <function>new</function>, which does nothing (like - it's supposed to) - </para></listitem> - <listitem><para> - Placement array <function>new</function>, which also does - nothing - </para></listitem> - </itemizedlist> - <para> - They are distinguished by the parameters that you pass to them, like - any other overloaded function. The six flavors of <function>delete</function> - are distinguished the same way, but none of them are allowed to throw - an exception under any circumstances anyhow. (They match up for - completeness' sake.) - </para> - <para> - Remember that it is perfectly okay to call <function>delete</function> on a - NULL pointer! Nothing happens, by definition. That is not the - same thing as deleting a pointer twice. - </para> - <para> - By default, if one of the <quote>throwing <function>new</function>s</quote> can't - allocate the memory requested, it tosses an instance of a - <classname>bad_alloc</classname> exception (or, technically, some class derived - from it). You can change this by writing your own function (called a - new-handler) and then registering it with <function>set_new_handler()</function>: - </para> - <programlisting> - typedef void (*PFV)(void); - - static char* safety; - static PFV old_handler; - - void my_new_handler () - { - delete[] safety; - popup_window ("Dude, you are running low on heap memory. You - should, like, close some windows, or something. - The next time you run out, we're gonna burn!"); - set_new_handler (old_handler); - return; - } - - int main () - { - safety = new char[500000]; - old_handler = set_new_handler (&my_new_handler); - ... - } - </programlisting> - <para> - <classname>bad_alloc</classname> is derived from the base <classname>exception</classname> - class defined in Chapter 19. - </para> -</chapter> - -<chapter id="manual.support.termination" xreflabel="Termination"> - <?dbhtml filename="termination.html"?> - <title>Termination</title> - <sect1 id="support.termination.handlers" xreflabel="Termination Handlers"> - <title>Termination Handlers</title> - <para> - Not many changes here to <filename - class="headerfile">cstdlib</filename>. You should note that the - <function>abort()</function> function does not call the - destructors of automatic nor static objects, so if you're - depending on those to do cleanup, it isn't going to happen. - (The functions registered with <function>atexit()</function> - don't get called either, so you can forget about that - possibility, too.) - </para> - <para> - The good old <function>exit()</function> function can be a bit - funky, too, until you look closer. Basically, three points to - remember are: - </para> - <orderedlist> - <listitem> - <para> - Static objects are destroyed in reverse order of their creation. - </para> - </listitem> - <listitem> - <para> - Functions registered with <function>atexit()</function> are called in - reverse order of registration, once per registration call. - (This isn't actually new.) - </para> - </listitem> - <listitem> - <para> - The previous two actions are <quote>interleaved,</quote> that is, - given this pseudocode: - </para> -<programlisting> - extern "C or C++" void f1 (void); - extern "C or C++" void f2 (void); - - static Thing obj1; - atexit(f1); - static Thing obj2; - atexit(f2); -</programlisting> - <para> - then at a call of <function>exit()</function>, - <varname>f2</varname> will be called, then - <varname>obj2</varname> will be destroyed, then - <varname>f1</varname> will be called, and finally - <varname>obj1</varname> will be destroyed. If - <varname>f1</varname> or <varname>f2</varname> allow an - exception to propagate out of them, Bad Things happen. - </para> - </listitem> - </orderedlist> - <para> - Note also that <function>atexit()</function> is only required to store 32 - functions, and the compiler/library might already be using some of - those slots. If you think you may run out, we recommend using - the <function>xatexit</function>/<function>xexit</function> combination from <literal>libiberty</literal>, which has no such limit. - </para> - </sect1> - - <sect1 id="support.termination.verbose" xreflabel="Verbose Terminate Handler"> - <?dbhtml filename="verbose_termination.html"?> - <title>Verbose Terminate Handler</title> - <para> - If you are having difficulty with uncaught exceptions and want a - little bit of help debugging the causes of the core dumps, you can - make use of a GNU extension, the verbose terminate handler. - </para> - -<programlisting> -#include <exception> - -int main() -{ - std::set_terminate(__gnu_cxx::__verbose_terminate_handler); - ... - - throw <replaceable>anything</replaceable>; -} -</programlisting> - - <para> - The <function>__verbose_terminate_handler</function> function - obtains the name of the current exception, attempts to demangle - it, and prints it to stderr. If the exception is derived from - <classname>exception</classname> then the output from - <function>what()</function> will be included. - </para> - - <para> - Any replacement termination function is required to kill the - program without returning; this one calls abort. - </para> - - <para> - For example: - </para> - -<programlisting> -#include <exception> -#include <stdexcept> - -struct argument_error : public std::runtime_error -{ - argument_error(const std::string& s): std::runtime_error(s) { } -}; - -int main(int argc) -{ - std::set_terminate(__gnu_cxx::__verbose_terminate_handler); - if (argc > 5) - throw argument_error(<quote>argc is greater than 5!</quote>); - else - throw argc; -} -</programlisting> - - <para> - With the verbose terminate handler active, this gives: - </para> - - <screen> - <computeroutput> - % ./a.out - terminate called after throwing a `int' - Aborted - % ./a.out f f f f f f f f f f f - terminate called after throwing an instance of `argument_error' - what(): argc is greater than 5! - Aborted - </computeroutput> - </screen> - - <para> - The 'Aborted' line comes from the call to - <function>abort()</function>, of course. - </para> - - <para> - This is the default termination handler; nothing need be done to - use it. To go back to the previous <quote>silent death</quote> - method, simply include <filename>exception</filename> and - <filename>cstdlib</filename>, and call - </para> - - <programlisting> - std::set_terminate(std::abort); - </programlisting> - - <para> - After this, all calls to <function>terminate</function> will use - <function>abort</function> as the terminate handler. - </para> - - <para> - Note: the verbose terminate handler will attempt to write to - stderr. If your application closes stderr or redirects it to an - inappropriate location, - <function>__verbose_terminate_handler</function> will behave in - an unspecified manner. - </para> - - </sect1> -</chapter> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/test.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/test.xml deleted file mode 100644 index 7072c81e6..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/test.xml +++ /dev/null @@ -1,804 +0,0 @@ -<sect1 id="manual.intro.setup.test" xreflabel="Testing"> -<?dbhtml filename="test.html"?> - -<sect1info> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - test - </keyword> - <keyword> - testsuite - </keyword> - <keyword> - performance - </keyword> - <keyword> - conformance - </keyword> - <keyword> - ABI - </keyword> - <keyword> - exception safety - </keyword> - </keywordset> -</sect1info> - -<title>Test</title> - -<para> -The libstdc++ testsuite includes testing for standard conformance, -regressions, ABI, and performance. -</para> - -<sect2 id="test.organization" xreflabel="test.organization"> -<title>Organization</title> - -<sect3 id="test.organization.layout" xreflabel="Directory Layout"> -<title>Directory Layout</title> - -<para> - The directory <emphasis>libsrcdir/testsuite</emphasis> contains the - individual test cases organized in sub-directories corresponding to - chapters of the C++ standard (detailed below), the dejagnu test - harness support files, and sources to various testsuite utilities - that are packaged in a separate testing library. -</para> - -<para> - All test cases for functionality required by the runtime components - of the C++ standard (ISO 14882) are files within the following - directories. -</para> - - <programlisting> -17_intro -18_support -19_diagnostics -20_util -21_strings -22_locale -23_containers -25_algorithms -26_numerics -27_io - </programlisting> - - <para> - In addition, the following directories include test files: - </para> - - <programlisting> -tr1 Tests for components as described by the Technical Report on Standard Library Extensions (TR1). -backward Tests for backwards compatibility and deprecated features. -demangle Tests for __cxa_demangle, the IA 64 C++ ABI demangler -ext Tests for extensions. -performance Tests for performance analysis, and performance regressions. -thread Tests for threads. - </programlisting> - - <para> - Some directories don't have test files, but instead contain - auxiliary information (<ulink url="#internals">more information</ulink>): - </para> - - <programlisting> -config Files for the dejagnu test harness. -lib Files for the dejagnu test harness. -libstdc++* Files for the dejagnu test harness. -data Sample text files for testing input and output. -util Files for libtestc++, utilities and testing routines. - </programlisting> - - <para> - Within a directory that includes test files, there may be - additional subdirectories, or files. Originally, test cases - were appended to one file that represented a particular section - of the chapter under test, and was named accordingly. For - instance, to test items related to <code> 21.3.6.1 - - basic_string::find [lib.string::find]</code> in the standard, - the following was used: - </para> - <programlisting> -21_strings/find.cc - </programlisting> - <para> - However, that practice soon became a liability as the test cases - became huge and unwieldy, and testing new or extended - functionality (like wide characters or named locales) became - frustrating, leading to aggressive pruning of test cases on some - platforms that covered up implementation errors. Now, the test - suite has a policy of one file, one test case, which solves the - above issues and gives finer grained results and more manageable - error debugging. As an example, the test case quoted above - becomes: - </para> - <programlisting> -21_strings/basic_string/find/char/1.cc -21_strings/basic_string/find/char/2.cc -21_strings/basic_string/find/char/3.cc -21_strings/basic_string/find/wchar_t/1.cc -21_strings/basic_string/find/wchar_t/2.cc -21_strings/basic_string/find/wchar_t/3.cc - </programlisting> - - <para> - All new tests should be written with the policy of one test - case, one file in mind. - </para> -</sect3> - - -<sect3 id="test.organization.naming" xreflabel="Naming Conventions"> -<title>Naming Conventions</title> - - <para> - In addition, there are some special names and suffixes that are - used within the testsuite to designate particular kinds of - tests. - </para> - -<itemizedlist> -<listitem> - <para> - <emphasis>_xin.cc</emphasis> - </para> - <para> - This test case expects some kind of interactive input in order - to finish or pass. At the moment, the interactive tests are not - run by default. Instead, they are run by hand, like: - </para> - <programlisting> -g++ 27_io/objects/char/3_xin.cc -cat 27_io/objects/char/3_xin.in | a.out - </programlisting> -</listitem> -<listitem> - <para> - <emphasis>.in</emphasis> - </para> - <para> - This file contains the expected input for the corresponding <emphasis> - _xin.cc</emphasis> test case. - </para> -</listitem> -<listitem> - <para> - <emphasis>_neg.cc</emphasis> - </para> - <para> - This test case is expected to fail: it's a negative test. At the - moment, these are almost always compile time errors. - </para> -</listitem> -<listitem> - <para> - <emphasis>char</emphasis> - </para> - <para> - This can either be a directory name or part of a longer file - name, and indicates that this file, or the files within this - directory are testing the <code>char</code> instantiation of a - template. - </para> -</listitem> -<listitem> - <para> - <emphasis>wchar_t</emphasis> - </para> - <para> - This can either be a directory name or part of a longer file - name, and indicates that this file, or the files within this - directory are testing the <code>wchar_t</code> instantiation of - a template. Some hosts do not support <code>wchar_t</code> - functionality, so for these targets, all of these tests will not - be run. - </para> -</listitem> -<listitem> - <para> - <emphasis>thread</emphasis> - </para> - <para> - This can either be a directory name or part of a longer file - name, and indicates that this file, or the files within this - directory are testing situations where multiple threads are - being used. - </para> -</listitem> -<listitem> - <para> - <emphasis>performance</emphasis> - </para> - <para> - This can either be an enclosing directory name or part of a - specific file name. This indicates a test that is used to - analyze runtime performance, for performance regression testing, - or for other optimization related analysis. At the moment, these - test cases are not run by default. - </para> -</listitem> -</itemizedlist> - -</sect3> -</sect2> - - -<sect2 id="test.run" xreflabel="test.run"> -<title>Running the Testsuite</title> - - <sect3 id="test.run.basic" xreflabel="test.run.basic"> - <title>Basic</title> - - <para> - You can check the status of the build without installing it - using the dejagnu harness, much like the rest of the gcc - tools.</para> - <programlisting> make check</programlisting> - <para>in the <emphasis>libbuilddir</emphasis> directory.</para> - <para>or</para> - <programlisting> make check-target-libstdc++-v3</programlisting> - <para>in the <emphasis>gccbuilddir</emphasis> directory. - </para> - - <para> - These commands are functionally equivalent and will create a - 'testsuite' directory underneath - <emphasis>libbuilddir</emphasis> containing the results of the - tests. Two results files will be generated: <emphasis> - libstdc++.sum</emphasis>, which is a PASS/FAIL summary for each - test, and <emphasis>libstdc++.log</emphasis> which is a log of - the exact command line passed to the compiler, the compiler - output, and the executable output (if any). - </para> - - <para> - Archives of test results for various versions and platforms are - available on the GCC website in the <ulink - url="http://gcc.gnu.org/gcc-4.3/buildstat.html">build - status</ulink> section of each individual release, and are also - archived on a daily basis on the <ulink - url="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</ulink> - mailing list. Please check either of these places for a similar - combination of source version, operating system, and host CPU. - </para> - </sect3> - - <sect3 id="test.run.variations" xreflabel="test.run.variations"> - <title>Variations</title> - <para> - There are several options for running tests, including testing - the regression tests, testing a subset of the regression tests, - testing the performance tests, testing just compilation, testing - installed tools, etc. In addition, there is a special rule for - checking the exported symbols of the shared library. - </para> - <para> - To debug the dejagnu test harness during runs, try invoking with a - specific argument to the variable RUNTESTFLAGS, as below. - </para> - -<programlisting> -make check-target-libstdc++-v3 RUNTESTFLAGS="-v" -</programlisting> - - <para> - or - </para> - -<programlisting> -make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v" -</programlisting> - - <para> - To run a subset of the library tests, you will need to generate - the <emphasis>testsuite_files</emphasis> file by running - <command>make testsuite_files</command> in the - <emphasis>libbuilddir/testsuite</emphasis> directory, described - below. Edit the file to remove the tests you don't want and - then run the testsuite as normal. - </para> - - <para> - There are two ways to run on a simulator: set up DEJAGNU to point to a - specially crafted site.exp, or pass down --target_board flags. - </para> - - <para> - Example flags to pass down for various embedded builds are as follows: - </para> - -<programlisting> - --target=powerpc-eabism (libgloss/sim) -make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim" - ---target=calmrisc32 (libgloss/sid) -make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid" - ---target=xscale-elf (newlib/sim) -make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim" -</programlisting> - - <para> - Also, here is an example of how to run the libstdc++ testsuite - for a multilibed build directory with different ABI settings: - </para> - - <programlisting> -make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"' -</programlisting> - - <para> - You can run the tests with a compiler and library that have - already been installed. Make sure that the compiler (e.g., - <code>g++</code>) is in your <code>PATH</code>. If you are - using shared libraries, then you must also ensure that the - directory containing the shared version of libstdc++ is in your - <code>LD_LIBRARY_PATH</code>, or equivalent. If your GCC source - tree is at <code>/path/to/gcc</code>, then you can run the tests - as follows: - </para> - -<programlisting> -runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite -</programlisting> - - <para> - The testsuite will create a number of files in the directory in - which you run this command,. Some of those files might use the - same name as files created by other testsuites (like the ones - for GCC and G++), so you should not try to run all the - testsuites in parallel from the same directory. - </para> - - <para> - In addition, there are some testing options that are mostly of - interest to library maintainers and system integrators. As such, - these tests may not work on all cpu and host combinations, and - may need to be executed in the - <emphasis>libbuilddir/testsuite</emphasis> directory. These - options include, but are not necessarily limited to, the - following: - </para> - - <programlisting> - make testsuite_files - </programlisting> - - <para> - Five files are generated that determine what test files - are run. These files are: - </para> - - <itemizedlist> - <listitem> - <para> - <emphasis>testsuite_files</emphasis> - </para> - <para> - This is a list of all the test cases that will be run. Each - test case is on a separate line, given with an absolute path - from the <emphasis>libsrcdir/testsuite</emphasis> directory. - </para> - </listitem> - - <listitem> - <para> - <emphasis>testsuite_files_interactive</emphasis> - </para> - <para> - This is a list of all the interactive test cases, using the - same format as the file list above. These tests are not run - by default. - </para> - </listitem> - - <listitem> - <para> - <emphasis>testsuite_files_performance</emphasis> - </para> - <para> - This is a list of all the performance test cases, using the - same format as the file list above. These tests are not run - by default. - </para> - </listitem> - - <listitem> - <para> - <emphasis>testsuite_thread</emphasis> - </para> - <para> - This file indicates that the host system can run tests which - involved multiple threads. - </para> - </listitem> - - <listitem> - <para> - <emphasis>testsuite_wchar_t</emphasis> - </para> - <para> - This file indicates that the host system can run the wchar_t - tests, and corresponds to the macro definition <code> - _GLIBCXX_USE_WCHAR_T</code> in the file c++config.h. - </para> - </listitem> - </itemizedlist> - - <programlisting> - make check-abi - </programlisting> - - <para> - The library ABI can be tested. This involves testing the shared - library against an ABI-defining previous version of symbol - exports. - </para> - - <programlisting> - make check-compile - </programlisting> - - <para> - This rule compiles, but does not link or execute, the - <emphasis>testsuite_files</emphasis> test cases and displays the - output on stdout. - </para> - - <programlisting> - make check-performance - </programlisting> - - <para> - This rule runs through the - <emphasis>testsuite_files_performance</emphasis> test cases and - collects information for performance analysis and can be used to - spot performance regressions. Various timing information is - collected, as well as number of hard page faults, and memory - used. This is not run by default, and the implementation is in - flux. - </para> - - <para> - We are interested in any strange failures of the testsuite; - please email the main libstdc++ mailing list if you see - something odd or have questions. - </para> - </sect3> - - <sect3 id="test.run.permutations" xreflabel="test.run.permutations"> - <title>Permutations</title> - <para> - To run the libstdc++ test suite under the <link - linkend="manual.ext.debug_mode">debug mode</link>, edit - <filename>libstdc++-v3/scripts/testsuite_flags</filename> to add the - compile-time flag <constant>-D_GLIBCXX_DEBUG</constant> to the - result printed by the <literal>--build-cxx</literal> - option. Additionally, add the - <constant>-D_GLIBCXX_DEBUG_PEDANTIC</constant> flag to turn on - pedantic checking. The libstdc++ test suite should produce - precisely the same results under debug mode that it does under - release mode: any deviation indicates an error in either the - library or the test suite. - </para> - - <para> - The <link linkend="manual.ext.parallel_mode">parallel - mode</link> can be tested in much the same manner, substituting - <constant>-D_GLIBCXX_PARALLEL</constant> for - <constant>-D_GLIBCXX_DEBUG</constant> in the previous paragraph. - </para> - - <para> - Or, just run the testsuites with <constant>CXXFLAGS</constant> - set to <constant>-D_GLIBCXX_DEBUG</constant> or - <constant>-D_GLIBCXX_PARALLEL</constant>. - </para> - </sect3> -</sect2> - -<sect2 id="test.new_tests" xreflabel="test.new_tests"> -<title>Writing a new test case</title> - - <para> - The first step in making a new test case is to choose the correct - directory and file name, given the organization as previously - described. - </para> - - <para> - All files are copyright the FSF, and GPL'd: this is very - important. The first copyright year should correspond to the date - the file was checked in to SVN. - </para> - - <para> - As per the dejagnu instructions, always return 0 from main to - indicate success. - </para> - - <para> - A bunch of utility functions and classes have already been - abstracted out into the testsuite utility library, <code> - libtestc++</code>. To use this functionality, just include the - appropriate header file: the library or specific object files will - automatically be linked in as part of the testsuite run. - </para> - - <para> - For a test that needs to take advantage of the dejagnu test - harness, what follows below is a list of special keyword that - harness uses. Basically, a test case contains dg-keywords (see - dg.exp) indicating what to do and what kinds of behavior are to be - expected. New test cases should be written with the new style - DejaGnu framework in mind. - </para> - - <para> - To ease transition, here is the list of dg-keyword documentation - lifted from dg.exp. - </para> - -<programlisting> -# The currently supported options are: -# -# dg-prms-id N -# set prms_id to N -# -# dg-options "options ..." [{ target selector }] -# specify special options to pass to the tool (eg: compiler) -# -# dg-do do-what-keyword [{ target/xfail selector }] -# `do-what-keyword' is tool specific and is passed unchanged to -# ${tool}-dg-test. An example is gcc where `keyword' can be any of: -# preprocess|compile|assemble|link|run -# and will do one of: produce a .i, produce a .s, produce a .o, -# produce an a.out, or produce an a.out and run it (the default is -# compile). -# -# dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]] -# indicate an error message <regexp> is expected on this line -# (the test fails if it doesn't occur) -# Linenum=0 for general tool messages (eg: -V arg missing). -# "." means the current line. -# -# dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]] -# indicate a warning message <regexp> is expected on this line -# (the test fails if it doesn't occur) -# -# dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]] -# indicate a bogus error message <regexp> use to occur here -# (the test fails if it does occur) -# -# dg-build regexp comment [{ target/xfail selector }] -# indicate the build use to fail for some reason -# (errors covered here include bad assembler generated, tool crashes, -# and link failures) -# (the test fails if it does occur) -# -# dg-excess-errors comment [{ target/xfail selector }] -# indicate excess errors are expected (any line) -# (this should only be used sparingly and temporarily) -# -# dg-output regexp [{ target selector }] -# indicate the expected output of the program is <regexp> -# (there may be multiple occurrences of this, they are concatenated) -# -# dg-final { tcl code } -# add some tcl code to be run at the end -# (there may be multiple occurrences of this, they are concatenated) -# (unbalanced braces must be \-escaped) -# -# "{ target selector }" is a list of expressions that determine whether the -# test succeeds or fails for a particular target, or in some cases whether the -# option applies for a particular target. If the case of `dg-do' it specifies -# whether the test case is even attempted on the specified target. -# -# The target selector is always optional. The format is one of: -# -# { xfail *-*-* ... } - the test is expected to fail for the given targets -# { target *-*-* ... } - the option only applies to the given targets -# -# At least one target must be specified, use *-*-* for "all targets". -# At present it is not possible to specify both `xfail' and `target'. -# "native" may be used in place of "*-*-*". - -Example 1: Testing compilation only -// { dg-do compile } - -Example 2: Testing for expected warnings on line 36, which all targets fail -// { dg-warning "string literals" "" { xfail *-*-* } 36 - -Example 3: Testing for expected warnings on line 36 -// { dg-warning "string literals" "" { target *-*-* } 36 - -Example 4: Testing for compilation errors on line 41 -// { dg-do compile } -// { dg-error "no match for" "" { target *-*-* } 41 } - -Example 5: Testing with special command line settings, or without the -use of pre-compiled headers, in particular the stdc++.h.gch file. Any -options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set -up in the normal.exp file. -// { dg-options "-O0" { target *-*-* } } -</programlisting> - - <para> - More examples can be found in the libstdc++-v3/testsuite/*/*.cc files. - </para> -</sect2> - - -<sect2 id="test.harness" xreflabel="Test Harness and Utilities"> -<title>Test Harness and Utilities</title> - -<sect3 id="test.harness.dejagnu" xreflabel="test.harness.dejagnu"> -<title>Dejagnu Harness Details</title> - <para> - Underlying details of testing for conformance and regressions are - abstracted via the GNU Dejagnu package. This is similar to the - rest of GCC. - </para> - - -<para>This is information for those looking at making changes to the testsuite -structure, and/or needing to trace dejagnu's actions with --verbose. This -will not be useful to people who are "merely" adding new tests to the existing -structure. -</para> - -<para>The first key point when working with dejagnu is the idea of a "tool". -Files, directories, and functions are all implicitly used when they are -named after the tool in use. Here, the tool will always be "libstdc++". -</para> - -<para>The <code>lib</code> subdir contains support routines. The -<code>lib/libstdc++.exp</code> file ("support library") is loaded -automagically, and must explicitly load the others. For example, files can -be copied from the core compiler's support directory into <code>lib</code>. -</para> - -<para>Some routines in <code>lib/libstdc++.exp</code> are callbacks, some are -our own. Callbacks must be prefixed with the name of the tool. To easily -distinguish the others, by convention our own routines are named "v3-*". -</para> - -<para>The next key point when working with dejagnu is "test files". Any -directory whose name starts with the tool name will be searched for test files. -(We have only one.) In those directories, any <code>.exp</code> file is -considered a test file, and will be run in turn. Our main test file is called -<code>normal.exp</code>; it runs all the tests in testsuite_files using the -callbacks loaded from the support library. -</para> - -<para>The <code>config</code> directory is searched for any particular "target -board" information unique to this library. This is currently unused and sets -only default variables. -</para> - -</sect3> - -<sect3 id="test.harness.utils" xreflabel="test.utils"> -<title>Utilities</title> - <para> - </para> - <para> - The testsuite directory also contains some files that implement - functionality that is intended to make writing test cases easier, - or to avoid duplication, or to provide error checking in a way that - is consistent across platforms and test harnesses. A stand-alone - executable, called <emphasis>abi_check</emphasis>, and a static - library called <emphasis>libtestc++</emphasis> are - constructed. Both of these items are not installed, and only used - during testing. - </para> - - <para> - These files include the following functionality: - </para> - - <itemizedlist> - <listitem> - <para> - <emphasis>testsuite_abi.h</emphasis>, - <emphasis>testsuite_abi.cc</emphasis>, - <emphasis>testsuite_abi_check.cc</emphasis> - </para> - <para> - Creates the executable <emphasis>abi_check</emphasis>. - Used to check correctness of symbol versioning, visibility of - exported symbols, and compatibility on symbols in the shared - library, for hosts that support this feature. More information - can be found in the ABI documentation <ulink url="abi.html">here</ulink> - </para> - </listitem> - <listitem> - <para> - <emphasis>testsuite_allocator.h</emphasis>, - <emphasis>testsuite_allocator.cc</emphasis> - </para> - <para> - Contains specialized allocators that keep track of construction - and destruction. Also, support for overriding global new and - delete operators, including verification that new and delete - are called during execution, and that allocation over max_size - fails. - </para> - </listitem> - <listitem> - <para> - <emphasis>testsuite_character.h</emphasis> - </para> - <para> - Contains <code>std::char_traits</code> and - <code>std::codecvt</code> specializations for a user-defined - POD. - </para> - </listitem> - <listitem> - <para> - <emphasis>testsuite_hooks.h</emphasis>, - <emphasis>testsuite_hooks.cc</emphasis> - </para> - <para> - A large number of utilities, including: - </para> - <itemizedlist> - <listitem><para>VERIFY</para></listitem> - <listitem><para>set_memory_limits</para></listitem> - <listitem><para>verify_demangle</para></listitem> - <listitem><para>run_tests_wrapped_locale</para></listitem> - <listitem><para>run_tests_wrapped_env</para></listitem> - <listitem><para>try_named_locale</para></listitem> - <listitem><para>try_mkfifo</para></listitem> - <listitem><para>func_callback</para></listitem> - <listitem><para>counter</para></listitem> - <listitem><para>copy_tracker</para></listitem> - <listitem><para>copy_constructor</para></listitem> - <listitem><para>assignment_operator</para></listitem> - <listitem><para>destructor</para></listitem> - <listitem> - <para>pod_char, pod_int and associated char_traits specializations</para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para> - <emphasis>testsuite_io.h</emphasis> - </para> - <para> - Error, exception, and constraint checking for - <code>std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>. - </para> - </listitem> - <listitem> - <para> - <emphasis>testsuite_iterators.h</emphasis> - </para> - <para> - Wrappers for various iterators. - </para> - </listitem> - <listitem> - <para> - <emphasis>testsuite_performance.h</emphasis> - </para> - <para> - A number of class abstractions for performance counters, and - reporting functions including: - </para> - <itemizedlist> - <listitem><para>time_counter</para></listitem> - <listitem><para>resource_counter</para></listitem> - <listitem><para>report_performance</para></listitem> - </itemizedlist> - </listitem> - </itemizedlist> -</sect3> - -</sect2> -</sect1> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/using.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/using.xml deleted file mode 100644 index 7b75b8be1..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/using.xml +++ /dev/null @@ -1,1297 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<chapter id="manual.intro.using" xreflabel="Using"> - <?dbhtml filename="using.html"?> - -<title>Using</title> - - <sect1 id="manual.intro.using.lib" xreflabel="Lib"> - <title>Linking Library Binary Files</title> - - <para> - If you only built a static library (libstdc++.a), or if you - specified static linking, you don't have to worry about this. - But if you built a shared library (libstdc++.so) and linked - against it, then you will need to find that library when you run - the executable. - </para> - <para> - Methods vary for different platforms and different styles, but - the usual ones are printed to the screen during installation. - They include: - </para> - <itemizedlist> - <listitem> - <para> - At runtime set LD_LIBRARY_PATH in your environment - correctly, so that the shared library for libstdc++ can be - found and loaded. Be certain that you understand all of the - other implications and behavior of LD_LIBRARY_PATH first - (few people do, and they get into trouble). - </para> - </listitem> - <listitem> - <para> - Compile the path to find the library at runtime into the - program. This can be done by passing certain options to - g++, which will in turn pass them on to the linker. The - exact format of the options is dependent on which linker you - use: - </para> - <itemizedlist> - <listitem> - <para> - GNU ld (default on Linux):<literal>-Wl,--rpath,<filename class="directory">destdir</filename>/lib</literal> - </para> - </listitem> - <listitem> - <para> - IRIX ld:<literal> - -Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal> - </para> - </listitem> - <listitem> - <para> - Solaris ld:<literal>-Wl,-R<filename class="directory">destdir</filename>/lib</literal> - </para> - </listitem> - <listitem> - <para> - More...? Let us know! - </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - <para> - Use the <command>ldd</command> utility to show which library the - system thinks it will get at runtime. - </para> - <para> - A libstdc++.la file is also installed, for use with Libtool. If - you use Libtool to create your executables, these details are - taken care of for you. - </para> - </sect1> - - <sect1 id="manual.intro.using.headers" xreflabel="Headers"> - <?dbhtml filename="using_headers.html"?> - <title>Headers</title> - - <sect2 id="manual.intro.using.headers.all" xreflabel="Header Files"> - <title>Header Files</title> - - <para> - The C++ standard specifies the entire set of header files that - must be available to all hosted implementations. Actually, the - word "files" is a misnomer, since the contents of the - headers don't necessarily have to be in any kind of external - file. The only rule is that when one <code>#include</code>'s a - header, the contents of that header become available, no matter - how. - </para> - - <para> - That said, in practice files are used. - </para> - - <para> - There are two main types of include files: header files related - to a specific version of the ISO C++ standard (called Standard - Headers), and all others (TR1, C++ ABI, and Extensions). - </para> - - <para> - Two dialects of standard headers are supported, corresponding to - the 1998 standard as updated for 2003, and the draft of the - upcoming 200x standard. - </para> - - <para> - C++98/03 include files. These are available in the default compilation mode, i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>. - </para> - -<table frame='all'> -<title>C++ 1998 Library Headers</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<tbody> -<row> -<entry><filename class="headerfile">algorithm</filename></entry> -<entry><filename class="headerfile">bitset</filename></entry> -<entry><filename class="headerfile">complex</filename></entry> -<entry><filename class="headerfile">deque</filename></entry> -<entry><filename class="headerfile">exception</filename></entry> -</row> -<row> -<entry><filename class="headerfile">fstream</filename></entry> -<entry><filename class="headerfile">functional</filename></entry> -<entry><filename class="headerfile">iomanip</filename></entry> -<entry><filename class="headerfile">ios</filename></entry> -<entry><filename class="headerfile">iosfwd</filename></entry> -</row> -<row> -<entry><filename class="headerfile">iostream</filename></entry> -<entry><filename class="headerfile">istream</filename></entry> -<entry><filename class="headerfile">iterator</filename></entry> -<entry><filename class="headerfile">limits</filename></entry> -<entry><filename class="headerfile">list</filename></entry> -</row> -<row> -<entry><filename class="headerfile">locale</filename></entry> -<entry><filename class="headerfile">map</filename></entry> -<entry><filename class="headerfile">memory</filename></entry> -<entry><filename class="headerfile">new</filename></entry> -<entry><filename class="headerfile">numeric</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ostream</filename></entry> -<entry><filename class="headerfile">queue</filename></entry> -<entry><filename class="headerfile">set</filename></entry> -<entry><filename class="headerfile">sstream</filename></entry> -<entry><filename class="headerfile">stack</filename></entry> -</row> -<row> -<entry><filename class="headerfile">stdexcept</filename></entry> -<entry><filename class="headerfile">streambuf</filename></entry> -<entry><filename class="headerfile">string</filename></entry> -<entry><filename class="headerfile">utility</filename></entry> -<entry><filename class="headerfile">typeinfo</filename></entry> -</row> -<row> -<entry><filename class="headerfile">valarray</filename></entry> -<entry><filename class="headerfile">vector</filename></entry> -</row> -</tbody> -</tgroup> -</table> - -<para></para> -<table frame='all'> -<title>C++ 1998 Library Headers for C Library Facilities</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<tbody> -<row> -<entry><filename class="headerfile">cassert</filename></entry> -<entry><filename class="headerfile">cerrno</filename></entry> -<entry><filename class="headerfile">cctype</filename></entry> -<entry><filename class="headerfile">cfloat</filename></entry> -<entry><filename class="headerfile">ciso646</filename></entry> -</row> -<row> -<entry><filename class="headerfile">climits</filename></entry> -<entry><filename class="headerfile">clocale</filename></entry> -<entry><filename class="headerfile">cmath</filename></entry> -<entry><filename class="headerfile">csetjmp</filename></entry> -<entry><filename class="headerfile">csignal</filename></entry> -</row> -<row> -<entry><filename class="headerfile">cstdarg</filename></entry> -<entry><filename class="headerfile">cstddef</filename></entry> -<entry><filename class="headerfile">cstdio</filename></entry> -<entry><filename class="headerfile">cstdlib</filename></entry> -<entry><filename class="headerfile">cstring</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ctime</filename></entry> -<entry><filename class="headerfile">cwchar</filename></entry> -<entry><filename class="headerfile">cwctype</filename></entry> -</row> -</tbody> -</tgroup> -</table> - -<para> -C++0x include files. These are only available in C++0x compilation -mode, i.e. <literal>-std=c++0x</literal> or <literal>-std=gnu++0x</literal>. -</para> - -<para></para> -<table frame='all'> -<title>C++ 200x Library Headers</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<tbody> - -<row> -<entry><filename class="headerfile">algorithm</filename></entry> -<entry><filename class="headerfile">array</filename></entry> -<entry><filename class="headerfile">bitset</filename></entry> -<entry><filename class="headerfile">chrono</filename></entry> -<entry><filename class="headerfile">complex</filename></entry> -</row> -<row> -<entry><filename class="headerfile">condition_variable</filename></entry> -<entry><filename class="headerfile">deque</filename></entry> -<entry><filename class="headerfile">exception</filename></entry> -<entry><filename class="headerfile">forward_list</filename></entry> -<entry><filename class="headerfile">fstream</filename></entry> -</row> -<row> -<entry><filename class="headerfile">functional</filename></entry> -<entry><filename class="headerfile">initalizer_list</filename></entry> -<entry><filename class="headerfile">iomanip</filename></entry> -<entry><filename class="headerfile">ios</filename></entry> -<entry><filename class="headerfile">iosfwd</filename></entry> -</row> -<row> -<entry><filename class="headerfile">iostream</filename></entry> -<entry><filename class="headerfile">istream</filename></entry> -<entry><filename class="headerfile">iterator</filename></entry> -<entry><filename class="headerfile">limits</filename></entry> -<entry><filename class="headerfile">list</filename></entry> -</row> -<row> -<entry><filename class="headerfile">locale</filename></entry> -<entry><filename class="headerfile">map</filename></entry> -<entry><filename class="headerfile">memory</filename></entry> -<entry><filename class="headerfile">mutex</filename></entry> -<entry><filename class="headerfile">new</filename></entry> -</row> -<row> -<entry><filename class="headerfile">numeric</filename></entry> -<entry><filename class="headerfile">ostream</filename></entry> -<entry><filename class="headerfile">queue</filename></entry> -<entry><filename class="headerfile">random</filename></entry> -<entry><filename class="headerfile">ratio</filename></entry> -</row> -<row> -<entry><filename class="headerfile">regex</filename></entry> -<entry><filename class="headerfile">set</filename></entry> -<entry><filename class="headerfile">sstream</filename></entry> -<entry><filename class="headerfile">stack</filename></entry> -<entry><filename class="headerfile">stdexcept</filename></entry> -</row> -<row> -<entry><filename class="headerfile">streambuf</filename></entry> -<entry><filename class="headerfile">string</filename></entry> -<entry><filename class="headerfile">system_error</filename></entry> -<entry><filename class="headerfile">thread</filename></entry> -<entry><filename class="headerfile">tuple</filename></entry> -</row> -<row> -<entry><filename class="headerfile">type_traits</filename></entry> -<entry><filename class="headerfile">typeinfo</filename></entry> -<entry><filename class="headerfile">unordered_map</filename></entry> -<entry><filename class="headerfile">unordered_set</filename></entry> -<entry><filename class="headerfile">utility</filename></entry> -</row> -<row> -<entry><filename class="headerfile">valarray</filename></entry> -<entry><filename class="headerfile">vector</filename></entry> -</row> - -</tbody> -</tgroup> -</table> - -<para></para> - -<table frame='all'> -<title>C++ 200x Library Headers for C Library Facilities</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<colspec colname='c5'></colspec> -<tbody> -<row> -<entry><filename class="headerfile">cassert</filename></entry> -<entry><filename class="headerfile">ccomplex</filename></entry> -<entry><filename class="headerfile">cctype</filename></entry> -<entry><filename class="headerfile">cerrno</filename></entry> -<entry><filename class="headerfile">cfenv</filename></entry> -</row> -<row> -<entry><filename class="headerfile">cfloat</filename></entry> -<entry><filename class="headerfile">cinttypes</filename></entry> -<entry><filename class="headerfile">ciso646</filename></entry> -<entry><filename class="headerfile">climits</filename></entry> -<entry><filename class="headerfile">clocale</filename></entry> -</row> -<row> -<entry><filename class="headerfile">cmath</filename></entry> -<entry><filename class="headerfile">csetjmp</filename></entry> -<entry><filename class="headerfile">csignal</filename></entry> -<entry><filename class="headerfile">cstdarg</filename></entry> -<entry><filename class="headerfile">cstdatomic</filename></entry> -</row> -<row> -<entry><filename class="headerfile">cstdbool</filename></entry> -<entry><filename class="headerfile">cstddef</filename></entry> -<entry><filename class="headerfile">cstdint</filename></entry> -<entry><filename class="headerfile">cstdlib</filename></entry> -<entry><filename class="headerfile">cstdio</filename></entry> -</row> -<row> -<entry><filename class="headerfile">cstring</filename></entry> -<entry><filename class="headerfile">ctgmath</filename></entry> -<entry><filename class="headerfile">ctime</filename></entry> -<entry><filename class="headerfile">cuchar</filename></entry> -<entry><filename class="headerfile">cwchar</filename></entry> -</row> -<row> -<entry><filename class="headerfile">cwctype</filename></entry> -<entry><filename class="headerfile">stdatomic.h</filename></entry> -</row> - -</tbody> -</tgroup> -</table> - - -<para> - In addition, TR1 includes as: -</para> - -<table frame='all'> -<title>C++ TR1 Library Headers</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<colspec colname='c5'></colspec> -<tbody> - -<row> -<entry><filename class="headerfile">tr1/array</filename></entry> -<entry><filename class="headerfile">tr1/complex</filename></entry> -<entry><filename class="headerfile">tr1/memory</filename></entry> -<entry><filename class="headerfile">tr1/functional</filename></entry> -<entry><filename class="headerfile">tr1/random</filename></entry> -</row> -<row> -<entry><filename class="headerfile">tr1/regex</filename></entry> -<entry><filename class="headerfile">tr1/tuple</filename></entry> -<entry><filename class="headerfile">tr1/type_traits</filename></entry> -<entry><filename class="headerfile">tr1/unordered_map</filename></entry> -<entry><filename class="headerfile">tr1/unordered_set</filename></entry> -</row> -<row> -<entry><filename class="headerfile">tr1/utility</filename></entry> -</row> - -</tbody> -</tgroup> -</table> - -<para></para> - - -<table frame='all'> -<title>C++ TR1 Library Headers for C Library Facilities</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<colspec colname='c5'></colspec> -<tbody> - -<row> -<entry><filename class="headerfile">tr1/ccomplex</filename></entry> -<entry><filename class="headerfile">tr1/cfenv</filename></entry> -<entry><filename class="headerfile">tr1/cfloat</filename></entry> -<entry><filename class="headerfile">tr1/cmath</filename></entry> -<entry><filename class="headerfile">tr1/cinttypes</filename></entry> -</row> -<row> -<entry><filename class="headerfile">tr1/climits</filename></entry> -<entry><filename class="headerfile">tr1/cstdarg</filename></entry> -<entry><filename class="headerfile">tr1/cstdbool</filename></entry> -<entry><filename class="headerfile">tr1/cstdint</filename></entry> -<entry><filename class="headerfile">tr1/cstdio</filename></entry> -</row> -<row> -<entry><filename class="headerfile">tr1/cstdlib</filename></entry> -<entry><filename class="headerfile">tr1/ctgmath</filename></entry> -<entry><filename class="headerfile">tr1/ctime</filename></entry> -<entry><filename class="headerfile">tr1/cwchar</filename></entry> -<entry><filename class="headerfile">tr1/cwctype</filename></entry> -</row> - -</tbody> -</tgroup> -</table> - -<para> - Also included are files for the C++ ABI interface: -</para> - -<table frame='all'> -<title>C++ ABI Headers</title> -<tgroup cols='2' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<tbody> -<row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row> -</tbody> -</tgroup> -</table> - -<para> - And a large variety of extensions. -</para> - -<table frame='all'> -<title>Extension Headers</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<colspec colname='c5'></colspec> -<tbody> - -<row> -<entry><filename class="headerfile">ext/algorithm</filename></entry> -<entry><filename class="headerfile">ext/atomicity.h</filename></entry> -<entry><filename class="headerfile">ext/array_allocator.h</filename></entry> -<entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry> -<entry><filename class="headerfile">ext/cast.h</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry> -<entry><filename class="headerfile">ext/concurrence.h</filename></entry> -<entry><filename class="headerfile">ext/debug_allocator.h</filename></entry> -<entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry> -<entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ext/functional</filename></entry> -<entry><filename class="headerfile">ext/iterator</filename></entry> -<entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry> -<entry><filename class="headerfile">ext/memory</filename></entry> -<entry><filename class="headerfile">ext/mt_allocator.h</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ext/new_allocator.h</filename></entry> -<entry><filename class="headerfile">ext/numeric</filename></entry> -<entry><filename class="headerfile">ext/numeric_traits.h</filename></entry> -<entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry> -<entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry> -<entry><filename class="headerfile">ext/pool_allocator.h</filename></entry> -<entry><filename class="headerfile">ext/rb_tree</filename></entry> -<entry><filename class="headerfile">ext/rope</filename></entry> -<entry><filename class="headerfile">ext/slist</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry> -<entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry> -<entry><filename class="headerfile">ext/throw_allocator.h</filename></entry> -<entry><filename class="headerfile">ext/typelist.h</filename></entry> -<entry><filename class="headerfile">ext/type_traits.h</filename></entry> -</row> -<row> -<entry><filename class="headerfile">ext/vstring.h</filename></entry> -</row> - -</tbody> -</tgroup> -</table> - -<para></para> - -<table frame='all'> -<title>Extension Debug Headers</title> -<tgroup cols='5' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<colspec colname='c3'></colspec> -<colspec colname='c4'></colspec> -<colspec colname='c5'></colspec> -<tbody> - -<row> -<entry><filename class="headerfile">debug/bitset</filename></entry> -<entry><filename class="headerfile">debug/deque</filename></entry> -<entry><filename class="headerfile">debug/list</filename></entry> -<entry><filename class="headerfile">debug/map</filename></entry> -<entry><filename class="headerfile">debug/set</filename></entry> -</row> - -<row> -<entry><filename class="headerfile">debug/string</filename></entry> -<entry><filename class="headerfile">debug/unordered_map</filename></entry> -<entry><filename class="headerfile">debug/unordered_set</filename></entry> -<entry><filename class="headerfile">debug/vector</filename></entry> -</row> - -</tbody> -</tgroup> -</table> - -<para></para> - -<table frame='all'> -<title>Extension Parallel Headers</title> -<tgroup cols='2' align='left' colsep='1' rowsep='1'> -<colspec colname='c1'></colspec> -<colspec colname='c2'></colspec> -<tbody> -<row> -<entry><filename class="headerfile">parallel/algorithm</filename></entry> -<entry><filename class="headerfile">parallel/numeric</filename></entry> -</row> -</tbody> -</tgroup> -</table> - - </sect2> - - <sect2 id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"> - <title>Mixing Headers</title> - -<para> A few simple rules. -</para> - -<para>First, mixing different dialects of the standard headers is not -possible. It's an all-or-nothing affair. Thus, code like -</para> - -<programlisting> -#include <array> -#include <functional> -</programlisting> - -<para>Implies C++0x mode. To use the entities in <array>, the C++0x -compilation mode must be used, which implies the C++0x functionality -(and deprecations) in <functional> will be present. -</para> - -<para>Second, the other headers can be included with either dialect of -the standard headers, although features and types specific to C++0x -are still only enabled when in C++0x compilation mode. So, to use -rvalue references with <code>__gnu_cxx::vstring</code>, or to use the -debug-mode versions of <code>std::unordered_map</code>, one must use -the <code>std=gnu++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.) -</para> - -<para>A special case of the second rule is the mixing of TR1 and C++0x -facilities. It is possible (although not especially prudent) to -include both the TR1 version and the C++0x version of header in the -same translation unit: -</para> - -<programlisting> -#include <tr1/type_traits> -#include <type_traits> -</programlisting> - -<para> Several parts of C++0x diverge quite substantially from TR1 predecessors. -</para> - </sect2> - - <sect2 id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"> - <title>The C Headers and <code>namespace std</code></title> - -<para> - The standard specifies that if one includes the C-style header - (<math.h> in this case), the symbols will be available - in the global namespace and perhaps in - namespace <code>std::</code> (but this is no longer a firm - requirement.) One the other hand, including the C++-style - header (<cmath>) guarantees that the entities will be - found in namespace std and perhaps in the global namespace. - </para> - -<para> -Usage of C++-style headers is recommended, as then -C-linkage names can be disambiguated by explicit qualification, such -as by <code>std::abort</code>. In addition, the C++-style headers can -use function overloading to provide a simpler interface to certain -families of C-functions. For instance in <cmath>, the -function <code>std::sin</code> has overloads for all the builtin -floating-point types. This means that <code>std::sin</code> can be -used uniformly, instead of a combination -of <code>std::sinf</code>, <code>std::sin</code>, -and <code>std::sinl</code>. -</para> - </sect2> - - <sect2 id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"> - <title>Precompiled Headers</title> - - -<para>There are three base header files that are provided. They can be -used to precompile the standard headers and extensions into binary -files that may the be used to speed compiles that use these headers. -</para> - - -<itemizedlist> -<listitem> - <para>stdc++.h</para> -<para>Includes all standard headers. Actual content varies depending on -language dialect. -</para> -</listitem> - -<listitem> - <para>stdtr1c++.h</para> -<para>Includes all of <stdc++.h>, and adds all the TR1 headers. -</para> -</listitem> - -<listitem><para>extc++.h</para> -<para>Includes all of <stdtr1c++.h>, and adds all the Extension headers. -</para></listitem> -</itemizedlist> - -<para>How to construct a .gch file from one of these base header files.</para> - -<para>First, find the include directory for the compiler. One way to do -this is:</para> - -<programlisting> -g++ -v hello.cc - -#include <...> search starts here: - /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0 -... -End of search list. -</programlisting> - - -<para>Then, create a precompiled header file with the same flags that -will be used to compile other projects.</para> - -<programlisting> -g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h -</programlisting> - -<para>The resulting file will be quite large: the current size is around -thirty megabytes. </para> - -<para>How to use the resulting file.</para> - -<programlisting> -g++ -I. -include stdc++.h -H -g -O2 hello.cc -</programlisting> - -<para>Verification that the PCH file is being used is easy:</para> - -<programlisting> -g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe -! ./stdc++.h.gch -. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream -. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string -</programlisting> - -<para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </para> -<para></para> - -<para> Detailed information about creating precompiled header files can be found in the GCC <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</ulink>. -</para> - - - </sect2> - </sect1> - - <sect1 id="manual.intro.using.namespaces" xreflabel="Namespaces"> - <?dbhtml filename="using_namespaces.html"?> - <title>Namespaces</title> - - <sect2 id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"> - <title>Available Namespaces</title> - - - -<para> There are three main namespaces. -</para> - -<itemizedlist> - <listitem><para>std</para> -<para>The ISO C++ standards specify that "all library entities are defined -within namespace std." This includes namespaces nested -within <code>namespace std</code>, such as <code>namespace -std::tr1</code>. -</para> -</listitem> -<listitem><para>abi</para> -<para>Specified by the C++ ABI. This ABI specifies a number of type and -function APIs supplemental to those required by the ISO C++ Standard, -but necessary for interoperability. -</para> -</listitem> - -<listitem><para>__gnu_</para> -<para>Indicating one of several GNU extensions. Choices -include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>, -and <code>__gnu_pbds</code>. -</para></listitem> -</itemizedlist> - -<para> A complete list of implementation namespaces (including namespace contents) is available in the generated source <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</ulink>. -</para> - - - </sect2> - - <sect2 id="manual.intro.using.namespaces.std" xreflabel="namespace std"> - <title>namespace std</title> - - -<para> - One standard requirement is that the library components are defined - in <code>namespace std::</code>. Thus, in order to use these types or - functions, one must do one of two things: -</para> - -<itemizedlist> - <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source -(either <code>using namespace std;</code> or i.e. <code>using -std::string;</code>) This approach works well for individual source files, but -should not be used in a global context, like header files. - </para></listitem> <listitem><para>use a <emphasis>fully -qualified name</emphasis>for each library symbol -(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be -used, and usually enhanced, by strategic use of typedefs. (In the -cases where the qualified verbiage becomes unwieldy.) - </para> - </listitem> -</itemizedlist> - - </sect2> - - <sect2 id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"> - <title>Using Namespace Composition</title> - -<para> -Best practice in programming suggests sequestering new data or -functionality in a sanely-named, unique namespace whenever -possible. This is considered an advantage over dumping everything in -the global namespace, as then name look-up can be explicitly enabled or -disabled as above, symbols are consistently mangled without repetitive -naming prefixes or macros, etc. -</para> - -<para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to - adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called - <emphasis>namespace composition</emphasis>. This is what happens if - a <emphasis>using</emphasis>-declaration is put into a - namespace-definition: the imported symbol(s) gets imported into the - currently active namespace(s). For example: -</para> -<programlisting> -namespace gtk -{ - using std::string; - using std::tr1::array; - - class Window { ... }; -} -</programlisting> -<para> - In this example, <code>std::string</code> gets imported into - <code>namespace gtk</code>. The result is that use of - <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification. - As an added bonus, - <code>std::string</code> does not get imported into - the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the - <code>using</code>-declarations can wrapped in macros that - are set based on autoconf-tests to either "" or i.e. <code>using - std::string;</code> (depending on whether the system has - libstdc++ in <code>std::</code> or not). (ideas from - <email>llewelly@dbritsch.dsl.xmission.com</email>, Karl Nelson <email>kenelson@ece.ucdavis.edu</email>) -</para> - - - </sect2> - </sect1> - - <sect1 id="manual.intro.using.macros" xreflabel="Macros"> - <?dbhtml filename="using_macros.html"?> - <title>Macros</title> - - <para>All pre-processor switches and configurations are all gathered - in the file <code>c++config.h</code>, which is generated during - the libstdc++ configuration and build process, and included by - files part of the public libstdc++ API. Most of these macros - should not be used by consumers of libstdc++, and are reserved - for internal implementation use. <emphasis>These macros cannot be - redefined</emphasis>. However, a select handful of these macro - control libstdc++ extensions and extra features, or provide - versioning information for the API, and are able to be used. - </para> - - <para>All library macros begin with <code>_GLIBCXX_</code> (except for - versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>). - </para> - - <para>Below is the macro which users may check for library version - information. </para> - - <variablelist> - <varlistentry> - <term><code>__GLIBCXX__</code></term> - <listitem> - <para>The current version of - libstdc++ in compressed ISO date format, form of an unsigned - long. For details on the value of this particular macro for a - particular release, please consult this <ulink url="abi.html"> - document</ulink>. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para>Below are the macros which users may change with #define/#undef or - with -D/-U compiler flags. The default state of the symbol is - listed.</para> - - <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means - that the symbol is initially chosen (or not) based on - --enable/--disable options at library build and configure time - (documented <link linkend="manual.intro.setup.configure">here</link>), with the - various --enable/--disable choices being translated to - #define/#undef). - </para> - - <para> <acronym>ABI</acronym> means that changing from the default value may - mean changing the <acronym>ABI</acronym> of compiled code. In other words, these - choices control code which has already been compiled (i.e., in a - binary such as libstdc++.a/.so). If you explicitly #define or - #undef these macros, the <emphasis>headers</emphasis> may see different code - paths, but the <emphasis>libraries</emphasis> which you link against will not. - Experimenting with different values with the expectation of - consistent linkage requires changing the config headers before - building/installing the library. - </para> - - <variablelist> - <varlistentry><term><code>_GLIBCXX_DEPRECATED</code></term> - <listitem> - <para> - Defined by default. Not configurable. ABI-changing. Turning this off - removes older ARM-style iostreams code, and other anachronisms - from the API. This macro is dependent on the version of the - standard being tracked, and as a result may give different results for - <code>-std=c++98</code> and <code>-std=c++0x</code>. This may - be useful in updating old C++ code which no longer meet the - requirements of the language, or for checking current code - against new language standards. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>_GLIBCXX_FORCE_NEW</code></term> - <listitem> - <para> - Undefined by default. When defined, memory allocation and - allocators controlled by libstdc++ call operator new/delete - without caching and pooling. Configurable via - <code>--enable-libstdcxx-allocator</code>. ABI-changing. - </para> - </listitem></varlistentry> - - - <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term> - <listitem> - <para> - Undefined by default. Configurable via - <code>--enable-concept-checks</code>. When defined, performs - compile-time checking on certain template instantiations to - detect violations of the requirements of the standard. This - is described in more detail <ulink - url="../19_diagnostics/howto.html#3">here</ulink>. - </para> - </listitem></varlistentry> - - <varlistentry><term><code>_GLIBCXX_DEBUG</code></term> - <listitem> - <para> - Undefined by default. When defined, compiles - user code using the <ulink url="../ext/debug.html#safe">libstdc++ debug - mode</ulink>. - </para> - </listitem></varlistentry> - <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term> - <listitem> - <para> - Undefined by default. When defined while - compiling with the <ulink url="../ext/debug.html#safe">libstdc++ debug - mode</ulink>, makes the debug mode extremely picky by making the use - of libstdc++ extensions and libstdc++-specific behavior into - errors. - </para> - </listitem></varlistentry> - <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term> - <listitem> - <para>Undefined by default. When defined, compiles - user code using the <ulink url="../ext/parallel_mode.html">libstdc++ parallel - mode</ulink>. - </para> - </listitem></varlistentry> - </variablelist> - - - </sect1> - - <sect1 id="manual.intro.using.concurrency" xreflabel="Concurrency"> - <?dbhtml filename="using_concurrency.html"?> - <title>Concurrency</title> - - <para>This section discusses issues surrounding the proper compilation - of multithreaded applications which use the Standard C++ - library. This information is GCC-specific since the C++ - standard does not address matters of multithreaded applications. - </para> - - <sect2 id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"> - <title>Prerequisites</title> - - <para>All normal disclaimers aside, multithreaded C++ application are - only supported when libstdc++ and all user code was built with - compilers which report (via <code> gcc/g++ -v </code>) the same thread - model and that model is not <emphasis>single</emphasis>. As long as your - final application is actually single-threaded, then it should be - safe to mix user code built with a thread model of - <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built - with another thread model useful on the platform. Other mixes - may or may not work but are not considered supported. (Thus, if - you distribute a shared C++ library in binary form only, it may - be best to compile it with a GCC configured with - --enable-threads for maximal interchangeability and usefulness - with a user population that may have built GCC with either - --enable-threads or --disable-threads.) - </para> - <para>When you link a multithreaded application, you will probably - need to add a library or flag to g++. This is a very - non-standardized area of GCC across ports. Some ports support a - special flag (the spelling isn't even standardized yet) to add - all required macros to a compilation (if any such flags are - required then you must provide the flag for all compilations not - just linking) and link-library additions and/or replacements at - link time. The documentation is weak. Here is a quick summary - to display how ad hoc this is: On Solaris, both -pthreads and - -threads (with subtly different meanings) are honored. On OSF, - -pthread and -threads (with subtly different meanings) are - honored. On Linux/i386, -pthread is honored. On FreeBSD, - -pthread is honored. Some other ports use other switches. - AFAIK, none of this is properly documented anywhere other than - in ``gcc -dumpspecs'' (look at lib and cpp entries). - </para> - - </sect2> - - <sect2 id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"> - <title>Thread Safety</title> - - -<para> -We currently use the <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</ulink> definition of thread safety. -</para> - - - <para>The library strives to be thread-safe when all of the following - conditions are met: - </para> - <itemizedlist> - <listitem> - <para>The system's libc is itself thread-safe, - </para> - </listitem> - <listitem> - <para> - The compiler in use reports a thread model other than - 'single'. This can be tested via output from <code>gcc - -v</code>. Multi-thread capable versions of gcc output - something like this: - </para> -<programlisting> -%gcc -v -Using built-in specs. -... -Thread model: posix -gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) -</programlisting> - -<para>Look for "Thread model" lines that aren't equal to "single."</para> - </listitem> - <listitem> - <para> - Requisite command-line flags are used for atomic operations - and threading. Examples of this include <code>-pthread</code> - and <code>-march=native</code>, although specifics vary - depending on the host environment. See <ulink - url="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine - Dependent Options</ulink>. - </para> - </listitem> - <listitem> - <para> - An implementation of atomicity.h functions - exists for the architecture in question. See the internals documentation for more <ulink url="../ext/concurrence.html">details</ulink>. - </para> - </listitem> - - </itemizedlist> - <para>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: - </para> - <programlisting> - 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.</programlisting> - <para>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: - </para> - <programlisting> - 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 (); - } </programlisting> - <para>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. - </para> - <para>See chapters <ulink url="../17_intro/howto.html#3">17</ulink> (library - introduction), <ulink url="../23_containers/howto.html#3">23</ulink> - (containers), and <ulink url="../27_io/howto.html#9">27</ulink> (I/O) for - more information. - </para> - - - </sect2> - <sect2 id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"> - <title>Atomics</title> - <para> - </para> - </sect2> - - <sect2 id="manual.intro.using.concurrency.io" xreflabel="IO"> - <title>IO</title> - <para>I'll assume that you have already read the - <ulink url="../17_intro/howto.html#3">general notes on library threads</ulink>, - and the - <ulink url="../23_containers/howto.html#3">notes on threaded container - access</ulink> (you might not think of an I/O stream as a container, but - the points made there also hold here). If you have not read them, - please do so first. - </para> - <para>This gets a bit tricky. Please read carefully, and bear with me. - </para> - - <sect3 id="concurrency.io.structure" xreflabel="Structure"> - <title>Structure</title> - <para>A wrapper - type called <code>__basic_file</code> provides our abstraction layer - for the <code>std::filebuf</code> classes. Nearly all decisions dealing - with actual input and output must be made in <code>__basic_file</code>. - </para> - <para>A generic locking mechanism is somewhat in place at the filebuf layer, - but is not used in the current code. Providing locking at any higher - level is akin to providing locking within containers, and is not done - for the same reasons (see the links above). - </para> - </sect3> - - <sect3 id="concurrency.io.defaults" xreflabel="Defaults"> - <title>Defaults</title> - <para>The __basic_file type is simply a collection of small wrappers around - the C stdio layer (again, see the link under Structure). We do no - locking ourselves, but simply pass through to calls to <code>fopen</code>, - <code>fwrite</code>, and so forth. - </para> - <para>So, for 3.0, the question of "is multithreading safe for I/O" - must be answered with, "is your platform's C library threadsafe - for I/O?" Some are by default, some are not; many offer multiple - implementations of the C library with varying tradeoffs of threadsafety - and efficiency. You, the programmer, are always required to take care - with multiple threads. - </para> - <para>(As an example, the POSIX standard requires that C stdio FILE* - operations are atomic. POSIX-conforming C libraries (e.g, on Solaris - and GNU/Linux) have an internal mutex to serialize operations on - FILE*s. However, you still need to not do stupid things like calling - <code>fclose(fs)</code> in one thread followed by an access of - <code>fs</code> in another.) - </para> - <para>So, if your platform's C library is threadsafe, then your - <code>fstream</code> I/O operations will be threadsafe at the lowest - level. For higher-level operations, such as manipulating the data - contained in the stream formatting classes (e.g., setting up callbacks - inside an <code>std::ofstream</code>), you need to guard such accesses - like any other critical shared resource. - </para> - </sect3> - - <sect3 id="concurrency.io.future" xreflabel="Future"> - <title>Future</title> - <para> A - second choice may be available for I/O implementations: libio. This is - disabled by default, and in fact will not currently work due to other - issues. It will be revisited, however. - </para> - <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O - implementation. When libio is in use, the <code>__basic_file</code> - type is basically derived from FILE. (The real situation is more - complex than that... it's derived from an internal type used to - implement FILE. See libio/libioP.h to see scary things done with - vtbls.) The result is that there is no "layer" of C stdio - to go through; the filebuf makes calls directly into the same - functions used to implement <code>fread</code>, <code>fwrite</code>, - and so forth, using internal data structures. (And when I say - "makes calls directly," I mean the function is literally - replaced by a jump into an internal function. Fast but frightening. - *grin*) - </para> - <para>Also, the libio internal locks are used. This requires pulling in - large chunks of glibc, such as a pthreads implementation, and is one - of the issues preventing widespread use of libio as the libstdc++ - cstdio implementation. - </para> - <para>But we plan to make this work, at least as an option if not a future - default. Platforms running a copy of glibc with a recent-enough - version will see calls from libstdc++ directly into the glibc already - installed. For other platforms, a copy of the libio subsection will - be built and included in libstdc++. - </para> - </sect3> - - <sect3 id="concurrency.io.alt" xreflabel="Alt"> - <title>Alternatives</title> - <para>Don't forget that other cstdio implementations are possible. You could - easily write one to perform your own forms of locking, to solve your - "interesting" problems. - </para> - </sect3> - - </sect2> - - <sect2 id="manual.intro.using.concurrency.containers" xreflabel="Containers"> - <title>Containers</title> - - <para>This section discusses issues surrounding the design of - multithreaded applications which use Standard C++ containers. - All information in this section is current as of the gcc 3.0 - release and all later point releases. Although earlier gcc - releases had a different approach to threading configuration and - proper compilation, the basic code design rules presented here - were similar. For information on all other aspects of - multithreading as it relates to libstdc++, including details on - the proper compilation of threaded code (and compatibility between - threaded and non-threaded code), see Chapter 17. - </para> - <para>Two excellent pages to read when working with the Standard C++ - containers and threads are - <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI's - http://www.sgi.com/tech/stl/thread_safety.html</ulink> and - <ulink url="http://www.sgi.com/tech/stl/Allocators.html">SGI's - http://www.sgi.com/tech/stl/Allocators.html</ulink>. - </para> - <para><emphasis>However, please ignore all discussions about the user-level - configuration of the lock implementation inside the STL - container-memory allocator on those pages. For the sake of this - discussion, libstdc++ configures the SGI STL implementation, - not you. This is quite different from how gcc pre-3.0 worked. - In particular, past advice was for people using g++ to - explicitly define _PTHREADS or other macros or port-specific - compilation options on the command line to get a thread-safe - STL. This is no longer required for any port and should no - longer be done unless you really know what you are doing and - assume all responsibility.</emphasis> - </para> - <para>Since the container implementation of libstdc++ uses the SGI - code, we use the same definition of thread safety as SGI when - discussing design. A key point that beginners may miss is the - fourth major paragraph of the first page mentioned above - ("For most clients,"...), which points out that - locking must nearly always be done outside the container, by - client code (that'd be you, not us). There is a notable - exceptions to this rule. Allocators called while a container or - element is constructed uses an internal lock obtained and - released solely within libstdc++ code (in fact, this is the - reason STL requires any knowledge of the thread configuration). - </para> - <para>For implementing a container which does its own locking, it is - trivial to provide a wrapper class which obtains the lock (as - SGI suggests), performs the container operation, and then - releases the lock. This could be templatized <emphasis>to a certain - extent</emphasis>, on the underlying container and/or a locking - mechanism. Trying to provide a catch-all general template - solution would probably be more trouble than it's worth. - </para> - <para>The STL implementation is currently configured to use the - high-speed caching memory allocator. Some people like to - test and/or normally run threaded programs with a different - default. For all details about how to globally override this - at application run-time see <ulink url="../ext/howto.html#3">here</ulink>. - </para> - <para>There is a better way (not standardized yet): It is possible to - force the malloc-based allocator on a per-case-basis for some - application code. The library team generally believes that this - is a better way to tune an application for high-speed using this - implementation of the STL. There is - <ulink url="../ext/howto.html#3">more information on allocators here</ulink>. - </para> - - </sect2> - </sect1> - - <sect1 id="manual.intro.using.exception" xreflabel="Exceptions"> - <?dbhtml filename="using_exceptions.html"?> - <title>Exceptions</title> - - <sect2 id="intro.using.exception.propagating" xreflabel="Propagating Exceptions"> - - <title>Propagating Exceptions aka Exception Neutrality</title> - <para> - </para> - </sect2> - - <sect2 id="intro.using.exception.safety" xreflabel="Exception Safety"> - <title>Exception Safety</title> - <para> - </para> - </sect2> - - <sect2 id="intro.using.exception.no" xreflabel="-fno-exceptions"> - <title>Support for <literal>-fno-exceptions</literal></title> - <para> - </para> - </sect2> - - </sect1> - -<!-- Section 0x : Debug --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="debug.xml"> -</xi:include> - -</chapter> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/utilities.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/manual/utilities.xml deleted file mode 100644 index 56d614ec6..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/manual/utilities.xml +++ /dev/null @@ -1,131 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ ]> - -<part id="manual.util" xreflabel="Utilities"> -<?dbhtml filename="utilities.html"?> - -<partinfo> - <keywordset> - <keyword> - ISO C++ - </keyword> - <keyword> - library - </keyword> - </keywordset> -</partinfo> - -<title> - Utilities - <indexterm><primary>Utilities</primary></indexterm> -</title> - -<!-- Chapter 01 : Functors --> -<chapter id="manual.util.functors" xreflabel="Functors"> -<?dbhtml filename="functors.html"?> - <title>Functors</title> - <para>If you don't know what functors are, you're not alone. Many people - get slightly the wrong idea. In the interest of not reinventing - the wheel, we will refer you to the introduction to the functor - concept written by SGI as part of their STL, in - <ulink url="http://www.sgi.com/tech/stl/functors.html">their - http://www.sgi.com/tech/stl/functors.html</ulink>. - </para> -</chapter> - -<!-- Chapter 02 : Pairs --> -<chapter id="manual.util.pairs" xreflabel="Pairs"> -<?dbhtml filename="pairs.html"?> - <title>Pairs</title> - <para>The <code>pair<T1,T2></code> is a simple and handy way to - carry around a pair of objects. One is of type T1, and another of - type T2; they may be the same type, but you don't get anything - extra if they are. The two members can be accessed directly, as - <code>.first</code> and <code>.second</code>. - </para> - <para>Construction is simple. The default ctor initializes each member - with its respective default ctor. The other simple ctor, - </para> - <programlisting> - pair (const T1& x, const T2& y); - </programlisting> - <para>does what you think it does, <code>first</code> getting <code>x</code> - and <code>second</code> getting <code>y</code>. - </para> - <para>There is a copy constructor, but it requires that your compiler - handle member function templates: - </para> - <programlisting> - template <class U, class V> pair (const pair<U,V>& p); - </programlisting> - <para>The compiler will convert as necessary from U to T1 and from - V to T2 in order to perform the respective initializations. - </para> - <para>The comparison operators are done for you. Equality - of two <code>pair<T1,T2></code>s is defined as both <code>first</code> - members comparing equal and both <code>second</code> members comparing - equal; this simply delegates responsibility to the respective - <code>operator==</code> functions (for types like MyClass) or builtin - comparisons (for types like int, char, etc). - </para> - <para> - The less-than operator is a bit odd the first time you see it. It - is defined as evaluating to: - </para> - <programlisting> - x.first < y.first || - ( !(y.first < x.first) && x.second < y.second ) - </programlisting> - <para>The other operators are not defined using the <code>rel_ops</code> - functions above, but their semantics are the same. - </para> - <para>Finally, there is a template function called <function>make_pair</function> - that takes two references-to-const objects and returns an - instance of a pair instantiated on their respective types: - </para> - <programlisting> - pair<int,MyClass> p = make_pair(4,myobject); - </programlisting> - -</chapter> - -<!-- Chapter 03 : Memory --> -<chapter id="manual.util.memory" xreflabel="Memory"> -<?dbhtml filename="memory.html"?> - <title>Memory</title> - <para> - Memory contains three general areas. First, function and operator - calls via <function>new</function> and <function>delete</function> - operator or member function calls. Second, allocation via - <classname>allocator</classname>. And finally, smart pointer and - intelligent pointer abstractions. - </para> - - <!-- Section 01 : allocator --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="allocator.xml"> - </xi:include> - - <!-- Section 02 : auto_ptr --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="auto_ptr.xml"> - </xi:include> - - <!-- Section 03 : shared_ptr --> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - parse="xml" href="shared_ptr.xml"> - </xi:include> - -</chapter> - -<!-- Chapter 04 : Traits --> -<chapter id="manual.util.traits" xreflabel="Traits"> -<?dbhtml filename="traits.html"?> - <title>Traits</title> - <para> - </para> -</chapter> - -</part> diff --git a/gcc-4.4.3/libstdc++-v3/doc/xml/spine.xml b/gcc-4.4.3/libstdc++-v3/doc/xml/spine.xml deleted file mode 100644 index 392f7e1be..000000000 --- a/gcc-4.4.3/libstdc++-v3/doc/xml/spine.xml +++ /dev/null @@ -1,47 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -[ -<!ENTITY authors SYSTEM "authors.xml"> -]> - -<set id="set-index" xreflabel="The GNU C++ Library Documentation"> -<?dbhtml filename="spine.html"?> -<title>The GNU C++ Library Documentation</title> - -<setinfo> - <copyright> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <year>2008</year> - <year>2009</year> - <holder> - <ulink url="http://fsf.org">FSF</ulink> - </holder> - </copyright> - &authors; -</setinfo> - - -<!-- User Manual --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="manual/spine.xml" parse="xml"> -</xi:include> - -<!-- Source Level Documentation--> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="api.xml" parse="xml"> -</xi:include> - -<!-- FAQ --> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" - href="faq.xml" parse="xml"> -</xi:include> - -</set> |
