summaryrefslogtreecommitdiff
path: root/libstdc++-v3/doc/xml
diff options
context:
space:
mode:
authorupstream source tree <ports@midipix.org>2015-03-15 20:14:05 -0400
committerupstream source tree <ports@midipix.org>2015-03-15 20:14:05 -0400
commit554fd8c5195424bdbcabf5de30fdc183aba391bd (patch)
tree976dc5ab7fddf506dadce60ae936f43f58787092 /libstdc++-v3/doc/xml
downloadcbb-gcc-4.6.4-554fd8c5195424bdbcabf5de30fdc183aba391bd.tar.bz2
cbb-gcc-4.6.4-554fd8c5195424bdbcabf5de30fdc183aba391bd.tar.xz
obtained gcc-4.6.4.tar.bz2 from upstream website;upstream
verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository.
Diffstat (limited to 'libstdc++-v3/doc/xml')
-rw-r--r--libstdc++-v3/doc/xml/api.xml106
-rw-r--r--libstdc++-v3/doc/xml/authors.xml120
-rw-r--r--libstdc++-v3/doc/xml/book.txml30
-rw-r--r--libstdc++-v3/doc/xml/chapter.txml51
-rw-r--r--libstdc++-v3/doc/xml/class.txml156
-rw-r--r--libstdc++-v3/doc/xml/faq.xml1246
-rw-r--r--libstdc++-v3/doc/xml/gnu/fdl-1.3.xml562
-rw-r--r--libstdc++-v3/doc/xml/gnu/gpl-3.0.xml834
-rw-r--r--libstdc++-v3/doc/xml/images/confdeps.dot16
-rw-r--r--libstdc++-v3/doc/xml/images/confdeps.pdfbin0 -> 50629 bytes
-rw-r--r--libstdc++-v3/doc/xml/images/confdeps.pngbin0 -> 20653 bytes
-rw-r--r--libstdc++-v3/doc/xml/manual/abi.xml1208
-rw-r--r--libstdc++-v3/doc/xml/manual/algorithms.xml101
-rw-r--r--libstdc++-v3/doc/xml/manual/allocator.xml585
-rw-r--r--libstdc++-v3/doc/xml/manual/appendix_contributing.xml1805
-rw-r--r--libstdc++-v3/doc/xml/manual/appendix_free.xml178
-rw-r--r--libstdc++-v3/doc/xml/manual/appendix_porting.xml50
-rw-r--r--libstdc++-v3/doc/xml/manual/atomics.xml57
-rw-r--r--libstdc++-v3/doc/xml/manual/auto_ptr.xml134
-rw-r--r--libstdc++-v3/doc/xml/manual/backwards_compatibility.xml1282
-rw-r--r--libstdc++-v3/doc/xml/manual/bitmap_allocator.xml561
-rw-r--r--libstdc++-v3/doc/xml/manual/build_hacking.xml355
-rw-r--r--libstdc++-v3/doc/xml/manual/codecvt.xml674
-rw-r--r--libstdc++-v3/doc/xml/manual/concurrency.xml81
-rw-r--r--libstdc++-v3/doc/xml/manual/concurrency_extensions.xml333
-rw-r--r--libstdc++-v3/doc/xml/manual/configure.xml365
-rw-r--r--libstdc++-v3/doc/xml/manual/containers.xml462
-rw-r--r--libstdc++-v3/doc/xml/manual/ctype.xml221
-rw-r--r--libstdc++-v3/doc/xml/manual/debug.xml355
-rw-r--r--libstdc++-v3/doc/xml/manual/debug_mode.xml889
-rw-r--r--libstdc++-v3/doc/xml/manual/diagnostics.xml129
-rw-r--r--libstdc++-v3/doc/xml/manual/documentation_hacking.xml990
-rw-r--r--libstdc++-v3/doc/xml/manual/evolution.xml631
-rw-r--r--libstdc++-v3/doc/xml/manual/extensions.xml581
-rw-r--r--libstdc++-v3/doc/xml/manual/internals.xml549
-rw-r--r--libstdc++-v3/doc/xml/manual/intro.xml878
-rw-r--r--libstdc++-v3/doc/xml/manual/io.xml649
-rw-r--r--libstdc++-v3/doc/xml/manual/iterators.xml185
-rw-r--r--libstdc++-v3/doc/xml/manual/locale.xml618
-rw-r--r--libstdc++-v3/doc/xml/manual/localization.xml51
-rw-r--r--libstdc++-v3/doc/xml/manual/messages.xml566
-rw-r--r--libstdc++-v3/doc/xml/manual/mt_allocator.xml555
-rw-r--r--libstdc++-v3/doc/xml/manual/numerics.xml145
-rw-r--r--libstdc++-v3/doc/xml/manual/parallel_mode.xml878
-rw-r--r--libstdc++-v3/doc/xml/manual/prerequisites.xml160
-rw-r--r--libstdc++-v3/doc/xml/manual/profile_mode.xml1718
-rw-r--r--libstdc++-v3/doc/xml/manual/shared_ptr.xml543
-rw-r--r--libstdc++-v3/doc/xml/manual/spine.xml119
-rw-r--r--libstdc++-v3/doc/xml/manual/status_cxx1998.xml1164
-rw-r--r--libstdc++-v3/doc/xml/manual/status_cxx200x.xml2628
-rw-r--r--libstdc++-v3/doc/xml/manual/status_cxxtr1.xml1782
-rw-r--r--libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml299
-rw-r--r--libstdc++-v3/doc/xml/manual/strings.xml486
-rw-r--r--libstdc++-v3/doc/xml/manual/support.xml443
-rw-r--r--libstdc++-v3/doc/xml/manual/test.xml1035
-rw-r--r--libstdc++-v3/doc/xml/manual/using.xml1543
-rw-r--r--libstdc++-v3/doc/xml/manual/using_exceptions.xml548
-rw-r--r--libstdc++-v3/doc/xml/manual/utilities.xml124
-rw-r--r--libstdc++-v3/doc/xml/spine.xml162
59 files changed, 32976 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/xml/api.xml b/libstdc++-v3/doc/xml/api.xml
new file mode 100644
index 000000000..dcd88d7e3
--- /dev/null
+++ b/libstdc++-v3/doc/xml/api.xml
@@ -0,0 +1,106 @@
+<book xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+<article xml:id="api" xreflabel="API">
+<?dbhtml filename="api.html"?>
+
+<title>The GNU C++ Library API Reference</title>
+
+<info>
+ <copyright>
+ <year>
+ 2008
+ </year>
+ <year>
+ 2010
+ </year>
+ <holder>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org/">FSF
+ </link>
+ </holder>
+ </copyright>
+ <legalnotice>
+ <para>
+ <link linkend="manual.intro.status.license">License
+ </link>
+ </para>
+ </legalnotice>
+</info>
+
+<para>
+ The GNU C++ library sources have been specially formatted so that
+ with the proper invocation of another tool (Doxygen), a set of
+ indexed reference material can generated from the sources files
+ themselves. The resultant documentation is referred to as the API
+ 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 API documentation, rendered into HTML, can be viewed online:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-html-USERS-3.4/index.html">for the 3.4 release
+ </link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-html-USERS-4.1/index.html">for the 4.1 release
+ </link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-html-USERS-4.2/index.html">for the 4.2 release
+ </link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-html-USERS-4.3/index.html">for the 4.3 release
+ </link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-html-USERS-4.4/index.html">for the 4.4 release
+ </link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-api-4.5/index.html">for the 4.5 release
+ </link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html">"the latest collection"
+ </link>
+ (For the main development tree; see the date on the first page.)
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+ The rendered HTML, as above, is also available for download on the
+ gcc.org site in a directory located at
+ <literal>&lt;URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/&gt;</literal>.
+ You will almost certainly need to use one of the
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/mirrors.html">mirror sites</link> to download
+ the tarball. After unpacking, simply load libstdc++-html-*/index.html
+ into a browser.
+</para>
+
+<para>
+ In addition, a rendered set of man pages are available in the same
+ location specified above. Start with C++Intro(3).
+</para>
+
+</article>
+
+</book>
diff --git a/libstdc++-v3/doc/xml/authors.xml b/libstdc++-v3/doc/xml/authors.xml
new file mode 100644
index 000000000..1f26f63fb
--- /dev/null
+++ b/libstdc++-v3/doc/xml/authors.xml
@@ -0,0 +1,120 @@
+<authorgroup xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+<!--
+ <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><personname><firstname/><surname/></personname><personblurb>
+ <para>
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Paolo</firstname><surname>Carlini</surname></personname><personblurb>
+ <para>
+ TR1, LWG Active, Closed, Defects lists.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Phil</firstname><surname>Edwards</surname></personname><personblurb>
+ <para>
+ Originating author, started HOWTO and FAQ, worked on sections
+ Demangling, Macros, Strings, Iterators, Backwards
+ Compatibility, SGI Extensions, Configure, Build, Install.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Doug</firstname><surname>Gregor</surname></personname><personblurb>
+ <para>
+ Debug Mode, TR1 function objects
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname><personblurb>
+ <para>
+ Allocators, ABI, API evolution and deprecation history,
+ Backwards Compatibility, Thread, Debug Support, Locales,
+ Facets, Parallel Mode, Headers, Namespaces, Construction and
+ Structure, Using Exceptions, DocBook conversion and layout.
+ </para>
+ </personblurb></author>
+
+
+ <author><personname><firstname>Dhruv</firstname><surname>Matani</surname></personname><personblurb>
+ <para>
+ bitmap_allocator
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Jason</firstname><surname>Merrill</surname></personname><personblurb>
+ <para>
+ License, __verbose_terminate_handler
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Mark</firstname><surname>Mitchell</surname></personname><personblurb>
+ <para>
+ Porting
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Nathan</firstname><surname>Myers</surname></personname><personblurb>
+ <para>
+ Referenced counted string, C++1998 implementation status.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Felix</firstname><surname>Natter</surname></personname><personblurb>
+ <para>
+ Namespace composition, Backwards Compatibility.
+ </para>
+ </personblurb></author>
+
+
+ <author><personname><firstname>Stefan</firstname><surname>Olsson</surname></personname><personblurb>
+ <para>
+ mt_allocator
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Silvius</firstname><surname>Rus</surname></personname><personblurb>
+ <para>
+ Profile mode
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname><personblurb>
+ <para>
+ Parallel mode
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Ami</firstname><surname>Tavory</surname></personname><personblurb>
+ <para>
+ Policy Based Data Structures, Associative Containers, Unordered
+ Containers.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Jonathan</firstname><surname>Wakely</surname></personname><personblurb>
+ <para>
+ shared_ptr, markup editing and styling
+ </para>
+ </personblurb></author>
+
+</authorgroup>
diff --git a/libstdc++-v3/doc/xml/book.txml b/libstdc++-v3/doc/xml/book.txml
new file mode 100644
index 000000000..55b050271
--- /dev/null
+++ b/libstdc++-v3/doc/xml/book.txml
@@ -0,0 +1,30 @@
+<!-- Converted by db4-upgrade version 1.0 -->
+
+<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="api" xreflabel="Source Level Documentation">
+
+
+<info>
+ <copyright>
+ <year>2007</year>
+ <holder>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="www.fsf.org">FSF
+ </link>
+ </holder>
+ </copyright>
+ <legalnotice>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="17_intro/license.html">License
+ </link>
+ </para>
+ </legalnotice>
+</info>
+
+<part><info><title/></info>
+
+ <chapter><info><title/></info>
+
+ <para/>
+ </chapter>
+</part>
+
+</book>
diff --git a/libstdc++-v3/doc/xml/chapter.txml b/libstdc++-v3/doc/xml/chapter.txml
new file mode 100644
index 000000000..85323e73b
--- /dev/null
+++ b/libstdc++-v3/doc/xml/chapter.txml
@@ -0,0 +1,51 @@
+<!-- Converted by db4-upgrade version 1.0 -->
+
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="manual.intro" xreflabel="Introduction">
+
+<info><title>Introduction</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<section xml:id="manual.intro.status" xreflabel="Status"><info><title>Status</title></info>
+
+ <para>
+ The GNU C++ ...
+ </para>
+</section>
+
+<section xml:id="manual.intro.setup" xreflabel="Setup"><info><title>Setup</title></info>
+
+ <para>
+ The GNU C++ ...
+ </para>
+ <section xml:id="manual.intro.setup.next1" xreflabel="Next1"><info><title>Next1</title></info>
+
+ <para>
+ The GNU C++ ...
+ </para>
+ </section>
+ <section xml:id="manual.intro.setup.next2" xreflabel="Next2"><info><title>Next2</title></info>
+
+ <para>
+ The GNU C++ ...
+ </para>
+ </section>
+</section>
+
+<section xml:id="manual.intro.using" xreflabel="Using"><info><title>Using</title></info>
+
+ <para>
+ The GNU C++ ...
+ </para>
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/class.txml b/libstdc++-v3/doc/xml/class.txml
new file mode 100644
index 000000000..26c9acf97
--- /dev/null
+++ b/libstdc++-v3/doc/xml/class.txml
@@ -0,0 +1,156 @@
+<!-- Converted by db4-upgrade version 1.0 -->
+
+<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="manual.util.memory.allocator" xreflabel="allocator">
+<?dbhtml filename="allocator.html"?>
+
+<info><title>allocator</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ allocator
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+</para>
+
+<section xml:id="allocator.req" xreflabel="allocator.req"><info><title>Requirements</title></info>
+
+
+ <para>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ </para>
+</section>
+
+<section xml:id="allocator.design_issues" xreflabel="allocator.design_issues"><info><title>Design Issues</title></info>
+
+
+ <para>
+ </para>
+
+ <para>
+ </para>
+</section>
+
+<section xml:id="allocator.impl" xreflabel="allocator.impl"><info><title>Implementation</title></info>
+
+
+ <section><info><title>Interface Design</title></info>
+
+
+ <para>
+ </para>
+
+ <para>
+ </para>
+ </section>
+
+ <section><info><title>Selecting Default Allocation Strategy</title></info>
+
+
+ <para>
+ </para>
+
+ <orderedlist>
+ <listitem>
+ </listitem>
+
+ <listitem>
+ </listitem>
+
+ <listitem>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section><info><title>Disabling Memory Caching</title></info>
+
+
+ <para>
+ </para>
+
+ <para>
+ </para>
+ </section>
+</section>
+
+<section xml:id="allocator.using" xreflabel="allocator.using"><info><title>Using</title></info>
+
+
+ <para>
+ </para>
+</section>
+
+<section xml:id="allocator.custom" xreflabel="allocator.custom"><info><title>Custom Allocators</title></info>
+
+
+ <para>
+ </para>
+
+ <para>
+ </para>
+</section>
+
+<bibliography xml:id="allocator.biblio" xreflabel="allocator.biblio"><info><title>Bibliography</title></info>
+
+
+<!--
+ <biblioentry>
+ <abbrev>
+ </abbrev>
+
+ <biblioid class="uri">
+ <ulink url="http://about:blank">
+ </ulink>
+ </biblioid>
+ <citetitle>
+ The Title
+ </citetitle>
+
+ <editor>
+ <firstname></firstname>
+ <surname></surname>
+ </editor>
+
+ <author>
+ <surname></surname>
+ <firstname></firstname>
+ </author>
+
+ <copyright>
+ <year></year>
+ <holder></holder>
+ </copyright>
+ <pagenums></pagenums>
+
+ <publisher>
+ <publishername>
+ </publishername>
+ </publisher>
+
+ </biblioentry>
+-->
+
+ <biblioentry>
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml
new file mode 100644
index 000000000..05e805e90
--- /dev/null
+++ b/libstdc++-v3/doc/xml/faq.xml
@@ -0,0 +1,1246 @@
+<book xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+<article xml:id="faq" xreflabel="Frequently Asked Questions">
+<?dbhtml filename="faq.html"?>
+
+<info><title>Frequently Asked Questions</title>
+
+ <copyright>
+ <year>
+ 2008, 2010
+ </year>
+ <holder>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org">FSF</link>
+ </holder>
+ </copyright>
+</info>
+
+<!-- FAQ starts here -->
+<qandaset>
+
+<!-- General Information -->
+<qandadiv xml:id="faq.info" xreflabel="General Information">
+
+
+<qandaentry xml:id="faq.what">
+ <question xml:id="faq.what.q">
+ <para>
+ What is libstdc++?
+ </para>
+ </question>
+ <answer xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/svn.html">web</link>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.why">
+ <question xml:id="q-why">
+ <para>
+ Why should I use libstdc++?
+ </para>
+ </question>
+ <answer xml: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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/">GCC team</link>. All of
+ the rapid development and near-legendary
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/buildstat.html">portability</link>
+ 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&lt;&gt;</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 xml:id="faq.who">
+ <question xml:id="q-who">
+ <para>
+ Who's in charge of it?
+ </para>
+ </question>
+ <answer xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/libstdc++/">homepage</link>.
+ If you have questions, ideas, code, or are just curious, sign up!
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.when">
+ <question xml:id="q-when">
+ <para>
+ When is libstdc++ going to be finished?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.how">
+ <question xml:id="q-how">
+ <para>
+ How do I contribute to the effort?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.whereis_old">
+ <question xml:id="q-whereis_old">
+ <para>
+ What happened to the older libg++? I need that!
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.more_questions">
+ <question xml:id="q-more_questions">
+ <para>
+ What if I have more questions?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.license" xreflabel="License QA">
+
+
+<qandaentry xml:id="faq.license.what">
+ <question xml:id="q-license.what">
+ <para>
+ What are the license terms for libstdc++?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.license.any_program">
+ <question xml:id="q-license.any_program">
+ <para>
+ So any program which uses libstdc++ falls under the GPL?
+ </para>
+ </question>
+ <answer xml:id="a-license.any_program">
+ <para>
+ No. The special exception permits use of the library in
+ proprietary applications.
+ </para>
+ </answer>
+</qandaentry>
+
+
+<qandaentry xml:id="faq.license.lgpl">
+ <question xml:id="q-license.lgpl">
+ <para>
+ How is that different from the GNU {Lesser,Library} GPL?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.license.what_restrictions">
+ <question xml:id="q-license.what_restrictions">
+ <para>
+ I see. So, what restrictions are there on programs that use the library?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.installation" xreflabel="Installation">
+
+
+<qandaentry xml:id="faq.how_to_install">
+ <question xml:id="q-how_to_install">
+ <para>How do I install libstdc++?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.how_to_get_sources">
+ <question xml:id="q-how_to_get_sources">
+ <para>How does one get current libstdc++ sources?
+ </para>
+ </question>
+ <answer xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/mirrors.html">list of
+ download sites</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://subversion.tigris.org"> Subversion
+ home page</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/svn.html"><acronym>SVN</acronym>
+ details</link>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.how_to_test">
+ <question xml:id="q-how_to_test">
+ <para>How do I know if it works?
+ </para>
+ </question>
+ <answer xml: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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/test.html">testing
+ documentation</link> 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 xml:id="faq.how_to_set_paths">
+ <question xml:id="q-how_to_set_paths">
+ <para>How do I insure that the dynamically linked library will be found?
+ </para>
+ </question>
+ <answer xml: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>
+ <para>
+ Using LD_LIBRARY_PATH is not always the best solution, <link linkend="manual.intro.using.linkage.dynamic">Finding Dynamic or Shared
+ Libraries</link> in the manual gives some alternatives.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.what_is_libsupcxx">
+ <question xml:id="q-what_is_libsupcxx">
+ <para>
+ What's libsupc++?
+ </para>
+ </question>
+ <answer xml: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="std.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 xml:id="faq.size">
+ <question xml:id="q-size">
+ <para>
+ This library is HUGE!
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.platform-specific" xreflabel="Platform-Specific Issues">
+
+
+<qandaentry xml:id="faq.other_compilers">
+ <question xml:id="q-other_compilers">
+ <para>
+ Can libstdc++ be used with non-GNU compilers?
+ </para>
+ </question>
+ <answer xml: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 to 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 xml:id="faq.solaris_long_long">
+ <question xml:id="q-solaris_long_long">
+ <para>
+ No 'long long' type on Solaris?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.predefined">
+ <question xml:id="q-predefined">
+ <para>
+ <constant>_XOPEN_SOURCE</constant> and <constant>_GNU_SOURCE</constant> are always defined?
+ </para>
+ </question>
+ <answer xml: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 - &lt; /dev/null"</command> to display
+ a list of predefined macros for any particular installation.
+ </para>
+ <para>This has been discussed on the mailing lists
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/cgi-bin/htsearch?method=and&amp;format=builtin-long&amp;sort=score&amp;words=_XOPEN_SOURCE+Solaris">quite a bit</link>.
+ </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 xml:id="faq.darwin_ctype">
+ <question xml:id="q-darwin_ctype">
+ <para>
+ Mac OS X <filename class="headerfile">ctype.h</filename> is broken! How can I fix it?
+ </para>
+ </question>
+ <answer xml: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.
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html"> Here's a
+ link to the solution</link>.
+ </para>
+
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.threads_i386">
+ <question xml:id="q-threads_i386">
+ <para>
+ Threading is broken on i386?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.atomic_mips">
+ <question xml:id="q-atomic_mips">
+ <para>
+ MIPS atomic operations
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.linux_glibc">
+ <question xml:id="q-linux_glibc">
+ <para>
+ Recent GNU/Linux glibc required?
+ </para>
+ </question>
+ <answer xml: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 which contains necessary bugfixes.
+ Most GNU/Linux distros make more recent versions available now.
+ libstdc++ 4.6.0 and later require glibc 2.3 or later for this
+ localization and formatting code.
+ </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 xml:id="faq.freebsd_wchar">
+ <question xml:id="q-freebsd_wchar">
+ <para>
+ Can't use wchar_t/wstring on FreeBSD
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.known_bugs" xreflabel="Known Bugs">
+
+
+<qandaentry xml:id="faq.what_works">
+ <question xml:id="q-what_works">
+ <para>
+ What works already?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.standard_bugs">
+ <question xml:id="q-standard_bugs">
+ <para>
+ Bugs in the ISO C++ language or library specification
+ </para>
+ </question>
+ <answer xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/">here</link>.
+ 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 xml:id="faq.compiler_bugs">
+ <question xml:id="q-compiler_bugs">
+ <para>
+ Bugs in the compiler (gcc/g++) and not libstdc++
+ </para>
+ </question>
+ <answer xml: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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/bugs/">bugs database</link> with the
+ category set to <quote>g++</quote>.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+<!-- Known Non-Bugs -->
+<qandadiv xml:id="faq.known_non-bugs" xreflabel="Known Non-Bugs">
+
+
+<qandaentry xml:id="faq.stream_reopening_fails">
+ <question xml:id="q-stream_reopening_fails">
+ <para>
+ Reopening a stream fails
+ </para>
+ </question>
+ <answer xml:id="a-stream_reopening_fails">
+ <para>
+ One of the most-reported non-bug reports. Executing a sequence like:
+ </para>
+
+ <literallayout class="normal">
+ #include &lt;fstream&gt;
+ ...
+ 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 xml:id="faq.wefcxx_verbose">
+ <question xml:id="q-wefcxx_verbose">
+ <para>
+ -Weffc++ complains too much
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.ambiguous_overloads">
+ <question xml:id="q-ambiguous_overloads">
+ <para>
+ Ambiguous overloads after including an old-style header
+ </para>
+ </question>
+ <answer xml: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 &lt;iterator&gt; header),
+ then you will suddenly be faced with huge numbers of ambiguity
+ errors. This was discussed on the -v3 list; Nathan Myers
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums
+ things up here</link>. The collisions with vector/string iterator
+ types have been fixed for 3.1.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.v2_headers">
+ <question xml:id="q-v2_headers">
+ <para>
+ The g++-3 headers are <emphasis>not ours</emphasis>
+ </para>
+ </question>
+ <answer xml:id="a-v2_headers">
+ <para>
+ If you are using headers 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 xml:id="faq.boost_concept_checks">
+ <question xml:id="q-boost_concept_checks">
+ <para>
+ Errors about <emphasis>*Concept</emphasis> and
+ <emphasis>constraints</emphasis> in the STL
+ </para>
+ </question>
+ <answer xml: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 in the
+ <link linkend="std.diagnostics.concept_checking">Diagnostics</link>.
+ chapter of the manual.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.dlopen_crash">
+ <question xml:id="q-dlopen_crash">
+ <para>
+ Program crashes when using library code in a
+ dynamically-loaded library
+ </para>
+ </question>
+ <answer xml: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 class="normal">
+ // 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 xml:id="faq.memory_leaks">
+ <question xml:id="q-memory_leaks">
+ <para>
+ <quote>Memory leaks</quote> in containers
+ </para>
+ </question>
+ <answer xml: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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://valgrind.org/">valgrind</link>.
+ 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 xml:id="faq.list_size_on">
+ <question xml:id="q-list_size_on">
+ <para>
+ list::size() is O(n)!
+ </para>
+ </question>
+ <answer xml:id="a-list_size_on">
+ <para>
+ See
+ the <link linkend="std.containers">Containers</link>
+ chapter.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.easy_to_fix">
+ <question xml:id="q-easy_to_fix">
+ <para>
+ Aw, that's easy to fix!
+ </para>
+ </question>
+ <answer xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/contribute.html">submitting
+ patches</link> 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 testsuite -
+ but only if such a test exists.
+ </para>
+ </answer>
+</qandaentry>
+
+</qandadiv>
+
+
+<!-- Miscellaneous -->
+<qandadiv xml:id="faq.misc" xreflabel="Miscellaneous">
+
+
+<qandaentry xml:id="faq.iterator_as_pod">
+ <question xml:id="faq.iterator_as_pod_q">
+ <para>
+ string::iterator is not char*; vector&lt;T&gt;::iterator is not T*
+ </para>
+ </question>
+ <answer xml:id="faq.iterator_as_pod_a">
+ <para>
+ If you have code that depends on container&lt;T&gt; 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>&amp;*i</varname>. Future revisions
+ of the Standard are expected to bless this usage for
+ vector&lt;&gt; (but not for basic_string&lt;&gt;).
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.what_is_next">
+ <question xml:id="q-what_is_next">
+ <para>
+ What's next after libstdc++?
+ </para>
+ </question>
+ <answer xml: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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">
+ The C++ Library Technical Report 1</link>.
+ </para>
+ </answer>
+</qandaentry>
+
+<qandaentry xml:id="faq.sgi_stl">
+ <question xml:id="q-sgi_stl">
+ <para>
+ What about the STL from SGI?
+ </para>
+ </question>
+ <answer xml:id="a-sgi_stl">
+ <para>
+ The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/">STL from SGI</link>,
+ 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&lt;&gt;</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 xml:id="faq.extensions_and_backwards_compat">
+ <question xml:id="q-extensions_and_backwards_compat">
+ <para>
+ Extensions and Backward Compatibility
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.tr1_support">
+ <question xml:id="q-tr1_support">
+ <para>
+ Does libstdc++ support TR1?
+ </para>
+ </question>
+ <answer xml: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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">
+ Technical Report 1</link>.
+ </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 xml:id="faq.get_iso_cxx">
+ <question xml:id="q-get_iso_cxx">
+ <para>How do I get a copy of the ISO C++ Standard?
+ </para>
+ </question>
+ <answer xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.ansi.org">here</link>. (And if
+ you've already registered with them, clicking this link will take
+ you to directly to the place where you can
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line</link>.
+ </para>
+ <para>
+ Who is your country's member body? Visit the
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.iso.ch/">ISO homepage</link> 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 xml:id="faq.what_is_abi">
+ <question xml:id="q-what_is_abi">
+ <para>
+ What's an ABI and why is it so messy?
+ </para>
+ </question>
+ <answer xml: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 xml:id="faq.size_equals_capacity">
+ <question xml:id="q-size_equals_capacity">
+ <para>
+ How do I make std::vector&lt;T&gt;::capacity() == std::vector&lt;T&gt;::size?
+ </para>
+ </question>
+ <answer xml:id="a-size_equals_capacity">
+ <para>
+ The standard idiom for deallocating a <classname>vector&lt;T&gt;</classname>'s
+ unused memory is to create a temporary copy of the vector and swap their
+ contents, e.g. for <classname>vector&lt;T&gt; v</classname>
+ </para>
+ <literallayout class="normal">
+ std::vector&lt;T&gt;(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/libstdc++-v3/doc/xml/gnu/fdl-1.3.xml b/libstdc++-v3/doc/xml/gnu/fdl-1.3.xml
new file mode 100644
index 000000000..9500e11fe
--- /dev/null
+++ b/libstdc++-v3/doc/xml/gnu/fdl-1.3.xml
@@ -0,0 +1,562 @@
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.gfdl-1.3">
+<info><title>GNU Free Documentation License</title></info>
+ <?dbhtml filename="appendix_gfdl.html"?>
+
+ <simpara>Version 1.3, 3 November 2008</simpara>
+ <simpara>
+ Copyright © 2000, 2001, 2002, 2007, 2008
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org/">Free Software Foundation, Inc.</link>
+ </simpara>
+ <simpara>
+ Everyone is permitted to copy and distribute verbatim copies of this
+ license document, but changing it is not allowed.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section0" renderas="sect2">
+ 0. PREAMBLE
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section1" renderas="sect2">
+ 1. APPLICABILITY AND DEFINITIONS
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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”.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ The “publisher” means any person or entity that distributes
+ copies of the Document to the public.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section2" renderas="sect2">
+ 2. VERBATIM COPYING
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ You may also lend copies, under the same conditions stated above, and you
+ may publicly display copies.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section3" renderas="sect2">
+ 3. COPYING IN QUANTITY
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section4" renderas="sect2">
+ 4. MODIFICATIONS
+ </bridgehead>
+ <simpara>
+ 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:
+ </simpara>
+ <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>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section5" renderas="sect2">
+ 5. COMBINING DOCUMENTS
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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”.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section6" renderas="sect2">
+ 6. COLLECTIONS OF DOCUMENTS
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section7" renderas="sect2">
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section8" renderas="sect2">
+ 8. TRANSLATION
+ </bridgehead>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section9" renderas="sect2">
+ 9. TERMINATION
+ </bridgehead>
+ <simpara>
+ You may not copy, modify, sublicense, or distribute the Document except as
+ expressly provided under this License. Any attempt otherwise to copy,
+ modify, sublicense, or distribute it is void, and will automatically
+ terminate your rights under this License.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+ <simpara>
+ 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, receipt of a copy of some or all of the same material does not
+ give you any rights to use it.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section10" renderas="sect2">
+ 10. FUTURE REVISIONS OF THIS LICENSE
+ </bridgehead>
+ <simpara>
+ 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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/copyleft/">Copyleft</link>.
+ </simpara>
+ <simpara>
+ 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. If the Document specifies that a proxy
+ can decide which future versions of this License can be used, that
+ proxy’s public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Document.
+ </simpara>
+ <bridgehead xml:id="fdl-1-section11" renderas="sect2">
+ 11. RELICENSING
+ </bridgehead>
+ <simpara>
+ “Massive Multiauthor Collaboration Site” (or “MMC
+ Site”) means any World Wide Web server that publishes copyrightable
+ works and also provides prominent facilities for anybody to edit those
+ works. A public wiki that anybody can edit is an example of such a
+ server. A “Massive Multiauthor Collaboration” (or
+ “MMC”) contained in the site means any set of copyrightable
+ works thus published on the MMC site.
+ </simpara>
+ <simpara>
+ “CC-BY-SA” means the Creative Commons Attribution-Share Alike
+ 3.0 license published by Creative Commons Corporation, a not-for-profit
+ corporation with a principal place of business in San Francisco,
+ California, as well as future copyleft versions of that license published
+ by that same organization.
+ </simpara>
+ <simpara>
+ “Incorporate” means to publish or republish a Document, in
+ whole or in part, as part of another Document.
+ </simpara>
+ <simpara>
+ An MMC is “eligible for relicensing” if it is licensed under
+ this License, and if all works that were first published under this
+ License somewhere other than this MMC, and subsequently incorporated in
+ whole or in part into the MMC, (1) had no cover texts or invariant
+ sections, and (2) were thus incorporated prior to November 1, 2008.
+ </simpara>
+ <simpara>
+ The operator of an MMC Site may republish an MMC contained in the site
+ under CC-BY-SA on the same site at any time before August 1, 2009,
+ provided the MMC is eligible for relicensing.
+ </simpara>
+ <bridgehead xml:id="fdl-1-addendum" renderas="sect2">
+ ADDENDUM: How to use this License for your documents
+ </bridgehead>
+ <simpara>
+ 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:
+ </simpara>
+ <screen>Copyright © YEAR YOUR NAME
+
+Permission is granted to copy, distribute and/or modify this document under the
+terms of the GNU Free Documentation License, Version 1.3 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”.</screen>
+ <simpara>
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+ replace the “with… Texts.” line with this:
+ </simpara>
+ <screen>with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts
+being LIST, and with the Back-Cover Texts being LIST.</screen>
+ <simpara>
+ If you have Invariant Sections without Cover Texts, or some other
+ combination of the three, merge those two alternatives to suit the
+ situation.
+ </simpara>
+ <simpara>
+ 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.
+ </simpara>
+</appendix>
diff --git a/libstdc++-v3/doc/xml/gnu/gpl-3.0.xml b/libstdc++-v3/doc/xml/gnu/gpl-3.0.xml
new file mode 100644
index 000000000..d5a5eae20
--- /dev/null
+++ b/libstdc++-v3/doc/xml/gnu/gpl-3.0.xml
@@ -0,0 +1,834 @@
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.gpl-3.0"><info><title>
+ <acronym>GNU</acronym> General Public License version 3
+ </title></info>
+ <?dbhtml filename="appendix_gpl.html"?>
+
+ <para>
+ Version 3, 29 June 2007
+ </para>
+ <para>
+ Copyright © 2007 Free Software Foundation, Inc.
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org/">http://www.fsf.org/</link>
+ </para>
+ <para>
+ Everyone is permitted to copy and distribute verbatim copies of this license
+ document, but changing it is not allowed.
+ </para>
+ <bridgehead xml: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 xml: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 xml: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 xml: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 xml: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 xml: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 xml: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" inheritnum="ignore" continuation="restarts">
+ <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 xml: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" inheritnum="ignore" continuation="restarts">
+ <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 xml: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" inheritnum="ignore" continuation="restarts">
+ <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 xml: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 xml: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 xml: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 xml: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 xml: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 xml: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 xml: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 xml: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 xml: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 xml: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 xml: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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</link>.
+ </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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</link>.
+ </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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/philosophy/why-not-lgpl.html">http://www.gnu.org/philosophy/why-not-lgpl.html</link>.
+ </para>
+</appendix>
diff --git a/libstdc++-v3/doc/xml/images/confdeps.dot b/libstdc++-v3/doc/xml/images/confdeps.dot
new file mode 100644
index 000000000..047436eef
--- /dev/null
+++ b/libstdc++-v3/doc/xml/images/confdeps.dot
@@ -0,0 +1,16 @@
+# 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" -> "[*/]Makefile.in";
+ "[*/]Makefile.in" -> "Makefile.am";
+ "[*/]Makefile.in" -> "configure.ac";
+ "config.h" -> "config.h.in"
+ "config.h.in" -> "acconfig.h";
+ "config.h.in" -> "configure.ac";
+}
diff --git a/libstdc++-v3/doc/xml/images/confdeps.pdf b/libstdc++-v3/doc/xml/images/confdeps.pdf
new file mode 100644
index 000000000..dab5ef341
--- /dev/null
+++ b/libstdc++-v3/doc/xml/images/confdeps.pdf
Binary files differ
diff --git a/libstdc++-v3/doc/xml/images/confdeps.png b/libstdc++-v3/doc/xml/images/confdeps.png
new file mode 100644
index 000000000..55c07ba01
--- /dev/null
+++ b/libstdc++-v3/doc/xml/images/confdeps.png
Binary files differ
diff --git a/libstdc++-v3/doc/xml/manual/abi.xml b/libstdc++-v3/doc/xml/manual/abi.xml
new file mode 100644
index 000000000..6e7d46bfa
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/abi.xml
@@ -0,0 +1,1208 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.porting.abi" xreflabel="abi">
+<?dbhtml filename="abi.html"?>
+
+<info><title>ABI Policy and Guidelines</title>
+ <keywordset>
+ <keyword>
+ C++
+ </keyword>
+ <keyword>
+ ABI
+ </keyword>
+ <keyword>
+ version
+ </keyword>
+ <keyword>
+ dynamic
+ </keyword>
+ <keyword>
+ shared
+ </keyword>
+ <keyword>
+ compatibility
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+</para>
+
+<section xml:id="abi.cxx_interface"><info><title>The C++ Interface</title></info>
+
+
+<para>
+ C++ applications often depend on specific language support
+ routines, say for throwing exceptions, or catching exceptions, and
+ perhaps also depend 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.codesourcery.com/public/cxx-abi/abi.html">ABI
+ specification</link>.
+</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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options
+ for Code Generation Conventions</link>.
+</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>
+
+</section>
+
+<section xml:id="abi.versioning"><info><title>Versioning</title></info>
+
+
+<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>
+
+ <section xml:id="abi.versioning.goals"><info><title>Goals</title></info>
+
+
+<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 run 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>
+ </section>
+
+ <section xml:id="abi.versioning.history"><info><title>History</title></info>
+
+
+<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-5].x: libgcc_s.so.1</para></listitem>
+ </itemizedlist>
+
+ <para>For m68k-linux the versions differ as follows: </para>
+
+ <itemizedlist>
+ <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: libgcc_s.so.1
+ when configuring <code>--with-sjlj-exceptions</code>, or
+ libgcc_s.so.2 </para> </listitem>
+ </itemizedlist>
+
+ <para>For hppa-linux the versions differ as follows: </para>
+
+ <itemizedlist>
+ <listitem><para>gcc-3.4.x, gcc-4.[0-1].x: either libgcc_s.so.1
+ when configuring <code>--with-sjlj-exceptions</code>, or
+ libgcc_s.so.2 </para> </listitem>
+ <listitem><para>gcc-4.[2-5].x: either libgcc_s.so.3 when configuring
+ <code>--with-sjlj-exceptions</code>) or libgcc_s.so.4
+ </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 way 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.3.4: libstdc++.so.6.0.10</para></listitem>
+ <listitem><para>gcc-4.4.0: libstdc++.so.6.0.11</para></listitem>
+ <listitem><para>gcc-4.4.1: libstdc++.so.6.0.12</para></listitem>
+ <listitem><para>gcc-4.4.2: libstdc++.so.6.0.13</para></listitem>
+ <listitem><para>gcc-4.5.0: libstdc++.so.6.0.14</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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</link>
+ in the GCC bug database.
+ </para>
+ </listitem>
+
+ <listitem><para>Symbol versioning on the libstdc++.so binary.</para>
+
+ <para>mapfile: libstdc++-v3/config/abi/pre/gnu.ver</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 symbols 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>
+ <listitem><para>gcc-4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3</para></listitem>
+ <listitem><para>gcc-4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3</para></listitem>
+ <listitem><para>gcc-4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4</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-5].x: 102 (when n=1)</para></listitem>
+ <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: 1000 + n (when n&gt;1) </para></listitem>
+ <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: 999999 (when n=0)</para></listitem>
+ </itemizedlist>
+ <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-5].x: <code>-fabi-version=2</code> <emphasis>(Incompatible with previous)</emphasis></para></listitem>
+ </itemizedlist>
+ <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++-v3/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>
+ <listitem><para>gcc-4.4.1: 20090722</para></listitem>
+ <listitem><para>gcc-4.4.2: 20091015</para></listitem>
+ </itemizedlist>
+ <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++-v3/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-5].x: "version-unused"</para></listitem>
+ </itemizedlist>
+ <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++-v3/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.3.4: include/c++/4.3.4</para></listitem>
+ <listitem><para>gcc-4.4.0: include/c++/4.4.0</para></listitem>
+ <listitem><para>gcc-4.4.1: include/c++/4.4.1</para></listitem>
+ <listitem><para>gcc-4.4.2: include/c++/4.4.2</para></listitem>
+ <listitem><para>gcc-4.5.0: include/c++/4.5.0</para></listitem>
+ </itemizedlist>
+ <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>
+
+
+ </section>
+
+ <section xml:id="abi.versioning.prereq"><info><title>Prerequisites</title></info>
+
+ <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) or the Sun linker, 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, as does Solaris 2.5 and up.
+ </para>
+ </section>
+
+ <section xml:id="abi.versioning.config"><info><title>Configuring</title></info>
+
+
+ <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:
+ <link linkend="manual.intro.setup.configure">here</link>
+ </para>
+
+ <para>
+ There is one flag that explicitly deals with symbol versioning:
+ --enable-symvers.
+ </para>
+
+ <para>
+ In particular, libstdc++-v3/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>
+ </section>
+
+ <section xml:id="abi.versioning.active"><info><title>Checking Active</title></info>
+
+
+ <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>
+ or another of the supported styles.
+ 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 &lt;iostream&gt;
+
+int main()
+{ std::cout &lt;&lt; "hello" &lt;&lt; std::endl; return 0; }
+
+%g++ hello.cc -o hello.out
+
+%ldd hello.out
+ libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
+ libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
+ libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
+ libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
+ /lib/ld-linux.so.2 =&gt; /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>
+
+<para>
+On Solaris 2, you can use <code>pvs -r</code> instead:
+</para>
+
+<programlisting>
+%g++ hello.cc -o hello.out
+
+%pvs -r hello.out
+ libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12);
+ libgcc_s.so.1 (GCC_3.0);
+ libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3);
+</programlisting>
+
+<para>
+<code>ldd -v</code> works too, but is very verbose.
+</para>
+
+ </section>
+</section>
+
+<section xml:id="abi.changes_allowed"><info><title>Allowed Changes</title></info>
+
+
+<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>
+
+</section>
+
+<section xml:id="abi.changes_no"><info><title>Prohibited Changes</title></info>
+
+
+<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 passing instances of this
+class in registers, the compiler will be forced to use memory. See the
+section on <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.codesourcery.com/public/cxx-abi/abi.html#calls">Function
+Calling Conventions and APIs</link>
+ of the C++ ABI documentation for further details.
+</para></listitem>
+
+</orderedlist>
+
+</section>
+
+
+
+<section xml:id="abi.impl"><info><title>Implementation</title></info>
+
+
+<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>
+
+</section>
+
+<section xml:id="abi.testing"><info><title>Testing</title></info>
+
+
+ <section xml:id="abi.testing.single"><info><title>Single ABI Testing</title></info>
+
+
+ <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.
+ </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 of 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 PR 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>
+
+ </section>
+ <section xml:id="abi.testing.multi"><info><title>Multiple ABI Testing</title></info>
+
+<para>
+A "C" application, dynamically linked to two shared libraries, liba,
+libb. The dependent library liba is a 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 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
+ libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
+ libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
+ libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
+ /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
+
+%ldd libtwo.so.1.0.0
+ libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
+ libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
+ libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
+ libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
+ /lib/ld-linux.so.2 =&gt; /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 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
+ libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
+ libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
+ libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
+ libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
+ /lib/ld-linux.so.2 =&gt; /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>
+ </section>
+</section>
+
+<section xml:id="abi.issues"><info><title>Outstanding Issues</title></info>
+
+
+<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>
+<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</link>
+</para>
+
+<para>
+<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</link>
+</para>
+
+</section>
+
+<bibliography xml:id="abi.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://abicheck.sourceforge.net/" class="uri">
+ </biblioid>
+ <citetitle>
+ ABIcheck, a vague idea of checking ABI compatibility
+ </citetitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.codesourcery.com/public/cxx-abi/" class="uri">
+ </biblioid>
+ <citetitle>
+ C++ ABI Reference
+ </citetitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.intel.com/cd/software/products/asmo-na/eng/284736.htm" class="uri">
+ </biblioid>
+ <citetitle>
+ Intel Compilers for Linux Compatibility with the GNU Compilers
+ </citetitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://download.oracle.com/docs/cd/E19963-01/html/819-0690/index.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Linker and Libraries Guide (document 819-0690)
+ </citetitle>
+ </biblioentry>
+
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://download.oracle.com/docs/cd/E19422-01/819-3689/index.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Sun Studio 11: C++ Migration Guide (document 819-3689)
+ </citetitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://people.redhat.com/drepper/dsohowto.pdf" class="uri">
+ </biblioid>
+ <citetitle>
+ How to Write Shared Libraries
+ </citetitle>
+
+ <author>
+ <personname>
+ <firstname>Ulrich</firstname><surname>Drepper</surname>
+ </personname>
+ </author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.arm.com/miscPDFs/8033.pdf" class="uri">
+ </biblioid>
+ <citetitle>
+ C++ ABI for the ARM Architecture
+ </citetitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Dynamic Shared Objects: Survey and Issues
+ </citetitle>
+ <subtitle>
+ ISO C++ J16/06-0046
+ </subtitle>
+ <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Versioning With Namespaces
+ </citetitle>
+ <subtitle>
+ ISO C++ J16/06-0083
+ </subtitle>
+ <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://syrcose.ispras.ru/2009/files/SYRCoSE2009-CfP.pdf" class="uri">
+ </biblioid>
+ <citetitle>
+ Binary Compatibility of Shared Libraries Implemented in C++
+ on GNU/Linux Systems
+ </citetitle>
+
+ <subtitle>
+ SYRCoSE 2009
+ </subtitle>
+ <author><personname><firstname>Pavel</firstname><surname>Shved</surname></personname></author>
+ <author><personname><firstname>Denis</firstname><surname>Silakov</surname></personname></author>
+ </biblioentry>
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/algorithms.xml b/libstdc++-v3/doc/xml/manual/algorithms.xml
new file mode 100644
index 000000000..831fe5fe6
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/algorithms.xml
@@ -0,0 +1,101 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.algorithms" xreflabel="Algorithms">
+<?dbhtml filename="algorithms.html"?>
+
+<info><title>
+ Algorithms
+ <indexterm><primary>Algorithms</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ algorithm
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+ The neatest accomplishment of the algorithms sect1 is that all the
+ work is done via iterators, not containers directly. This means two
+ important things:
+</para>
+<orderedlist inheritnum="ignore" continuation="restarts">
+ <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 <link linkend="std.containers">containers sect1</link> 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
+ <link linkend="std.iterators">iterators sect1</link> 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>
+
+<!-- Sect1 01 : Non Modifying -->
+
+<!-- Sect1 02 : Mutating -->
+<section xml:id="std.algorithms.mutating" xreflabel="Mutating"><info><title>Mutating</title></info>
+
+
+ <section xml:id="algorithms.mutating.swap" xreflabel="swap"><info><title><function>swap</function></title></info>
+
+
+ <section xml:id="algorithms.swap.specializations" xreflabel="Specializations"><info><title>Specializations</title></info>
+
+
+ <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>
+
+ </section>
+ </section>
+</section>
+
+<!-- Sect1 03 : Sorting -->
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/allocator.xml b/libstdc++-v3/doc/xml/manual/allocator.xml
new file mode 100644
index 000000000..b73554eb9
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/allocator.xml
@@ -0,0 +1,585 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.util.memory.allocator" xreflabel="Allocator">
+<?dbhtml filename="allocator.html"?>
+
+<info><title>Allocators</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ allocator
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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>
+
+<section xml:id="allocator.req"><info><title>Requirements</title></info>
+
+
+ <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&lt;T&gt;</classname>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The interface of the <classname>allocator&lt;T&gt;</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 can be found in the C++ standard, look in
+ <constant>[20.4 Memory]</constant>.
+ </para>
+
+</section>
+
+<section xml:id="allocator.design_issues"><info><title>Design Issues</title></info>
+
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</link>
+ 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&lt;int&gt;</classname> gets
+ cut in half and frees a bunch of its storage, that memory can be
+ reused by the private
+ <classname>std::list&lt;WonkyWidget&gt;</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>
+
+</section>
+
+<section xml:id="allocator.impl"><info><title>Implementation</title></info>
+
+
+ <section><info><title>Interface Design</title></info>
+
+
+ <para>
+ The only allocator interface that
+ is supported 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>
+
+ </section>
+
+ <section><info><title>Selecting Default Allocation Policy</title></info>
+
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup">sequence</link>
+ and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup">associative</link>
+ 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 per-thread basis, as well as measuring thread contention
+ for memory resources.
+ Test source
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup">here</link>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A threaded producer/consumer model.
+ </para>
+ <para>
+ Test source for
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup">sequence</link>
+ and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup">associative</link>
+ containers.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ The current default choice for
+ <classname>allocator</classname> is
+ <classname>__gnu_cxx::new_allocator</classname>.
+ </para>
+
+ </section>
+
+ <section><info><title>Disabling Memory Caching</title></info>
+
+
+ <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>
+
+ </section>
+
+</section>
+
+<section xml:id="allocator.using"><info><title>Using a Specific Allocator</title></info>
+
+
+ <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 &lt;int, __gnu_cxx::malloc_allocator&lt;int&gt; &gt; malloc_list;</programlisting>
+ <para>
+ Likewise, a debugging form of whichever allocator is currently in use:
+ </para>
+ <programlisting>
+ std::deque &lt;int, __gnu_cxx::debug_allocator&lt;std::allocator&lt;int&gt; &gt; &gt; debug_deque;
+ </programlisting>
+</section>
+
+<section xml:id="allocator.custom"><info><title>Custom Allocators</title></info>
+
+
+ <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>
+
+</section>
+
+<section xml:id="allocator.ext"><info><title>Extension Allocators</title></info>
+
+
+ <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&lt;true,0&gt; normal;
+ typedef __pool_alloc&lt;true,1&gt; private;
+ typedef __pool_alloc&lt;true,42&gt; 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 thread-safe, while <varname>thr</varname> =
+ <constant>false</constant>, 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>
+</section>
+
+
+<bibliography xml:id="allocator.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 14882:1998 Programming languages - C++
+ </citetitle>
+ <abbrev>
+ isoc++_1998
+ </abbrev>
+ <pagenums>20.4 Memory</pagenums>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.drdobbs.com/cpp/184403759" class="uri">
+ </biblioid>
+ <citetitle>
+ The Standard Librarian: What Are Allocators Good For?
+ </citetitle>
+
+ <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author>
+ <publisher>
+ <publishername>
+ C/C++ Users Journal
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cs.umass.edu/~emery/hoard/" class="uri">
+ </biblioid>
+ <citetitle>
+ The Hoard Memory Allocator
+ </citetitle>
+
+ <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf" class="uri">
+ </biblioid>
+ <citetitle>
+ Reconsidering Custom Memory Allocation
+ </citetitle>
+
+ <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author>
+ <author><personname><firstname>Ben</firstname><surname>Zorn</surname></personname></author>
+ <author><personname><firstname>Kathryn</firstname><surname>McKinley</surname></personname></author>
+ <copyright>
+ <year>2002</year>
+ <holder>OOPSLA</holder>
+ </copyright>
+ </biblioentry>
+
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Allocator Types
+ </citetitle>
+
+ <author><personname><firstname>Klaus</firstname><surname>Kreft</surname></personname></author>
+ <author><personname><firstname>Angelika</firstname><surname>Langer</surname></personname></author>
+ <publisher>
+ <publishername>
+ C/C++ Users Journal
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>The C++ Programming Language</citetitle>
+ <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder/>
+ </copyright>
+ <pagenums>19.4 Allocators</pagenums>
+ <publisher>
+ <publishername>
+ Addison Wesley
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>Yalloc: A Recycling C++ Allocator</citetitle>
+ <author><personname><firstname>Felix</firstname><surname>Yen</surname></personname></author>
+ </biblioentry>
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
new file mode 100644
index 000000000..49cbcab9b
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
@@ -0,0 +1,1805 @@
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.contrib" xreflabel="Contributing">
+<?dbhtml filename="appendix_contributing.html"?>
+
+<info><title>
+ Contributing
+ <indexterm>
+ <primary>Appendix</primary>
+ <secondary>Contributing</secondary>
+ </indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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>
+
+<section xml:id="contrib.list" xreflabel="Contributor Checklist"><info><title>Contributor Checklist</title></info>
+
+
+ <section xml:id="list.reading"><info><title>Reading</title></info>
+
+
+ <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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.ansi.org">here.</link>
+ (And if you've already registered with them, clicking this link will take you to directly to the place where you can
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line</link>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The library working group bugs, and known defects, can
+ be obtained here:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </link>
+ </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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.comeaucomputing.com/csc/faq.html">
+ here </link>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Peruse
+ the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/prep/standards">GNU
+ Coding Standards</link>, 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>
+
+ </section>
+ <section xml:id="list.copyright"><info><title>Assignment</title></info>
+
+ <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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal
+ Matters</link>.
+ </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>
+ </section>
+
+ <section xml:id="list.getting"><info><title>Getting Sources</title></info>
+
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/svnwrite.html">Getting write access
+ (look for "Write after approval")</link>
+ </para>
+ </section>
+
+ <section xml:id="list.patches"><info><title>Submitting Patches</title></info>
+
+
+ <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 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/wiki/SvnTricks">SVN
+ Tricks</link> 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>
+
+ </section>
+
+</section>
+
+<section xml:id="contrib.organization" xreflabel="Source Organization"><info><title>Directory Layout and Source Conventions</title></info>
+ <?dbhtml filename="source_organization.html"?>
+
+
+ <para>
+ The unpacked source directory of libstdc++ contains the files
+ needed to create the GNU C++ Library.
+ </para>
+
+ <literallayout class="normal">
+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 &lt;name&gt; 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 &lt;iostream.h&gt;.
+ 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>
+
+</section>
+
+<section xml:id="contrib.coding_style" xreflabel="Coding Style"><info><title>Coding Style</title></info>
+ <?dbhtml filename="source_code_style.html"?>
+
+ <para>
+ </para>
+ <section xml:id="coding_style.bad_identifiers"><info><title>Bad Identifiers</title></info>
+
+ <para>
+ Identifiers that conflict and should be avoided.
+ </para>
+
+ <literallayout class="normal">
+ 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>
+ </section>
+
+ <section xml:id="coding_style.example"><info><title>By Example</title></info>
+
+ <literallayout class="normal">
+ 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:
+
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/prep/standards/standards.html#Formatting">http://www.gnu.org/prep/standards/standards.html#Formatting</link>
+
+ The rest of this is also interesting reading, but skip the "Design
+ Advice" part.
+
+ The GCC coding conventions are here, and are also useful:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/codingconventions.html">http://gcc.gnu.org/codingconventions.html</link>
+
+ In addition, because it doesn't seem to be stated explicitly anywhere
+ else, there is an 80 column source limit.
+
+ <filename>ChangeLog</filename> entries for member functions should use the
+ classname::member function name syntax as follows:
+
+<code>
+1999-04-15 Dennis Ritchie &lt;dr@att.com&gt;
+
+ * src/basic_file.cc (__basic_file::open): Fix thinko in
+ _G_HAVE_IO_FILE_OPEN bits.
+</code>
+
+ Notable areas of divergence from what may be previous local practice
+ (particularly for GNU C) include:
+
+ 01. Pointers and references
+ <code>
+ char* p = "flop";
+ char&amp; c = *p;
+ -NOT-
+ char *p = "flop"; // wrong
+ char &amp;c = *p; // wrong
+ </code>
+
+ Reason: In C++, definitions are mixed with executable code. Here,
+ <code>p</code> is being initialized, not <code>*p</code>. 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
+ <code>
+ operator==(type)
+ -NOT-
+ operator == (type) // wrong
+ </code>
+
+ Reason: The <code>==</code> is part of the function name. Separating
+ it makes the declaration look like an expression.
+
+ 03. Function names and parentheses
+ <code>
+ void mangle()
+ -NOT-
+ void mangle () // wrong
+ </code>
+
+ 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
+ <code>
+ template&lt;typename T&gt;
+ void
+ template_function(args)
+ { }
+ -NOT-
+ template&lt;class T&gt;
+ void template_function(args) {};
+ </code>
+
+ 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".) <code>T</code> often could be <code>int</code>, which is
+ not a class. ("class", here, is an anachronism.)
+
+ 05. Template class indentation
+ <code>
+ template&lt;typename _CharT, typename _Traits&gt;
+ class basic_ios : public ios_base
+ {
+ public:
+ // Types:
+ };
+ -NOT-
+ template&lt;class _CharT, class _Traits&gt;
+ class basic_ios : public ios_base
+ {
+ public:
+ // Types:
+ };
+ -NOT-
+ template&lt;class _CharT, class _Traits&gt;
+ class basic_ios : public ios_base
+ {
+ public:
+ // Types:
+ };
+ </code>
+
+ 06. Enumerators
+ <code>
+ enum
+ {
+ space = _ISspace,
+ print = _ISprint,
+ cntrl = _IScntrl
+ };
+ -NOT-
+ enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
+ </code>
+
+ 07. Member initialization lists
+ All one line, separate from class name.
+
+ <code>
+ 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)
+ { }
+ </code>
+
+ 08. Try/Catch blocks
+ <code>
+ try
+ {
+ //
+ }
+ catch (...)
+ {
+ //
+ }
+ -NOT-
+ try {
+ //
+ } catch(...) {
+ //
+ }
+ </code>
+
+ 09. Member functions declarations and definitions
+ Keywords such as extern, static, export, explicit, inline, etc
+ go on the line above the function name. Thus
+
+ <code>
+ virtual int
+ foo()
+ -NOT-
+ virtual int foo()
+ </code>
+
+ 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-&gt;"
+ For non-uglified names, use <code>this-&gt;name</code> to call the function.
+
+ <code>
+ this-&gt;sync()
+ -NOT-
+ sync()
+ </code>
+
+ Reason: Koenig lookup.
+
+ 11. Namespaces
+ <code>
+ namespace std
+ {
+ blah blah blah;
+ } // namespace std
+
+ -NOT-
+
+ namespace std {
+ blah blah blah;
+ } // namespace std
+ </code>
+
+ 12. Spacing under protected and private in class declarations:
+ space above, none below
+ i.e.
+
+ <code>
+ public:
+ int foo;
+
+ -NOT-
+ public:
+
+ int foo;
+ </code>
+
+ 13. Spacing WRT return statements.
+ no extra spacing before returns, no parenthesis
+ i.e.
+
+ <code>
+ }
+ return __ret;
+
+ -NOT-
+ }
+
+ return __ret;
+
+ -NOT-
+
+ }
+ return (__ret);
+ </code>
+
+
+ 14. Location of global variables.
+ All global variables of class type, whether in the "user visible"
+ space (e.g., <code>cin</code>) 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 <filename>src/globals.cc</filename>. All such
+ variables should be contained in that file, for simplicity.
+
+ 15. Exception abstractions
+ Use the exception abstractions found in <filename class="headerfile">functexcept.h</filename>, which allow
+ C++ programmers to use this library with <literal>-fno-exceptions</literal>. (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:
+
+ <code>
+ __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
+ </code>
+
+ Reason: The verbose terminate handler prints out <code>exception::what()</code>,
+ 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: <literal>__[a-z].*</literal>
+
+ Examples: <code>__count __ix __s1</code>
+
+ Type names and template formal-argument names: <literal>_[A-Z][^_].*</literal>
+
+ Examples: <code>_Helper _CharT _N</code>
+
+ Member data and function names: <literal>_M_.*</literal>
+
+ Examples: <code>_M_num_elements _M_initialize ()</code>
+
+ Static data members, constants, and enumerations: <literal>_S_.*</literal>
+
+ Examples: <code>_S_max_elements _S_default_value</code>
+
+ 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]
+ <code>
+
+ #ifndef _HEADER_
+ #define _HEADER_ 1
+
+ namespace std
+ {
+ class gribble
+ {
+ public:
+ gribble() throw();
+
+ gribble(const gribble&amp;);
+
+ explicit
+ gribble(int __howmany);
+
+ gribble&amp;
+ operator=(const gribble&amp;);
+
+ 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&lt;typename _Formal_argument&gt;
+ void
+ public_template() const throw();
+
+ template&lt;typename _Iterator&gt;
+ 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&lt;typename T&gt; // notice: "typename", not "class", no space
+ long_return_value_type&lt;with_many, args&gt;
+ function_name(char* pointer, // "char *pointer" is wrong.
+ char* argument,
+ const Reference&amp; 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 &lt;&lt;= 1) {
+ // ...
+ }
+ }
+
+ gribble::gribble()
+ : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
+ { }
+
+ int
+ gribble::three_lines()
+ {
+ // doesn't fit in one line.
+ }
+ } // namespace std
+ </code>
+ </literallayout>
+ </section>
+</section>
+
+<section xml:id="contrib.design_notes" xreflabel="Design Notes"><info><title>Design Notes</title></info>
+ <?dbhtml filename="source_design_notes.html"?>
+
+ <para>
+ </para>
+
+ <literallayout class="normal">
+
+ 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
+ &lt;string&gt;, we might have:
+
+ template &lt;class _CharT, ... &gt; class basic_string {
+ ... // member declarations
+ };
+ ... // operator declarations
+
+ #ifdef _STRICT_ISO_
+ # if _G_NO_TEMPLATE_EXPORT
+ # include &lt;bits/std_locale.h&gt; // headers needed by definitions
+ # ...
+ # include &lt;bits/string.tcc&gt; // 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 &amp; 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 &lt;string&gt; 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&lt;T*&gt;, 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.org/ 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
+ &lt;http://www.cantrip.org/cheaders.html&gt;). 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&lt;&gt; 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: &lt;limits&gt; &lt;new&gt; &lt;typeinfo&gt; &lt;exception&gt;
+ C headers: &lt;cstddef&gt; &lt;climits&gt; &lt;cfloat&gt; &lt;cstdarg&gt; &lt;csetjmp&gt;
+ &lt;ctime&gt; &lt;csignal&gt; &lt;cstdlib&gt; (also 21, 25, 26)
+
+ This defines the built-in exceptions, rtti, numeric_limits&lt;&gt;,
+ operator new and delete. Much of this is provided by the
+ compiler in its static runtime library.
+
+ Work to do includes defining numeric_limits&lt;&gt; 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
+ &lt;limits.h&gt;, 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.
+
+ &lt;cstdarg&gt;, 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: &lt;stdexcept&gt;
+ C headers: &lt;cassert&gt; &lt;cerrno&gt;
+
+ 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: &lt;utility&gt; &lt;functional&gt; &lt;memory&gt;
+ C header: &lt;ctime&gt; (also in 18)
+
+ SGI STL provides "mostly complete" versions of all the components
+ defined in this chapter. However, the auto_ptr&lt;&gt; 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&lt;&gt; 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: &lt;string&gt;
+ C headers: &lt;cctype&gt; &lt;cwctype&gt; &lt;cstring&gt; &lt;cwchar&gt; (also in 27)
+ &lt;cstdlib&gt; (also in 18, 25, 26)
+
+ We have "mostly-complete" char_traits&lt;&gt; implementations. Many of the
+ char_traits&lt;char&gt; operations might be optimized further using existing
+ proprietary language extensions.
+
+ We have a "mostly-complete" basic_string&lt;&gt; 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 &lt;cwchar&gt; and used in char_traits&lt;&gt;
+ 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&lt;&gt; 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&lt;&gt; 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 &lt;cstring&gt; are different from the C version.
+ generally overloaded on const and non-const argument pointers. For
+ example, in &lt;cstring&gt; strchr is overloaded. The functions isupper
+ etc. in &lt;cctype&gt; typically implemented as macros in C are functions
+ in C++, because they are overloaded with others of the same name
+ defined in &lt;locale&gt;.
+
+ Many of the functions required in &lt;cwctype&gt; and &lt;cwchar&gt; cannot be
+ implemented using underlying C facilities on intended targets because
+ such facilities only partly exist.
+
+ Chapter 22 Locale
+ ------------------
+ Headers: &lt;locale&gt;
+ C headers: &lt;clocale&gt;
+
+ 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 &lt;locale&gt; 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&lt;&gt;, collate&lt;&gt;,
+ and numpunct&lt;&gt; 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&lt;&gt;::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&lt;wchar_t,char,mbstate_t&gt; 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&lt;&gt;, numpunct&lt;&gt;, num_put&lt;&gt;, and num_get&lt;&gt; facets
+ are used by other library facilities defined in &lt;string&gt;, &lt;istream&gt;,
+ and &lt;ostream&gt;, and the codecvt&lt;&gt; facet is used by basic_filebuf&lt;&gt;
+ in &lt;fstream&gt;, 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&lt;&gt; and num_get&lt;&gt; 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&lt;&lt; would be prohibitively slow. To cache format
+ data for use by num_put&lt;&gt; and num_get&lt;&gt; we have a _Format_cache&lt;&gt;
+ 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: &lt;deque&gt; &lt;list&gt; &lt;queue&gt; &lt;stack&gt; &lt;vector&gt; &lt;map&gt; &lt;set&gt; &lt;bitset&gt;
+
+ 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: &lt;iterator&gt;
+
+ 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&lt;&gt; 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: &lt;algorithm&gt;
+ C headers: &lt;cstdlib&gt; (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: &lt;complex&gt; &lt;valarray&gt; &lt;numeric&gt;
+ C headers: &lt;cmath&gt;, &lt;cstdlib&gt; (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: &lt;iosfwd&gt; &lt;streambuf&gt; &lt;ios&gt; &lt;ostream&gt; &lt;istream&gt; &lt;iostream&gt;
+ &lt;iomanip&gt; &lt;sstream&gt; &lt;fstream&gt;
+ C headers: &lt;cstdio&gt; &lt;cwchar&gt; (also in 21)
+
+ Iostream is currently in a very incomplete state. &lt;iosfwd&gt;, &lt;iomanip&gt;,
+ ios_base, and basic_ios&lt;&gt; are "mostly complete". basic_streambuf&lt;&gt; and
+ basic_ostream&lt;&gt; are well along, but basic_istream&lt;&gt; has had little work
+ done. The standard stream objects, &lt;sstream&gt; and &lt;fstream&gt; have been
+ started; basic_filebuf&lt;&gt; "write" functions have been implemented just
+ enough to do "hello, world".
+
+ Most of the istream and ostream operators &lt;&lt; and &gt;&gt; (with the exception
+ of the op&lt;&lt;(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 &lt;&lt; and &gt;&gt;) can take advantage
+ of the case where user code has not specified a locale, and bypass locale
+ operations entirely. The current implementation of op&lt;&lt;/num_put&lt;&gt;::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 &lt;sstream&gt; header work has begun. stringbuf can benefit from
+ friendship with basic_string&lt;&gt; and basic_string&lt;&gt;::_Rep to use
+ those objects directly as buffers, and avoid allocating and making
+ copies.
+
+ The basic_filebuf&lt;&gt; template is a complex beast. It is specified to
+ use the locale facet codecvt&lt;&gt; 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&lt;&gt; 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&lt;char&gt;, 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 &lt;cstdio&gt; 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: &lt;strstream&gt;
+
+ 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 &lt;strstream&gt;
+ 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: &lt;iostream.h&gt; &lt;strstream.h&gt; &lt;hash&gt; &lt;rbtree&gt;
+ &lt;pthread_alloc&gt; &lt;stdiobuf&gt; (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
+ &lt;iostream.h&gt;, &lt;strstream.h&gt;, and various SGI extensions such
+ as &lt;hash_map.h&gt;. Many of these are already placed in the
+ subdirectories ext/ and backward/. (Note that it is better to
+ include them via "&lt;backward/hash_map.h&gt;" or "&lt;ext/hash_map&gt;" than
+ to search the subdirectory itself via a "-I" directive.
+ </literallayout>
+</section>
+
+</appendix>
diff --git a/libstdc++-v3/doc/xml/manual/appendix_free.xml b/libstdc++-v3/doc/xml/manual/appendix_free.xml
new file mode 100644
index 000000000..86d503c94
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/appendix_free.xml
@@ -0,0 +1,178 @@
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.free" xreflabel="Free">
+<?dbhtml filename="appendix_free.html"?>
+
+<info><title>
+ Free Software Needs Free Documentation
+ <indexterm>
+ <primary>Appendix</primary>
+ <secondary>Free Documentation</secondary>
+ </indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/doc/doc.html">sells printed copies</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org/licensing/doc/other-free-books.html">web page
+that lists free books available from other publishers</link>].
+</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/libstdc++-v3/doc/xml/manual/appendix_porting.xml b/libstdc++-v3/doc/xml/manual/appendix_porting.xml
new file mode 100644
index 000000000..68f3f435d
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/appendix_porting.xml
@@ -0,0 +1,50 @@
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.porting" xreflabel="Porting">
+<?dbhtml filename="appendix_porting.html"?>
+
+<info><title>
+ Porting and Maintenance
+ <indexterm>
+ <primary>Appendix</primary>
+ <secondary>Porting and Maintenance</secondary>
+ </indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+ <!-- Hacking the Build System -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="build_hacking.xml">
+ </xi:include>
+
+ <!-- Hacking the Documentation Systems -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="documentation_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>
+
+ <!-- Test -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="test.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/libstdc++-v3/doc/xml/manual/atomics.xml b/libstdc++-v3/doc/xml/manual/atomics.xml
new file mode 100644
index 000000000..ddeea0185
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/atomics.xml
@@ -0,0 +1,57 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.atomics" xreflabel="Atomics">
+<?dbhtml filename="atomics.html"?>
+
+<info><title>
+ Atomics
+ <indexterm><primary>Atomics</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ atomic
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+ Facilities for atomic operations.
+</para>
+
+<!-- Sect1 01 : API -->
+<section xml:id="std.atomics.api"><info><title>API Reference</title></info>
+
+
+ <para>
+ All items are declared in the standard header
+ file <filename>atomic</filename>.
+ </para>
+
+ <para>
+ Set of typedefs that map <type>int</type> to
+ <classname>atomic_int</classname>, and so on for all builtin
+ integral types. Global enumeration <type>memory_order</type> to
+ control memory ordering. Also includes
+ <classname>atomic</classname>, a class template with member
+ functions such as <function>load</function> and
+ <function>store</function> that is instantiable such that
+ <classname>atomic_int</classname> is the base class of
+ <classname>atomic&lt;int&gt;</classname>.
+ </para>
+
+ <para>
+ Full API details.
+ </para>
+
+ <!-- Doxygen XML: api/group__atomics.xml -->
+
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/auto_ptr.xml b/libstdc++-v3/doc/xml/manual/auto_ptr.xml
new file mode 100644
index 000000000..f62d8f472
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/auto_ptr.xml
@@ -0,0 +1,134 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.util.memory.auto_ptr" xreflabel="auto_ptr">
+<?dbhtml filename="auto_ptr.html"?>
+
+<info><title>auto_ptr</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ auto_ptr
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<section xml:id="auto_ptr.limitations"><info><title>Limitations</title></info>
+
+
+ <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&lt;MyClass&gt; 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>
+</section>
+
+<section xml:id="auto_ptr.using"><info><title>Use in Containers</title></info>
+
+
+ <para>
+ </para>
+ <para>All of the <link linkend="std.containers">containers</link>
+ 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&amp;);
+ };
+ </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
+ <link linkend="manual.ext.compile_checks">concept checks</link> built
+ in to this implementation will issue an error if you try to
+ compile code like this:
+ </para>
+ <programlisting>
+ #include &lt;vector&gt;
+ #include &lt;memory&gt;
+
+ void f()
+ {
+ std::vector&lt; std::auto_ptr&lt;int&gt; &gt; vec_ap_int;
+ }
+ </programlisting>
+ <para>
+Should you try this with the checks enabled, you will see an error.
+ </para>
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
new file mode 100644
index 000000000..1f7348a0e
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
@@ -0,0 +1,1282 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.appendix.porting.backwards" xreflabel="backwards">
+<?dbhtml filename="backwards.html"?>
+
+<info><title>Backwards Compatibility</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ backwards
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<section xml:id="backwards.first"><info><title>First</title></info>
+
+
+<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&lt;T&gt;</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>
+
+<section><info><title>No <code>ios_base</code></title></info>
+
+
+<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>
+</section>
+
+<section><info><title>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></title></info>
+
+
+<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/extensions.html">GCC extensions
+page</link> describes where to find the last libg++ source. The code is
+considered replaced and rewritten.
+</para>
+</section>
+</section>
+
+<section xml:id="backwards.second"><info><title>Second</title></info>
+
+
+<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>
+
+<section><info><title>Namespace <code>std::</code> not supported</title></info>
+
+
+ <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 &lt;luc@spaceroots.org&gt;
+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 &lt;iostream&gt;
+ std::istream&amp; 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>
+</section>
+
+<section><info><title>Illegal iterator usage</title></info>
+
+<para>
+ The following illustrate implementation-allowed illegal iterator
+ use, and then correct use.
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+ you cannot do <code>ostream::operator&lt;&lt;(iterator)</code>
+ to print the address of the iterator =&gt; use
+ <code>operator&lt;&lt; &amp;*iterator</code> instead
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ you cannot clear an iterator's reference (<code>iterator =
+ 0</code>) =&gt; use <code>iterator = iterator_type();</code>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code>if (iterator)</code> won't work any more =&gt; use
+ <code>if (iterator != iterator_type())</code>
+ </para>
+ </listitem>
+</itemizedlist>
+</section>
+
+<section><info><title><code>isspace</code> from <filename class="headerfile">cctype</filename> is a macro
+ </title></info>
+
+
+ <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 &lt;cctype&gt;
+int main() { std::isspace('X'); }
+</programlisting>
+
+<para>
+ Results in something like this:
+</para>
+
+<programlisting>
+std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (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>&lt;cctype&gt;</code>).
+</para>
+</section>
+
+<section><info><title>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></title></info>
+
+
+<para>
+ One solution is to add an autoconf-test for this:
+</para>
+
+<programlisting>
+AC_MSG_CHECKING(for container::at)
+AC_TRY_COMPILE(
+[
+#include &lt;vector&gt;
+#include &lt;deque&gt;
+#include &lt;string&gt;
+
+using namespace std;
+],
+[
+deque&lt;int&gt; test_deque(3);
+test_deque.at(2);
+vector&lt;int&gt; 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>
+
+</section>
+
+<section><info><title>No <code>std::char_traits&lt;char&gt;::eof</code></title></info>
+
+
+<para>
+ Use some kind of autoconf test, plus this:
+</para>
+
+<programlisting>
+#ifdef HAVE_CHAR_TRAITS
+#define CPP_EOF std::char_traits&lt;char&gt;::eof()
+#else
+#define CPP_EOF EOF
+#endif
+</programlisting>
+
+</section>
+
+<section><info><title>No <code>string::clear</code></title></info>
+
+
+<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-&gt;size(), 0); }
+</programlisting>
+
+<programlisting>
+basic_string&amp;
+erase(size_type __pos = 0, size_type __n = npos)
+{
+ return this-&gt;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>
+</section>
+
+<section><info><title>
+ Removal of <code>ostream::form</code> and <code>istream::scan</code>
+ extensions
+</title></info>
+
+
+<para>
+ These are no longer supported. Please use stringstreams instead.
+</para>
+</section>
+
+<section><info><title>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></title></info>
+
+
+<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 &lt;sstream&gt;
+#else
+# include &lt;strstream&gt;
+#endif
+
+#ifdef HAVE_SSTREAM
+ std::ostringstream oss;
+#else
+ std::ostrstream oss;
+#endif
+
+oss &lt;&lt; <quote>Name=</quote> &lt;&lt; m_name &lt;&lt; <quote>, number=</quote> &lt;&lt; m_number &lt;&lt; std::endl;
+...
+#ifndef HAVE_SSTREAM
+ oss &lt;&lt; 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 &gt;&gt; i;
+</programlisting>
+
+<para> One (the only?) restriction is that an istrstream cannot be re-filled:
+</para>
+
+<programlisting>
+std::istringstream iss(numerator);
+iss &gt;&gt; m_num;
+// this is not possible with istrstream
+iss.clear();
+iss.str(denominator);
+iss &gt;&gt; m_den;
+</programlisting>
+
+<para>
+If you don't care about speed, you can put these conversions in
+ a template-function:
+</para>
+<programlisting>
+template &lt;class X&gt;
+void fromString(const string&amp; input, X&amp; any)
+{
+#ifdef HAVE_SSTREAM
+std::istringstream iss(input);
+#else
+std::istrstream iss(input.c_str());
+#endif
+X temp;
+iss &gt;&gt; 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>
+</section>
+
+<section><info><title>Little or no wide character support</title></info>
+
+ <para>
+ Classes <classname>wstring</classname> and
+ <classname>char_traits&lt;wchar_t&gt;</classname> are
+ not supported.
+ </para>
+</section>
+
+<section><info><title>No templatized iostreams</title></info>
+
+ <para>
+ Classes <classname>wfilebuf</classname> and
+ <classname>wstringstream</classname> are not supported.
+ </para>
+</section>
+
+<section><info><title>Thread safety issues</title></info>
+
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">same
+ definition that SGI</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
+ six situations involving threads</link> for the 3.0
+ release series.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
+ This message</link> 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>
+</section>
+
+</section>
+
+<section xml:id="backwards.third"><info><title>Third</title></info>
+
+
+<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 <link linkend="contrib.design_notes">design document</link>.
+ </para>
+
+<para>Portability notes and known implementation limitations are as follows.</para>
+
+<section><info><title>Pre-ISO headers moved to backwards or removed</title></info>
+
+
+<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item
+ [27.4]</link>.
+ </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 &lt;new.h&gt;
+ #include &lt;iterator.h&gt;
+ #include &lt;alloc.h&gt;
+ #include &lt;set.h&gt;
+ #include &lt;hashtable.h&gt;
+ #include &lt;hash_set.h&gt;
+ #include &lt;fstream.h&gt;
+ #include &lt;tempbuf.h&gt;
+ #include &lt;istream.h&gt;
+ #include &lt;bvector.h&gt;
+ #include &lt;stack.h&gt;
+ #include &lt;rope.h&gt;
+ #include &lt;complex.h&gt;
+ #include &lt;ostream.h&gt;
+ #include &lt;heap.h&gt;
+ #include &lt;iostream.h&gt;
+ #include &lt;function.h&gt;
+ #include &lt;multimap.h&gt;
+ #include &lt;pair.h&gt;
+ #include &lt;stream.h&gt;
+ #include &lt;iomanip.h&gt;
+ #include &lt;slist.h&gt;
+ #include &lt;tree.h&gt;
+ #include &lt;vector.h&gt;
+ #include &lt;deque.h&gt;
+ #include &lt;multiset.h&gt;
+ #include &lt;list.h&gt;
+ #include &lt;map.h&gt;
+ #include &lt;algobase.h&gt;
+ #include &lt;hash_map.h&gt;
+ #include &lt;algo.h&gt;
+ #include &lt;queue.h&gt;
+ #include &lt;streambuf.h&gt;
+ ],,
+ 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>
+</section>
+
+<section><info><title>Extension headers hash_map, hash_set moved to ext or backwards</title></info>
+
+
+ <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__ &lt; 3
+ #include &lt;hash_map.h&gt;
+ namespace extension { using ::hash_map; }; // inherit globals
+ #else
+ #include &lt;backward/hash_map&gt;
+ #if __GNUC__ == 3 &amp;&amp; __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&lt;int,int&gt; 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 &lt;ext/hash_map&gt;], [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 &lt;ext/hash_set&gt;], [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>
+</section>
+
+<section><info><title>No <code>ios::nocreate/ios::noreplace</code>.
+</title></info>
+
+
+<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>
+</section>
+
+<section><info><title>
+No <code>stream::attach(int fd)</code>
+</title></info>
+
+
+<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&lt;..&gt;</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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00074.html"><code>__gnu_cxx::stdio_filebuf</code></link>.
+ 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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.josuttis.com/cppcode/fdstream.html">fdstream example</link>
+ by Nicolai Josuttis.
+</para>
+</section>
+
+<section><info><title>
+Support for C++98 dialect.
+</title></info>
+
+
+<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 &lt;cassert&gt;
+ #include &lt;cctype&gt;
+ #include &lt;cerrno&gt;
+ #include &lt;cfloat&gt;
+ #include &lt;ciso646&gt;
+ #include &lt;climits&gt;
+ #include &lt;clocale&gt;
+ #include &lt;cmath&gt;
+ #include &lt;csetjmp&gt;
+ #include &lt;csignal&gt;
+ #include &lt;cstdarg&gt;
+ #include &lt;cstddef&gt;
+ #include &lt;cstdio&gt;
+ #include &lt;cstdlib&gt;
+ #include &lt;cstring&gt;
+ #include &lt;ctime&gt;
+
+ #include &lt;algorithm&gt;
+ #include &lt;bitset&gt;
+ #include &lt;complex&gt;
+ #include &lt;deque&gt;
+ #include &lt;exception&gt;
+ #include &lt;fstream&gt;
+ #include &lt;functional&gt;
+ #include &lt;iomanip&gt;
+ #include &lt;ios&gt;
+ #include &lt;iosfwd&gt;
+ #include &lt;iostream&gt;
+ #include &lt;istream&gt;
+ #include &lt;iterator&gt;
+ #include &lt;limits&gt;
+ #include &lt;list&gt;
+ #include &lt;locale&gt;
+ #include &lt;map&gt;
+ #include &lt;memory&gt;
+ #include &lt;new&gt;
+ #include &lt;numeric&gt;
+ #include &lt;ostream&gt;
+ #include &lt;queue&gt;
+ #include &lt;set&gt;
+ #include &lt;sstream&gt;
+ #include &lt;stack&gt;
+ #include &lt;stdexcept&gt;
+ #include &lt;streambuf&gt;
+ #include &lt;string&gt;
+ #include &lt;typeinfo&gt;
+ #include &lt;utility&gt;
+ #include &lt;valarray&gt;
+ #include &lt;vector&gt;
+ ],,
+ 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>
+</section>
+
+<section><info><title>
+Support for C++TR1 dialect.
+</title></info>
+
+
+<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 &lt;tr1/array&gt;
+ #include &lt;tr1/ccomplex&gt;
+ #include &lt;tr1/cctype&gt;
+ #include &lt;tr1/cfenv&gt;
+ #include &lt;tr1/cfloat&gt;
+ #include &lt;tr1/cinttypes&gt;
+ #include &lt;tr1/climits&gt;
+ #include &lt;tr1/cmath&gt;
+ #include &lt;tr1/complex&gt;
+ #include &lt;tr1/cstdarg&gt;
+ #include &lt;tr1/cstdbool&gt;
+ #include &lt;tr1/cstdint&gt;
+ #include &lt;tr1/cstdio&gt;
+ #include &lt;tr1/cstdlib&gt;
+ #include &lt;tr1/ctgmath&gt;
+ #include &lt;tr1/ctime&gt;
+ #include &lt;tr1/cwchar&gt;
+ #include &lt;tr1/cwctype&gt;
+ #include &lt;tr1/functional&gt;
+ #include &lt;tr1/memory&gt;
+ #include &lt;tr1/random&gt;
+ #include &lt;tr1/regex&gt;
+ #include &lt;tr1/tuple&gt;
+ #include &lt;tr1/type_traits&gt;
+ #include &lt;tr1/unordered_set&gt;
+ #include &lt;tr1/unordered_map&gt;
+ #include &lt;tr1/utility&gt;
+ ],,
+ 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 &lt;unordered_map&gt; and &lt;unordered_set&gt;.
+</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 &lt;tr1/unordered_map&gt;], [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 &lt;tr1/unordered_set&gt;], [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>
+</section>
+
+
+<section><info><title>
+Support for C++0x dialect.
+</title></info>
+
+
+<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 &lt;typename T&gt;
+ struct check
+ {
+ static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
+ };
+
+ typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;
+
+ int a;
+ decltype(a) b;
+
+ typedef check&lt;int&gt; check_type;
+ check_type c;
+ check_type&amp;&amp; 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 &lt;typename T&gt;
+ struct check
+ {
+ static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
+ };
+
+ typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;
+
+ int a;
+ decltype(a) b;
+
+ typedef check&lt;int&gt; check_type;
+ check_type c;
+ check_type&amp;&amp; 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 &lt;typename T&gt;
+ struct check
+ {
+ static_assert(sizeof(int) &lt;= sizeof(T), "not big enough");
+ };
+
+ typedef check&lt;check&lt;bool&gt;&gt; right_angle_brackets;
+
+ int a;
+ decltype(a) b;
+
+ typedef check&lt;int&gt; check_type;
+ check_type c;
+ check_type&amp;&amp; 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 &lt;cassert&gt;
+ #include &lt;ccomplex&gt;
+ #include &lt;cctype&gt;
+ #include &lt;cerrno&gt;
+ #include &lt;cfenv&gt;
+ #include &lt;cfloat&gt;
+ #include &lt;cinttypes&gt;
+ #include &lt;ciso646&gt;
+ #include &lt;climits&gt;
+ #include &lt;clocale&gt;
+ #include &lt;cmath&gt;
+ #include &lt;csetjmp&gt;
+ #include &lt;csignal&gt;
+ #include &lt;cstdarg&gt;
+ #include &lt;cstdbool&gt;
+ #include &lt;cstddef&gt;
+ #include &lt;cstdint&gt;
+ #include &lt;cstdio&gt;
+ #include &lt;cstdlib&gt;
+ #include &lt;cstring&gt;
+ #include &lt;ctgmath&gt;
+ #include &lt;ctime&gt;
+ #include &lt;cwchar&gt;
+ #include &lt;cwctype&gt;
+
+ #include &lt;algorithm&gt;
+ #include &lt;array&gt;
+ #include &lt;bitset&gt;
+ #include &lt;complex&gt;
+ #include &lt;deque&gt;
+ #include &lt;exception&gt;
+ #include &lt;fstream&gt;
+ #include &lt;functional&gt;
+ #include &lt;iomanip&gt;
+ #include &lt;ios&gt;
+ #include &lt;iosfwd&gt;
+ #include &lt;iostream&gt;
+ #include &lt;istream&gt;
+ #include &lt;iterator&gt;
+ #include &lt;limits&gt;
+ #include &lt;list&gt;
+ #include &lt;locale&gt;
+ #include &lt;map&gt;
+ #include &lt;memory&gt;
+ #include &lt;new&gt;
+ #include &lt;numeric&gt;
+ #include &lt;ostream&gt;
+ #include &lt;queue&gt;
+ #include &lt;random&gt;
+ #include &lt;regex&gt;
+ #include &lt;set&gt;
+ #include &lt;sstream&gt;
+ #include &lt;stack&gt;
+ #include &lt;stdexcept&gt;
+ #include &lt;streambuf&gt;
+ #include &lt;string&gt;
+ #include &lt;tuple&gt;
+ #include &lt;typeinfo&gt;
+ #include &lt;type_traits&gt;
+ #include &lt;unordered_map&gt;
+ #include &lt;unordered_set&gt;
+ #include &lt;utility&gt;
+ #include &lt;valarray&gt;
+ #include &lt;vector&gt;
+ ],,
+ 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 &lt;unordered_map&gt;
+</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 &lt;unordered_map&gt;], [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 &lt;unordered_set&gt;], [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>
+</section>
+
+<section><info><title>
+ Container::iterator_type is not necessarily Container::value_type*
+</title></info>
+
+
+<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>
+</section>
+
+</section>
+
+<bibliography xml:id="backwards.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.kegel.com/gcc/gcc4.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Migrating to GCC 4.1
+ </citetitle>
+
+ <author><personname><firstname>Dan</firstname><surname>Kegel</surname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://lists.debian.org/debian-gcc/2006/03/msg00405.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Building the Whole Debian Archive with GCC 4.1: A Summary
+ </citetitle>
+
+ <author><personname><firstname>Martin</firstname><surname>Michlmayr</surname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Migration guide for GCC-3.2
+ </citetitle>
+
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml b/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml
new file mode 100644
index 000000000..19b190661
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/bitmap_allocator.xml
@@ -0,0 +1,561 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.ext.allocator.bitmap" xreflabel="bitmap_allocator">
+<?dbhtml filename="bitmap_allocator.html"?>
+
+<info><title>bitmap_allocator</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ allocator
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+</para>
+
+<section xml:id="allocator.bitmap.design"><info><title>Design</title></info>
+
+
+ <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>
+
+</section>
+
+<section xml:id="allocator.bitmap.impl"><info><title>Implementation</title></info>
+
+
+<section xml:id="bitmap.impl.free_list_store" xreflabel="Free List Store"><info><title>Free List Store</title></info>
+
+
+ <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 &gt; _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 &gt; _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>
+</section>
+
+<section xml:id="bitmap.impl.super_block" xreflabel="Super Block"><info><title>Super Block</title></info>
+
+
+ <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>
+</section>
+
+<section xml:id="bitmap.impl.super_block_data" xreflabel="Super Block Data"><info><title>Super Block Data Layout</title></info>
+
+ <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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+
+<tbody>
+ <row>
+ <entry>268</entry>
+ <entry>0</entry>
+ <entry>4294967295</entry>
+ <entry>4294967295</entry>
+ <entry>Data -&gt; 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>
+</section>
+
+<section xml:id="bitmap.impl.max_wasted" xreflabel="Max Wasted Percentage"><info><title>Maximum Wasted Percentage</title></info>
+
+
+ <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>
+
+</section>
+
+<section xml:id="bitmap.impl.allocate" xreflabel="Allocate"><info><title><function>allocate</function></title></info>
+
+
+ <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>
+
+</section>
+
+<section xml:id="bitmap.impl.deallocate" xreflabel="Deallocate"><info><title><function>deallocate</function></title></info>
+
+ <para>
+ The deallocate function again is specialized for single objects ONLY.
+ For all n belonging to &gt; 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>
+</section>
+
+<section xml:id="bitmap.impl.questions" xreflabel="Questions"><info><title>Questions</title></info>
+
+
+ <section xml:id="bitmap.impl.question.1" xreflabel="Question 1"><info><title>1</title></info>
+
+ <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>
+ </section>
+
+ <section xml:id="bitmap.impl.question.2" xreflabel="Question 2"><info><title>2</title></info>
+
+ <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>
+ </section>
+
+ <section xml:id="bitmap.impl.question.3" xreflabel="Question 3"><info><title>3</title></info>
+
+ <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>
+ </section>
+</section>
+
+<section xml:id="bitmap.impl.locality" xreflabel="Locality"><info><title>Locality</title></info>
+
+ <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>
+</section>
+
+<section xml:id="bitmap.impl.grow_policy" xreflabel="Grow Policy"><info><title>Overhead and Grow Policy</title></info>
+
+ <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>
+</section>
+
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml b/libstdc++-v3/doc/xml/manual/build_hacking.xml
new file mode 100644
index 000000000..945ef4996
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml
@@ -0,0 +1,355 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.porting.build_hacking" xreflabel="Build Hacking">
+<?dbhtml filename="build_hacking.html"?>
+
+<info><title>Configure and Build Hacking</title>
+ <keywordset>
+ <keyword>
+ C++
+ </keyword>
+ <keyword>
+ BUILD_HACKING
+ </keyword>
+ <keyword>
+ version
+ </keyword>
+ <keyword>
+ dynamic
+ </keyword>
+ <keyword>
+ shared
+ </keyword>
+ </keywordset>
+</info>
+
+<section xml:id="build_hacking.prereq"><info><title>Prerequisites</title></info>
+
+ <para>
+ As noted <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/prerequisites.html">previously</link>,
+ 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>
+</section>
+
+<section xml:id="build_hacking.map"><info><title>Overview: What Comes from Where</title></info>
+
+
+ <figure>
+ <title>Configure and Build File Dependencies</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="PDF" fileref="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.pdf"/>
+ </imageobject>
+ <imageobject>
+ <imagedata align="center" format="PNG" fileref="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.png"/>
+ </imageobject>
+ <textobject>
+ <phrase>Dependency Graph for Configure and Build Files</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <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.11 &amp;&amp; autoconf-2.64 &amp;&amp;
+ autoheader-2.64 &amp;&amp; automake-1.11"</code> The version
+ numbers may be absent entirely or otherwise vary depending on
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/prerequisites.html">the
+ current requirements</link> and your vendor's choice of
+ installation names.
+ </para>
+</section>
+
+<section xml:id="build_hacking.scripts"><info><title>Storing Information in non-AC files (like configure.host)</title></info>
+
+
+ <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>
+</section>
+
+<section xml:id="build_hacking.conventions"><info><title>Coding and Commenting Conventions</title></info>
+
+
+ <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>
+</section>
+
+<section xml:id="build_hacking.acinclude"><info><title>The acinclude.m4 layout</title></info>
+
+ <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>
+
+</section>
+
+<section xml:id="build_hacking.enable"><info><title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title></info>
+
+
+ <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>[@&lt;:@=BAR@:&gt;@]</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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs"><emphasis>quadrigraphs</emphasis></link>
+ 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>
+
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/codecvt.xml b/libstdc++-v3/doc/xml/manual/codecvt.xml
new file mode 100644
index 000000000..39a95aace
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/codecvt.xml
@@ -0,0 +1,674 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.localization.facet.codecvt" xreflabel="codecvt">
+<?dbhtml filename="codecvt.html"?>
+
+<info><title>codecvt</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ codecvt
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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>
+
+<section xml:id="facet.codecvt.req"><info><title>Requirements</title></info>
+
+
+<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&lt;internT,externT,stateT&gt; 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&lt;wchar_t,char,mbstate_t&gt; and
+codecvt&lt;char,char,mbstate_t&gt;, convert the implementation-defined
+native character set. codecvt&lt;char,char,mbstate_t&gt; implements a
+degenerate conversion; it does not convert at
+all. codecvt&lt;wchar_t,char,mbstate_t&gt; 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>
+</section>
+
+<section xml:id="facet.codecvt.design"><info><title>Design</title></info>
+
+
+<section xml:id="codecvt.design.wchar_t_size"><info><title><type>wchar_t</type> Size</title></info>
+
+
+ <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>
+ </section>
+
+<section xml:id="codecvt.design.unicode"><info><title>Support for Unicode</title></info>
+
+ <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>
+</section>
+
+<section xml:id="codecvt.design.issues"><info><title>Other Issues</title></info>
+
+<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&lt;wchar_t, char, mbstate_t&gt;
+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&lt;wchar_t, char, mbstate_t&gt; ,
+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>
+
+</section>
+
+</section>
+
+<section xml:id="facet.codecvt.impl"><info><title>Implementation</title></info>
+
+
+<para>
+The two required specializations are implemented as follows:
+</para>
+
+<para>
+<code>
+codecvt&lt;char, char, mbstate_t&gt;
+</code>
+</para>
+<para>
+This is a degenerate (i.e., does nothing) specialization. Implementing
+this was a piece of cake.
+</para>
+
+<para>
+<code>
+codecvt&lt;char, wchar_t, mbstate_t&gt;
+</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&amp;)
+</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&lt;internal character type,
+external character type, encoding_state&gt; is consistent with other
+codecvt usage.
+</para>
+
+</section>
+
+<section xml:id="facet.codecvt.use"><info><title>Use</title></info>
+
+<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&lt;int_type, ext_type, state_type&gt; 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&lt;unicode_codecvt&gt;(loc) );
+ const unicode_codecvt&amp; cvt = use_facet&lt;unicode_codecvt&gt;(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>
+
+</section>
+
+<section xml:id="facet.codecvt.future"><info><title>Future</title></info>
+
+<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>
+</section>
+
+
+<bibliography xml:id="facet.codecvt.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <citetitle>
+ The GNU C Library
+ </citetitle>
+ <author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2007</year>
+ <holder>FSF</holder>
+ </copyright>
+ <pagenums>
+ Chapters 6 Character Set Handling and 7 Locales and Internationalization
+ </pagenums>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Correspondence
+ </citetitle>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2002</year>
+ <holder/>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 14882:1998 Programming languages - C++
+ </citetitle>
+ <copyright>
+ <year>1998</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 9899:1999 Programming languages - C
+ </citetitle>
+ <copyright>
+ <year>1999</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opengroup.org/austin/" class="uri">
+ </biblioid>
+ <citetitle>
+ System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
+ </citetitle>
+ <copyright>
+ <year>2008</year>
+ <holder>
+ The Open Group/The Institute of Electrical and Electronics
+ Engineers, Inc.
+ </holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ The C++ Programming Language, Special Edition
+ </citetitle>
+ <author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley, Inc.</holder>
+ </copyright>
+ <pagenums>Appendix D</pagenums>
+ <publisher>
+ <publishername>
+ Addison Wesley
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+
+ <biblioentry>
+ <citetitle>
+ Standard C++ IOStreams and Locales
+ </citetitle>
+ <subtitle>
+ Advanced Programmer's Guide and Reference
+ </subtitle>
+ <author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author>
+ <author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley Longman, Inc.</holder>
+ </copyright>
+ <publisher>
+ <publishername>
+ Addison Wesley Longman
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.lysator.liu.se/c/na1.html" class="uri">
+ </biblioid>
+ <citetitle>
+ A brief description of Normative Addendum 1
+ </citetitle>
+
+ <author><personname><surname>Feather</surname><firstname>Clive</firstname></personname></author>
+ <pagenums>Extended Character Sets</pagenums>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tldp.org/HOWTO/Unicode-HOWTO.html" class="uri">
+ </biblioid>
+ <citetitle>
+ The Unicode HOWTO
+ </citetitle>
+
+ <author><personname><surname>Haible</surname><firstname>Bruno</firstname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cl.cam.ac.uk/~mgk25/unicode.html" class="uri">
+ </biblioid>
+ <citetitle>
+ UTF-8 and Unicode FAQ for Unix/Linux
+ </citetitle>
+
+ <author><personname><surname>Khun</surname><firstname>Markus</firstname></personname></author>
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/concurrency.xml b/libstdc++-v3/doc/xml/manual/concurrency.xml
new file mode 100644
index 000000000..e3dd9b946
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/concurrency.xml
@@ -0,0 +1,81 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.concurrency" xreflabel="Concurrency">
+<?dbhtml filename="concurrency.html"?>
+
+<info><title>
+ Concurrency
+ <indexterm><primary>Concurrency</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ mutex
+ </keyword>
+ <keyword>
+ thread
+ </keyword>
+ <keyword>
+ future
+ </keyword>
+ <keyword>
+ condition_variable
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+ Facilities for concurrent operation, and control thereof.
+</para>
+
+
+<!-- Sect1 01 : API -->
+<section xml:id="std.concurrency.api"><info><title>API Reference</title></info>
+
+
+ <para>
+ All items are declared in one of four standard header files.
+ </para>
+
+ <para>
+ In header <filename>mutex</filename>, class
+ template <classname>mutex</classname> and variants,
+ class <classname>once_flag</classname>, and class
+ template <classname>unique_lock</classname>.
+ </para>
+
+ <para>
+ In header <filename>condition_variable</filename>,
+ classes <classname>condition_variable</classname>
+ and <classname>condition_variable_any</classname>.
+ </para>
+
+ <para>
+ In header <filename>thread</filename>,
+ class <classname>thread</classname> and
+ namespace <code>this_thread</code>.
+ </para>
+
+ <para>
+ In header <filename>future</filename>, class
+ template <classname>future</classname> and class
+ template <classname>shared_future</classname>, class
+ template <classname>promise</classname>,
+ and <classname>packaged_task</classname>.
+ </para>
+
+ <para>
+ Full API details.
+ </para>
+
+ <!-- Doxygen XML: api/group__concurrency.xml -->
+
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml b/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml
new file mode 100644
index 000000000..9092c8def
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml
@@ -0,0 +1,333 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.ext.concurrency" xreflabel="Concurrency Extensions">
+<?dbhtml filename="ext_concurrency.html"?>
+
+<info><title>Concurrency</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<section xml:id="manual.ext.concurrency.design" xreflabel="Design"><info><title>Design</title></info>
+
+
+ <section xml:id="manual.ext.concurrency.design.threads" xreflabel="Threads API"><info><title>Interface to Locks and Mutexes</title></info>
+
+
+<para>The file &lt;ext/concurrence.h&gt; 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>
+ </section>
+
+ <section xml:id="manual.ext.concurrency.design.atomics" xreflabel="Atomic API"><info><title>Interface to Atomic Functions</title></info>
+
+
+
+<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
+&lt;ext/atomicity.h&gt;, 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>
+ </section>
+
+</section>
+
+
+<section xml:id="manual.ext.concurrency.impl" xreflabel="Implementation"><info><title>Implementation</title></info>
+
+ <section xml:id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"><info><title>Using Builtin Atomic Functions</title></info>
+
+
+<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</link>.
+</para>
+
+<para> More details on the library fallbacks from the porting <link linkend="internals.thread_safety">section</link>.
+</para>
+
+
+ </section>
+ <section xml:id="manual.ext.concurrency.impl.thread" xreflabel="Pthread"><info><title>Thread Abstraction</title></info>
+
+
+<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 &lt;gthr-default.h&gt; points to the deduced wrapper for
+the current host. In libstdc++ implementation files,
+&lt;bits/gthr.h&gt; 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00883_source.html">documentation</link>.
+</para>
+
+<para>By design, the gthread layer is interoperable with the types,
+functions, and usage found in the usual &lt;pthread.h&gt; file,
+including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
+etc.
+</para>
+
+ </section>
+</section>
+
+<section xml:id="manual.ext.concurrency.use" xreflabel="Use"><info><title>Use</title></info>
+
+
+
+<para>Typical usage of the last two constructs is demonstrated as follows:
+</para>
+
+<programlisting>
+#include &lt;ext/concurrence.h&gt;
+
+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 &lt; max; ++i)
+ {
+ _Safe_iterator_base* __old = __iter;
+ __iter = __iter-&lt;_M_next;
+ __old-&lt;_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>
+
+
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/configure.xml b/libstdc++-v3/doc/xml/manual/configure.xml
new file mode 100644
index 000000000..6b1efa800
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/configure.xml
@@ -0,0 +1,365 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.setup.configure" xreflabel="Configuring">
+<?dbhtml filename="configure.html"?>
+
+<info><title>Configure</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ configure
+ </keyword>
+ <keyword>
+ options
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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. -->
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/autobook/autobook/autobook_14.html">they
+ all have opposite forms as well</link> (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=</literal><filename class="directory">dirname</filename> during configuration.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term><code>--with-gxx-include-dir=&lt;include-files dir&gt;</code></term>
+ <listitem><para>Adds support for named libstdc++ include directory. For instance,
+ the following puts all the libstdc++ headers into a directory
+ called "4.4-20090404" instead of the usual
+ "c++/(version)".
+ </para>
+ <programlisting>
+ --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404</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).
+ </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'. This option can change the library ABI.
+ </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).
+ </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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sources.redhat.com/glibc/">glibc</link>, the GNU C
+ library), or 'generic' to use a generic "C"
+ abstraction which consists of "C" locale info.
+ </para>
+
+ <para>If not explicitly specified, the configure proccess tries
+ to guess the most suitable package from the choices above. The
+ default is 'generic'. On glibc-based systems of sufficient
+ vintage (2.3 and newer), 'gnu' is automatically selected. This option
+ can change the library ABI.
+ </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).
+ </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.
+ See this page for more information on allocator
+ <link linkend="allocator.ext">extensions</link>. This option
+ can change the library ABI.
+ </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).
+ </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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/configure.html">compiler
+ configuration instructions</link>. This option can change the
+ library ABI.
+ </para>
+ </listitem></varlistentry>
+
+
+ <varlistentry><term><code>--enable-libstdcxx-time</code></term>
+ <listitem><para>This is an abbreviated form of
+ <code>'--enable-libstdcxx-time=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>
+
+ <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., &lt;cmath&gt; not &lt;math.h&gt;)
+ 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="std.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',
+ 'darwin-export', and 'sun'. 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>--enable-extern-template</code>[default]</term>
+ <listitem><para>Use extern template to pre-instantiate all required
+ specializations for certain types defined in the standard libraries.
+ These types include <classname>string</classname> and dependents like
+ <classname>char_traits</classname>, the templateized io classes,
+ <classname>allocator</classname>, and others.
+ Disabling means that implicit
+ template generation will be used when compiling these types. By
+ default, this option is on. This option can change the library ABI.
+ </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>
+
+</variablelist>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/containers.xml b/libstdc++-v3/doc/xml/manual/containers.xml
new file mode 100644
index 000000000..377b1a2ee
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/containers.xml
@@ -0,0 +1,462 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.containers" xreflabel="Containers">
+<?dbhtml filename="containers.html"?>
+
+<info><title>
+ Containers
+ <indexterm><primary>Containers</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<!-- Sect1 01 : Sequences -->
+<section xml:id="std.containers.sequences" xreflabel="Sequences"><info><title>Sequences</title></info>
+<?dbhtml filename="sequences.html"?>
+
+
+<section xml:id="containers.sequences.list" xreflabel="list"><info><title>list</title></info>
+<?dbhtml filename="list.html"?>
+
+ <section xml:id="sequences.list.size" xreflabel="list::size() is O(n)"><info><title>list::size() is O(n)</title></info>
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</link>:
+ </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>
+ </section>
+</section>
+
+<section xml:id="containers.sequences.vector" xreflabel="vector"><info><title>vector</title></info>
+<?dbhtml filename="vector.html"?>
+
+ <para>
+ </para>
+ <section xml:id="sequences.vector.management" xreflabel="Space Overhead Management"><info><title>Space Overhead Management</title></info>
+
+ <para>
+ In <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this
+ message to the list</link>, 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html">here</link>
+ and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html">here</link>.
+ </para>
+
+ </section></section>
+</section>
+
+<!-- Sect1 02 : Associative -->
+<section xml:id="std.containers.associative" xreflabel="Associative"><info><title>Associative</title></info>
+<?dbhtml filename="associative.html"?>
+
+
+ <section xml:id="containers.associative.insert_hints" xreflabel="Insertion Hints"><info><title>Insertion Hints</title></info>
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html">N1780</link>.
+ 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>&lt;</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 before <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>
+ </section>
+
+
+ <section xml:id="containers.associative.bitset" xreflabel="bitset"><info><title>bitset</title></info>
+ <?dbhtml filename="bitset.html"?>
+
+ <section xml:id="associative.bitset.size_variable" xreflabel="Variable"><info><title>Size Variable</title></info>
+
+ <para>
+ No, you cannot write code of the form
+ </para>
+ <!-- Careful, the leading spaces in PRE show up directly. -->
+ <programlisting>
+ #include &lt;bitset&gt;
+
+ void foo (size_t n)
+ {
+ std::bitset&lt;n&gt; 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 chaptericular order:
+ </para>
+ <itemizedlist>
+ <listitem><para>A very large N in <code>bitset&lt;N&gt;</code>.</para></listitem>
+ <listitem><para>A container&lt;bool&gt;.</para></listitem>
+ <listitem><para>Extremely weird solutions.</para></listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>A very large N in
+ <code>bitset&lt;N&gt;</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&lt;bool&gt;.  </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&lt;char&gt;</code> or
+ <code>Container&lt;short int&gt;</code>. Specifically,
+ <code>vector&lt;bool&gt;</code> is required to be specialized for
+ that space savings.
+ </para>
+ <para>
+ The problem is that <code>vector&lt;bool&gt;</code> doesn't
+ behave like a normal vector anymore. There have been
+ 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&lt;bool&gt;</code>
+ specialization. In the meantime, <code>deque&lt;bool&gt;</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&lt;N&gt;</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
+ <link linkend="manual.ext.containers.sgi">some extensions</link>.
+ </para>
+
+ </section>
+ <section xml:id="associative.bitset.type_string" xreflabel="Type String"><info><title>Type String</title></info>
+
+ <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&lt;5&gt; b ( std::string(<quote>10110</quote>) );
+ </programlisting>
+
+ <para>
+ instead of
+ </para>
+
+ <programlisting>
+ std::bitset&lt;5&gt; b ( <quote>10110</quote> ); // invalid
+ </programlisting>
+ </section>
+ </section>
+
+</section>
+
+<!-- Sect1 03 : Interacting with C -->
+<section xml:id="std.containers.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
+<?dbhtml filename="containers_and_c.html"?>
+
+
+ <section xml:id="containers.c.vs_array" xreflabel="Containers vs. Arrays"><info><title>Containers vs. Arrays</title></info>
+
+ <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 <link linkend="iterators.predefined.end">past-the-end</link> 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>
+
+<programlisting>
+// beginof
+template&lt;typename T&gt;
+ inline typename vector&lt;T&gt;::iterator
+ beginof(vector&lt;T&gt; &amp;v)
+ { return v.begin(); }
+
+template&lt;typename T, unsigned int sz&gt;
+ inline T*
+ beginof(T (&amp;array)[sz]) { return array; }
+
+// endof
+template&lt;typename T&gt;
+ inline typename vector&lt;T&gt;::iterator
+ endof(vector&lt;T&gt; &amp;v)
+ { return v.end(); }
+
+template&lt;typename T, unsigned int sz&gt;
+ inline T*
+ endof(T (&amp;array)[sz]) { return array + sz; }
+
+// lengthof
+template&lt;typename T&gt;
+ inline typename vector&lt;T&gt;::size_type
+ lengthof(vector&lt;T&gt; &amp;v)
+ { return v.size(); }
+
+template&lt;typename T, unsigned int sz&gt;
+ inline unsigned int
+ lengthof(T (&amp;)[sz]) { return sz; }
+</programlisting>
+
+ <para>
+ Astute readers will notice two things at once: first, that the
+ container class is still a <code>vector&lt;T&gt;</code> instead
+ of a more general <code>Container&lt;T&gt;</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 (&amp;)[sz]) { return sz; }
+ </programlisting>
+ <para>
+ looks just weird! Hint: unused parameters can be left nameless.
+ </para>
+ </section>
+
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/ctype.xml b/libstdc++-v3/doc/xml/manual/ctype.xml
new file mode 100644
index 000000000..afca9be54
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/ctype.xml
@@ -0,0 +1,221 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.localization.facet.ctype" xreflabel="ctype">
+<?dbhtml filename="ctype.html"?>
+
+<info><title>ctype</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ ctype
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<section xml:id="facet.ctype.impl"><info><title>Implementation</title></info>
+
+
+ <section><info><title>Specializations</title></info>
+
+
+<para>
+For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; ,
+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&lt;char&gt;
+</code>
+</para>
+<para>
+This is simple specialization. Implementing this was a piece of cake.
+</para>
+
+<para>
+<code>
+ctype&lt;wchar_t&gt;
+</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>
+
+ </section>
+</section>
+
+<section xml:id="facet.ctype.future"><info><title>Future</title></info>
+
+
+
+<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&lt;wchar_t&gt;::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&lt;wchar_t&gt;
+ </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>
+
+
+</section>
+
+
+<bibliography xml:id="facet.ctype.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <citetitle>
+ The GNU C Library
+ </citetitle>
+ <author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2007</year>
+ <holder>FSF</holder>
+ </copyright>
+ <pagenums>Chapters 6 Character Set Handling and 7 Locales and Internationalization</pagenums>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Correspondence
+ </citetitle>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2002</year>
+ <holder/>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 14882:1998 Programming languages - C++
+ </citetitle>
+ <copyright>
+ <year>1998</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 9899:1999 Programming languages - C
+ </citetitle>
+ <copyright>
+ <year>1999</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.unix.org/version3/ieee_std.html" class="uri">
+ </biblioid>
+ <citetitle>
+ The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004)
+ </citetitle>
+
+ <copyright>
+ <year>1999</year>
+ <holder>
+ The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ The C++ Programming Language, Special Edition
+ </citetitle>
+ <author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley, Inc.</holder>
+ </copyright>
+ <pagenums>Appendix D</pagenums>
+ <publisher>
+ <publishername>
+ Addison Wesley
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Standard C++ IOStreams and Locales
+ </citetitle>
+ <subtitle>
+ Advanced Programmer's Guide and Reference
+ </subtitle>
+ <author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author>
+ <author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley Longman, Inc.</holder>
+ </copyright>
+ <publisher>
+ <publishername>
+ Addison Wesley Longman
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml
new file mode 100644
index 000000000..05994ec17
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/debug.xml
@@ -0,0 +1,355 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.using.debug" xreflabel="Debugging Support">
+<?dbhtml filename="debug.html"?>
+
+<info><title>Debugging Support</title>
+ <keywordset>
+ <keyword>
+ C++
+ </keyword>
+ <keyword>
+ debug
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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>
+
+<section xml:id="debug.compiler"><info><title>Using <command>g++</command></title></info>
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options
+ for Debugging Your Program"</link> in Using the GNU Compiler
+ Collection (GCC) for a complete list.
+</para>
+</section>
+
+<section xml:id="debug.req"><info><title>Debug Versions of Library Binary Files</title></info>
+
+
+<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>
+</section>
+
+<section xml:id="debug.memory"><info><title>Memory Leak Hunting</title></info>
+
+
+<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 &lt;cstdlib&gt;
+
+ 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,
+ &amp;__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>
+
+</section>
+
+<section xml:id="debug.races"><info><title>Data Race Hunting</title></info>
+<para>
+ All synchronization primitives used in the library internals need to be
+ understood by race detectors so that they do not produce false reports.
+</para>
+
+<para>
+ Two annotation macros are used to explain low-level synchronization
+ to race detectors:
+ <code>_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and
+ <code> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>.
+ By default, these macros are defined empty -- anyone who wants
+ to use a race detector needs to redefine them to call an
+ appropriate API.
+ Since these macros are empty by default when the library is built,
+ redefining them will only affect inline functions and template
+ instantiations which are compiled in user code. This allows annotation
+ of templates such as <code>shared_ptr</code>, but not code which is
+ only instantiated in the library.
+ In order to annotate <code>basic_string</code> reference counting it
+ is necessary to disable extern templates (by defining
+ <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or to rebuild the
+ <code>.so</code> file.
+ Annotating the remaining atomic operations (at the time of writing these
+ are in <code>ios_base::Init::~Init</code>, <code>locale::_Impl</code> and
+ <code>locale::facet</code>) requires rebuilding the <code>.so</code> file.
+</para>
+
+<para>
+ The approach described above is known to work with the following race
+ detection tools:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://valgrind.org/docs/manual/drd-manual.html">
+ DRD</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://valgrind.org/docs/manual/hg-manual.html">
+ Helgrind</link>, and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://code.google.com/p/data-race-test">
+ ThreadSanitizer</link>.
+</para>
+
+<para>
+ With DRD, Helgrind and ThreadSanitizer you will need to define
+ the macros like this:
+<programlisting>
+ #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A)
+ #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A)
+</programlisting>
+ Refer to the documentation of each particular tool for details.
+</para>
+
+</section>
+
+<section xml:id="debug.gdb"><info><title>Using <command>gdb</command></title></info>
+
+ <para>
+ </para>
+
+<para>
+ Many options are available for GDB itself: please see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sources.redhat.com/gdb/current/onlinedocs/gdb/">
+ "GDB features for C++" </link> 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>
+
+<para>
+ Starting with version 7.0, GDB includes support for writing
+ pretty-printers in Python. Pretty printers for STL classes are
+ distributed with GCC from version 4.5.0. The most recent version of
+ these printers are always found in libstdc++ svn repository.
+ To enable these printers, check-out the latest printers to a local
+ directory:
+</para>
+
+<programlisting>
+ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
+</programlisting>
+
+<para>
+ Next, add the following section to your ~/.gdbinit The path must
+ match the location where the Python module above was checked-out.
+ So if checked out to: /home/maude/gdb_printers/, the path would be as
+ written in the example below.
+</para>
+
+<programlisting>
+ python
+ import sys
+ sys.path.insert(0, '/home/maude/gdb_printers/python')
+ from libstdcxx.v6.printers import register_libstdcxx_printers
+ register_libstdcxx_printers (None)
+ end
+</programlisting>
+
+<para>
+ The path should be the only element that needs to be adjusted in the
+ example. Once loaded, STL classes that the printers support
+ should print in a more human-readable format. To print the classes
+ in the old style, use the /r (raw) switch in the print command
+ (i.e., print /r foo). This will print the classes as if the Python
+ pretty-printers were not loaded.
+</para>
+
+<para>
+ For additional information on STL support and GDB please visit:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/gdb/wiki/STLSupport"> "GDB Support
+ for STL" </link> in the GDB wiki. Additionally, in-depth
+ documentation and discussion of the pretty printing feature can be
+ found in "Pretty Printing" node in the GDB manual. You can find
+ on-line versions of the GDB user manual in GDB's homepage, at
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/gdb/"> "GDB: The GNU Project
+ Debugger" </link>.
+</para>
+
+</section>
+
+<section xml:id="debug.exceptions"><info><title>Tracking uncaught exceptions</title></info>
+
+<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>
+</section>
+
+<section xml:id="debug.debug_mode"><info><title>Debug Mode</title></info>
+
+ <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link>
+ has compile and run-time checks for many containers.
+ </para>
+</section>
+
+<section xml:id="debug.compile_time_checks"><info><title>Compile Time Checking</title></info>
+
+ <para> The <link linkend="manual.ext.compile_checks">Compile-Time
+ Checks</link> Extension has compile-time checks for many algorithms.
+ </para>
+</section>
+
+<section xml:id="debug.profile_mode" xreflabel="debug.profile_mode"><info><title>Profile-based Performance Analysis</title></info>
+
+ <para> The <link linkend="manual.ext.profile_mode">Profile-based
+ Performance Analysis</link> Extension has performance checks for many
+ algorithms.
+ </para>
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/debug_mode.xml b/libstdc++-v3/doc/xml/manual/debug_mode.xml
new file mode 100644
index 000000000..c58bde340
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/debug_mode.xml
@@ -0,0 +1,889 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.ext.debug_mode" xreflabel="Debug Mode">
+<?dbhtml filename="debug_mode.html"?>
+
+<info><title>Debug Mode</title>
+ <keywordset>
+ <keyword>
+ C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ debug
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<section xml:id="manual.ext.debug_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
+
+ <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>
+
+</section>
+
+<section xml:id="manual.ext.debug_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info>
+
+ <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>
+
+</section>
+
+<section xml:id="manual.ext.debug_mode.using" xreflabel="Using"><info><title>Using</title></info>
+
+ <para>
+ </para>
+<section xml:id="debug_mode.using.mode" xreflabel="Using Mode"><info><title>Using the Debug Mode</title></info>
+
+
+<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>
+
+</section>
+
+<section xml:id="debug_mode.using.specific" xreflabel="Using Specific"><info><title>Using a Specific Debug Container</title></info>
+
+<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="4" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+
+<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">&lt;debug/bitset&gt;</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">&lt;debug/deque&gt;</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">&lt;debug/list&gt;</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">&lt;debug/map&gt;</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">&lt;debug/map&gt;</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">&lt;debug/set&gt;</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">&lt;debug/set&gt;</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">&lt;debug/string&gt;</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">&lt;debug/string&gt;</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">&lt;debug/string&gt;</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">&lt;debug/vector&gt;</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="4" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+
+<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">&lt;debug/unordered_map&gt;</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">&lt;debug/unordered_map&gt;</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">&lt;debug/unordered_set&gt;</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">&lt;debug/unordered_set&gt;</filename></entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+</section>
+</section>
+
+<section xml:id="manual.ext.debug_mode.design" xreflabel="Design"><info><title>Design</title></info>
+
+ <para>
+ </para>
+ <section xml:id="debug_mode.design.goals" xreflabel="Goals"><info><title>Goals</title></info>
+
+ <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 inheritnum="ignore" continuation="restarts">
+ <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&lt;int&gt;</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>
+ </section>
+
+ <section xml:id="debug_mode.design.methods" xreflabel="Methods"><info><title>Methods</title></info>
+
+ <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>
+
+ <section xml:id="debug_mode.design.methods.wrappers" xreflabel="Method Wrapper"><info><title>The Wrapper Model</title></info>
+
+<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 <link linkend="methods.coexistence.link">mixing debug and
+ release code</link> 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>
+
+ <section xml:id="debug_mode.design.methods.safe_iter" xreflabel="Method Safe Iter"><info><title>Safe Iterators</title></info>
+
+<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>
+ </section>
+
+ <section xml:id="debug_mode.design.methods.safe_seq" xreflabel="Method Safe Seq"><info><title>Safe Sequences (Containers)</title></info>
+
+
+<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
+ <link linkend="debug_mode.design.methods.safe_iter">safe
+ iterators</link> 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&lt;typename _Tp, typename _Allocator = allocator&lt;_Tp&gt;
+ class debug-list :
+ public release-list&lt;_Tp, _Allocator&gt;,
+ public __gnu_debug::_Safe_sequence&lt;debug-list&lt;_Tp, _Allocator&gt; &gt;
+ {
+ typedef release-list&lt;_Tp, _Allocator&gt; _Base;
+ typedef debug-list&lt;_Tp, _Allocator&gt; _Self;
+
+ public:
+ typedef __gnu_debug::_Safe_iterator&lt;typename _Base::iterator, _Self&gt; iterator;
+ typedef __gnu_debug::_Safe_iterator&lt;typename _Base::const_iterator, _Self&gt; const_iterator;
+
+ // duplicate std::list interface with debugging semantics
+ };
+</programlisting>
+ </section>
+ </section>
+
+ <section xml:id="debug_mode.design.methods.precond" xreflabel="Precondition check"><info><title>Precondition Checking</title></info>
+
+<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>
+ </section>
+
+ <section xml:id="debug_mode.design.methods.coexistence" xreflabel="Coexistence"><info><title>Release- and debug-mode coexistence</title></info>
+
+<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 (since incorporated into the C++0x language specification, described in the GCC Manual for the C++ language as
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Namespace-Association.html#Namespace-Association">namespace
+ association</link>), 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>
+
+ <section xml:id="methods.coexistence.compile" xreflabel="Compile"><info><title>Compile-time coexistence of release- and debug-mode components</title></info>
+
+
+<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&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
+ class list
+ {
+ // ...
+ };
+} // namespace std
+</programlisting>
+
+<para>In debug mode we include the release-mode container (which is now
+defined in the namespace <code>__cxx1998</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 C++0x namespace association language feature. 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 __cxx1998
+ {
+ template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
+ class list
+ {
+ // ...
+ };
+ } // namespace __gnu_norm
+
+ namespace __debug
+ {
+ template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
+ class list
+ : public __cxx1998::list&lt;_Tp, _Alloc&gt;,
+ public __gnu_debug::_Safe_sequence&lt;list&lt;_Tp, _Alloc&gt; &gt;
+ {
+ // ...
+ };
+ } // namespace __cxx1998
+
+ // namespace __debug __attribute__ ((strong));
+ inline namespace __debug { }
+}
+</programlisting>
+ </section>
+
+ <section xml:id="methods.coexistence.link" xreflabel="Link"><info><title>Link- and run-time coexistence of release- and
+ debug-mode components</title></info>
+
+
+<para>Because each component has a distinct and separate release and
+debug implementation, there is no issue 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 &lt;string&gt;
+
+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 &lt;string&gt;
+
+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 inheritnum="ignore" continuation="restarts">
+ <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>
+ </section>
+
+ <section xml:id="methods.coexistence.alt" xreflabel="Alternatives"><info><title>Alternatives for Coexistence</title></info>
+
+
+<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&lt;&gt;</code> that
+ signals the user's intention to use debugging, and pick up
+ the <code>debug&lt;&gt;</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&lt;T&gt;</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
+ in 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html"> this post
+ </link>
+ 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html">link
+ name</link> </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>
+ </section>
+ </section>
+ </section>
+
+ <section xml:id="debug_mode.design.other" xreflabel="Other"><info><title>Other Implementations</title></info>
+
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.mathcs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</link>:
+ 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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stlport.org/">STLport</link>: STLport is a free
+ implementation of the C++ standard library derived from the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/">SGI implementation</link>, and
+ ported to many other platforms. It includes a debug mode that uses a
+ wrapper model (that in some ways 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>Metrowerks CodeWarrior: 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>
+
+ </section>
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/diagnostics.xml b/libstdc++-v3/doc/xml/manual/diagnostics.xml
new file mode 100644
index 000000000..1a6a3f17d
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/diagnostics.xml
@@ -0,0 +1,129 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.diagnostics" xreflabel="Diagnostics">
+<?dbhtml filename="diagnostics.html"?>
+
+<info><title>
+ Diagnostics
+ <indexterm><primary>Diagnostics</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<section xml:id="std.diagnostics.exceptions" xreflabel="Exceptions"><info><title>Exceptions</title></info>
+ <?dbhtml filename="exceptions.html"?>
+
+
+ <section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info>
+
+ <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 source documentation.
+ </para>
+
+ <para>
+ Full API details.
+ </para>
+
+ <!-- Doxygen XML: api/group__exceptions.xml -->
+
+ </section>
+ <section xml:id="std.diagnostics.exceptions.data" xreflabel="Adding Data to Exceptions"><info><title>Adding Data to <classname>exception</classname></title></info>
+
+ <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&amp; 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>
+
+ </section>
+</section>
+
+<section xml:id="std.diagnostics.concept_checking" xreflabel="Concept Checking"><info><title>Concept Checking</title></info>
+
+ <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 was
+ formally reviewed and accepted into
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
+ Boost libraries</link>, 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
+ <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
+ You can enable them on a per-translation-unit basis with
+ <literal>-D_GLIBCXX_CONCEPT_CHECKS</literal>.
+ </para>
+
+ <para>
+ Please note that the checks are based on the requirements in the original
+ C++ standard, some of which have changed in the upcoming C++0x revision.
+ Additionally, some correct code might be rejected by the concept checks,
+ for example template argument types may need to be complete when used in
+ a template definition, rather than at the point of instantiation.
+ There are no plans to address these shortcomings.
+ </para>
+
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/documentation_hacking.xml b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
new file mode 100644
index 000000000..7b2ed7c09
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/documentation_hacking.xml
@@ -0,0 +1,990 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.porting.doc" xreflabel="Documentation Hacking">
+<?dbhtml filename="documentation_hacking.html"?>
+
+<info><title>Writing and Generating Documentation</title>
+ <keywordset>
+ <keyword>ISO C++</keyword>
+ <keyword>documentation</keyword>
+ <keyword>style</keyword>
+ <keyword>docbook</keyword>
+ <keyword>doxygen</keyword>
+ </keywordset>
+</info>
+
+ <section xml:id="doc.intro">
+ <info>
+ <title>Introduction</title>
+ </info>
+ <para>
+ Documentation for the GNU C++ Library is created from three
+ independent sources: a manual, a FAQ, and an API reference.
+ </para>
+ <para>
+ The sub-directory <filename class="directory">doc</filename>
+ within the main source directory contains
+ <filename>Makefile.am</filename> and
+ <filename>Makefile.in</filename>, which provide rules for
+ generating documentation, described in excruciating detail
+ below. The <filename class="directory">doc</filename>
+ sub-directory also contains three directories: <filename
+ class="directory">doxygen</filename>, which contains scripts and
+ fragments for <command>doxygen</command>, <filename
+ class="directory">html</filename>, which contains an html
+ version of the manual, and <filename
+ class="directory">xml</filename>, which contains an xml version
+ of the manual.
+ </para>
+ <para>
+ Diverging from established documentation conventions in the rest
+ of the GCC project, libstdc++ does not use Texinfo as a markup
+ language. Instead, Docbook is used to create the manual and the
+ FAQ, and Doxygen is used to construct the API
+ reference. Although divergent, this conforms to the GNU Project
+ recommendations as long as the output is of sufficient quality,
+ as per
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://www.gnu.org/prep/standards/standards.html#Documentation">
+ GNU Manuals</link>.
+ </para>
+ </section>
+
+ <section xml:id="doc.generation">
+ <info>
+ <title>Generating Documentation</title>
+ </info>
+
+ <para>
+ Certain Makefile rules are required by the GNU Coding
+ Standards. These standard rules generate HTML, PDF, XML, or man
+ files. For each of the generative rules, there is an additional
+ install rule that is used to install any generated documentation
+ files into the prescribed installation directory. Files are
+ installed into <filename class="directory">share/doc</filename>
+ or <filename class="directory">share/man</filename> directories.
+ </para>
+
+ <para>
+ The standard Makefile rules are conditionally supported, based
+ on the results of examining the host environment for
+ prerequisites at configuration time. If requirements are not
+ found, the rule is aliased to a dummy rule that does nothing,
+ and produces no documentation. If the requirements are found,
+ the rule forwards to a private rule that produces the requested
+ documentation.
+ </para>
+
+ <para>
+ For more details on what prerequisites were found and where,
+ please consult the file <filename>config.log</filename> in the
+ libstdc++ build directory. Compare this log to what is expected
+ for the relevant Makefile conditionals:
+ <literal>BUILD_INFO</literal>, <literal>BUILD_XML</literal>,
+ <literal>BUILD_HTML</literal>, <literal>BUILD_MAN</literal>,
+ <literal>BUILD_PDF</literal>, and <literal>BUILD_EPUB</literal>.
+ </para>
+
+ <para>
+ Supported Makefile rules:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <emphasis>make html</emphasis>
+ </term>
+ <term>
+ <emphasis>make install-html</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Generates multi-page HTML documentation, and installs it
+ in the following directories:
+ </para>
+ <para>
+ <filename class="directory">
+ doc/libstdc++/libstdc++-api.html
+ </filename>
+ </para>
+ <para>
+ <filename class="directory">
+ doc/libstdc++/libstdc++-manual.html
+ </filename>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis>make pdf</emphasis>
+ </term>
+ <term>
+ <emphasis>make install-pdf</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Generates indexed PDF documentation, and installs it as
+ the following files:
+ </para>
+ <para>
+ <filename>doc/libstdc++/libstdc++-api.pdf</filename>
+ </para>
+ <para>
+ <filename>doc/libstdc++/libstdc++-manual.pdf</filename>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis>make man</emphasis>
+ </term>
+ <term>
+ <emphasis>make install-man</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Generates man pages, and installs it in the following directory:
+ </para>
+ <para>
+ <filename class="directory">man/man3/</filename>
+ </para>
+ <para>
+ The generated man pages are namespace-qualified, so to look at
+ the man page for <classname>vector</classname>, one would use
+ <command>man std::vector</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis>make epub</emphasis>
+ </term>
+ <term>
+ <emphasis>make install-epub</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Generates documentation in the ebook/portable electronic
+ reader format called Epub, and installs it as the
+ following file.
+ </para>
+ <para>
+ <filename>doc/libstdc++/libstdc++-manual.epub</filename>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <emphasis>make xml</emphasis>
+ </term>
+ <term>
+ <emphasis>make install-xml</emphasis>
+ </term>
+ <listitem>
+ <para>
+ Generates single-file XML documentation, and installs it
+ as the following files:
+ </para>
+ <para>
+ <filename>doc/libstdc++/libstdc++-api-single.xml</filename>
+ </para>
+ <para>
+ <filename>doc/libstdc++/libstdc++-manual-single.xml</filename>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Makefile rules for several other formats are explicitly not
+ supported, and are always aliased to dummy rules. These
+ unsupported formats are: <emphasis>info</emphasis>,
+ <emphasis>ps</emphasis>, and <emphasis>dvi</emphasis>.
+ </para>
+ </section>
+
+ <section xml:id="doc.doxygen"><info><title>Doxygen</title></info>
+
+ <section xml:id="doxygen.prereq"><info><title>Prerequisites</title></info>
+
+ <table frame="all">
+<title>Doxygen Prerequisites</title>
+
+<tgroup cols="3" align="center" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+
+ <thead>
+ <row>
+ <entry>Tool</entry>
+ <entry>Version</entry>
+ <entry>Required By</entry>
+ </row>
+ </thead>
+
+ <tbody>
+
+ <row>
+ <entry>coreutils</entry>
+ <entry>8.5</entry>
+ <entry>all</entry>
+ </row>
+
+ <row>
+ <entry>bash</entry>
+ <entry>4.1</entry>
+ <entry>all</entry>
+ </row>
+
+ <row>
+ <entry>doxygen</entry>
+ <entry>1.7.0</entry>
+ <entry>all</entry>
+ </row>
+
+ <row>
+ <entry>graphviz</entry>
+ <entry>2.26</entry>
+ <entry>graphical hierarchies</entry>
+ </row>
+
+ <row>
+ <entry>pdflatex</entry>
+ <entry>2007-59</entry>
+ <entry>pdf output</entry>
+ </row>
+
+ </tbody>
+</tgroup>
+</table>
+
+
+ <para>
+ Prerequisite tools are Bash 2.0 or later,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.doxygen.org/">Doxygen</link>, and
+ the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/coreutils/">GNU
+ coreutils</link>. (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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.graphviz.org">Graphviz</link> package
+ will need to be installed. For PDF
+ output, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.tug.org/applications/pdftex/">
+ pdflatex</link> is required.
+ </para>
+ </section>
+
+ <section xml:id="doxygen.rules"><info><title>Generating the Doxygen Files</title></info>
+
+ <para>
+ The following Makefile rules run Doxygen to generate HTML
+ docs, XML docs, XML docs as a single file, PDF docs, and the
+ man pages. These rules are not conditional! If the required
+ tools are not found, or are the wrong versions, the rule may
+ end in an error.
+ </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-xml-single-doxygen</userinput></screen>
+ </para>
+
+ <para>
+ <screen><userinput>make doc-pdf-doxygen</userinput></screen>
+ </para>
+
+ <para>
+ <screen><userinput>make doc-man-doxygen</userinput></screen>
+ </para>
+
+ <para>
+ Generated files are output into separate sub directories of
+ <filename class="directory">doc/doxygen/</filename> in the
+ build directory, based on the output format. For instance, the
+ HTML docs will be in <filename class="directory">doc/doxygen/html</filename>.
+ </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>
+
+ </section>
+
+ <section xml:id="doxygen.markup"><info><title>Markup</title></info>
+
+
+ <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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</link>.
+ 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>
+ Some commentary to accompany
+ the first list in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special
+ Documentation Blocks</link> section of
+ the Doxygen manual:
+ </para>
+
+ <orderedlist inheritnum="ignore" continuation="restarts">
+ <listitem>
+ <para>For longer comments, 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).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ This is disgusting. Don't do this.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ Some specific guidelines:
+ </para>
+
+ <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 &lt;pre&gt; 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>
+
+ <para>
+ Complicated math functions should use the multi-line
+ format. An example from <filename>random.h</filename>:
+ </para>
+
+ <para>
+<literallayout class="normal">
+/**
+ * @brief A model of a linear congruential random number generator.
+ *
+ * @f[
+ * x_{i+1}\leftarrow(ax_{i} + c) \bmod m
+ * @f]
+ */
+</literallayout>
+ </para>
+
+ <para>
+ One area of note is the markup required for
+ <literal>@file</literal> markup in header files. Two details
+ are important: for filenames that have the same name in
+ multiple directories, include part of the installed path to
+ disambiguate. For example:
+ </para>
+
+ <para>
+<literallayout class="normal">
+/** @file debug/vector
+ * This file is a GNU debug extension to the Standard C++ Library.
+ */
+</literallayout>
+ </para>
+
+ <para>
+ The other relevant detail for header files is the use of a
+ libstdc++-specific doxygen alias that helps distinguish
+ between public header files (like <filename>random</filename>)
+ from implementation or private header files (like
+ <filename>bits/c++config.h</filename>.) This alias is spelled
+ <literal>@headername</literal> and can take one or two
+ arguments that detail the public header file or files that
+ should be included to use the contents of the file. All header
+ files that are not intended for direct inclusion must use
+ <literal>headername</literal> in the <literal>file</literal>
+ block. An example:
+ </para>
+
+ <para>
+<literallayout class="normal">
+/** @file bits/basic_string.h
+ * This is an internal header file, included by other library headers.
+ * Do not attempt to use it directly. @headername{string}
+ */
+</literallayout>
+ </para>
+
+ <para>
+ Be careful about using certain, special characters when
+ writing Doxygen comments. Single and double quotes, and
+ separators in filenames are two common trouble spots. When in
+ doubt, consult the following table.
+ </para>
+
+<table frame="all">
+<title>HTML to Doxygen Markup Comparison</title>
+
+<tgroup cols="2" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+
+ <thead>
+ <row>
+ <entry>HTML</entry>
+ <entry>Doxygen</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>\</entry>
+ <entry>\\</entry>
+ </row>
+
+ <row>
+ <entry>"</entry>
+ <entry>\"</entry>
+ </row>
+
+ <row>
+ <entry>'</entry>
+ <entry>\'</entry>
+ </row>
+
+ <row>
+ <entry>&lt;i&gt;</entry>
+ <entry>@a word</entry>
+ </row>
+
+ <row>
+ <entry>&lt;b&gt;</entry>
+ <entry>@b word</entry>
+ </row>
+
+ <row>
+ <entry>&lt;code&gt;</entry>
+ <entry>@c word</entry>
+ </row>
+
+ <row>
+ <entry>&lt;em&gt;</entry>
+ <entry>@a word</entry>
+ </row>
+
+ <row>
+ <entry>&lt;em&gt;</entry>
+ <entry>&lt;em&gt;two words or more&lt;/em&gt;</entry>
+ </row>
+ </tbody>
+
+</tgroup>
+</table>
+
+
+ </section>
+
+ </section>
+
+ <section xml:id="doc.docbook"><info><title>Docbook</title></info>
+
+
+ <section xml:id="docbook.prereq"><info><title>Prerequisites</title></info>
+
+
+ <table frame="all">
+<title>Docbook Prerequisites</title>
+
+<tgroup cols="3" align="center" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+
+ <thead>
+ <row>
+ <entry>Tool</entry>
+ <entry>Version</entry>
+ <entry>Required By</entry>
+ </row>
+ </thead>
+
+ <tbody>
+
+ <row>
+ <entry>docbook5-style-xsl</entry>
+ <entry>1.76.1</entry>
+ <entry>all</entry>
+ </row>
+
+ <row>
+ <entry>xsltproc</entry>
+ <entry>1.1.26</entry>
+ <entry>all</entry>
+ </row>
+
+ <row>
+ <entry>xmllint</entry>
+ <entry>2.7.7</entry>
+ <entry>validation</entry>
+ </row>
+
+ <row>
+ <entry>dblatex</entry>
+ <entry>0.3</entry>
+ <entry>pdf output</entry>
+ </row>
+
+ <row>
+ <entry>pdflatex</entry>
+ <entry>2007-59</entry>
+ <entry>pdf output</entry>
+ </row>
+
+ <row>
+ <entry>docbook2X</entry>
+ <entry>0.8.8</entry>
+ <entry>info output</entry>
+ </row>
+
+ </tbody>
+</tgroup>
+</table>
+
+ <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 5.0 stylesheets and schema is required. The
+ stylesheets are usually packaged by vendor, in something
+ like <filename>docbook5-style-xsl</filename>. To exactly match
+ generated output, please use a version of the stylesheets
+ equivalent
+ to <filename>docbook5-style-xsl-1.75.2-3</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-ns-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
+ relevant DocBook schema. These are provided
+ by a vendor package like <filename>libxml2</filename> and <filename>docbook5-schemas-5.0-4</filename>
+ </para>
+
+ <para>
+ For PDF output, something that transforms valid Docbook XML to PDF is
+ required. Possible solutions include <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dblatex.sourceforge.net">dblatex</link>,
+ <command>xmlto</command>, or <command>prince</command>. Of
+ these, <command>dblatex</command> is the default. Other
+ options are listed on the DocBook web <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</link>. Please
+ consult the <email>libstdc++@gcc.gnu.org</email> list when
+ preparing printed manuals for current best practice and
+ suggestions.
+ </para>
+
+ <para>
+ For Texinfo output, something that transforms valid Docbook
+ XML to Texinfo is required. The default choice is <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook2x.sourceforge.net/">docbook2X</link>.
+ </para>
+ </section>
+
+ <section xml:id="docbook.rules"><info><title>Generating the DocBook Files</title></info>
+
+
+ <para>
+ The following Makefile rules generate (in order): an HTML
+ version of all the DocBook documentation, a PDF version of the
+ same, and a single XML document. These rules are not
+ conditional! If the required tools are not found, or are the
+ wrong versions, the rule may end in an error.
+ </para>
+
+ <para>
+ <screen><userinput>make doc-html-docbook</userinput></screen>
+ </para>
+
+ <para>
+ <screen><userinput>make doc-pdf-docbook</userinput></screen>
+ </para>
+
+ <para>
+ <screen><userinput>make doc-xml-single-docbook</userinput></screen>
+ </para>
+
+ <para>
+ Generated files are output into separate sub directores of
+ <filename class="directory">doc/docbook/</filename> in the
+ build directory, based on the output format. For instance, the
+ HTML docs will be in <filename
+ class="directory">doc/docbook/html</filename>.
+ </para>
+
+ <para>
+ If the Docbook stylesheets are installed in a custom location,
+ one can use the variable <literal>XSL_STYLE_DIR</literal> to
+ over-ride the Makefile defaults. As so:
+ </para>
+
+ <screen>
+ <userinput>
+make <literal>XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwalsh"</literal> doc-html-docbook
+ </userinput>
+ </screen>
+
+ </section>
+
+ <section xml:id="docbook.validation"><info><title>Editing and Validation</title></info>
+
+ <para>
+ After editing the xml sources, please make sure that the XML
+ documentation and markup is still valid. This can be
+ done easily, with the following validation rule:
+ </para>
+
+ <screen>
+ <userinput>make doc-xml-validate-docbook</userinput>
+ </screen>
+
+ <para>
+ This is equivalent to doing:
+ </para>
+
+ <screen>
+ <userinput>
+ xmllint --noout --valid <filename>xml/index.xml</filename>
+ </userinput>
+ </screen>
+
+ <para>
+ Please note that individual sections and chapters of the
+ manual can be validated by substituting the file desired for
+ <filename>xml/index.xml</filename> in the command
+ above. Reducing scope in this manner can be helpful when
+ validation on the entire manual fails.
+ </para>
+
+ <para>
+ All Docbook xml sources should always validate. No excuses!
+ </para>
+
+ </section>
+
+ <section xml:id="docbook.examples"><info><title>File Organization and Basics</title></info>
+
+
+ <literallayout class="normal">
+ <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 &lt;iostream&gt;
+
+
+ <emphasis>General structure</emphasis>
+
+ &lt;set&gt;
+ &lt;book&gt;
+ &lt;/book&gt;
+
+ &lt;book&gt;
+ &lt;chapter&gt;
+ &lt;/chapter&gt;
+ &lt;/book&gt;
+
+ &lt;book&gt;
+ &lt;part&gt;
+ &lt;chapter&gt;
+ &lt;section&gt;
+ &lt;/section&gt;
+
+ &lt;sect1&gt;
+ &lt;/sect1&gt;
+
+ &lt;sect1&gt;
+ &lt;sect2&gt;
+ &lt;/sect2&gt;
+ &lt;/sect1&gt;
+ &lt;/chapter&gt;
+
+ &lt;chapter&gt;
+ &lt;/chapter&gt;
+ &lt;/part&gt;
+ &lt;/book&gt;
+
+ &lt;/set&gt;
+ </literallayout>
+ </section>
+
+ <section xml:id="docbook.markup"><info><title>Markup By Example</title></info>
+
+
+ <para>
+ Complete details on Docbook markup can be found in the DocBook
+ Element Reference,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.docbook.org/tdg/en/html/part2.html">online</link>.
+ 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 colname="c2"/>
+
+ <thead>
+ <row>
+ <entry>HTML</entry>
+ <entry>Docbook</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>&lt;p&gt;</entry>
+ <entry>&lt;para&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;pre&gt;</entry>
+ <entry>&lt;computeroutput&gt;, &lt;programlisting&gt;,
+ &lt;literallayout&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;ul&gt;</entry>
+ <entry>&lt;itemizedlist&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;ol&gt;</entry>
+ <entry>&lt;orderedlist&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;il&gt;</entry>
+ <entry>&lt;listitem&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;dl&gt;</entry>
+ <entry>&lt;variablelist&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;dt&gt;</entry>
+ <entry>&lt;term&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;dd&gt;</entry>
+ <entry>&lt;listitem&gt;</entry>
+ </row>
+
+ <row>
+ <entry>&lt;a href=""&gt;</entry>
+ <entry>&lt;ulink url=""&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;code&gt;</entry>
+ <entry>&lt;literal&gt;, &lt;programlisting&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;strong&gt;</entry>
+ <entry>&lt;emphasis&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;em&gt;</entry>
+ <entry>&lt;emphasis&gt;</entry>
+ </row>
+ <row>
+ <entry>"</entry>
+ <entry>&lt;quote&gt;</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 colname="c2"/>
+
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Use</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>&lt;structname&gt;</entry>
+ <entry>&lt;structname&gt;char_traits&lt;/structname&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;classname&gt;</entry>
+ <entry>&lt;classname&gt;string&lt;/classname&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;function&gt;</entry>
+ <entry>
+ <para>&lt;function&gt;clear()&lt;/function&gt;</para>
+ <para>&lt;function&gt;fs.clear()&lt;/function&gt;</para>
+ </entry>
+ </row>
+ <row>
+ <entry>&lt;type&gt;</entry>
+ <entry>&lt;type&gt;long long&lt;/type&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;varname&gt;</entry>
+ <entry>&lt;varname&gt;fs&lt;/varname&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;literal&gt;</entry>
+ <entry>
+ <para>&lt;literal&gt;-Weffc++&lt;/literal&gt;</para>
+ <para>&lt;literal&gt;rel_ops&lt;/literal&gt;</para>
+ </entry>
+ </row>
+ <row>
+ <entry>&lt;constant&gt;</entry>
+ <entry>
+ <para>&lt;constant&gt;_GNU_SOURCE&lt;/constant&gt;</para>
+ <para>&lt;constant&gt;3.0&lt;/constant&gt;</para>
+ </entry>
+ </row>
+ <row>
+ <entry>&lt;command&gt;</entry>
+ <entry>&lt;command&gt;g++&lt;/command&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;errortext&gt;</entry>
+ <entry>&lt;errortext&gt;In instantiation of&lt;/errortext&gt;</entry>
+ </row>
+ <row>
+ <entry>&lt;filename&gt;</entry>
+ <entry>
+ <para>&lt;filename class="headerfile"&gt;ctype.h&lt;/filename&gt;</para>
+ <para>&lt;filename class="directory"&gt;/home/gcc/build&lt;/filename&gt;</para>
+ <para>&lt;filename class="libraryfile"&gt;libstdc++.so&lt;/filename&gt;</para>
+ </entry>
+ </row>
+ </tbody>
+</tgroup>
+</table>
+
+</section>
+</section>
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/evolution.xml b/libstdc++-v3/doc/xml/manual/evolution.xml
new file mode 100644
index 000000000..08876deb1
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/evolution.xml
@@ -0,0 +1,631 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.porting.api" xreflabel="api">
+<?dbhtml filename="api.html"?>
+
+<info><title>API Evolution and Deprecation History</title>
+ <keywordset>
+ <keyword>ISO C++</keyword>
+ <keyword>api</keyword>
+ <keyword>evolution</keyword>
+ <keyword>deprecation</keyword>
+ <keyword>history</keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+A list of user-visible changes, in chronological order
+</para>
+
+<section xml:id="api.rel_300"><info><title><constant>3.0</constant></title></info>
+
+
+ <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>
+
+
+
+</section>
+
+<section xml:id="api.rel_310"><info><title><constant>3.1</constant></title></info>
+
+ <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>
+
+</section>
+
+<section xml:id="api.rel_320"><info><title><constant>3.2</constant></title></info>
+
+ <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>. (This same functionality is now spelled <literal>_GLIBCXX_FORCE_NEW</literal>, see
+ <link linkend="manual.intro.using.macros">this page</link>
+ for details.
+ </para>
+
+
+<para>Error handling in iostreams cleaned up, made consistent. </para>
+
+
+</section>
+
+<section xml:id="api.rel_330"><info><title><constant>3.3</constant></title></info>
+
+ <para>
+ </para>
+</section>
+
+<section xml:id="api.rel_340"><info><title><constant>3.4</constant></title></info>
+
+ <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&lt;T,A&gt;</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&lt;T,A&gt;</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&lt;T, __alloc&gt;</code> is thus the same as
+ <code>allocator&lt;T&gt;</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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+
+ <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&lt;T&gt;</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&lt;T&gt;</classname></entry>
+ <entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry>
+ <entry><classname>std::__malloc_alloc_template&lt;int&gt;</classname></entry>
+ <entry><filename class="headerfile">memory</filename></entry>
+ </row>
+ <row>
+ <entry><classname>__gnu_cxx::debug_allocator&lt;T&gt;</classname></entry>
+ <entry><filename class="headerfile">ext/debug_allocator.h</filename></entry>
+ <entry><classname>std::debug_alloc&lt;T&gt;</classname></entry>
+ <entry><filename class="headerfile">memory</filename></entry>
+ </row>
+ <row>
+ <entry><classname>__gnu_cxx::__pool_alloc&lt;T&gt;</classname></entry>
+ <entry><filename class="headerfile">ext/pool_allocator.h</filename></entry>
+ <entry><classname>std::__default_alloc_template&lt;bool,int&gt;</classname></entry>
+ <entry><filename class="headerfile">memory</filename></entry>
+ </row>
+ <row>
+ <entry><classname>__gnu_cxx::__mt_alloc&lt;T&gt;</classname></entry>
+ <entry><filename class="headerfile">ext/mt_allocator.h</filename></entry>
+ <entry> </entry>
+ <entry> </entry>
+ </row>
+ <row>
+ <entry><classname>__gnu_cxx::bitmap_allocator&lt;T&gt;</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 colname="c2"/>
+<colspec colname="c3"/>
+
+<thead>
+ <row>
+ <entry>Allocator</entry>
+ <entry>Include</entry>
+ <entry>Version</entry>
+ </row>
+</thead>
+
+<tbody>
+ <row>
+ <entry><classname>__gnu_cxx::array_allocator&lt;T&gt;</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&lt;T&gt;</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>
+
+
+</section>
+
+<section xml:id="api.rel_400"><info><title><constant>4.0</constant></title></info>
+
+ <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>
+
+
+</section>
+
+<section xml:id="api.rel_410"><info><title><constant>4.1</constant></title></info>
+
+ <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>
+
+</section>
+
+<section xml:id="api.rel_420"><info><title><constant>4.2</constant></title></info>
+
+ <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>
+
+</section>
+
+<section xml:id="api.rel_430"><info><title><constant>4.3</constant></title></info>
+
+ <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>
+
+</section>
+
+
+<section xml:id="api.rel_440"><info><title><constant>4.4</constant></title></info>
+
+ <para>
+ </para>
+
+<para>
+C++0X features.
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>
+ Added.
+ </para>
+ <para>
+ <filename class="headerfile">atomic</filename>,
+ <filename class="headerfile">chrono</filename>,
+ <filename class="headerfile">condition_variable</filename>,
+ <filename class="headerfile">forward_list</filename>,
+ <filename class="headerfile">initializer_list</filename>,
+ <filename class="headerfile">mutex</filename>,
+ <filename class="headerfile">ratio</filename>,
+ <filename class="headerfile">thread</filename>
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Updated and improved.
+ </para>
+ <para>
+ <filename class="headerfile">algorithm</filename>,
+ <filename class="headerfile">system_error</filename>,
+ <filename class="headerfile">type_traits</filename>
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Use of the GNU extension namespace association converted to inline namespaces.
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Preliminary support for <classname>initializer_list</classname>
+ and defaulted and deleted constructors in container classes.
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ <classname>unique_ptr</classname>.
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Support for new character types <type>char16_t</type>
+ and <type>char32_t</type> added
+ to <classname>char_traits</classname>, <classname>basic_string</classname>, <classname>numeric_limits</classname>,
+ and assorted compile-time type traits.
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Support for string conversions <function>to_string</function>
+ and <function>to_wstring</function>.
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Member functions taking string arguments were added to iostreams
+ including <classname>basic_filebuf</classname>, <classname>basic_ofstream</classname>,
+ and <classname>basic_ifstream</classname>.
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Exception propagation support,
+ including <classname>exception_ptr</classname>, <function>current_exception</function>, <function>copy_exception</function>,
+ and <function>rethrow_exception</function>.
+ </para>
+</listitem>
+</itemizedlist>
+
+
+ <para>
+Uglification of <literal>try</literal> to <literal>__try</literal>
+and <literal>catch</literal> to <literal>__catch</literal>.
+ </para>
+
+ <para>
+Audit of internal mutex usage, conversion to functions returning static
+local mutex.
+ </para>
+
+<para> Extensions
+added: <filename class="headerfile">ext/pointer.h</filename>
+and <filename class="headerfile">ext/extptr_allocator.h</filename>. Support
+for non-standard pointer types has been added
+to <classname>vector</classname>
+and <classname>forward_list</classname>.
+</para>
+</section>
+
+<section xml:id="api.rel_450"><info><title><constant>4.5</constant></title></info>
+
+ <para>
+ </para>
+
+<para>
+C++0X features.
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>
+ Added.
+ </para>
+ <para>
+ <filename class="headerfile">functional</filename>,
+ <filename class="headerfile">future</filename>,
+ <filename class="headerfile">random</filename>
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Updated and improved.
+ </para>
+ <para>
+ <filename class="headerfile">atomic</filename>,
+ <filename class="headerfile">system_error</filename>,
+ <filename class="headerfile">type_traits</filename>
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ Add support for explicit operators and standard layout types.
+ </para>
+</listitem>
+</itemizedlist>
+
+<para>
+Profile mode first appears.
+</para>
+
+<para>
+Support for decimal floating-point arithmetic, including <classname>decimal32</classname>, <classname>decimal64</classname>, and <classname>decimal128</classname>.
+</para>
+
+<para>
+Python pretty-printers are added for use with appropriately-advanced versions of <command>gdb</command>.
+</para>
+
+<para>
+Audit for application of function attributes notrow, const, pure, and noreturn.
+</para>
+
+<para>
+The default behavior for comparing typeinfo names changed, so
+in <filename class="headerfile">typeinfo</filename>, <literal>__GXX_MERGED_TYPEINFO_NAMES</literal>
+now defaults to zero.
+</para>
+
+<para> Extensions modified: <filename class="headerfile">ext/throw_allocator.h</filename>.
+</para>
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/extensions.xml b/libstdc++-v3/doc/xml/manual/extensions.xml
new file mode 100644
index 000000000..b93c61f1b
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/extensions.xml
@@ -0,0 +1,581 @@
+<part xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.ext" xreflabel="Extensions">
+<?dbhtml filename="extensions.html"?>
+
+<info><title>
+ Extensions
+ <indexterm><primary>Extensions</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<preface><info><title/></info>
+
+<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 inheritnum="ignore" continuation="restarts">
+ <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 access these headers properly.
+ </para>
+ </listitem>
+</orderedlist>
+</preface>
+
+<!-- Chapter 01 : Compile Time Checks -->
+<chapter xml:id="manual.ext.compile_checks" xreflabel="Compile Time Checks"><info><title>Compile Time Checks</title></info>
+<?dbhtml filename="ext_compile_checks.html"?>
+
+ <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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
+ Boost libraries</link>, 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
+ <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
+ 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 : Profile Mode -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="profile_mode.xml">
+</xi:include>
+
+
+<!-- Chapter 05 : Allocators -->
+<chapter xml:id="manual.ext.allocator" xreflabel="Allocators"><info><title>Allocators</title></info>
+<?dbhtml filename="ext_allocators.html"?>
+
+
+ <!-- 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 06 : Containers -->
+<chapter xml:id="manual.ext.containers" xreflabel="Containers"><info><title>Containers</title></info>
+<?dbhtml filename="ext_containers.html"?>
+
+ <para>
+ </para>
+ <section xml:id="manual.ext.containers.pbds" xreflabel="Policy Based Data Structures"><info><title>Policy Based Data Structures</title></info>
+
+ <para>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here</link>.
+ </para>
+ </section>
+
+ <section xml:id="manual.ext.containers.sgi" xreflabel="SGI ext"><info><title>HP/SGI</title></info>
+
+ <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&lt;bool&gt;</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&lt;N&gt;</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 (&lt;=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&lt;N&gt;," then their names and signatures are:
+</para>
+ <programlisting>
+ bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos);
+ bitset&lt;N&gt;&amp; _Unchecked_set (size_t pos, int val);
+ bitset&lt;N&gt;&amp; _Unchecked_reset (size_t pos);
+ bitset&lt;N&gt;&amp; _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>
+ </section>
+
+
+ <section xml:id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"><info><title>Deprecated HP/SGI</title></info>
+
+
+ <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>
+ &lt;hash_map&gt;
+ &lt;hash_set&gt;
+ &lt;rope&gt;
+ &lt;slist&gt;
+ &lt;rb_tree&gt;
+ </programlisting>
+ <para>are all here;
+ <code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code>
+ are deprecated but available as backwards-compatible extensions,
+ as discussed further below. <code>&lt;rope&gt;</code> is the
+ SGI specialization for large strings ("rope,"
+ "large strings," get it? Love that geeky humor.)
+ <code>&lt;slist&gt;</code> is a singly-linked list, for when the
+ doubly-linked <code>list&lt;&gt;</code> is too much space
+ overhead, and <code>&lt;rb_tree&gt;</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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/HashFunction.html">hashing
+ function</link> 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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/hash.html">hash</link>.
+ 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>
+
+ </section>
+</chapter>
+
+<!-- Chapter 07 : Utilities -->
+<chapter xml:id="manual.ext.util" xreflabel="Utilities"><info><title>Utilities</title></info>
+<?dbhtml filename="ext_utilities.html"?>
+
+ <para>
+ The &lt;functional&gt; 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&lt;int&gt;(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 08 : Algorithms -->
+<chapter xml:id="manual.ext.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info>
+<?dbhtml filename="ext_algorithms.html"?>
+
+<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 09 : Numerics -->
+<chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info>
+<?dbhtml filename="ext_numerics.html"?>
+
+<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&gt;=0. In the
+ case of n == 0, returns the identity element 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 10 : Iterators -->
+<chapter xml:id="manual.ext.iterators" xreflabel="Iterators"><info><title>Iterators</title></info>
+<?dbhtml filename="ext_iterators.html"?>
+
+<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 11 : IO -->
+<chapter xml:id="manual.ext.io" xreflabel="IO"><info><title>Input and Output</title></info>
+<?dbhtml filename="ext_io.html"?>
+
+
+ <para>
+ Extensions allowing <code>filebuf</code>s to be constructed from
+ "C" types like FILE*s and file descriptors.
+ </para>
+
+ <section xml:id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"><info><title>Derived filebufs</title></info>
+
+
+ <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>&lt;ext/stdio_filebuf.h&gt;</code> contains
+ a derived class called
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00074.html"><code>__gnu_cxx::stdio_filebuf</code></link>.
+ 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 RWLock class.
+ <!-- url="http://suter.home.cern.ch/suter/RWLock.html" -->
+ </para>
+
+ <para>
+ </para>
+ </section>
+</chapter>
+
+<!-- Chapter 12 : Demangling -->
+<chapter xml:id="manual.ext.demangle" xreflabel="Demangling"><info><title>Demangling</title></info>
+<?dbhtml filename="ext_demangling.html"?>
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01115.html">source
+ documentation for <code>namespace abi</code></link> 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 &lt;exception&gt;
+#include &lt;iostream&gt;
+#include &lt;cxxabi.h&gt;
+
+struct empty { };
+
+template &lt;typename T, int N&gt;
+ struct bar { };
+
+
+int main()
+{
+ int status;
+ char *realname;
+
+ // exception classes not in &lt;stdexcept&gt;, thrown by the implementation
+ // instead of the user
+ std::bad_exception e;
+ realname = abi::__cxa_demangle(e.what(), 0, 0, &amp;status);
+ std::cout &lt;&lt; e.what() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
+ free(realname);
+
+
+ // typeid
+ bar&lt;empty,17&gt; u;
+ const std::type_info &amp;ti = typeid(u);
+
+ realname = abi::__cxa_demangle(ti.name(), 0, 0, &amp;status);
+ std::cout &lt;&lt; ti.name() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
+ free(realname);
+
+ return 0;
+}
+ </programlisting>
+ <para>
+ This prints
+ </para>
+
+ <screen>
+ <computeroutput>
+ St13bad_exception =&gt; std::bad_exception : 0
+ 3barI5emptyLi17EE =&gt; bar&lt;empty, 17&gt; : 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 13 : Concurrency -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency_extensions.xml">
+</xi:include>
+
+</part>
diff --git a/libstdc++-v3/doc/xml/manual/internals.xml b/libstdc++-v3/doc/xml/manual/internals.xml
new file mode 100644
index 000000000..72af0b835
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/internals.xml
@@ -0,0 +1,549 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="appendix.porting.internals" xreflabel="Portin Internals">
+<?dbhtml filename="internals.html"?>
+
+<info><title>Porting to New Hardware or Operating Systems</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ internals
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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>
+
+
+<section xml:id="internals.os"><info><title>Operating System</title></info>
+
+
+<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>
+</section>
+
+
+<section xml:id="internals.cpu"><info><title>CPU</title></info>
+
+
+<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>&lt;CPU&gt;-&lt;vendor&gt;-&lt;OS&gt;</code>, you
+name your configuration directory <code>config/cpu/&lt;CPU&gt;</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>
+
+</section>
+
+
+<section xml:id="internals.char_types"><info><title>Character Types</title></info>
+
+
+<para>The library requires that you provide three header files to implement
+character classification, analogous to that provided by the C libraries
+<code>&lt;ctype.h&gt;</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>&lt;ctype.h&gt;</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>&lt;ctype.h&gt;</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>&lt;ctype.h&gt;</code>. They can
+be given symbolically (as above), or numerically, if you prefer. You do
+not have to include <code>&lt;ctype.h&gt;</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&lt;char&gt;::ctype</code>
+constructor. Here is the IRIX example:
+ </para>
+
+<programlisting>
+ctype&lt;char&gt;::ctype(const mask* __table = 0, bool __del = false,
+ size_t __refs = 0)
+ : _Ctype_nois&lt;char&gt;(__refs), _M_del(__table != 0 &amp;&amp; __del),
+ _M_toupper(NULL),
+ _M_tolower(NULL),
+ _M_ctable(NULL),
+ _M_table(!__table
+ ? (const mask*) (__libc_attr._ctype_tbl-&gt;_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&lt;char&gt;::do_toupper(char __c) const
+ { return _toupper(__c); }
+
+ char
+ ctype&lt;char&gt;::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&lt;char&gt;::do_toupper(char* __low, const char* __high) const
+ {
+ while (__low &lt; __high)
+ {
+ *__low = do_toupper(*__low);
+ ++__low;
+ }
+ return __high;
+ }
+
+ const char*
+ ctype&lt;char&gt;::do_tolower(char* __low, const char* __high) const
+ {
+ while (__low &lt; __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&lt;char&gt;::
+ is(mask __m, char __c) const throw()
+ { return (_M_table)[(unsigned char)(__c)] &amp; __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&lt;char&gt;::
+ is(const char* __low, const char* __high, mask* __vec) const throw()
+ {
+ while (__low &lt; __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&lt;char&gt;::
+ scan_is(mask __m, const char* __low, const char* __high) const throw()
+ {
+ while (__low &lt; __high &amp;&amp; !this-&gt;is(__m, *__low))
+ ++__low;
+ return __low;
+ }
+
+ const char*
+ ctype&lt;char&gt;::
+ scan_not(mask __m, const char* __low, const char* __high) const throw()
+ {
+ while (__low &lt; __high &amp;&amp; this-&gt;is(__m, *__low))
+ ++__low;
+ return __low;
+ }
+</programlisting>
+
+</section>
+
+
+<section xml:id="internals.thread_safety"><info><title>Thread Safety</title></info>
+
+
+<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/&lt;chip&gt;/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>
+
+</section>
+
+
+<section xml:id="internals.numeric_limits"><info><title>Numeric Limits</title></info>
+
+
+<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>
+
+</section>
+
+
+<section xml:id="internals.libtool"><info><title>Libtool</title></info>
+
+
+<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>
+
+
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/intro.xml b/libstdc++-v3/doc/xml/manual/intro.xml
new file mode 100644
index 000000000..36e07b437
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/intro.xml
@@ -0,0 +1,878 @@
+<part xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="manual.intro" xreflabel="Introduction">
+<?dbhtml filename="intro.html"?>
+
+<info><title>
+ Introduction
+ <indexterm><primary>Introduction</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+<!-- Chapter 01 : Status -->
+<chapter xml:id="manual.intro.status" xreflabel="Status"><info><title>Status</title></info>
+ <?dbhtml filename="status.html"?>
+
+
+ <!-- Section 01 : Implementation Status -->
+ <section xml:id="manual.intro.status.iso" xreflabel="Status"><info><title>Implementation Status</title></info>
+
+
+ <!-- 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++ 200x -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxx200x.xml">
+ </xi:include>
+
+ <!-- Section 01.3 : Status C++ TR1 -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxxtr1.xml">
+ </xi:include>
+
+ <!-- Section 01.4 : Status C++ TR24733 -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxxtr24733.xml">
+ </xi:include>
+ </section>
+
+ <!-- Section 02 : License -->
+ <section xml:id="manual.intro.status.license" xreflabel="License"><info><title>License</title></info>
+ <?dbhtml filename="license.html"?>
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/lists.html">gcc mailing list</link>.
+ </para>
+
+ <section xml:id="manual.intro.status.license.gpl" xreflabel="License GPL"><info><title>The Code: GPL</title></info>
+
+
+ <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 class="normal">
+GCC RUNTIME LIBRARY EXCEPTION
+
+Version 3.1, 31 March 2009
+
+Copyright (C) 2009 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org">Free Software Foundation, Inc.</link>
+
+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>
+ </section>
+
+ <section xml:id="manual.intro.status.license.fdl" xreflabel="License FDL"><info><title>The Documentation: GPL, FDL</title></info>
+
+
+ <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.3"> GNU Free Documentation
+ License version 1.3</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>
+ </section>
+
+ </section>
+
+ <!-- Section 03 : Known Bugs -->
+ <section xml:id="manual.intro.status.bugs" xreflabel="Bugs"><info><title>Bugs</title></info>
+ <?dbhtml filename="bugs.html"?>
+
+
+ <section xml:id="manual.intro.status.bugs.impl" xreflabel="Bugs impl"><info><title>Implementation Bugs</title></info>
+
+ <para>
+ Information on known bugs, details on efforts to fix them, and
+ fixed bugs are all available as part of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/bugs/">GCC bug tracking system</link>,
+ with the category set to <literal>libstdc++</literal>.
+ </para>
+ </section>
+
+ <section xml:id="manual.intro.status.bugs.iso" xreflabel="Bugs iso"><info><title>Standard Bugs</title></info>
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/">ISO C++
+ Committee homepage</link>, linked to on the
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/readings.html">GCC "Readings"
+ page</link>. 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-active.html#DR">DR</link> status.
+ </para>
+
+ <variablelist>
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#5">5</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#17">17</link>:
+ <emphasis>Bad bool parsing</emphasis>
+ </term>
+ <listitem><para>Apparently extracting Boolean values was messed up...
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#19">19</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#22">22</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#23">23</link>:
+ <emphasis>Num_get overflow result</emphasis>
+ </term>
+ <listitem><para>Implement the proposed resolution.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#25">25</link>:
+ <emphasis>String operator&lt;&lt; uses width() value wrong</emphasis>
+ </term>
+ <listitem><para>Padding issues.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#48">48</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#49">49</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#50">50</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#60">60</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#63">63</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#68">68</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#74">74</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#75">75</link>:
+ <emphasis>Contradiction in codecvt::length's argument types</emphasis>
+ </term>
+ <listitem><para>Change the first parameter to <code>stateT&amp;</code> and implement
+ the new effects paragraph.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#83">83</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#90">90</link>:
+ <emphasis>Incorrect description of operator&gt;&gt; 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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#91">91</link>:
+ <emphasis>Description of operator&gt;&gt; and getline() for string&lt;&gt;
+ 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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#103">103</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#109">109</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#110">110</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#117">117</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#118">118</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#129">129</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#130">130</link>:
+ <emphasis>Return type of container::erase(iterator) differs for associative containers</emphasis>
+ </term>
+ <listitem><para>Make member <code>erase</code> return iterator for <code>set</code>, <code>multiset</code>, <code>map</code>, <code>multimap</code>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#136">136</link>:
+ <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&lt;&gt;::showmanyc() function
+ should probably not be calling <code>underflow()</code>.
+ </para></listitem></varlistentry> -->
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#167">167</link>:
+ <emphasis>Improper use of traits_type::length()</emphasis>
+ </term>
+ <listitem><para><code>op&lt;&lt;</code> with a <code>const char*</code> was
+ calculating an incorrect number of characters to write.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#169">169</link>:
+ <emphasis>Bad efficiency of overflow() mandated</emphasis>
+ </term>
+ <listitem><para>Grow efficiently the internal array object.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#171">171</link>:
+ <emphasis>Strange seekpos() semantics due to joint position</emphasis>
+ </term>
+ <listitem><para>Quite complex to summarize...
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#181">181</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#195">195</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#211">211</link>:
+ <emphasis>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</emphasis>
+ </term>
+ <listitem><para>If nothing is extracted into the string, <code>op&gt;&gt;</code> now
+ sets <code>failbit</code> (which can cause an exception, etc., etc.).
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#214">214</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#231">231</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#233">233</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#235">235</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#241">241</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#243">243</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#251">251</link>:
+ <emphasis>basic_stringbuf missing allocator_type</emphasis>
+ </term>
+ <listitem><para>This nested typedef was originally not specified.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#253">253</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#265">265</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#266">266</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#271">271</link>:
+ <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&lt;T&gt;::traits_type</code> is ambiguous.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#275">275</link>:
+ <emphasis>Wrong type in num_get::get() overloads</emphasis>
+ </term>
+ <listitem><para>Similar to 118.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#280">280</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#292">292</link>:
+ <emphasis>Effects of a.copyfmt (a)</emphasis>
+ </term>
+ <listitem><para>If <code>(this == &amp;rhs)</code> do nothing.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#300">300</link>:
+ <emphasis>List::merge() specification incomplete</emphasis>
+ </term>
+ <listitem><para>If <code>(this == &amp;x)</code> do nothing.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#303">303</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#305">305</link>:
+ <emphasis>Default behavior of codecvt&lt;wchar_t, char,
+ mbstate_t&gt;::length()</emphasis>
+ </term>
+ <listitem><para>Do not specify what <code>codecvt&lt;wchar_t, char,
+ mbstate_t&gt;::do_length</code> must return.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#328">328</link>:
+ <emphasis>Bad sprintf format modifier in
+ money_put&lt;&gt;::do_put()</emphasis>
+ </term>
+ <listitem><para>Change the format string to "%.0Lf".
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#365">365</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#387">387</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#389">389</link>:
+ <emphasis>Const overload of valarray::operator[] returns
+ by value</emphasis>
+ </term>
+ <listitem><para>Change it to return a <code>const T&amp;</code>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#396">396</link>:
+ <emphasis>what are characters zero and one</emphasis>
+ </term>
+ <listitem><para>Implement the proposed resolution.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#402">402</link>:
+ <emphasis>Wrong new expression in [some_]allocator::construct</emphasis>
+ </term>
+ <listitem><para>Replace "new" with "::new".
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#408">408</link>:
+ <emphasis>
+ Is vector&lt;reverse_iterator&lt;char*&gt; &gt; forbidden?
+ </emphasis>
+ </term>
+ <listitem><para>Tweak the debug-mode checks in _Safe_iterator.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#409">409</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#431">431</link>:
+ <emphasis>Swapping containers with unequal allocators</emphasis>
+ </term>
+ <listitem><para>Implement Option 3, as per N1599.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#432">432</link>:
+ <emphasis>stringbuf::overflow() makes only one write position
+ available</emphasis>
+ </term>
+ <listitem><para>Implement the resolution, beyond DR 169.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#434">434</link>:
+ <emphasis>bitset::to_string() hard to use</emphasis>
+ </term>
+ <listitem><para>Add three overloads, taking fewer template arguments.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#438">438</link>:
+ <emphasis>Ambiguity in the "do the right thing" clause</emphasis>
+ </term>
+ <listitem><para>Implement the resolution, basically cast less.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#453">453</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#455">455</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#464">464</link>:
+ <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&amp;)</code> to <code>std::map</code>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#508">508</link>:
+ <emphasis>Bad parameters for ranlux64_base_01</emphasis>
+ </term>
+ <listitem><para>Fix the parameters.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#512">512</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#526">526</link>:
+ <emphasis>Is it undefined if a function in the standard changes in
+ parameters?</emphasis>
+ </term>
+ <listitem><para>Use &amp;value.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#538">538</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#539">539</link>:
+ <emphasis>partial_sum and adjacent_difference should mention
+ requirements</emphasis>
+ </term>
+ <listitem><para>We were almost doing the right thing, just use std::move
+ in adjacent_difference.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#541">541</link>:
+ <emphasis>shared_ptr template assignment and void</emphasis>
+ </term>
+ <listitem><para>Add an auto_ptr&lt;void&gt; specialization.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#543">543</link>:
+ <emphasis>valarray slice default constructor</emphasis>
+ </term>
+ <listitem><para>Follow the straightforward proposed resolution.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#550">550</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#586">586</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#596">596</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#630">630</link>:
+ <emphasis>arrays of valarray</emphasis>
+ </term>
+ <listitem><para>Implement the simple resolution.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#660">660</link>:
+ <emphasis>Missing bitwise operations</emphasis>
+ </term>
+ <listitem><para>Add the missing operations.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#691">691</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#693">693</link>:
+ <emphasis>std::bitset::all() missing</emphasis>
+ </term>
+ <listitem><para>Add it, consistently with the discussion.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#695">695</link>:
+ <emphasis>ctype&lt;char&gt;::classic_table() not accessible</emphasis>
+ </term>
+ <listitem><para>Make the member functions table and classic_table public.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#696">696</link>:
+ <emphasis>istream::operator&gt;&gt;(int&amp;) broken</emphasis>
+ </term>
+ <listitem><para>Implement the straightforward resolution.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#761">761</link>:
+ <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><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#775">775</link>:
+ <emphasis>Tuple indexing should be unsigned?</emphasis>
+ </term>
+ <listitem><para>Implement the int -&gt; size_t replacements.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#776">776</link>:
+ <emphasis>Undescribed assign function of std::array</emphasis>
+ </term>
+ <listitem><para>In C++0x mode, remove assign, add fill.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#781">781</link>:
+ <emphasis>std::complex should add missing C99 functions</emphasis>
+ </term>
+ <listitem><para>In C++0x mode, add std::proj.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#809">809</link>:
+ <emphasis>std::swap should be overloaded for array types</emphasis>
+ </term>
+ <listitem><para>Add the overload.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#844">844</link>:
+ <emphasis>complex pow return type is ambiguous</emphasis>
+ </term>
+ <listitem><para>In C++0x mode, remove the pow(complex&lt;T&gt;, int) signature.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#853">853</link>:
+ <emphasis>to_string needs updating with zero and one</emphasis>
+ </term>
+ <listitem><para>Update / add the signatures.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#865">865</link>:
+ <emphasis>More algorithms that throw away information</emphasis>
+ </term>
+ <listitem><para>The traditional HP / SGI return type and value is blessed
+ by the resolution of the DR.
+ </para></listitem></varlistentry>
+ </variablelist>
+
+ </section>
+ </section>
+</chapter>
+
+
+<!-- Chapter 02 : Setup -->
+<chapter xml:id="manual.intro.setup" xreflabel="Setup"><info><title>Setup</title></info>
+ <?dbhtml filename="setup.html"?>
+
+
+ <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 -->
+<section xml:id="manual.intro.setup.make" xreflabel="Make"><info><title>Make</title></info>
+ <?dbhtml filename="make.html"?>
+
+ <para>If you have never done this before, you should read the basic
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/">GCC Installation
+ Instructions</link> first. Read <emphasis>all of them</emphasis>.
+ <emphasis>Twice.</emphasis>
+ </para>
+
+<para>Then type: <command>make</command>, and congratulations, you've
+started to build.
+</para>
+
+</section>
+
+</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/libstdc++-v3/doc/xml/manual/io.xml b/libstdc++-v3/doc/xml/manual/io.xml
new file mode 100644
index 000000000..339ac1f45
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/io.xml
@@ -0,0 +1,649 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.io" xreflabel="Input and Output">
+<?dbhtml filename="io.html"?>
+
+<info><title>
+ Input and Output
+ <indexterm><primary>Input and Output</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<!-- Sect1 01 : Iostream Objects -->
+<section xml:id="std.io.objects" xreflabel="IO Objects"><info><title>Iostream Objects</title></info>
+<?dbhtml filename="iostream_objects.html"?>
+
+
+ <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
+ &lt;iostream&gt; 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>&lt;iosfwd&gt;</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 &lt;iosfwd&gt;
+
+ class MyClass
+ {
+ ....
+ std::ifstream&amp; input_file;
+ };
+
+ extern std::ostream&amp; operator&lt;&lt; (std::ostream&amp;, MyClass&amp;);
+ </programlisting>
+ <para><emphasis>&lt;ios&gt;</emphasis> declares the base classes for the entire
+ I/O stream hierarchy, std::ios_base and std::basic_ios&lt;charT&gt;, 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>&lt;streambuf&gt;</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>&lt;istream&gt;</emphasis>/<emphasis>&lt;ostream&gt;</emphasis> are
+ the headers to include when you are using the &gt;&gt;/&lt;&lt;
+ interface, or any of the other abstract stream formatting functions.
+ For example,
+ </para>
+ <programlisting>
+ #include &lt;istream&gt;
+
+ std::ostream&amp; operator&lt;&lt; (std::ostream&amp; os, MyClass&amp; c)
+ {
+ return os &lt;&lt; c.data1() &lt;&lt; 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>&lt;iomanip&gt;</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 &lt;&lt; setw(3);</code> or
+ <code>is &gt;&gt; setbase(8);</code>, you must include &lt;iomanip&gt;.
+ </para>
+ <para><emphasis>&lt;sstream&gt;</emphasis>/<emphasis>&lt;fstream&gt;</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>&lt;iostream&gt;</emphasis> provides the eight standard
+ global objects (cin, cout, etc). To do this correctly, this header
+ also provides the contents of the &lt;istream&gt; and &lt;ostream&gt;
+ headers, but nothing else. The contents of this header look like
+ </para>
+ <programlisting>
+ #include &lt;ostream&gt;
+ #include &lt;istream&gt;
+
+ 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 &lt;iostream&gt; 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 &lt;iostream&gt; 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>
+
+</section>
+
+<!-- Sect1 02 : Stream Buffers -->
+<section xml:id="std.io.streambufs" xreflabel="Stream Buffers"><info><title>Stream Buffers</title></info>
+<?dbhtml filename="streambufs.html"?>
+
+
+ <section xml:id="io.streambuf.derived" xreflabel="Derived streambuf Classes"><info><title>Derived streambuf Classes</title></info>
+
+ <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:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.angelikalanger.com/iostreams.html">Standard C++
+ IOStreams and Locales</link> by Langer and Kreft, ISBN 0-201-18395-1, and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.josuttis.com/libbook/">The C++ Standard Library</link>
+ 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 &lt;iostream&gt;
+ #include &lt;streambuf&gt;
+ #include &lt;locale&gt;
+ #include &lt;cstdio&gt;
+
+ 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&lt;char&gt;(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(&amp;ob);
+
+ out &lt;&lt; "31 hexadecimal: "
+ &lt;&lt; std::hex &lt;&lt; 31 &lt;&lt; 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 in this article by James Kanze:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kanze.james.neuf.fr/articles/fltrsbf1.html">Filtering
+ Streambufs</link>.
+ </para>
+
+ </section>
+
+ <section xml:id="io.streambuf.buffering" xreflabel="Buffering"><info><title>Buffering</title></info>
+
+ <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 &lt;&lt; "a line of text" &lt;&lt; endl;
+ output &lt;&lt; some_data_variable &lt;&lt; endl;
+ output &lt;&lt; "another line of text" &lt;&lt; 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 &lt;&lt; "a line of text\n"
+ &lt;&lt; some_data_variable &lt;&lt; '\n'
+ &lt;&lt; "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 &lt;&lt; ...... &lt;&lt; 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()-&gt;pubsetbuf(0,0);
+ is.rdbuf()-&gt;pubsetbuf(0,0);
+
+ os.open("/foo/bar/baz");
+ is.open("/qux/quux/quuux");
+ ...
+ os &lt;&lt; "this data is written immediately\n";
+ is &gt;&gt; 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>
+
+ </section>
+</section>
+
+<!-- Sect1 03 : Memory-based Streams -->
+<section xml:id="std.io.memstreams" xreflabel="Memory Streams"><info><title>Memory Based Streams</title></info>
+<?dbhtml filename="stringstreams.html"?>
+
+ <section xml:id="std.io.memstreams.compat" xreflabel="Compatibility strstream"><info><title>Compatibility With strstream</title></info>
+
+ <para>
+ </para>
+ <para>Stringstreams (defined in the header <code>&lt;sstream&gt;</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 Sect1 21 (Strings),
+ <link linkend="strings.string.Cstring"> describing how to
+ format strings</link>.
+ </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>&lt;&lt;</code> and
+ <code>&gt;&gt;</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>&lt;&lt;</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>&gt;&gt;</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>&lt;&lt;</code>/<code>&gt;&gt;</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>
+
+
+ </section>
+</section>
+
+<!-- Sect1 04 : File-based Streams -->
+<section xml:id="std.io.filestreams" xreflabel="File Streams"><info><title>File Based Streams</title></info>
+<?dbhtml filename="fstreams.html"?>
+
+
+ <section xml:id="std.io.filestreams.copying_a_file" xreflabel="Copying a File"><info><title>Copying a File</title></info>
+
+ <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 &lt;fstream&gt;
+
+ 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 &lt;&lt; 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 chaptericular, 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&lt;&lt;</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 chapter 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 &lt;&lt; IN.rdbuf();</programlisting>
+ <para>So what <emphasis>was</emphasis> happening with OUT&lt;&lt;IN? Undefined
+ behavior, since that chaptericular &lt;&lt; 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>
+
+ </section>
+
+ <section xml:id="std.io.filestreams.binary" xreflabel="Binary Input and Output"><info><title>Binary Input and Output</title></info>
+
+ <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>&lt;&lt;/&gt;&gt;</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"
+ covers a lot of ground), 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 chapter of the C++ implementation,
+ possibly the runtime system).
+ </para>
+ <para>Second, using <code>&lt;&lt;</code> to write and <code>&gt;&gt;</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
+ &lt;&lt;/&gt;&gt; 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.
+ </para>
+ <para>
+ An instructive thread from comp.lang.c++.moderated delved off into
+ this topic starting more or less at
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://groups.google.com/group/comp.std.c++/browse_thread/thread/f87b4abd7954a87/946a3eb9921e382d?q=comp.std.c%2B%2B+binary+iostream#946a3eb9921e382d">this</link>
+ post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++
+ and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl.
+ </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>
+ </section>
+
+</section>
+
+<!-- Sect1 03 : Interacting with C -->
+<section xml:id="std.io.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
+<?dbhtml filename="io_and_c.html"?>
+
+
+
+ <section xml:id="std.io.c.FILE" xreflabel="Using FILE* and file descriptors"><info><title>Using FILE* and file descriptors</title></info>
+
+ <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>
+ </section>
+
+ <section xml:id="std.io.c.sync" xreflabel="Performance Issues"><info><title>Performance</title></info>
+
+ <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 &lt;iostream&gt;
+ #include &lt;cstdio&gt;
+
+ std::cout &lt;&lt; "Hel";
+ std::printf ("lo, worl");
+ std::cout &lt;&lt; "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 counterchapters). File stream
+ objects that you declare yourself have no such requirement and are fully
+ buffered.
+ </para>
+
+
+ </section>
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/iterators.xml b/libstdc++-v3/doc/xml/manual/iterators.xml
new file mode 100644
index 000000000..bcfa30cd5
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/iterators.xml
@@ -0,0 +1,185 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.iterators" xreflabel="Iterators">
+<?dbhtml filename="iterators.html"?>
+
+<info><title>
+ Iterators
+ <indexterm><primary>Iterators</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<!-- Sect1 01 : Predefined -->
+<section xml:id="std.iterators.predefined" xreflabel="Predefined"><info><title>Predefined</title></info>
+
+
+ <section xml:id="iterators.predefined.vs_pointers" xreflabel="Versus Pointers"><info><title>Iterators vs. Pointers</title></info>
+
+ <para>
+ The following
+FAQ <link linkend="faq.iterator_as_pod">entry</link> 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 sect1 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>
+
+
+ </section>
+
+ <section xml:id="iterators.predefined.end" xreflabel="end() Is One Past the End"><info><title>One Past the End</title></info>
+
+
+ <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 inheritnum="ignore" continuation="restarts">
+ <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 chapter 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>
+
+ </section>
+</section>
+
+<!-- Sect1 02 : Stream -->
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/locale.xml b/libstdc++-v3/doc/xml/manual/locale.xml
new file mode 100644
index 000000000..4dabea41f
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/locale.xml
@@ -0,0 +1,618 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.localization.locales.locale" xreflabel="Locale">
+
+<info><title>locale</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ locale
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+Describes the basic locale object, including nested
+classes id, facet, and the reference-counted implementation object,
+class _Impl.
+</para>
+
+<section xml:id="locales.locale.req"><info><title>Requirements</title></info>
+
+
+<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 object that can be used to query for the
+thousands separator in the 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&lt;user-defined-type&gt;</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>
+</section>
+
+<section xml:id="locales.locale.design"><info><title>Design</title></info>
+
+
+<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>
+
+</section>
+
+<section xml:id="locales.locale.impl"><info><title>Implementation</title></info>
+
+
+ <section xml:id="locale.impl.c"><info><title>Interacting with "C" locales</title></info>
+
+
+<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>
+
+ </section>
+</section>
+
+<section xml:id="locales.locale.future"><info><title>Future</title></info>
+
+
+<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>
+</section>
+
+<bibliography xml:id="locales.locale.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <citetitle>
+ The GNU C Library
+ </citetitle>
+ <author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2007</year>
+ <holder>FSF</holder>
+ </copyright>
+ <pagenums>
+ Chapters 6 Character Set Handling and 7 Locales and
+ Internationalization
+ </pagenums>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Correspondence
+ </citetitle>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2002</year>
+ <holder/>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 14882:1998 Programming languages - C++
+ </citetitle>
+ <copyright>
+ <year>1998</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 9899:1999 Programming languages - C
+ </citetitle>
+ <copyright>
+ <year>1999</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opengroup.org/austin/" class="uri">
+ </biblioid>
+ <citetitle>
+ System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
+ </citetitle>
+ <copyright>
+ <year>2008</year>
+ <holder>
+ The Open Group/The Institute of Electrical and Electronics
+ Engineers, Inc.
+ </holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ The C++ Programming Language, Special Edition
+ </citetitle>
+ <author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley, Inc.</holder>
+ </copyright>
+ <pagenums>Appendix D</pagenums>
+ <publisher>
+ <publishername>
+ Addison Wesley
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Standard C++ IOStreams and Locales
+ </citetitle>
+ <subtitle>
+ Advanced Programmer's Guide and Reference
+ </subtitle>
+ <author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author>
+ <author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley Longman, Inc.</holder>
+ </copyright>
+ <publisher>
+ <publishername>
+ Addison Wesley Longman
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/localization.xml b/libstdc++-v3/doc/xml/manual/localization.xml
new file mode 100644
index 000000000..b46e707fc
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/localization.xml
@@ -0,0 +1,51 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.localization" xreflabel="Localization">
+<?dbhtml filename="localization.html"?>
+
+<info><title>
+ Localization
+ <indexterm><primary>Localization</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<!-- Section 01 : Locale -->
+<section xml:id="std.localization.locales" xreflabel="Locales"><info><title>Locales</title></info>
+<?dbhtml filename="locales.html"?>
+
+
+ <!-- Section 01 : locale -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="locale.xml">
+ </xi:include>
+</section>
+
+<!-- Section 02 : Facet -->
+<section xml:id="std.localization.facet" xreflabel="Facets"><info><title>Facets</title></info>
+<?dbhtml filename="facets.html"?>
+
+
+ <!-- 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>
+</section>
+
+<!-- Section 03 : Interacting with C -->
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/messages.xml b/libstdc++-v3/doc/xml/manual/messages.xml
new file mode 100644
index 000000000..753b965e6
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/messages.xml
@@ -0,0 +1,566 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.localization.facet.messages" xreflabel="Messages">
+<?dbhtml filename="messages.html"?>
+
+<info><title>messages</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ messages
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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>
+
+<section xml:id="facet.messages.req"><info><title>Requirements</title></info>
+
+
+<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&amp;, const locale&amp;) const</code>
+</para>
+
+<para>
+<code>string_type get(catalog, int, int, const string_type&amp;) 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&amp;, const locale&amp;) 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&amp;) 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>
+
+
+</section>
+
+<section xml:id="facet.messages.design"><info><title>Design</title></info>
+
+
+<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&amp; </code> argument, for instance, instead of just <code>const
+char*</code>? Or, why specify a <code>const locale&amp;</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>
+
+</section>
+
+<section xml:id="facet.messages.impl"><info><title>Implementation</title></info>
+
+
+ <section xml:id="messages.impl.models"><info><title>Models</title></info>
+
+ <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>
+
+ </section>
+
+ <section xml:id="messages.impl.gnu"><info><title>The GNU Model</title></info>
+
+
+ <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&lt;messages&lt;char&gt; &gt;(loc_de).open("libstdc++", locale(), dir);
+ </code>
+ </para>
+ </listitem>
+</itemizedlist>
+
+ </section>
+</section>
+
+<section xml:id="facet.messages.use"><info><title>Use</title></info>
+
+ <para>
+ A simple example using the GNU model of message conversion.
+ </para>
+
+<programlisting>
+#include &lt;iostream&gt;
+#include &lt;locale&gt;
+using namespace std;
+
+void test01()
+{
+ typedef messages&lt;char&gt;::catalog catalog;
+ const char* dir =
+ "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";
+ const locale loc_de("de_DE");
+ const messages&lt;char&gt;&amp; mssg_de = use_facet&lt;messages&lt;char&gt; &gt;(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 &lt;&lt; "please in german:" &lt;&lt; s01 &lt;&lt; '\n';
+ cout &lt;&lt; "thank you in german:" &lt;&lt; s02 &lt;&lt; '\n';
+ mssg_de.close(cat_de);
+}
+</programlisting>
+
+</section>
+
+<section xml:id="facet.messages.future"><info><title>Future</title></info>
+
+
+<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&lt;char&gt;&amp; __s, const locale&amp; __loc) const
+ </code>
+ </para>
+
+ <para>
+ <code>
+ catalog
+ open(const basic_string&lt;char&gt;&amp;, const locale&amp;, 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>
+
+</section>
+
+<bibliography xml:id="facet.messages.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <citetitle>
+ The GNU C Library
+ </citetitle>
+ <author><personname><surname>McGrath</surname><firstname>Roland</firstname></personname></author>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2007</year>
+ <holder>FSF</holder>
+ </copyright>
+ <pagenums>Chapters 6 Character Set Handling, and 7 Locales and Internationalization
+ </pagenums>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Correspondence
+ </citetitle>
+ <author><personname><surname>Drepper</surname><firstname>Ulrich</firstname></personname></author>
+ <copyright>
+ <year>2002</year>
+ <holder/>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 14882:1998 Programming languages - C++
+ </citetitle>
+ <copyright>
+ <year>1998</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ ISO/IEC 9899:1999 Programming languages - C
+ </citetitle>
+
+ <copyright>
+ <year>1999</year>
+ <holder>ISO</holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opengroup.org/austin/" class="uri">
+ </biblioid>
+ <citetitle>
+ System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
+ </citetitle>
+ <copyright>
+ <year>2008</year>
+ <holder>
+ The Open Group/The Institute of Electrical and Electronics
+ Engineers, Inc.
+ </holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ The C++ Programming Language, Special Edition
+ </citetitle>
+ <author><personname><surname>Stroustrup</surname><firstname>Bjarne</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley, Inc.</holder>
+ </copyright>
+ <pagenums>Appendix D</pagenums>
+ <publisher>
+ <publishername>
+ Addison Wesley
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Standard C++ IOStreams and Locales
+ </citetitle>
+ <subtitle>
+ Advanced Programmer's Guide and Reference
+ </subtitle>
+ <author><personname><surname>Langer</surname><firstname>Angelika</firstname></personname></author>
+ <author><personname><surname>Kreft</surname><firstname>Klaus</firstname></personname></author>
+ <copyright>
+ <year>2000</year>
+ <holder>Addison Wesley Longman, Inc.</holder>
+ </copyright>
+ <publisher>
+ <publishername>
+ Addison Wesley Longman
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://java.sun.com/reference/api/index.html" class="uri">
+ </biblioid>
+ <citetitle>
+ API Specifications, Java Platform
+ </citetitle>
+
+ <pagenums>java.util.Properties, java.text.MessageFormat,
+java.util.Locale, java.util.ResourceBundle
+ </pagenums>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/gettext/" class="uri">
+ </biblioid>
+ <citetitle>
+ GNU gettext tools, version 0.10.38, Native Language Support
+ Library and Tools.
+ </citetitle>
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/mt_allocator.xml b/libstdc++-v3/doc/xml/manual/mt_allocator.xml
new file mode 100644
index 000000000..b31b593bc
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/mt_allocator.xml
@@ -0,0 +1,555 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.ext.allocator.mt" xreflabel="mt allocator">
+<?dbhtml filename="mt_allocator.html"?>
+
+<info><title>mt_allocator</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ allocator
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+</para>
+
+<section xml:id="allocator.mt.intro"><info><title>Intro</title></info>
+
+
+<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>
+
+</section>
+
+
+<section xml:id="allocator.mt.design_issues"><info><title>Design Issues</title></info>
+
+
+<section xml:id="allocator.mt.overview"><info><title>Overview</title></info>
+
+
+
+<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&lt;bool _Thread&gt;
+ 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&lt;bool _Thread&gt;
+ struct __common_pool_policy
+
+ template&lt;typename _Tp, bool _Thread&gt;
+ 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&lt;typename _Tp, typename _Poolp = __default_policy&gt;
+ class __mt_alloc : public __mt_alloc_base&lt;_Tp&gt;, _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>
+
+</section>
+</section>
+
+<section xml:id="allocator.mt.impl"><info><title>Implementation</title></info>
+
+
+
+<section xml:id="allocator.mt.tune"><info><title>Tunable Parameters</title></info>
+
+
+<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 &lt;ext/mt_allocator.h&gt;
+
+struct pod
+{
+ int i;
+ int j;
+};
+
+int main()
+{
+ typedef pod value_type;
+ typedef __gnu_cxx::__mt_alloc&lt;value_type&gt; 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>
+
+</section>
+
+<section xml:id="allocator.mt.init"><info><title>Initialization</title></info>
+
+
+<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-&gt;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-&gt;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-&gt;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-&gt;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-&gt;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>
+
+</section>
+
+<section xml:id="allocator.mt.deallocation"><info><title>Deallocation Notes</title></info>
+
+
+<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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/ext/mt_allocator/deallocate_local-6.cc?view=markup">
+ example.</link>
+</para>
+
+</section>
+
+</section>
+
+<section xml:id="allocator.mt.example_single"><info><title>Single Thread Example</title></info>
+
+
+<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* |&lt;-+ (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 &gt; _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>
+
+</section>
+
+<section xml:id="allocator.mt.example_multi"><info><title>Multiple Thread Example</title></info>
+
+
+<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 &gt;_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>
+
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/numerics.xml b/libstdc++-v3/doc/xml/manual/numerics.xml
new file mode 100644
index 000000000..a9e866e78
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/numerics.xml
@@ -0,0 +1,145 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.numerics" xreflabel="Numerics">
+<?dbhtml filename="numerics.html"?>
+
+<info><title>
+ Numerics
+ <indexterm><primary>Numerics</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<!-- Sect1 01 : Complex -->
+<section xml:id="std.numerics.complex" xreflabel="complex"><info><title>Complex</title></info>
+<?dbhtml filename="complex.html"?>
+
+ <para>
+ </para>
+ <section xml:id="numerics.complex.processing" xreflabel="complex Processing"><info><title>complex Processing</title></info>
+
+ <para>
+ </para>
+ <para>Using <code>complex&lt;&gt;</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
+<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://david.tribble.com/text/cdiffs.htm#C99-complex">here</link>.
+ </para>
+ <para><code>complex&lt;&gt;</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&lt;&lt;</code>
+ and <code>op&gt;&gt;</code> that work with iostreams: <code>op&lt;&lt;</code>
+ prints <code>(u,v)</code> and <code>op&gt;&gt;</code> can read <code>u</code>,
+ <code>(u)</code>, and <code>(u,v)</code>.
+ </para>
+
+ </section>
+</section>
+
+<!-- Sect1 02 : Generalized Operations -->
+<section xml:id="std.numerics.generalized_ops" xreflabel="Generalized Ops"><info><title>Generalized Operations</title></info>
+<?dbhtml filename="generalized_numeric_operations.html"?>
+
+ <para>
+ </para>
+
+ <para>There are four generalized functions in the &lt;numeric&gt; header
+ that follow the same conventions as those in &lt;algorithm&gt;. 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>chapterial_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&lt;int&gt;());
+ </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>
+
+</section>
+
+<!-- Sect1 03 : Interacting with C -->
+<section xml:id="std.numerics.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
+<?dbhtml filename="numerics_and_c.html"?>
+
+
+ <section xml:id="numerics.c.array" xreflabel="Numerics vs. Arrays"><info><title>Numerics vs. Arrays</title></info>
+
+
+ <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>
+
+ </section>
+
+ <section xml:id="numerics.c.c99" xreflabel="C99"><info><title>C99</title></info>
+
+
+ <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>
+
+ </section>
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/parallel_mode.xml b/libstdc++-v3/doc/xml/manual/parallel_mode.xml
new file mode 100644
index 000000000..ec0faf9c7
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/parallel_mode.xml
@@ -0,0 +1,878 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.ext.parallel_mode" xreflabel="Parallel Mode">
+<?dbhtml filename="parallel_mode.html"?>
+
+<info><title>Parallel Mode</title>
+ <keywordset>
+ <keyword>
+ C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ parallel
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<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>
+
+
+<section xml:id="manual.ext.parallel_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
+
+
+<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>
+
+</section>
+
+<section xml:id="manual.ext.parallel_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info>
+
+
+<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>
+
+</section>
+
+<section xml:id="manual.ext.parallel_mode.using" xreflabel="Using"><info><title>Using</title></info>
+
+
+<section xml:id="parallel_mode.using.prereq_flags"><info><title>Prerequisite Compiler Flags</title></info>
+
+
+<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libgomp">implementation</link>,
+ 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>
+
+</section>
+
+<section xml:id="parallel_mode.using.parallel_mode"><info><title>Using Parallel Mode</title></info>
+
+
+<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>
+</section>
+
+<section xml:id="parallel_mode.using.specific"><info><title>Using Specific Parallel Components</title></info>
+
+
+<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 &lt;vector&gt;
+#include &lt;parallel/algorithm&gt;
+
+int main()
+{
+ std::vector&lt;int&gt; 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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+
+<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>
+
+</section>
+
+</section>
+
+<section xml:id="manual.ext.parallel_mode.design" xreflabel="Design"><info><title>Design</title></info>
+
+ <para>
+ </para>
+<section xml:id="parallel_mode.design.intro" xreflabel="Intro"><info><title>Interface Basics</title></info>
+
+
+<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&lt;typename _FIter&gt;
+ _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&lt;typename _FIter&gt;
+ _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>
+
+
+</section>
+
+<section xml:id="parallel_mode.design.tuning" xreflabel="Tuning"><info><title>Configuration and Tuning</title></info>
+
+
+
+<section xml:id="parallel_mode.design.tuning.omp" xreflabel="OpenMP Environment"><info><title>Setting up the OpenMP Environment</title></info>
+
+
+<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 &lt;stdlib.h&gt;
+#include &lt;omp.h&gt;
+
+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>
+
+</section>
+
+<section xml:id="parallel_mode.design.tuning.compile" xreflabel="Compile Switches"><info><title>Compile Time Switches</title></info>
+
+
+<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>
+
+</section>
+
+<section xml:id="parallel_mode.design.tuning.settings" xreflabel="_Settings"><info><title>Run Time Settings and Defaults</title></info>
+
+
+<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01005.html">
+ <filename class="headerfile">settings.h</filename></link>
+for complete details.
+</para>
+
+<para>
+A small example of tuning the default:
+</para>
+
+<programlisting>
+#include &lt;parallel/algorithm&gt;
+#include &lt;parallel/settings.h&gt;
+
+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>
+
+</section>
+
+</section>
+
+<section xml:id="parallel_mode.design.impl" xreflabel="Impl"><info><title>Implementation Namespaces</title></info>
+
+
+<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>
+
+</section>
+
+</section>
+
+<section xml:id="manual.ext.parallel_mode.test" xreflabel="Testing"><info><title>Testing</title></info>
+
+
+ <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>
+</section>
+
+<bibliography xml:id="parallel_mode.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <citetitle>
+ Parallelization of Bulk Operations for STL Dictionaries
+ </citetitle>
+
+ <author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname></author>
+ <author><personname><firstname>Leonor</firstname><surname>Frias</surname></personname></author>
+
+ <copyright>
+ <year>2007</year>
+ <holder/>
+ </copyright>
+
+ <publisher>
+ <publishername>
+ Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS)
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ The Multi-Core Standard Template Library
+ </citetitle>
+
+ <author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname></author>
+ <author><personname><firstname>Peter</firstname><surname>Sanders</surname></personname></author>
+ <author><personname><firstname>Felix</firstname><surname>Putze</surname></personname></author>
+
+ <copyright>
+ <year>2007</year>
+ <holder/>
+ </copyright>
+
+ <publisher>
+ <publishername>
+ Euro-Par 2007: Parallel Processing. (LNCS 4641)
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+</bibliography>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/prerequisites.xml b/libstdc++-v3/doc/xml/manual/prerequisites.xml
new file mode 100644
index 000000000..0a41c44ea
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/prerequisites.xml
@@ -0,0 +1,160 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.setup.prereq" xreflabel="Prerequisites">
+<?dbhtml filename="prerequisites.html"?>
+
+<info><title>Prerequisites</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ Prerequisites
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+ Because libstdc++ is part of GCC, the primary source for
+ installation instructions is
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/">the GCC install page</link>.
+ In particular, list of prerequisite software needed to build the library
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/prerequisites.html">
+ starts with those requirements.</link> 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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="ftp://sources.redhat.com/pub/binutils/">
+ ftp://sources.redhat.com/pub/binutils</link>.
+ 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>
+ To generate the API documentation from the sources you will need
+ Doxygen, see <link linkend="appendix.porting.doc">Documentation
+ Hacking</link> in the appendix for full details.
+ </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 4.6.0 and later, this
+ means that glibc 2.3 or later is required.
+ </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_GB ISO-8859-1
+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
+ru_RU.ISO-8859-5 ISO-8859-5
+ru_RU.UTF-8 UTF-8
+se_NO.UTF-8 UTF-8
+ta_IN UTF-8
+zh_TW BIG5
+</programlisting>
+
+ <para>Failure to have installed the underlying "C" library
+ locale information for any of the above regions means that
+ the corresponding C++ named locale will not work: because of
+ this, the libstdc++ testsuite will skip named locale tests
+ which need missing information. If this isn't an issue, don't
+ worry about it. If a named locale is needed, the underlying
+ locale information must be installed. Note that rebuilding
+ libstdc++ after "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>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/profile_mode.xml b/libstdc++-v3/doc/xml/manual/profile_mode.xml
new file mode 100644
index 000000000..cb4db6732
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/profile_mode.xml
@@ -0,0 +1,1718 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.ext.profile_mode" xreflabel="Profile Mode">
+<?dbhtml filename="profile_mode.html"?>
+
+<info><title>Profile Mode</title>
+ <keywordset>
+ <keyword>
+ C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ <keyword>
+ profile
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+
+<section xml:id="manual.ext.profile_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
+
+ <para>
+ <emphasis>Goal: </emphasis>Give performance improvement advice based on
+ recognition of suboptimal usage patterns of the standard library.
+ </para>
+
+ <para>
+ <emphasis>Method: </emphasis>Wrap the standard library code. Insert
+ calls to an instrumentation library to record the internal state of
+ various components at interesting entry/exit points to/from the standard
+ library. Process trace, recognize suboptimal patterns, give advice.
+ For details, see
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dx.doi.org/10.1109/CGO.2009.36">paper presented at
+ CGO 2009</link>.
+ </para>
+ <para>
+ <emphasis>Strengths: </emphasis>
+<itemizedlist>
+ <listitem><para>
+ Unintrusive solution. The application code does not require any
+ modification.
+ </para></listitem>
+ <listitem><para> The advice is call context sensitive, thus capable of
+ identifying precisely interesting dynamic performance behavior.
+ </para></listitem>
+ <listitem><para>
+ The overhead model is pay-per-view. When you turn off a diagnostic class
+ at compile time, its overhead disappears.
+ </para></listitem>
+</itemizedlist>
+ </para>
+ <para>
+ <emphasis>Drawbacks: </emphasis>
+<itemizedlist>
+ <listitem><para>
+ You must recompile the application code with custom options.
+ </para></listitem>
+ <listitem><para>You must run the application on representative input.
+ The advice is input dependent.
+ </para></listitem>
+ <listitem><para>
+ The execution time will increase, in some cases by factors.
+ </para></listitem>
+</itemizedlist>
+ </para>
+
+
+<section xml:id="manual.ext.profile_mode.using" xreflabel="Using"><info><title>Using the Profile Mode</title></info>
+
+
+ <para>
+ This is the anticipated common workflow for program <code>foo.cc</code>:
+<programlisting>
+$ cat foo.cc
+#include &lt;vector&gt;
+int main() {
+ vector&lt;int&gt; v;
+ for (int k = 0; k &lt; 1024; ++k) v.insert(v.begin(), k);
+}
+
+$ g++ -D_GLIBCXX_PROFILE foo.cc
+$ ./a.out
+$ cat libstdcxx-profile.txt
+vector-to-list: improvement = 5: call stack = 0x804842c ...
+ : advice = change std::vector to std::list
+vector-size: improvement = 3: call stack = 0x804842c ...
+ : advice = change initial container size from 0 to 1024
+</programlisting>
+ </para>
+
+ <para>
+ Anatomy of a warning:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Warning id. This is a short descriptive string for the class
+ that this warning belongs to. E.g., "vector-to-list".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Estimated improvement. This is an approximation of the benefit expected
+ from implementing the change suggested by the warning. It is given on
+ a log10 scale. Negative values mean that the alternative would actually
+ do worse than the current choice.
+ In the example above, 5 comes from the fact that the overhead of
+ inserting at the beginning of a vector vs. a list is around 1024 * 1024 / 2,
+ which is around 10e5. The improvement from setting the initial size to
+ 1024 is in the range of 10e3, since the overhead of dynamic resizing is
+ linear in this case.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Call stack. Currently, the addresses are printed without
+ symbol name or code location attribution.
+ Users are expected to postprocess the output using, for instance, addr2line.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The warning message. For some warnings, this is static text, e.g.,
+ "change vector to list". For other warnings, such as the one above,
+ the message contains numeric advice, e.g., the suggested initial size
+ of the vector.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Three files are generated. <code>libstdcxx-profile.txt</code>
+ contains human readable advice. <code>libstdcxx-profile.raw</code>
+ contains implementation specific data about each diagnostic.
+ Their format is not documented. They are sufficient to generate
+ all the advice given in <code>libstdcxx-profile.txt</code>. The advantage
+ of keeping this raw format is that traces from multiple executions can
+ be aggregated simply by concatenating the raw traces. We intend to
+ offer an external utility program that can issue advice from a trace.
+ <code>libstdcxx-profile.conf.out</code> lists the actual diagnostic
+ parameters used. To alter parameters, edit this file and rename it to
+ <code>libstdcxx-profile.conf</code>.
+ </para>
+
+ <para>Advice is given regardless whether the transformation is valid.
+ For instance, we advise changing a map to an unordered_map even if the
+ application semantics require that data be ordered.
+ We believe such warnings can help users understand the performance
+ behavior of their application better, which can lead to changes
+ at a higher abstraction level.
+ </para>
+
+</section>
+
+<section xml:id="manual.ext.profile_mode.tuning" xreflabel="Tuning"><info><title>Tuning the Profile Mode</title></info>
+
+
+ <para>Compile time switches and environment variables (see also file
+ profiler.h). Unless specified otherwise, they can be set at compile time
+ using -D_&lt;name&gt; or by setting variable &lt;name&gt;
+ in the environment where the program is run, before starting execution.
+ <itemizedlist>
+ <listitem><para>
+ <code>_GLIBCXX_PROFILE_NO_&lt;diagnostic&gt;</code>:
+ disable specific diagnostics.
+ See section Diagnostics for possible values.
+ (Environment variables not supported.)
+ </para></listitem>
+ <listitem><para>
+ <code>_GLIBCXX_PROFILE_TRACE_PATH_ROOT</code>: set an alternative root
+ path for the output files.
+ </para></listitem>
+ <listitem><para>_GLIBCXX_PROFILE_MAX_WARN_COUNT: set it to the maximum
+ number of warnings desired. The default value is 10.</para></listitem>
+ <listitem><para>
+ <code>_GLIBCXX_PROFILE_MAX_STACK_DEPTH</code>: if set to 0,
+ the advice will
+ be collected and reported for the program as a whole, and not for each
+ call context.
+ This could also be used in continuous regression tests, where you
+ just need to know whether there is a regression or not.
+ The default value is 32.
+ </para></listitem>
+ <listitem><para>
+ <code>_GLIBCXX_PROFILE_MEM_PER_DIAGNOSTIC</code>:
+ set a limit on how much memory to use for the accounting tables for each
+ diagnostic type. When this limit is reached, new events are ignored
+ until the memory usage decreases under the limit. Generally, this means
+ that newly created containers will not be instrumented until some
+ live containers are deleted. The default is 128 MB.
+ </para></listitem>
+ <listitem><para>
+ <code>_GLIBCXX_PROFILE_NO_THREADS</code>:
+ Make the library not use threads. If thread local storage (TLS) is not
+ available, you will get a preprocessor error asking you to set
+ -D_GLIBCXX_PROFILE_NO_THREADS if your program is single-threaded.
+ Multithreaded execution without TLS is not supported.
+ (Environment variable not supported.)
+ </para></listitem>
+ <listitem><para>
+ <code>_GLIBCXX_HAVE_EXECINFO_H</code>:
+ This name should be defined automatically at library configuration time.
+ If your library was configured without <code>execinfo.h</code>, but
+ you have it in your include path, you can define it explicitly. Without
+ it, advice is collected for the program as a whole, and not for each
+ call context.
+ (Environment variable not supported.)
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+</section>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.design" xreflabel="Design"><info><title>Design</title></info>
+
+
+<para>
+</para>
+<table frame="all">
+<title>Profile Code Location</title>
+
+<tgroup cols="2" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+
+<thead>
+ <row>
+ <entry>Code Location</entry>
+ <entry>Use</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><code>libstdc++-v3/include/std/*</code></entry>
+ <entry>Preprocessor code to redirect to profile extension headers.</entry>
+ </row>
+ <row>
+ <entry><code>libstdc++-v3/include/profile/*</code></entry>
+ <entry>Profile extension public headers (map, vector, ...).</entry>
+ </row>
+ <row>
+ <entry><code>libstdc++-v3/include/profile/impl/*</code></entry>
+ <entry>Profile extension internals. Implementation files are
+ only included from <code>impl/profiler.h</code>, which is the only
+ file included from the public headers.</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+</para>
+
+<section xml:id="manual.ext.profile_mode.design.wrapper" xreflabel="Wrapper"><info><title>Wrapper Model</title></info>
+
+ <para>
+ In order to get our instrumented library version included instead of the
+ release one,
+ we use the same wrapper model as the debug mode.
+ We subclass entities from the release version. Wherever
+ <code>_GLIBCXX_PROFILE</code> is defined, the release namespace is
+ <code>std::__norm</code>, whereas the profile namespace is
+ <code>std::__profile</code>. Using plain <code>std</code> translates
+ into <code>std::__profile</code>.
+ </para>
+ <para>
+ Whenever possible, we try to wrap at the public interface level, e.g.,
+ in <code>unordered_set</code> rather than in <code>hashtable</code>,
+ in order not to depend on implementation.
+ </para>
+ <para>
+ Mixing object files built with and without the profile mode must
+ not affect the program execution. However, there are no guarantees to
+ the accuracy of diagnostics when using even a single object not built with
+ <code>-D_GLIBCXX_PROFILE</code>.
+ Currently, mixing the profile mode with debug and parallel extensions is
+ not allowed. Mixing them at compile time will result in preprocessor errors.
+ Mixing them at link time is undefined.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.design.instrumentation" xreflabel="Instrumentation"><info><title>Instrumentation</title></info>
+
+ <para>
+ Instead of instrumenting every public entry and exit point,
+ we chose to add instrumentation on demand, as needed
+ by individual diagnostics.
+ The main reason is that some diagnostics require us to extract bits of
+ internal state that are particular only to that diagnostic.
+ We plan to formalize this later, after we learn more about the requirements
+ of several diagnostics.
+ </para>
+ <para>
+ All the instrumentation points can be switched on and off using
+ <code>-D[_NO]_GLIBCXX_PROFILE_&lt;diagnostic&gt;</code> options.
+ With all the instrumentation calls off, there should be negligible
+ overhead over the release version. This property is needed to support
+ diagnostics based on timing of internal operations. For such diagnostics,
+ we anticipate turning most of the instrumentation off in order to prevent
+ profiling overhead from polluting time measurements, and thus diagnostics.
+ </para>
+ <para>
+ All the instrumentation on/off compile time switches live in
+ <code>include/profile/profiler.h</code>.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.design.rtlib" xreflabel="Run Time Behavior"><info><title>Run Time Behavior</title></info>
+
+ <para>
+ For practical reasons, the instrumentation library processes the trace
+ partially
+ rather than dumping it to disk in raw form. Each event is processed when
+ it occurs. It is usually attached a cost and it is aggregated into
+ the database of a specific diagnostic class. The cost model
+ is based largely on the standard performance guarantees, but in some
+ cases we use knowledge about GCC's standard library implementation.
+ </para>
+ <para>
+ Information is indexed by (1) call stack and (2) instance id or address
+ to be able to understand and summarize precise creation-use-destruction
+ dynamic chains. Although the analysis is sensitive to dynamic instances,
+ the reports are only sensitive to call context. Whenever a dynamic instance
+ is destroyed, we accumulate its effect to the corresponding entry for the
+ call stack of its constructor location.
+ </para>
+
+ <para>
+ For details, see
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dx.doi.org/10.1109/CGO.2009.36">paper presented at
+ CGO 2009</link>.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.design.analysis" xreflabel="Analysis and Diagnostics"><info><title>Analysis and Diagnostics</title></info>
+
+ <para>
+ Final analysis takes place offline, and it is based entirely on the
+ generated trace and debugging info in the application binary.
+ See section Diagnostics for a list of analysis types that we plan to support.
+ </para>
+ <para>
+ The input to the analysis is a table indexed by profile type and call stack.
+ The data type for each entry depends on the profile type.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.design.cost-model" xreflabel="Cost Model"><info><title>Cost Model</title></info>
+
+ <para>
+ While it is likely that cost models become complex as we get into
+ more sophisticated analysis, we will try to follow a simple set of rules
+ at the beginning.
+ </para>
+<itemizedlist>
+ <listitem><para><emphasis>Relative benefit estimation:</emphasis>
+ The idea is to estimate or measure the cost of all operations
+ in the original scenario versus the scenario we advise to switch to.
+ For instance, when advising to change a vector to a list, an occurrence
+ of the <code>insert</code> method will generally count as a benefit.
+ Its magnitude depends on (1) the number of elements that get shifted
+ and (2) whether it triggers a reallocation.
+ </para></listitem>
+ <listitem><para><emphasis>Synthetic measurements:</emphasis>
+ We will measure the relative difference between similar operations on
+ different containers. We plan to write a battery of small tests that
+ compare the times of the executions of similar methods on different
+ containers. The idea is to run these tests on the target machine.
+ If this training phase is very quick, we may decide to perform it at
+ library initialization time. The results can be cached on disk and reused
+ across runs.
+ </para></listitem>
+ <listitem><para><emphasis>Timers:</emphasis>
+ We plan to use timers for operations of larger granularity, such as sort.
+ For instance, we can switch between different sort methods on the fly
+ and report the one that performs best for each call context.
+ </para></listitem>
+ <listitem><para><emphasis>Show stoppers:</emphasis>
+ We may decide that the presence of an operation nullifies the advice.
+ For instance, when considering switching from <code>set</code> to
+ <code>unordered_set</code>, if we detect use of operator <code>++</code>,
+ we will simply not issue the advice, since this could signal that the use
+ care require a sorted container.</para></listitem>
+</itemizedlist>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.design.reports" xreflabel="Reports"><info><title>Reports</title></info>
+
+ <para>
+There are two types of reports. First, if we recognize a pattern for which
+we have a substitute that is likely to give better performance, we print
+the advice and estimated performance gain. The advice is usually associated
+to a code position and possibly a call stack.
+ </para>
+ <para>
+Second, we report performance characteristics for which we do not have
+a clear solution for improvement. For instance, we can point to the user
+the top 10 <code>multimap</code> locations
+which have the worst data locality in actual traversals.
+Although this does not offer a solution,
+it helps the user focus on the key problems and ignore the uninteresting ones.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.design.testing" xreflabel="Testing"><info><title>Testing</title></info>
+
+ <para>
+ First, we want to make sure we preserve the behavior of the release mode.
+ You can just type <code>"make check-profile"</code>, which
+ builds and runs the whole test suite in profile mode.
+ </para>
+ <para>
+ Second, we want to test the correctness of each diagnostic.
+ We created a <code>profile</code> directory in the test suite.
+ Each diagnostic must come with at least two tests, one for false positives
+ and one for false negatives.
+ </para>
+</section>
+
+</section>
+
+<section xml:id="manual.ext.profile_mode.api" xreflabel="API"><info><title>Extensions for Custom Containers</title></info>
+
+
+ <para>
+ Many large projects use their own data structures instead of the ones in the
+ standard library. If these data structures are similar in functionality
+ to the standard library, they can be instrumented with the same hooks
+ that are used to instrument the standard library.
+ The instrumentation API is exposed in file
+ <code>profiler.h</code> (look for "Instrumentation hooks").
+ </para>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.cost_model" xreflabel="Cost Model"><info><title>Empirical Cost Model</title></info>
+
+
+ <para>
+ Currently, the cost model uses formulas with predefined relative weights
+ for alternative containers or container implementations. For instance,
+ iterating through a vector is X times faster than iterating through a list.
+ </para>
+ <para>
+ (Under development.)
+ We are working on customizing this to a particular machine by providing
+ an automated way to compute the actual relative weights for operations
+ on the given machine.
+ </para>
+ <para>
+ (Under development.)
+ We plan to provide a performance parameter database format that can be
+ filled in either by hand or by an automated training mechanism.
+ The analysis module will then use this database instead of the built in.
+ generic parameters.
+ </para>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.implementation" xreflabel="Implementation"><info><title>Implementation Issues</title></info>
+
+
+
+<section xml:id="manual.ext.profile_mode.implementation.stack" xreflabel="Stack Traces"><info><title>Stack Traces</title></info>
+
+ <para>
+ Accurate stack traces are needed during profiling since we group events by
+ call context and dynamic instance. Without accurate traces, diagnostics
+ may be hard to interpret. For instance, when giving advice to the user
+ it is imperative to reference application code, not library code.
+ </para>
+ <para>
+ Currently we are using the libc <code>backtrace</code> routine to get
+ stack traces.
+ <code>_GLIBCXX_PROFILE_STACK_DEPTH</code> can be set
+ to 0 if you are willing to give up call context information, or to a small
+ positive value to reduce run time overhead.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.implementation.symbols" xreflabel="Symbolization"><info><title>Symbolization of Instruction Addresses</title></info>
+
+ <para>
+ The profiling and analysis phases use only instruction addresses.
+ An external utility such as addr2line is needed to postprocess the result.
+ We do not plan to add symbolization support in the profile extension.
+ This would require access to symbol tables, debug information tables,
+ external programs or libraries and other system dependent information.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.implementation.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
+
+ <para>
+ Our current model is simplistic, but precise.
+ We cannot afford to approximate because some of our diagnostics require
+ precise matching of operations to container instance and call context.
+ During profiling, we keep a single information table per diagnostic.
+ There is a single lock per information table.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.implementation.stdlib-in-proflib" xreflabel="Using the Standard Library in the Runtime Library"><info><title>Using the Standard Library in the Instrumentation Implementation</title></info>
+
+ <para>
+ As much as we would like to avoid uses of libstdc++ within our
+ instrumentation library, containers such as unordered_map are very
+ appealing. We plan to use them as long as they are named properly
+ to avoid ambiguity.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.implementation.malloc-hooks" xreflabel="Malloc Hooks"><info><title>Malloc Hooks</title></info>
+
+ <para>
+ User applications/libraries can provide malloc hooks.
+ When the implementation of the malloc hooks uses stdlibc++, there can
+ be an infinite cycle between the profile mode instrumentation and the
+ malloc hook code.
+ </para>
+ <para>
+ We protect against reentrance to the profile mode instrumentation code,
+ which should avoid this problem in most cases.
+ The protection mechanism is thread safe and exception safe.
+ This mechanism does not prevent reentrance to the malloc hook itself,
+ which could still result in deadlock, if, for instance, the malloc hook
+ uses non-recursive locks.
+ XXX: A definitive solution to this problem would be for the profile extension
+ to use a custom allocator internally, and perhaps not to use libstdc++.
+ </para>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.implementation.construction-destruction" xreflabel="Construction and Destruction of Global Objects"><info><title>Construction and Destruction of Global Objects</title></info>
+
+ <para>
+ The profiling library state is initialized at the first call to a profiling
+ method. This allows us to record the construction of all global objects.
+ However, we cannot do the same at destruction time. The trace is written
+ by a function registered by <code>atexit</code>, thus invoked by
+ <code>exit</code>.
+ </para>
+</section>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.developer" xreflabel="Developer Information"><info><title>Developer Information</title></info>
+
+
+<section xml:id="manual.ext.profile_mode.developer.bigpic" xreflabel="Big Picture"><info><title>Big Picture</title></info>
+
+
+ <para>The profile mode headers are included with
+ <code>-D_GLIBCXX_PROFILE</code> through preprocessor directives in
+ <code>include/std/*</code>.
+ </para>
+
+ <para>Instrumented implementations are provided in
+ <code>include/profile/*</code>. All instrumentation hooks are macros
+ defined in <code>include/profile/profiler.h</code>.
+ </para>
+
+ <para>All the implementation of the instrumentation hooks is in
+ <code>include/profile/impl/*</code>. Although all the code gets included,
+ thus is publicly visible, only a small number of functions are called from
+ outside this directory. All calls to hook implementations must be
+ done through macros defined in <code>profiler.h</code>. The macro
+ must ensure (1) that the call is guarded against reentrance and
+ (2) that the call can be turned off at compile time using a
+ <code>-D_GLIBCXX_PROFILE_...</code> compiler option.
+ </para>
+
+</section>
+
+<section xml:id="manual.ext.profile_mode.developer.howto" xreflabel="How To Add A Diagnostic"><info><title>How To Add A Diagnostic</title></info>
+
+
+ <para>Let's say the diagnostic name is "magic".
+ </para>
+
+ <para>If you need to instrument a header not already under
+ <code>include/profile/*</code>, first edit the corresponding header
+ under <code>include/std/</code> and add a preprocessor directive such
+ as the one in <code>include/std/vector</code>:
+<programlisting>
+#ifdef _GLIBCXX_PROFILE
+# include &lt;profile/vector&gt;
+#endif
+</programlisting>
+ </para>
+
+ <para>If the file you need to instrument is not yet under
+ <code>include/profile/</code>, make a copy of the one in
+ <code>include/debug</code>, or the main implementation.
+ You'll need to include the main implementation and inherit the classes
+ you want to instrument. Then define the methods you want to instrument,
+ define the instrumentation hooks and add calls to them.
+ Look at <code>include/profile/vector</code> for an example.
+ </para>
+
+ <para>Add macros for the instrumentation hooks in
+ <code>include/profile/impl/profiler.h</code>.
+ Hook names must start with <code>__profcxx_</code>.
+ Make sure they transform
+ in no code with <code>-D_NO_GLBICXX_PROFILE_MAGIC</code>.
+ Make sure all calls to any method in namespace <code>__gnu_profile</code>
+ is protected against reentrance using macro
+ <code>_GLIBCXX_PROFILE_REENTRANCE_GUARD</code>.
+ All names of methods in namespace <code>__gnu_profile</code> called from
+ <code>profiler.h</code> must start with <code>__trace_magic_</code>.
+ </para>
+
+ <para>Add the implementation of the diagnostic.
+ <itemizedlist>
+ <listitem><para>
+ Create new file <code>include/profile/impl/profiler_magic.h</code>.
+ </para></listitem>
+ <listitem><para>
+ Define class <code>__magic_info: public __object_info_base</code>.
+ This is the representation of a line in the object table.
+ The <code>__merge</code> method is used to aggregate information
+ across all dynamic instances created at the same call context.
+ The <code>__magnitude</code> must return the estimation of the benefit
+ as a number of small operations, e.g., number of words copied.
+ The <code>__write</code> method is used to produce the raw trace.
+ The <code>__advice</code> method is used to produce the advice string.
+ </para></listitem>
+ <listitem><para>
+ Define class <code>__magic_stack_info: public __magic_info</code>.
+ This defines the content of a line in the stack table.
+ </para></listitem>
+ <listitem><para>
+ Define class <code>__trace_magic: public __trace_base&lt;__magic_info,
+ __magic_stack_info&gt;</code>.
+ It defines the content of the trace associated with this diagnostic.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Add initialization and reporting calls in
+ <code>include/profile/impl/profiler_trace.h</code>. Use
+ <code>__trace_vector_to_list</code> as an example.
+ </para>
+
+ <para>Add documentation in file <code>doc/xml/manual/profile_mode.xml</code>.
+ </para>
+</section>
+</section>
+
+<section xml:id="manual.ext.profile_mode.diagnostics"><info><title>Diagnostics</title></info>
+
+
+ <para>
+ The table below presents all the diagnostics we intend to implement.
+ Each diagnostic has a corresponding compile time switch
+ <code>-D_GLIBCXX_PROFILE_&lt;diagnostic&gt;</code>.
+ Groups of related diagnostics can be turned on with a single switch.
+ For instance, <code>-D_GLIBCXX_PROFILE_LOCALITY</code> is equivalent to
+ <code>-D_GLIBCXX_PROFILE_SOFTWARE_PREFETCH
+ -D_GLIBCXX_PROFILE_RBTREE_LOCALITY</code>.
+ </para>
+
+ <para>
+ The benefit, cost, expected frequency and accuracy of each diagnostic
+ was given a grade from 1 to 10, where 10 is highest.
+ A high benefit means that, if the diagnostic is accurate, the expected
+ performance improvement is high.
+ A high cost means that turning this diagnostic on leads to high slowdown.
+ A high frequency means that we expect this to occur relatively often.
+ A high accuracy means that the diagnostic is unlikely to be wrong.
+ These grades are not perfect. They are just meant to guide users with
+ specific needs or time budgets.
+ </para>
+
+<table frame="all">
+<title>Profile Diagnostics</title>
+
+<tgroup cols="7" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<colspec colname="c6"/>
+<colspec colname="c7"/>
+
+<thead>
+ <row>
+ <entry>Group</entry>
+ <entry>Flag</entry>
+ <entry>Benefit</entry>
+ <entry>Cost</entry>
+ <entry>Freq.</entry>
+ <entry>Implemented</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.containers">
+ CONTAINERS</link></entry>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.hashtable_too_small">
+ HASHTABLE_TOO_SMALL</link></entry>
+ <entry>10</entry>
+ <entry>1</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.hashtable_too_large">
+ HASHTABLE_TOO_LARGE</link></entry>
+ <entry>5</entry>
+ <entry>1</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.inefficient_hash">
+ INEFFICIENT_HASH</link></entry>
+ <entry>7</entry>
+ <entry>3</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.vector_too_small">
+ VECTOR_TOO_SMALL</link></entry>
+ <entry>8</entry>
+ <entry>1</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.vector_too_large">
+ VECTOR_TOO_LARGE</link></entry>
+ <entry>5</entry>
+ <entry>1</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.vector_to_hashtable">
+ VECTOR_TO_HASHTABLE</link></entry>
+ <entry>7</entry>
+ <entry>7</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.hashtable_to_vector">
+ HASHTABLE_TO_VECTOR</link></entry>
+ <entry>7</entry>
+ <entry>7</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.vector_to_list">
+ VECTOR_TO_LIST</link></entry>
+ <entry>8</entry>
+ <entry>5</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.list_to_vector">
+ LIST_TO_VECTOR</link></entry>
+ <entry>10</entry>
+ <entry>5</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.assoc_ord_to_unord">
+ ORDERED_TO_UNORDERED</link></entry>
+ <entry>10</entry>
+ <entry>5</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>only map/unordered_map</entry>
+ </row>
+ <row>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.algorithms">
+ ALGORITHMS</link></entry>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.algorithms.sort">
+ SORT</link></entry>
+ <entry>7</entry>
+ <entry>8</entry>
+ <entry/>
+ <entry>7</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.locality">
+ LOCALITY</link></entry>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.locality.sw_prefetch">
+ SOFTWARE_PREFETCH</link></entry>
+ <entry>8</entry>
+ <entry>8</entry>
+ <entry/>
+ <entry>5</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.locality.linked">
+ RBTREE_LOCALITY</link></entry>
+ <entry>4</entry>
+ <entry>8</entry>
+ <entry/>
+ <entry>5</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#manual.ext.profile_mode.analysis.mthread.false_share">
+ FALSE_SHARING</link></entry>
+ <entry>8</entry>
+ <entry>10</entry>
+ <entry/>
+ <entry>10</entry>
+ <entry>no</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<section xml:id="manual.ext.profile_mode.analysis.template" xreflabel="Template"><info><title>Diagnostic Template</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_&lt;diagnostic&gt;</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> What problem will it diagnose?
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>.
+ What is the fundamental reason why this is a problem</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>
+ Percentage reduction in execution time. When reduction is more than
+ a constant factor, describe the reduction rate formula.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>
+ What would the advise look like?</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis>
+ What stdlibc++ components need to be instrumented?</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ How do we decide when to issue the advice?</para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ How do we measure benefits? Math goes here.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+program code
+...
+advice sample
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.analysis.containers" xreflabel="Containers"><info><title>Containers</title></info>
+
+
+<para>
+<emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_CONTAINERS</code>.
+</para>
+
+<section xml:id="manual.ext.profile_mode.analysis.hashtable_too_small" xreflabel="Hashtable Too Small"><info><title>Hashtable Too Small</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_HASHTABLE_TOO_SMALL</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect hashtables with many
+ rehash operations, small construction size and large destruction size.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis> Rehash is very expensive.
+ Read content, follow chains within bucket, evaluate hash function, place at
+ new location in different order.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis> 36%.
+ Code similar to example below.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>
+ Set initial size to N at construction site S.
+ </para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis>
+ <code>unordered_set, unordered_map</code> constructor, destructor, rehash.
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ For each dynamic instance of <code>unordered_[multi]set|map</code>,
+ record initial size and call context of the constructor.
+ Record size increase, if any, after each relevant operation such as insert.
+ Record the estimated rehash cost.</para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Number of individual rehash operations * cost per rehash.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 unordered_set&lt;int&gt; us;
+2 for (int k = 0; k &lt; 1000000; ++k) {
+3 us.insert(k);
+4 }
+
+foo.cc:1: advice: Changing initial unordered_set size from 10 to 1000000 saves 1025530 rehash operations.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.analysis.hashtable_too_large" xreflabel="Hashtable Too Large"><info><title>Hashtable Too Large</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_HASHTABLE_TOO_LARGE</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect hashtables which are
+ never filled up because fewer elements than reserved are ever
+ inserted.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis> Save memory, which
+ is good in itself and may also improve memory reference performance through
+ fewer cache and TLB misses.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis> unknown.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>
+ Set initial size to N at construction site S.
+ </para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis>
+ <code>unordered_set, unordered_map</code> constructor, destructor, rehash.
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ For each dynamic instance of <code>unordered_[multi]set|map</code>,
+ record initial size and call context of the constructor, and correlate it
+ with its size at destruction time.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Number of iteration operations + memory saved.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 vector&lt;unordered_set&lt;int&gt;&gt; v(100000, unordered_set&lt;int&gt;(100)) ;
+2 for (int k = 0; k &lt; 100000; ++k) {
+3 for (int j = 0; j &lt; 10; ++j) {
+4 v[k].insert(k + j);
+5 }
+6 }
+
+foo.cc:1: advice: Changing initial unordered_set size from 100 to 10 saves N
+bytes of memory and M iteration steps.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.inefficient_hash" xreflabel="Inefficient Hash"><info><title>Inefficient Hash</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_INEFFICIENT_HASH</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect hashtables with polarized
+ distribution.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis> A non-uniform
+ distribution may lead to long chains, thus possibly increasing complexity
+ by a factor up to the number of elements.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis> factor up
+ to container size.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis> Change hash function
+ for container built at site S. Distribution score = N. Access score = S.
+ Longest chain = C, in bucket B.
+ </para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis>
+ <code>unordered_set, unordered_map</code> constructor, destructor, [],
+ insert, iterator.
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ Count the exact number of link traversals.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Total number of links traversed.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+class dumb_hash {
+ public:
+ size_t operator() (int i) const { return 0; }
+};
+...
+ unordered_set&lt;int, dumb_hash&gt; hs;
+ ...
+ for (int i = 0; i &lt; COUNT; ++i) {
+ hs.find(i);
+ }
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.vector_too_small" xreflabel="Vector Too Small"><info><title>Vector Too Small</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_VECTOR_TOO_SMALL</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis>Detect vectors with many
+ resize operations, small construction size and large destruction size..
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>Resizing can be expensive.
+ Copying large amounts of data takes time. Resizing many small vectors may
+ have allocation overhead and affect locality.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>
+ Set initial size to N at construction site S.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis><code>vector</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ For each dynamic instance of <code>vector</code>,
+ record initial size and call context of the constructor.
+ Record size increase, if any, after each relevant operation such as
+ <code>push_back</code>. Record the estimated resize cost.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Total number of words copied * time to copy a word.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 vector&lt;int&gt; v;
+2 for (int k = 0; k &lt; 1000000; ++k) {
+3 v.push_back(k);
+4 }
+
+foo.cc:1: advice: Changing initial vector size from 10 to 1000000 saves
+copying 4000000 bytes and 20 memory allocations and deallocations.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.vector_too_large" xreflabel="Vector Too Large"><info><title>Vector Too Large</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_VECTOR_TOO_LARGE</code>
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis>Detect vectors which are
+ never filled up because fewer elements than reserved are ever
+ inserted.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>Save memory, which
+ is good in itself and may also improve memory reference performance through
+ fewer cache and TLB misses.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>
+ Set initial size to N at construction site S.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis><code>vector</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ For each dynamic instance of <code>vector</code>,
+ record initial size and call context of the constructor, and correlate it
+ with its size at destruction time.</para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Total amount of memory saved.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 vector&lt;vector&lt;int&gt;&gt; v(100000, vector&lt;int&gt;(100)) ;
+2 for (int k = 0; k &lt; 100000; ++k) {
+3 for (int j = 0; j &lt; 10; ++j) {
+4 v[k].insert(k + j);
+5 }
+6 }
+
+foo.cc:1: advice: Changing initial vector size from 100 to 10 saves N
+bytes of memory and may reduce the number of cache and TLB misses.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.vector_to_hashtable" xreflabel="Vector to Hashtable"><info><title>Vector to Hashtable</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_VECTOR_TO_HASHTABLE</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect uses of
+ <code>vector</code> that can be substituted with <code>unordered_set</code>
+ to reduce execution time.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ Linear search in a vector is very expensive, whereas searching in a hashtable
+ is very quick.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>factor up
+ to container size.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>Replace
+ <code>vector</code> with <code>unordered_set</code> at site S.
+ </para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis><code>vector</code>
+ operations and access methods.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ For each dynamic instance of <code>vector</code>,
+ record call context of the constructor. Issue the advice only if the
+ only methods called on this <code>vector</code> are <code>push_back</code>,
+ <code>insert</code> and <code>find</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Cost(vector::push_back) + cost(vector::insert) + cost(find, vector) -
+ cost(unordered_set::insert) + cost(unordered_set::find).
+ </para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 vector&lt;int&gt; v;
+...
+2 for (int i = 0; i &lt; 1000; ++i) {
+3 find(v.begin(), v.end(), i);
+4 }
+
+foo.cc:1: advice: Changing "vector" to "unordered_set" will save about 500,000
+comparisons.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.hashtable_to_vector" xreflabel="Hashtable to Vector"><info><title>Hashtable to Vector</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_HASHTABLE_TO_VECTOR</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect uses of
+ <code>unordered_set</code> that can be substituted with <code>vector</code>
+ to reduce execution time.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ Hashtable iterator is slower than vector iterator.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>95%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>Replace
+ <code>unordered_set</code> with <code>vector</code> at site S.
+ </para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis><code>unordered_set</code>
+ operations and access methods.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ For each dynamic instance of <code>unordered_set</code>,
+ record call context of the constructor. Issue the advice only if the
+ number of <code>find</code>, <code>insert</code> and <code>[]</code>
+ operations on this <code>unordered_set</code> are small relative to the
+ number of elements, and methods <code>begin</code> or <code>end</code>
+ are invoked (suggesting iteration).</para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Number of .</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 unordered_set&lt;int&gt; us;
+...
+2 int s = 0;
+3 for (unordered_set&lt;int&gt;::iterator it = us.begin(); it != us.end(); ++it) {
+4 s += *it;
+5 }
+
+foo.cc:1: advice: Changing "unordered_set" to "vector" will save about N
+indirections and may achieve better data locality.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.vector_to_list" xreflabel="Vector to List"><info><title>Vector to List</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_VECTOR_TO_LIST</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect cases where
+ <code>vector</code> could be substituted with <code>list</code> for
+ better performance.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ Inserting in the middle of a vector is expensive compared to inserting in a
+ list.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>factor up to
+ container size.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>Replace vector with list
+ at site S.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis><code>vector</code>
+ operations and access methods.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ For each dynamic instance of <code>vector</code>,
+ record the call context of the constructor. Record the overhead of each
+ <code>insert</code> operation based on current size and insert position.
+ Report instance with high insertion overhead.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ (Sum(cost(vector::method)) - Sum(cost(list::method)), for
+ method in [push_back, insert, erase])
+ + (Cost(iterate vector) - Cost(iterate list))</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 vector&lt;int&gt; v;
+2 for (int i = 0; i &lt; 10000; ++i) {
+3 v.insert(v.begin(), i);
+4 }
+
+foo.cc:1: advice: Changing "vector" to "list" will save about 5,000,000
+operations.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.list_to_vector" xreflabel="List to Vector"><info><title>List to Vector</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_LIST_TO_VECTOR</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect cases where
+ <code>list</code> could be substituted with <code>vector</code> for
+ better performance.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ Iterating through a vector is faster than through a list.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>64%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>Replace list with vector
+ at site S.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis><code>vector</code>
+ operations and access methods.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ Issue the advice if there are no <code>insert</code> operations.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ (Sum(cost(vector::method)) - Sum(cost(list::method)), for
+ method in [push_back, insert, erase])
+ + (Cost(iterate vector) - Cost(iterate list))</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 list&lt;int&gt; l;
+...
+2 int sum = 0;
+3 for (list&lt;int&gt;::iterator it = l.begin(); it != l.end(); ++it) {
+4 sum += *it;
+5 }
+
+foo.cc:1: advice: Changing "list" to "vector" will save about 1000000 indirect
+memory references.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.list_to_slist" xreflabel="List to Forward List"><info><title>List to Forward List (Slist)</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_LIST_TO_SLIST</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect cases where
+ <code>list</code> could be substituted with <code>forward_list</code> for
+ better performance.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ The memory footprint of a forward_list is smaller than that of a list.
+ This has beneficial effects on memory subsystem, e.g., fewer cache misses.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>40%.
+ Note that the reduction is only noticeable if the size of the forward_list
+ node is in fact larger than that of the list node. For memory allocators
+ with size classes, you will only notice an effect when the two node sizes
+ belong to different allocator size classes.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>Replace list with
+ forward_list at site S.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis><code>list</code>
+ operations and iteration methods.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ Issue the advice if there are no <code>backwards</code> traversals
+ or insertion before a given node.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Always true.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 list&lt;int&gt; l;
+...
+2 int sum = 0;
+3 for (list&lt;int&gt;::iterator it = l.begin(); it != l.end(); ++it) {
+4 sum += *it;
+5 }
+
+foo.cc:1: advice: Change "list" to "forward_list".
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.assoc_ord_to_unord" xreflabel="Ordered to Unordered Associative Container"><info><title>Ordered to Unordered Associative Container</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_ORDERED_TO_UNORDERED</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect cases where ordered
+ associative containers can be replaced with unordered ones.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ Insert and search are quicker in a hashtable than in
+ a red-black tree.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>52%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>
+ Replace set with unordered_set at site S.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis>
+ <code>set</code>, <code>multiset</code>, <code>map</code>,
+ <code>multimap</code> methods.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ Issue the advice only if we are not using operator <code>++</code> on any
+ iterator on a particular <code>[multi]set|map</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ (Sum(cost(hashtable::method)) - Sum(cost(rbtree::method)), for
+ method in [insert, erase, find])
+ + (Cost(iterate hashtable) - Cost(iterate rbtree))</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 set&lt;int&gt; s;
+2 for (int i = 0; i &lt; 100000; ++i) {
+3 s.insert(i);
+4 }
+5 int sum = 0;
+6 for (int i = 0; i &lt; 100000; ++i) {
+7 sum += *s.find(i);
+8 }
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+</section>
+
+
+
+<section xml:id="manual.ext.profile_mode.analysis.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info>
+
+
+ <para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_ALGORITHMS</code>.
+ </para>
+
+<section xml:id="manual.ext.profile_mode.analysis.algorithms.sort" xreflabel="Sorting"><info><title>Sort Algorithm Performance</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_SORT</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Give measure of sort algorithm
+ performance based on actual input. For instance, advise Radix Sort over
+ Quick Sort for a particular call context.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ See papers:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://portal.acm.org/citation.cfm?doid=1065944.1065981">
+ A framework for adaptive algorithm selection in STAPL</link> and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://ieeexplore.ieee.org/search/wrapper.jsp?arnumber=4228227">
+ Optimizing Sorting with Machine Learning Algorithms</link>.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>60%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis> Change sort algorithm
+ at site S from X Sort to Y Sort.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis> <code>sort</code>
+ algorithm.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ Issue the advice if the cost model tells us that another sort algorithm
+ would do better on this input. Requires us to know what algorithm we
+ are using in our sort implementation in release mode.</para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Runtime(algo) for algo in [radix, quick, merge, ...]</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.analysis.locality" xreflabel="Data Locality"><info><title>Data Locality</title></info>
+
+
+ <para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_LOCALITY</code>.
+ </para>
+
+<section xml:id="manual.ext.profile_mode.analysis.locality.sw_prefetch" xreflabel="Need Software Prefetch"><info><title>Need Software Prefetch</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_SOFTWARE_PREFETCH</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Discover sequences of indirect
+ memory accesses that are not regular, thus cannot be predicted by
+ hardware prefetchers.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ Indirect references are hard to predict and are very expensive when they
+ miss in caches.</para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>25%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis> Insert prefetch
+ instruction.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis> Vector iterator and
+ access operator [].
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ First, get cache line size and page size from system.
+ Then record iterator dereference sequences for which the value is a pointer.
+ For each sequence within a container, issue a warning if successive pointer
+ addresses are not within cache lines and do not form a linear pattern
+ (otherwise they may be prefetched by hardware).
+ If they also step across page boundaries, make the warning stronger.
+ </para>
+ <para>The same analysis applies to containers other than vector.
+ However, we cannot give the same advice for linked structures, such as list,
+ as there is no random access to the n-th element. The user may still be
+ able to benefit from this information, for instance by employing frays (user
+ level light weight threads) to hide the latency of chasing pointers.
+ </para>
+ <para>
+ This analysis is a little oversimplified. A better cost model could be
+ created by understanding the capability of the hardware prefetcher.
+ This model could be trained automatically by running a set of synthetic
+ cases.
+ </para>
+ </listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Total distance between pointer values of successive elements in vectors
+ of pointers.</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 int zero = 0;
+2 vector&lt;int*&gt; v(10000000, &amp;zero);
+3 for (int k = 0; k &lt; 10000000; ++k) {
+4 v[random() % 10000000] = new int(k);
+5 }
+6 for (int j = 0; j &lt; 10000000; ++j) {
+7 count += (*v[j] == 0 ? 0 : 1);
+8 }
+
+foo.cc:7: advice: Insert prefetch instruction.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.locality.linked" xreflabel="Linked Structure Locality"><info><title>Linked Structure Locality</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_RBTREE_LOCALITY</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Give measure of locality of
+ objects stored in linked structures (lists, red-black trees and hashtables)
+ with respect to their actual traversal patterns.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>Allocation can be tuned
+ to a specific traversal pattern, to result in better data locality.
+ See paper:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.springerlink.com/content/8085744l00x72662/">
+ Custom Memory Allocation for Free</link>.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>30%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis>
+ High scatter score N for container built at site S.
+ Consider changing allocation sequence or choosing a structure conscious
+ allocator.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis> Methods of all
+ containers using linked structures.</para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ First, get cache line size and page size from system.
+ Then record the number of successive elements that are on different line
+ or page, for each traversal method such as <code>find</code>. Give advice
+ only if the ratio between this number and the number of total node hops
+ is above a threshold.</para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Sum(same_cache_line(this,previous))</para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+ 1 set&lt;int&gt; s;
+ 2 for (int i = 0; i &lt; 10000000; ++i) {
+ 3 s.insert(i);
+ 4 }
+ 5 set&lt;int&gt; s1, s2;
+ 6 for (int i = 0; i &lt; 10000000; ++i) {
+ 7 s1.insert(i);
+ 8 s2.insert(i);
+ 9 }
+...
+ // Fast, better locality.
+10 for (set&lt;int&gt;::iterator it = s.begin(); it != s.end(); ++it) {
+11 sum += *it;
+12 }
+ // Slow, elements are further apart.
+13 for (set&lt;int&gt;::iterator it = s1.begin(); it != s1.end(); ++it) {
+14 sum += *it;
+15 }
+
+foo.cc:5: advice: High scatter score NNN for set built here. Consider changing
+the allocation sequence or switching to a structure conscious allocator.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.analysis.mthread" xreflabel="Multithreaded Data Access"><info><title>Multithreaded Data Access</title></info>
+
+
+ <para>
+ The diagnostics in this group are not meant to be implemented short term.
+ They require compiler support to know when container elements are written
+ to. Instrumentation can only tell us when elements are referenced.
+ </para>
+
+ <para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_MULTITHREADED</code>.
+ </para>
+
+<section xml:id="manual.ext.profile_mode.analysis.mthread.ddtest" xreflabel="Dependence Violations at Container Level"><info><title>Data Dependence Violations at Container Level</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_DDTEST</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect container elements
+ that are referenced from multiple threads in the parallel region or
+ across parallel regions.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis>
+ Sharing data between threads requires communication and perhaps locking,
+ which may be expensive.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>?%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis> Change data
+ distribution or parallel algorithm.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis> Container access methods
+ and iterators.
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ Keep a shadow for each container. Record iterator dereferences and
+ container member accesses. Issue advice for elements referenced by
+ multiple threads.
+ See paper: <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://portal.acm.org/citation.cfm?id=207110.207148">
+ The LRPD test: speculative run-time parallelization of loops with
+ privatization and reduction parallelization</link>.
+ </para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Number of accesses to elements referenced from multiple threads
+ </para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+<section xml:id="manual.ext.profile_mode.analysis.mthread.false_share" xreflabel="False Sharing"><info><title>False Sharing</title></info>
+
+<itemizedlist>
+ <listitem><para><emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_FALSE_SHARING</code>.
+ </para></listitem>
+ <listitem><para><emphasis>Goal:</emphasis> Detect elements in the
+ same container which share a cache line, are written by at least one
+ thread, and accessed by different threads.
+ </para></listitem>
+ <listitem><para><emphasis>Fundamentals:</emphasis> Under these assumptions,
+ cache protocols require
+ communication to invalidate lines, which may be expensive.
+ </para></listitem>
+ <listitem><para><emphasis>Sample runtime reduction:</emphasis>68%.
+ </para></listitem>
+ <listitem><para><emphasis>Recommendation:</emphasis> Reorganize container
+ or use padding to avoid false sharing.</para></listitem>
+ <listitem><para><emphasis>To instrument:</emphasis> Container access methods
+ and iterators.
+ </para></listitem>
+ <listitem><para><emphasis>Analysis:</emphasis>
+ First, get the cache line size.
+ For each shared container, record all the associated iterator dereferences
+ and member access methods with the thread id. Compare the address lists
+ across threads to detect references in two different threads to the same
+ cache line. Issue a warning only if the ratio to total references is
+ significant. Do the same for iterator dereference values if they are
+ pointers.</para></listitem>
+ <listitem><para><emphasis>Cost model:</emphasis>
+ Number of accesses to same cache line from different threads.
+ </para></listitem>
+ <listitem><para><emphasis>Example:</emphasis>
+<programlisting>
+1 vector&lt;int&gt; v(2, 0);
+2 #pragma omp parallel for shared(v, SIZE) schedule(static, 1)
+3 for (i = 0; i &lt; SIZE; ++i) {
+4 v[i % 2] += i;
+5 }
+
+OMP_NUM_THREADS=2 ./a.out
+foo.cc:1: advice: Change container structure or padding to avoid false
+sharing in multithreaded access at foo.cc:4. Detected N shared cache lines.
+</programlisting>
+</para></listitem>
+</itemizedlist>
+</section>
+
+</section>
+
+
+<section xml:id="manual.ext.profile_mode.analysis.statistics" xreflabel="Statistics"><info><title>Statistics</title></info>
+
+
+<para>
+<emphasis>Switch:</emphasis>
+ <code>_GLIBCXX_PROFILE_STATISTICS</code>.
+</para>
+
+<para>
+ In some cases the cost model may not tell us anything because the costs
+ appear to offset the benefits. Consider the choice between a vector and
+ a list. When there are both inserts and iteration, an automatic advice
+ may not be issued. However, the programmer may still be able to make use
+ of this information in a different way.
+</para>
+<para>
+ This diagnostic will not issue any advice, but it will print statistics for
+ each container construction site. The statistics will contain the cost
+ of each operation actually performed on the container.
+</para>
+
+</section>
+
+
+</section>
+
+
+<bibliography xml:id="profile_mode.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <citetitle>
+ Perflint: A Context Sensitive Performance Advisor for C++ Programs
+ </citetitle>
+
+ <author><personname><firstname>Lixia</firstname><surname>Liu</surname></personname></author>
+ <author><personname><firstname>Silvius</firstname><surname>Rus</surname></personname></author>
+
+ <copyright>
+ <year>2009</year>
+ <holder/>
+ </copyright>
+
+ <publisher>
+ <publishername>
+ Proceedings of the 2009 International Symposium on Code Generation
+ and Optimization
+ </publishername>
+ </publisher>
+ </biblioentry>
+</bibliography>
+
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/shared_ptr.xml b/libstdc++-v3/doc/xml/manual/shared_ptr.xml
new file mode 100644
index 000000000..4ef5f72b6
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/shared_ptr.xml
@@ -0,0 +1,543 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.util.memory.shared_ptr" xreflabel="shared_ptr">
+<?dbhtml filename="shared_ptr.html"?>
+
+<info><title>shared_ptr</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ shared_ptr
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<para>
+The shared_ptr class template stores a pointer, usually obtained via new,
+and implements shared ownership semantics.
+</para>
+
+<section xml:id="shared_ptr.req"><info><title>Requirements</title></info>
+
+
+ <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>
+</section>
+
+<section xml:id="shared_ptr.design_issues"><info><title>Design Issues</title></info>
+
+
+
+ <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>
+
+</section>
+
+<section xml:id="shared_ptr.impl"><info><title>Implementation</title></info>
+
+
+ <section><info><title>Class Hierarchy</title></info>
+
+
+ <para>
+A <classname>shared_ptr&lt;T&gt;</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&lt;Lp&gt;</classname></term>
+ <listitem>
+ <para>
+The base of the hierarchy is parameterized on the lock policy (see below.)
+_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&lt;Ptr, Deleter, Lp&gt;</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&lt;Ptr&gt;</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&lt;Ptr, Lp&gt;</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&lt;Ptr, Deleter, Alloc&gt;</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&lt;Tp, Alloc, Lp&gt;</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>
+
+ </section>
+
+ <section><info><title>Thread Safety</title></info>
+
+
+ <para>
+C++0x-only features are: rvalue-ref/move support, allocator support,
+aliasing constructor, make_shared &amp; allocate_shared. Additionally,
+the constructors taking <classname>auto_ptr</classname> parameters are
+deprecated in C++0x mode.
+ </para>
+
+<para>
+The
+<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread
+Safety</link> 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&lt;A&gt; a(new A);
+shared_ptr&lt;A&gt; 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>
+
+ </section>
+
+ <section><info><title>Selecting Lock Policy</title></info>
+
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Atomic
+Builtins</link>.) 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>
+ </section>
+
+ <section><info><title>Dual C++0x and TR1 Implementation</title></info>
+
+
+<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.
+The <classname>_Sp_counted_base</classname> base class is implemented in
+<filename>tr1/boost_sp_shared_count.h</filename> and is common to the TR1
+and C++0x versions of <classname>shared_ptr</classname>.
+</para>
+
+<para>
+The classes derived from <classname>_Sp_counted_base</classname> (see Class Hierarchy
+above) and <classname>__shared_count</classname> are implemented separately for C++0x
+and TR1, in <filename>bits/shared_ptr.h</filename> and
+<filename>tr1/shared_ptr.h</filename> respectively.
+</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 <classname>_Sp_counted_base</classname> and only make changes to
+the C++0x version.
+</para>
+</section>
+
+<section><info><title>Related functions and classes</title></info>
+
+
+<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&lt;Tp, Lp&gt;</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&lt;A&gt;</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&lt;_Sp_make_shared_tag&gt;()</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>
+
+</section>
+
+</section>
+
+<!--- XXX
+ <listitem>
+ <type>_Sp_counted_base&lt;Lp&gt;</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&lt;Ptr, Deleter, Lp&gt;</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&lt;Ptr&gt;</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>
+-->
+
+<section xml:id="shared_ptr.using"><info><title>Use</title></info>
+
+
+ <section><info><title>Examples</title></info>
+
+ <para>
+ Examples of use can be found in the testsuite, under
+ <filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>,
+ <filename class="directory">testsuite/20_util/shared_ptr</filename>
+ and
+ <filename class="directory">testsuite/20_util/weak_ptr</filename>.
+ </para>
+ </section>
+
+ <section><info><title>Unresolved Issues</title></info>
+
+ <para>
+ The <emphasis><classname>shared_ptr</classname> atomic access</emphasis>
+ clause in the C++0x working draft is not implemented in GCC.
+ </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&lt;_S_single&gt;</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&lt;_Sp_make_shared_tag&gt;()</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>
+
+ </section>
+
+</section>
+
+<section xml:id="shared_ptr.ack"><info><title>Acknowledgments</title></info>
+
+
+ <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>
+
+</section>
+
+<bibliography xml:id="shared_ptr.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm" class="uri">
+ </biblioid>
+ <citetitle>
+ Improving shared_ptr for C++0x, Revision 2
+ </citetitle>
+ <subtitle>
+ N2351
+ </subtitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html" class="uri">
+ </biblioid>
+ <citetitle>
+ C++ Standard Library Active Issues List
+ </citetitle>
+ <subtitle>
+ N2456
+ </subtitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf" class="uri">
+ </biblioid>
+ <citetitle>
+ Working Draft, Standard for Programming Language C++
+ </citetitle>
+ <subtitle>
+ N2461
+ </subtitle>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://boost.org/libs/smart_ptr/shared_ptr.htm" class="uri">shared_ptr
+ </biblioid>
+ <citetitle>
+ Boost C++ Libraries documentation, shared_ptr
+ </citetitle>
+ <subtitle>
+ N2461
+ </subtitle>
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/spine.xml b/libstdc++-v3/doc/xml/manual/spine.xml
new file mode 100644
index 000000000..808ca0341
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/spine.xml
@@ -0,0 +1,119 @@
+<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="manual-index">
+<?dbhtml dir="manual"?>
+<?dbhtml filename="spine.html"?>
+
+ <title>The GNU C++ Library Manual</title>
+
+<info>
+ <copyright>
+ <year>2009</year>
+ <year>2010</year>
+ <holder>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org">FSF</link>
+ </holder>
+ </copyright>
+ <legalnotice>
+ <para>
+ <link linkend="manual.intro.status.license">License</link>
+ </para>
+ </legalnotice>
+</info>
+
+<!-- Part 01 : Intro -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="intro.xml">
+</xi:include>
+
+<!-- Part 02 : Standard Contents -->
+<part xml:id="manual.std" xreflabel="Standard Contents">
+<info>
+ <title>
+ Standard Contents
+ </title>
+</info>
+
+
+<!-- Chapter 01 : Support -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="support.xml">
+</xi:include>
+
+
+<!-- Chapter 02 : Diagnostics -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="diagnostics.xml">
+</xi:include>
+
+<!-- Chapter 03 : Utilities -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="utilities.xml">
+</xi:include>
+
+<!-- Chapter 04 : Strings -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="strings.xml">
+</xi:include>
+
+<!-- Chapter 05 : Localization -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="localization.xml">
+</xi:include>
+
+<!-- Chapter 06 : Containers -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="containers.xml">
+</xi:include>
+
+<!-- Chapter 07 : Iterators -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="iterators.xml">
+</xi:include>
+
+<!-- Chapter 08 : Algorithms -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="algorithms.xml">
+</xi:include>
+
+<!-- Chapter 09 : Numerics -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="numerics.xml">
+</xi:include>
+
+<!-- Chapter 10 : Input Output -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="io.xml">
+</xi:include>
+
+<!-- Chapter 11 : Atomics -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="atomics.xml">
+</xi:include>
+
+<!-- Chapter 12 : Concurrency -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency.xml">
+</xi:include>
+
+</part>
+
+<!-- Part 03 : Extensions -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="extensions.xml">
+</xi:include>
+
+
+<!-- Part 04 : Appendices -->
+<part xml:id="appendix" xreflabel="Appendices"><info><title>
+ Appendices
+</title></info>
+
+
+<!-- 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.3.xml">
+</xi:include>
+
+</part>
+
+</book>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
new file mode 100644
index 000000000..67f6f891d
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
@@ -0,0 +1,1164 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="status.iso.1998" xreflabel="ISO C++ 1998">
+<?dbhtml filename="status_iso_cxx1998.html"?>
+
+<info><title>C++ 1998/2003</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ 1998
+ </keyword>
+ </keywordset>
+</info>
+
+
+<section xml:id="iso.1998.status" xreflabel="Implementation Status">
+<info><title>Implementation Status</title></info>
+
+<para>
+This status table is based on the table of contents of ISO/IEC 14882:2003.
+</para>
+
+<para>
+This page describes the C++ 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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+ <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/>
+ </row>
+ <row>
+ <entry>18.2</entry>
+ <entry>Implementation properties</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.2.1</entry>
+ <entry>Numeric Limits</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.2.1.1</entry>
+ <entry>Class template <code>numeric_limits</code></entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>18.2.2</entry>
+ <entry>C Library</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.3</entry>
+ <entry>Start and termination</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.4</entry>
+ <entry>Dynamic memory management</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.5</entry>
+ <entry>Type identification</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.5.1</entry>
+ <entry>Class type_info</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.5.2</entry>
+ <entry>Class bad_cast</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.5.3</entry>
+ <entry>Class bad_typeid</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.6</entry>
+ <entry>Exception handling</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.6.1</entry>
+ <entry>Class exception</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.6.2</entry>
+ <entry>Violation exception-specifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.6.3</entry>
+ <entry>Abnormal termination</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.6.4</entry>
+ <entry><code>uncaught_exception</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.7</entry>
+ <entry>Other runtime support</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>19.2</entry>
+ <entry>Assertions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.3</entry>
+ <entry>Error numbers</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>20.2</entry>
+ <entry>Utility components</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.2.1</entry>
+ <entry>Operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.2.2</entry>
+ <entry><code>pair</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3</entry>
+ <entry>Function objects</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.1</entry>
+ <entry>Base</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.2</entry>
+ <entry>Arithmetic operation</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.3</entry>
+ <entry>Comparisons</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.4</entry>
+ <entry>Logical operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.5</entry>
+ <entry>Negators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.6</entry>
+ <entry>Binders</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.7</entry>
+ <entry>Adaptors for pointers to functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.8</entry>
+ <entry>Adaptors for pointers to members</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4</entry>
+ <entry>Memory</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.1</entry>
+ <entry>The default allocator</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2</entry>
+ <entry>Raw storage iterator</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.3</entry>
+ <entry>Temporary buffers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.4</entry>
+ <entry>Specialized algorithms</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.4.1</entry>
+ <entry><code>uninitialized_copy</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.4.2</entry>
+ <entry><code>uninitialized_fill</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.4.3</entry>
+ <entry><code>uninitialized_fill_n</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.5</entry>
+ <entry>Class template <code>auto_ptr</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.6</entry>
+ <entry>C library</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>21.1.1</entry>
+ <entry>Character traits requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.1.2</entry>
+ <entry>traits typedef</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.1.3</entry>
+ <entry><code>char_traits</code> specializations</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.1.3.1</entry>
+ <entry>struct <code>char_traits&lt;char&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.1.3.2</entry>
+ <entry>struct <code>char_traits&lt;wchar_t&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.2</entry>
+ <entry>String classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.3</entry>
+ <entry>Class template <code>basic_string</code></entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>22.1.1</entry>
+ <entry>Class <code>locale</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.1.2</entry>
+ <entry><code>locale</code> globals</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.1.3</entry>
+ <entry>Convenience interfaces</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.1.3.1</entry>
+ <entry>Character classification</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.1.3.2</entry>
+ <entry>Character conversions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2</entry>
+ <entry>Standard locale categories</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.1</entry>
+ <entry><code>ctype</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.2</entry>
+ <entry>Numeric</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.2.1</entry>
+ <entry><code>num_get</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.2.2</entry>
+ <entry><code>num_put</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.3</entry>
+ <entry><code>num_punct</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.4</entry>
+ <entry><code>collate</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.5</entry>
+ <entry>Time</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.5.1</entry>
+ <entry><code>time_get</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.5.2</entry>
+ <entry><code>time_get_byname</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.5.3</entry>
+ <entry><code>time_put</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.5.3</entry>
+ <entry><code>time_put_byname</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.6</entry>
+ <entry>Monetary</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.6.1</entry>
+ <entry><code>money_get</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.6.2</entry>
+ <entry><code>money_put</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.6.3</entry>
+ <entry><code>money_punct</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.6.4</entry>
+ <entry><code>money_punct_byname</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.7</entry>
+ <entry><code>messages</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.2.8</entry>
+ <entry>Program-defined facets</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3</entry>
+ <entry>C Library Locales</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>23.2</entry>
+ <entry>Sequence containers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.1</entry>
+ <entry>Class template <code>deque</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.2</entry>
+ <entry>Class template <code>list</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.3</entry>
+ <entry>Adaptors</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.3.1</entry>
+ <entry>Class template <code>queue</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.3.2</entry>
+ <entry>Class template <code>priority_queue</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.3.3</entry>
+ <entry>Class template <code>stack</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.4</entry>
+ <entry>Class template <code>vector</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.5</entry>
+ <entry>Class <code>vector&lt;bool&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3</entry>
+ <entry>Associative containers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.1</entry>
+ <entry>Class template <code>map</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.2</entry>
+ <entry>Class template <code>multimap</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.3</entry>
+ <entry>Class template <code>set</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.4</entry>
+ <entry>Class template <code>multiset</code></entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>24.2</entry>
+ <entry>Header <code>&lt;iterator&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.3</entry>
+ <entry>Iterator primitives</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.4</entry>
+ <entry>Predefined iterators and Iterator adaptors</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.4.1</entry>
+ <entry>Reverse iterators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.4.2</entry>
+ <entry>Insert iterators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5</entry>
+ <entry>Stream iterators</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5.1</entry>
+ <entry>Class template <code>istream_iterator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5.2</entry>
+ <entry>Class template <code>ostream_iterator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5.3</entry>
+ <entry>Class template <code>istreambuf_iterator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5.4</entry>
+ <entry>Class template <code>ostreambuf_iterator</code></entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>25.2</entry>
+ <entry>Mutating sequence operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>25.3</entry>
+ <entry>Sorting and related operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>25.4</entry>
+ <entry>C library algorithms</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>26.2</entry>
+ <entry>Complex numbers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3</entry>
+ <entry>Numeric arrays</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.1</entry>
+ <entry>Header <code>&lt;valarray&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.2</entry>
+ <entry>Class template <code>valarray</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.3</entry>
+ <entry><code>valarray</code> non-member operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.4</entry>
+ <entry>Class <code>slice</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.5</entry>
+ <entry>Class template <code>slice_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.6</entry>
+ <entry>Class <code>gslice</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.7</entry>
+ <entry>Class template <code>gslice_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.8</entry>
+ <entry>Class template <code>mask_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3.9</entry>
+ <entry>Class template <code>indirect_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.4</entry>
+ <entry>Generalized numeric operations</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.4.1</entry>
+ <entry><code>accumulate</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.4.2</entry>
+ <entry><code>inner_product</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.4.3</entry>
+ <entry><code>partial_sum</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.4.4</entry>
+ <entry><code>adjacent_difference</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.4.5</entry>
+ <entry>iota</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5</entry>
+ <entry>C Library</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>27.2</entry>
+ <entry>Forward declarations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.3</entry>
+ <entry>Standard iostream objects</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.3.1</entry>
+ <entry>Narrow stream objects</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.3.2</entry>
+ <entry>Wide stream objects</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.4</entry>
+ <entry>Iostreams base classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.5</entry>
+ <entry>Stream buffers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.6</entry>
+ <entry>Formatting and manipulators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.7</entry>
+ <entry>String-based streams</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.8</entry>
+ <entry>File-based streams</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>D.2</entry>
+ <entry><code>static</code> keyword</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.3</entry>
+ <entry>Access declarations</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.4</entry>
+ <entry>Implicit conversion from const strings</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.5</entry>
+ <entry>C standard library headers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.6</entry>
+ <entry>Old iostreams members</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.7</entry>
+ <entry>char* streams</entry>
+ <entry/>
+ <entry/>
+ </row>
+
+ </tbody>
+</tgroup>
+</table>
+</section>
+
+<section xml:id="iso.1998.specific" xreflabel="Implementation Specific"><info><title>Implementation Specific Behavior</title></info>
+
+
+ <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
+ <link linkend="std.support.types.null">here</link>.
+ </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
+ <link linkend="manual.ext.demangle">runtime demangler function</link>.
+ (The classes in <code>&lt;stdexcept&gt;</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 <link linkend="std.localization.facet.codecvt">chapter 22
+ notes</link> for what does exist.
+ </para>
+ <para><emphasis>[22.*]</emphasis> Anything and everything we have on locale
+ implementation will be described
+ <link linkend="std.localization.locales.locale">over here</link>.
+ </para>
+ <para><emphasis>[26.2.8]/9</emphasis> I have no idea what
+ <code>complex&lt;T&gt;</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
+ <link linkend="std.io">in this chapter</link>.
+ </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>
+
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx200x.xml b/libstdc++-v3/doc/xml/manual/status_cxx200x.xml
new file mode 100644
index 000000000..3e4be8fca
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/status_cxx200x.xml
@@ -0,0 +1,2628 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="status.iso.200x" xreflabel="Status C++ 200x">
+<?dbhtml filename="status_iso_cxx200x.html"?>
+
+<info><title>C++ 200x</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ 200x
+ </keyword>
+ </keywordset>
+</info>
+
+<para>
+This table is based on the table of contents of ISO/IEC
+JTC1 SC22 WG21 Doc No: N3290 Date: 2011-04-11
+Final Draft International Standard, 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. See <link linkend="manual.intro.using.flags">dialect</link>
+options. 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 the GCC 4.6 release series.
+</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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+ <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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>18.2</entry>
+ <entry>Types</entry>
+ <entry>Partial</entry>
+ <entry>Missing offsetof, max_align_t</entry>
+ </row>
+ <row>
+ <entry>18.3</entry>
+ <entry>Implementation properties</entry>
+ <entry/>
+ <entry/>
+ </row>
+
+ <row>
+ <entry>18.3.2</entry>
+ <entry>Numeric Limits</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.3.2.3</entry>
+ <entry>Class template <code>numeric_limits</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.3.2.4</entry>
+ <entry><code>numeric_limits</code> members</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>18.3.2.5</entry>
+ <entry><code>float_round_style</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>18.3.2.6</entry>
+ <entry><code>float_denorm_style</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.3.2.7</entry>
+ <entry><code>numeric_limits</code> specializations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry>18.3.3</entry>
+ <entry>C Library</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry>18.4</entry>
+ <entry>Integer types</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.4.1</entry>
+ <entry>Header <code>&lt;cstdint&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>18.5</entry>
+ <entry>Start and termination</entry>
+ <entry>Partial</entry>
+ <entry>C library dependency for quick_exit, at_quick_exit</entry>
+ </row>
+ <row>
+ <entry>18.6</entry>
+ <entry>Dynamic memory management</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.7</entry>
+ <entry>Type identification</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.7.1</entry>
+ <entry>Class type_info</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.7.2</entry>
+ <entry>Class bad_cast</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.7.3</entry>
+ <entry>Class bad_typeid</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.8</entry>
+ <entry>Exception handling</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.8.1</entry>
+ <entry>Class exception</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.8.2</entry>
+ <entry>Class bad_exception</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.8.3</entry>
+ <entry>Abnormal termination</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.8.4</entry>
+ <entry><code>uncaught_exception</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.8.5</entry>
+ <entry>Exception Propagation</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.8.6</entry>
+ <entry><code>nested_exception</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.9</entry>
+ <entry>Initializer lists</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.9.1</entry>
+ <entry>Initializer list constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.9.2</entry>
+ <entry>Initializer list access</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>18.9.3</entry>
+ <entry>Initializer list range access</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>18.10</entry>
+ <entry>Other runtime support</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>19.2</entry>
+ <entry>Exception classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.3</entry>
+ <entry>Assertions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.4</entry>
+ <entry>Error numbers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.5</entry>
+ <entry>System error support</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.5.1</entry>
+ <entry>Class <code>error_category</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.5.2</entry>
+ <entry>Class <code>error_code</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.5.3</entry>
+ <entry>Class <code>error_condition</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.5.4</entry>
+ <entry>Comparison operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>19.5.5</entry>
+ <entry>Class <code>system_error</code></entry>
+ <entry>Y</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>General</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.2</entry>
+ <entry>Utility components</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.2.1</entry>
+ <entry>Operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.2.2</entry>
+ <entry>Swap</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.2.3</entry>
+ <entry><code>forward</code> and <code>move</code> helpers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.2.4</entry>
+ <entry>Function template <code>declval</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3</entry>
+ <entry>Pairs</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.1</entry>
+ <entry>In general</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.2</entry>
+ <entry>Class template <code>pair</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.3</entry>
+ <entry>Specialized algorithms</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.4</entry>
+ <entry>Tuple-like access to <code>pair</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.3.5</entry>
+ <entry>Piecewise construction</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4</entry>
+ <entry>Tuples</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.1</entry>
+ <entry>In general</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2</entry>
+ <entry>Class template <code>tuple</code></entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2.1</entry>
+ <entry>Construction</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2.2</entry>
+ <entry>Assignment</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2.3</entry>
+ <entry>Swap</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>20.4.2.4</entry>
+ <entry>Tuple creation functions</entry>
+ <entry>Partial</entry>
+ <entry><code>tuple_cat</code> should be a single variadic signature (DR 1385)</entry>
+ </row>
+ <row>
+ <entry>20.4.2.5</entry>
+ <entry>Tuple helper classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2.6</entry>
+ <entry>Element access</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2.7</entry>
+ <entry>Relational operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.4.2.8</entry>
+ <entry>Tuple traits</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.4.2.9</entry>
+ <entry>Tuple specialized algorithms</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.5</entry>
+ <entry>Class template <code>bitset</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.5.1</entry>
+ <entry><code>bitset</code> constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.5.2</entry>
+ <entry><code>bitset</code> members</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.5.3</entry>
+ <entry><code>bitset</code> hash support</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.5.4</entry>
+ <entry><code>bitset</code> operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6</entry>
+ <entry>Memory</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.1</entry>
+ <entry>In general</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.2</entry>
+ <entry>Header <code>&lt;memory&gt;</code> synopsis</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.6.3</entry>
+ <entry>Pointer traits</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>20.6.4</entry>
+ <entry>Pointer safety</entry>
+ <entry>Partial</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.6.5</entry>
+ <entry>Align</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.6</entry>
+ <entry>Allocator argument tag</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.7</entry>
+ <entry><code>uses_allocator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.6.8</entry>
+ <entry>Allocator traits</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.9</entry>
+ <entry>The default allocator</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.10</entry>
+ <entry>Raw storage iterator</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.11</entry>
+ <entry>Temporary buffers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.12</entry>
+ <entry>Specialized algorithms</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.12.1</entry>
+ <entry><code>addressof</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.12.2</entry>
+ <entry><code>uninitialized_copy</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.12.3</entry>
+ <entry><code>uninitialized_fill</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.12.4</entry>
+ <entry><code>uninitialized_fill_n</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.6.13</entry>
+ <entry>C library</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.7</entry>
+ <entry>Smart pointers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.7.1</entry>
+ <entry>Class template <code>unique_ptr</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.7.2</entry>
+ <entry>Shared-ownership pointers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.7.2.1</entry>
+ <entry>Class <code>bad_weak_ptr</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.7.2.2</entry>
+ <entry>Class template <code>shared_ptr</code></entry>
+ <entry>Y</entry>
+ <entry>
+ <para>
+ Uses code from
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</link>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>20.7.2.3</entry>
+ <entry>Class template <code>weak_ptr</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.7.2.4</entry>
+ <entry>Class template <code>emable_shared_from_this</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>20.7.2.5</entry>
+ <entry><code>shared_ptr</code> atomic access</entry>
+ <entry>Partial</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.7.2.6</entry>
+ <entry>Smart pointer hash support</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8</entry>
+ <entry>Function objects</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.1</entry>
+ <entry>Definitions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.2</entry>
+ <entry>Requirements</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.3</entry>
+ <entry>Class template <code>reference_wrapper</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.4</entry>
+ <entry>Arithmetic operation</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.5</entry>
+ <entry>Comparisons</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.6</entry>
+ <entry>Logical operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.7</entry>
+ <entry>Bitwise operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.8</entry>
+ <entry>Negators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.9</entry>
+ <entry>Function template <code>bind</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>20.8.10</entry>
+ <entry>Function template <code>mem_fn</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing overloads for reference-qualified member functions</entry>
+ </row>
+ <row>
+ <entry>20.8.11</entry>
+ <entry>Polymorphic function wrappers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.8.11.1</entry>
+ <entry>Class <code>bad_function_call</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>20.8.11.2</entry>
+ <entry>Class template <code>function</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing allocator support</entry>
+ </row>
+ <row>
+ <entry>20.8.12</entry>
+ <entry>Class template <code>hash</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9</entry>
+ <entry>Metaprogramming and type traits</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.1</entry>
+ <entry>Requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.2</entry>
+ <entry>Header <code>&lt;type_traits&gt;</code> synopsis</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.3</entry>
+ <entry>Helper classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.4</entry>
+ <entry>Unary Type Traits</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.4.1</entry>
+ <entry>Primary type categories</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.4.2</entry>
+ <entry>Composite type traits</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>20.9.4.3</entry>
+ <entry>Type properties</entry>
+ <entry>Partial</entry>
+ <entry>Missing is_trivially_copyable,
+ is_assignable, is_copy_assignable, is_move_assignable,
+ is_trivially_constructible, is_trivially_default_constructible,
+ is_trivially_copy_constructible, is_trivially_move_constructible,
+ is_trivially_assignable, is_trivially_default_assignable,
+ is_trivially_copy_assignable, is_trivially_move_assignable,
+ is_trivially_destructible,
+ is_nothrow_assignable,
+ is_nothrow_copy_assignable, is_nothrow_move_assignable,
+ is_nothrow_destructible
+ </entry>
+ </row>
+ <row>
+ <entry>20.9.5</entry>
+ <entry>Type property queries</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.6</entry>
+ <entry>Relationships between types</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.7</entry>
+ <entry>Transformations between types</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.7.1</entry>
+ <entry>Const-volatile modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.7.2</entry>
+ <entry>Reference modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.7.3</entry>
+ <entry>Sign modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.7.4</entry>
+ <entry>Array modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.7.5</entry>
+ <entry>Pointer modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.9.7.6</entry>
+ <entry>Other transformations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.10</entry>
+ <entry>Compile-time rational arithmetic</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.10.1</entry>
+ <entry>In general</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.10.2</entry>
+ <entry>Header <code>&lt;ratio&gt;</code> synopsis</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.10.3</entry>
+ <entry>Class template <code>ratio</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.10.4</entry>
+ <entry>Arithmetic on <code>ratio</code>s</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.10.5</entry>
+ <entry>Comparison of <code>ratio</code>s</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.10.6</entry>
+ <entry>SI types for <code>ratio</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11</entry>
+ <entry>Time utilities</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.3</entry>
+ <entry>Clock requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.4</entry>
+ <entry>Time-related traits</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.4.1</entry>
+ <entry><code>treat_as_floating_point</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.4.2</entry>
+ <entry><code>duration_values</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.4.3</entry>
+ <entry>Specializations of <code>common_type</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>20.11.5</entry>
+ <entry>Class template <code>duration</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing constexpr for non-member arithmetic operations</entry>
+ </row>
+ <row>
+ <entry>20.11.6</entry>
+ <entry>Class template <code>time_point</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.7</entry>
+ <entry>Clocks</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.7.1</entry>
+ <entry>Class <code>system_clock</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.11.7.2</entry>
+ <entry>Class <code>steady_clock</code></entry>
+ <entry>N</entry>
+ <entry>Support old <code>monotonic_clock</code> spec instead</entry>
+ </row>
+ <row>
+ <entry>20.11.7.3</entry>
+ <entry>Class <code>high_resolution_clock</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>20.11.8</entry>
+ <entry>Date and time functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.12</entry>
+ <entry>Scoped allocator adaptor</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.12.1</entry>
+ <entry>Header <code>&lt;scoped_allocator&gt;</code> synopsis</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.12.2</entry>
+ <entry>Scoped allocator adaptor member types</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.12.3</entry>
+ <entry>Scoped allocator adaptor constructors</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.12.4</entry>
+ <entry>Scoped allocator adaptor members</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.12.5</entry>
+ <entry>Scoped allocator operators</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>20.13</entry>
+ <entry>Class <code>type_index</code></entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <entry>21.2</entry>
+ <entry>Character traits</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.2.1</entry>
+ <entry>Character traits requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.2.2</entry>
+ <entry>traits typedefs</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.2.3</entry>
+ <entry><code>char_traits</code> specializations</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>21.2.3.1</entry>
+ <entry>struct <code>char_traits&lt;char&gt;</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>21.2.3.2</entry>
+ <entry>struct <code>char_traits&lt;char16_t&gt;</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>21.2.3.3</entry>
+ <entry>struct <code>char_traits&lt;char32_t&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.2.3.4</entry>
+ <entry>struct <code>char_traits&lt;wchar_t&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.3</entry>
+ <entry>String classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.4</entry>
+ <entry>Class template <code>basic_string</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.5</entry>
+ <entry>Numeric Conversions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.6</entry>
+ <entry>Hash support</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>21.7</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/>
+ </row>
+ <row>
+ <entry>22.2</entry>
+ <entry>Header <code>&lt;locale&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3</entry>
+ <entry>Locales</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3.1</entry>
+ <entry>Class <code>locale</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3.2</entry>
+ <entry><code>locale</code> globals</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3.3</entry>
+ <entry>Convenience interfaces</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3.3.1</entry>
+ <entry>Character classification</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3.3.2</entry>
+ <entry>Conversions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.3.3.2.1</entry>
+ <entry>Character conversions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>22.3.3.2.2</entry>
+ <entry><code>string</code> conversions</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>22.3.3.2.3</entry>
+ <entry>Buffer conversions</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4</entry>
+ <entry>Standard <code>locale</code> categories</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.1</entry>
+ <entry>The <code>ctype</code> category</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.2</entry>
+ <entry>The numeric category</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.2.1</entry>
+ <entry><code>num_get</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.2.2</entry>
+ <entry><code>num_put</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.3</entry>
+ <entry>The numeric punctuation facet</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.4</entry>
+ <entry>The collate category</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.5</entry>
+ <entry>The time category</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.5.1</entry>
+ <entry>Class template <code>time_get</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.5.2</entry>
+ <entry>Class template <code>time_get_byname</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.5.3</entry>
+ <entry>Class template <code>time_put</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.5.3</entry>
+ <entry>Class template <code>time_put_byname</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.6</entry>
+ <entry>The monetary category</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.6.1</entry>
+ <entry>Class template <code>money_get</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.6.2</entry>
+ <entry>Class template <code>money_put</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.6.3</entry>
+ <entry>Class template <code>money_punct</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.6.4</entry>
+ <entry>Class template <code>money_punct_byname</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.7</entry>
+ <entry>The message retrieval category</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.4.8</entry>
+ <entry>Program-defined facets</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>22.5</entry>
+ <entry>Standard code conversion facets</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>22.6</entry>
+ <entry>C Library Locales</entry>
+ <entry>Y</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>General</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2</entry>
+ <entry>Container requirements</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.1</entry>
+ <entry>General container requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.2</entry>
+ <entry>Container data races</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.3</entry>
+ <entry>Sequence containers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.4</entry>
+ <entry>Associative containers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.2.5</entry>
+ <entry>Unordered associative containers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3</entry>
+ <entry>Sequence containers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.2</entry>
+ <entry>Class template <code>array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.3</entry>
+ <entry>Class template <code>deque</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.4</entry>
+ <entry>Class template <code>forward_list</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.5</entry>
+ <entry>Class template <code>list</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.6</entry>
+ <entry>Class template <code>vector</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.3.7</entry>
+ <entry>Class <code>vector&lt;bool&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.4</entry>
+ <entry>Associative containers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.4.4</entry>
+ <entry>Class template <code>map</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.4.5</entry>
+ <entry>Class template <code>multimap</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.4.6</entry>
+ <entry>Class template <code>set</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.4.7</entry>
+ <entry>Class template <code>multiset</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.5</entry>
+ <entry>Unordered associative containers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.5.4</entry>
+ <entry>Class template <code>unordered_map</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.5.5</entry>
+ <entry>Class template <code>unordered_multimap</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.5.6</entry>
+ <entry>Class template <code>unordered_set</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.5.7</entry>
+ <entry>Class template <code>unordered_multiset</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.6</entry>
+ <entry>Container adaptors</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.6.1</entry>
+ <entry>Class template <code>queue</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.6.2</entry>
+ <entry>Class template <code>priority_queue</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>23.6.3</entry>
+ <entry>Class template <code>stack</code></entry>
+ <entry>Y</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>General</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.2</entry>
+ <entry>Iterator requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.3</entry>
+ <entry>Header <code>&lt;iterator&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.4</entry>
+ <entry>Iterator primitives</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5</entry>
+ <entry>Iterator adaptors</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5.1</entry>
+ <entry>Reverse iterators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5.2</entry>
+ <entry>Insert iterators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.5.3</entry>
+ <entry>Move iterators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.6</entry>
+ <entry>Stream iterators</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.6.1</entry>
+ <entry>Class template <code>istream_iterator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.6.2</entry>
+ <entry>Class template <code>ostream_iterator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.6.3</entry>
+ <entry>Class template <code>istreambuf_iterator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>24.6.4</entry>
+ <entry>Class template <code>ostreambuf_iterator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>24.6.5</entry>
+ <entry>range access</entry>
+ <entry>N</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>General</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>25.2</entry>
+ <entry>Non-modifying sequence operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>25.3</entry>
+ <entry>Mutating sequence operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>25.4</entry>
+ <entry>Sorting and related operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>25.5</entry>
+ <entry>C library algorithms</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>26.2</entry>
+ <entry>Numeric type requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.3</entry>
+ <entry>The floating-point environment</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.4</entry>
+ <entry>Complex numbers</entry>
+ <entry>Partial</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5</entry>
+ <entry>Random number generation</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.1</entry>
+ <entry>Requirements</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.2</entry>
+ <entry>Header <code>&lt;random&gt;</code> synopsis</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.3</entry>
+ <entry>Random number engine class templates</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.3.1</entry>
+ <entry>Class template <code>linear_congruential_engine</code></entry>
+ <entry>Y</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5.3.2</entry>
+ <entry>Class template <code>mersenne_twister_engine</code></entry>
+ <entry>Y</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5.3.3</entry>
+ <entry>Class template <code>subtract_with_carry_engine</code></entry>
+ <entry>Y</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5.4</entry>
+ <entry>Random number engine adaptor class templates</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.4.2</entry>
+ <entry>Class template <code>discard_block_engine</code></entry>
+ <entry>Y</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5.4.3</entry>
+ <entry>Class template <code>independent_bits_engine</code></entry>
+ <entry>Y</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5.4.4</entry>
+ <entry>Class template <code>shuffle_order_engine</code></entry>
+ <entry>Y</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5.5</entry>
+ <entry>Engines and engine adaptors with predefined parameters</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.6</entry>
+ <entry>Class <code>random_device</code></entry>
+ <entry>Y</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>26.5.7</entry>
+ <entry>Utilities</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.7.1</entry>
+ <entry>Class <code>seed_seq</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.7.2</entry>
+ <entry>Function template <code>generate_canonical</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8</entry>
+ <entry>Random number distribution class templates</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.2</entry>
+ <entry>Uniform distributions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.2.1</entry>
+ <entry>Class template <code>uniform_int_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.2.2</entry>
+ <entry>Class template <code>uniform_real_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.3</entry>
+ <entry>Bernoulli distributions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.3.1</entry>
+ <entry>Class <code>bernoulli_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.3.2</entry>
+ <entry>Class template <code>binomial_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.3.3</entry>
+ <entry>Class template <code>geometric_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.3.4</entry>
+ <entry>Class template <code>negative_binomial_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.4</entry>
+ <entry>Poisson distributions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.4.1</entry>
+ <entry>Class template <code>poisson_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.4.2</entry>
+ <entry>Class template <code>exponential_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.4.3</entry>
+ <entry>Class template <code>gamma_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.4.4</entry>
+ <entry>Class template <code>weibull_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.4.5</entry>
+ <entry>Class template <code>extreme_value_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.5</entry>
+ <entry>Normal distributions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.5.1</entry>
+ <entry>Class template <code>normal_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.5.2</entry>
+ <entry>Class template <code>lognormal_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.5.3</entry>
+ <entry>Class template <code>chi_squared_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.5.4</entry>
+ <entry>Class template <code>cauchy_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.5.5</entry>
+ <entry>Class template <code>fisher_f_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.5.6</entry>
+ <entry>Class template <code>student_t_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.6</entry>
+ <entry>Sampling distributions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.6.1</entry>
+ <entry>Class template <code>discrete_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.6.2</entry>
+ <entry>Class template <code>piecewise_constant_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.5.8.6.3</entry>
+ <entry>Class template <code>piecewise_linear_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6</entry>
+ <entry>Numeric arrays</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.1</entry>
+ <entry>Header <code>&lt;valarray&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>26.6.2</entry>
+ <entry>Class template <code>valarray</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing move and swap operations</entry>
+ </row>
+ <row>
+ <entry>26.6.3</entry>
+ <entry><code>valarray</code> non-member operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.4</entry>
+ <entry>Class <code>slice</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.5</entry>
+ <entry>Class template <code>slice_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.6</entry>
+ <entry>The <code>gslice</code> class</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.7</entry>
+ <entry>Class template <code>gslice_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.8</entry>
+ <entry>Class template <code>mask_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.9</entry>
+ <entry>Class template <code>indirect_array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.6.10</entry>
+ <entry><code>valarray</code> range access</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.7</entry>
+ <entry>Generalized numeric operations</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.7.1</entry>
+ <entry>Header <code>&lt;numeric&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.7.2</entry>
+ <entry><code>accumulate</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.7.3</entry>
+ <entry><code>inner_product</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.7.4</entry>
+ <entry><code>partial_sum</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.7.5</entry>
+ <entry><code>adjacent_difference</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.7.6</entry>
+ <entry>iota</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>26.8</entry>
+ <entry>C Library</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>
+ <emphasis>27</emphasis>
+ </entry>
+ <entry namest="c2" nameend="c4" align="left">
+ <emphasis>Input/output library</emphasis>
+ </entry>
+ </row>
+ <row>
+ <entry>27.1</entry>
+ <entry>General</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.2</entry>
+ <entry>Iostreams requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.2.1</entry>
+ <entry>Imbue Limitations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.2.2</entry>
+ <entry>Positioning Type Limitations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>27.2.3</entry>
+ <entry>Thread safety</entry>
+ <entry>Partial</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.3</entry>
+ <entry>Forward declarations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.4</entry>
+ <entry>Standard iostream objects</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.4.1</entry>
+ <entry>Overview</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.4.2</entry>
+ <entry>Narrow stream objects</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>27.4.3</entry>
+ <entry>Wide stream objects</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>27.5</entry>
+ <entry>Iostreams base classes</entry>
+ <entry>Partial</entry>
+ <entry>
+ Missing move and swap operations on <code>basic_ios</code>. Missing
+ <code>make_error_code</code> and <code>make_error_condition</code>.
+ </entry>
+ </row>
+ <row>
+ <entry>27.6</entry>
+ <entry>Stream buffers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>27.7</entry>
+ <entry>Formatting and manipulators</entry>
+ <entry>Partial</entry>
+ <entry>Missing move and swap operations</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>27.8</entry>
+ <entry>String-based streams</entry>
+ <entry>Partial</entry>
+ <entry>Missing move and swap operations</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>27.9</entry>
+ <entry>File-based streams</entry>
+ <entry>Partial</entry>
+ <entry>Missing move and swap operations</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.1</entry>
+ <entry>General</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>28.2</entry>
+ <entry>Definitions</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>28.3</entry>
+ <entry>Requirements</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>28.4</entry>
+ <entry>Header <code>&lt;regex&gt;</code> synopsis</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>28.5</entry>
+ <entry>Namespace <code>std::regex_constants</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>28.6</entry>
+ <entry>Class <code>regex_error</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>28.7</entry>
+ <entry>Class template <code>regex_traits</code></entry>
+ <entry>Partial</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>28.8</entry>
+ <entry>Class template <code>basic_regex</code></entry>
+ <entry>Partial</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>28.9</entry>
+ <entry>Class template <code>sub_match</code></entry>
+ <entry>Partial</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>28.10</entry>
+ <entry>Class template <code>match_results</code></entry>
+ <entry>Partial</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>28.11</entry>
+ <entry>Regular expression algorithms</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>28.12</entry>
+ <entry>Regular expression Iterators</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>28.13</entry>
+ <entry>Modified ECMAScript regular expression grammar</entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <entry>29.2</entry>
+ <entry>Header <code>&lt;atomic&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>29.3</entry>
+ <entry>Order and consistency</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>29.4</entry>
+ <entry>Lock-free property</entry>
+ <entry>Partial</entry>
+ <entry>Missing <code>ATOMIC_BOOL_LOCK_FREE</code> and
+ <code>ATOMIC_POINTER_LOCK_FREE</code>.
+ Based on _GLIBCXX_ATOMIC_PROPERTY
+ </entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>29.5</entry>
+ <entry>Atomic types</entry>
+ <entry>Partial</entry>
+ <entry>Missing constexpr</entry>
+ </row>
+ <row>
+ <entry>29.6</entry>
+ <entry>Operations on atomic types</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>29.7</entry>
+ <entry>Flag Type and operations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>29.8</entry>
+ <entry>Fences</entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <entry>30.2</entry>
+ <entry>Requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.3</entry>
+ <entry>Threads</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>30.3.1</entry>
+ <entry>Class <code>thread</code></entry>
+ <entry>Partial</entry>
+ <entry><code>thread::id</code> comparisons not well-defined</entry>
+ </row>
+ <row>
+ <entry>30.3.2</entry>
+ <entry>Namespace <code>this_thread</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4</entry>
+ <entry>Mutual exclusion</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1</entry>
+ <entry>Mutex requirements</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1.1</entry>
+ <entry>In general</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1.2</entry>
+ <entry>Mutex types</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1.2.1</entry>
+ <entry>Class <code>mutex</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1.2.2</entry>
+ <entry>Class <code>recursive_mutex</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1.3</entry>
+ <entry>Timed mutex types</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1.3.1</entry>
+ <entry>Class <code>timed_mutex</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.1.3.2</entry>
+ <entry>Class <code>recursive_timed_mutex</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.2</entry>
+ <entry>Locks</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.2.1</entry>
+ <entry>Class template <code>lock_guard</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.2.2</entry>
+ <entry>Class template <code>unique_lock</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.3</entry>
+ <entry>Generic locking algorithms</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.4</entry>
+ <entry>Call once</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.4.1</entry>
+ <entry>Struct <code>once_flag</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.4.4.2</entry>
+ <entry>Function <code>call_once</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>30.5</entry>
+ <entry>Condition variables</entry>
+ <entry>Partial</entry>
+ <entry>Missing notify_all_at_thread_exit</entry>
+ </row>
+ <row>
+ <entry>30.5.1</entry>
+ <entry>Class <code>condition_variable</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.5.2</entry>
+ <entry>Class <code>condition_variable_any</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.6</entry>
+ <entry>Futures</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.6.1</entry>
+ <entry>Overview</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.6.2</entry>
+ <entry>Error handling</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.6.3</entry>
+ <entry>Class <code>future_error</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>30.6.4</entry>
+ <entry>Shared state</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>30.6.5</entry>
+ <entry>Class template <code>promise</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing set_*_at_thread_exit</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>30.6.6</entry>
+ <entry>Class template <code>future</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing future_status and future::share()</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>30.6.7</entry>
+ <entry>Class template <code>shared_future</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing future_status</entry>
+ </row>
+ <row>
+ <entry>30.6.8</entry>
+ <entry>Function template <code>async</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>30.6.9</entry>
+ <entry>Class template <code>packaged_task</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing make_ready_at_thread_exit</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 <code>bool</code> operand</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.2</entry>
+ <entry><code>register</code> keyword</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.3</entry>
+ <entry>Implicit declaration of copy functions</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.4</entry>
+ <entry>Dynamic exception specifications</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.5</entry>
+ <entry>C standard library headers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.6</entry>
+ <entry>Old iostreams members</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.7</entry>
+ <entry><code>char*</code> streams</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.8</entry>
+ <entry>Function objects</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.9</entry>
+ <entry>Binders</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.10</entry>
+ <entry><code>auto_ptr</code></entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>D.11</entry>
+ <entry>Violating exception-specifications</entry>
+ <entry/>
+ <entry/>
+ </row>
+
+ </tbody>
+</tgroup>
+</table>
+
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml b/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml
new file mode 100644
index 000000000..321c4ba26
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/status_cxxtr1.xml
@@ -0,0 +1,1782 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="status.iso.tr1" xreflabel="Status C++ TR1">
+<?dbhtml filename="status_iso_cxxtr1.html"?>
+
+<info><title>C++ TR1</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ tr1
+ </keyword>
+ </keywordset>
+</info>
+
+<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>&lt;tr1/functional&gt;</code>,
+<code>&lt;tr1/memory&gt;</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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+
+ <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/>
+ </row>
+ <row>
+ <entry>2.1.1</entry>
+ <entry>Additions to header <code>&lt;functional&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.1.2</entry>
+ <entry>Class template <code>reference_wrapper</code></entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.1.2.1</entry>
+ <entry><code>reference_wrapper</code> construct/copy/destroy</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.1.2.2</entry>
+ <entry><code>reference_wrapper</code> assignment</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.1.2.3</entry>
+ <entry><code>reference_wrapper</code> access</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.1.2.4</entry>
+ <entry><code>reference_wrapper</code> invocation</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.1.2.5</entry>
+ <entry><code>reference_wrapper</code> helper functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2</entry>
+ <entry>Smart pointers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.1</entry>
+ <entry>Additions to header <code>&lt;memory&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.2</entry>
+ <entry>Class <code>bad_weak_ptr</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3</entry>
+ <entry>Class template <code>shared_ptr</code></entry>
+ <entry/>
+ <entry>
+ <para>
+ Uses code from
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</link>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>2.2.3.1</entry>
+ <entry><code>shared_ptr</code> constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.2</entry>
+ <entry><code>shared_ptr</code> destructor</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.3</entry>
+ <entry><code>shared_ptr</code> assignment</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.4</entry>
+ <entry><code>shared_ptr</code> modifiers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.5</entry>
+ <entry><code>shared_ptr</code> observers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.6</entry>
+ <entry><code>shared_ptr</code> comparison</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.7</entry>
+ <entry><code>shared_ptr</code> I/O</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.8</entry>
+ <entry><code>shared_ptr</code> specialized algorithms</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.9</entry>
+ <entry><code>shared_ptr</code> casts</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.3.10</entry>
+ <entry><code>get_deleter</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4</entry>
+ <entry>Class template <code>weak_ptr</code></entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4.1</entry>
+ <entry><code>weak_ptr</code> constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4.2</entry>
+ <entry><code>weak_ptr</code> destructor</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4.3</entry>
+ <entry><code>weak_ptr</code> assignment</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4.4</entry>
+ <entry><code>weak_ptr</code> modifiers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4.5</entry>
+ <entry><code>weak_ptr</code> observers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4.6</entry>
+ <entry><code>weak_ptr</code> comparison</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.4.7</entry>
+ <entry><code>weak_ptr</code> specialized algorithms</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>2.2.5</entry>
+ <entry>Class template <code>enable_shared_from_this</code></entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>3.2</entry>
+ <entry>Additions to <code>&lt;functional&gt; synopsis</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.3</entry>
+ <entry>Requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4</entry>
+ <entry>Function return types</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.5</entry>
+ <entry>Function template <code>mem_fn</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.6</entry>
+ <entry>Function object binders</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.6.1</entry>
+ <entry>Class template <code>is_bind_expression</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.6.2</entry>
+ <entry>Class template <code>is_placeholder</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.6.3</entry>
+ <entry>Function template <code>bind</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.6.4</entry>
+ <entry>Placeholders</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7</entry>
+ <entry>Polymorphic function wrappers</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.1</entry>
+ <entry>Class <code>bad_function_call</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.1.1</entry>
+ <entry><code>bad_function_call</code> constructor</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2</entry>
+ <entry>Class template <code>function</code></entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.1</entry>
+ <entry><code>function</code> construct/copy/destroy</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.2</entry>
+ <entry><code>function</code> modifiers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.3</entry>
+ <entry><code>function</code> capacity</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.4</entry>
+ <entry><code>function</code> invocation</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.5</entry>
+ <entry><code>function</code> target access</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.6</entry>
+ <entry>undefined operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.7</entry>
+ <entry>null pointer comparison operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.7.2.8</entry>
+ <entry>specialized algorithms</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>4.2</entry>
+ <entry>Header <code>&lt;type_traits&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.3</entry>
+ <entry>Helper classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.4</entry>
+ <entry>General Requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.5</entry>
+ <entry>Unary Type Traits</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.5.1</entry>
+ <entry>Primary Type Categories</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.5.2</entry>
+ <entry>Composite type traits</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.5.3</entry>
+ <entry>Type properties</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.6</entry>
+ <entry>Relationships between types</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.7</entry>
+ <entry>Transformations between types</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.7.1</entry>
+ <entry>Const-volatile modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.7.2</entry>
+ <entry>Reference modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.7.3</entry>
+ <entry>Array modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.7.4</entry>
+ <entry>Pointer modifications</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.8</entry>
+ <entry>Other transformations</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>4.9</entry>
+ <entry>Implementation requirements</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>5.1.1</entry>
+ <entry>Requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.2</entry>
+ <entry>Header <code>&lt;random&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.3</entry>
+ <entry>Class template <code>variate_generator</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.4</entry>
+ <entry>Random number engine class templates</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.4.1</entry>
+ <entry>Class template <code>linear_congruential</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.4.2</entry>
+ <entry>Class template <code>mersenne_twister</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.4.3</entry>
+ <entry>Class template <code>subtract_with_carry</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.4.4</entry>
+ <entry>Class template <code>subtract_with_carry_01</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.4.5</entry>
+ <entry>Class template <code>discard_block</code></entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>5.1.6</entry>
+ <entry>Class <code>random_device</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7</entry>
+ <entry>Random distribution class templates</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.1</entry>
+ <entry>Class template <code>uniform_int</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.2</entry>
+ <entry>Class <code>bernoulli_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.3</entry>
+ <entry>Class template <code>geometric_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.4</entry>
+ <entry>Class template <code>poisson_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.5</entry>
+ <entry>Class template <code>binomial_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.6</entry>
+ <entry>Class template <code>uniform_real</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.7</entry>
+ <entry>Class template <code>exponential_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.8</entry>
+ <entry>Class template <code>normal_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.1.7.9</entry>
+ <entry>Class template <code>gamma_distribution</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2</entry>
+ <entry>Mathematical special functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1</entry>
+ <entry>Additions to header <code>&lt;cmath&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.1</entry>
+ <entry>associated Laguerre polynomials</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.2</entry>
+ <entry>associated Legendre functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.3</entry>
+ <entry>beta function</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.4</entry>
+ <entry>(complete) elliptic integral of the first kind</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.5</entry>
+ <entry>(complete) elliptic integral of the second kind</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.6</entry>
+ <entry>(complete) elliptic integral of the third kind</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.7</entry>
+ <entry>confluent hypergeometric functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.8</entry>
+ <entry>regular modified cylindrical Bessel functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.9</entry>
+ <entry>cylindrical Bessel functions (of the first kind)</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.10</entry>
+ <entry>irregular modified cylindrical Bessel functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.11</entry>
+ <entry>cylindrical Neumann functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.12</entry>
+ <entry>(incomplete) elliptic integral of the first kind</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.13</entry>
+ <entry>(incomplete) elliptic integral of the second kind</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.14</entry>
+ <entry>(incomplete) elliptic integral of the third kind</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.15</entry>
+ <entry>exponential integral</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.16</entry>
+ <entry>Hermite polynomials</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.17</entry>
+ <entry>hypergeometric functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.18</entry>
+ <entry>Laguerre polynomials</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.19</entry>
+ <entry>Legendre polynomials</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.20</entry>
+ <entry>Riemann zeta function</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.21</entry>
+ <entry>spherical Bessel functions (of the first kind)</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.22</entry>
+ <entry>spherical associated Legendre functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.1.23</entry>
+ <entry>spherical Neumann functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>5.2.2</entry>
+ <entry>Additions to header <code>&lt;math.h&gt;</code> synopsis</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>6.1.1</entry>
+ <entry>Header <code>&lt;tuple&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.2</entry>
+ <entry>Additions to header <code>&lt;utility&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.3</entry>
+ <entry>Class template <code>tuple</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.3.1</entry>
+ <entry>Construction</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.3.2</entry>
+ <entry>Tuple creation functions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.3.3</entry>
+ <entry>Tuple helper classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.3.4</entry>
+ <entry>Element access</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.3.5</entry>
+ <entry>Relational operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.1.4</entry>
+ <entry>Pairs</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2</entry>
+ <entry>Fixed size array</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2.1</entry>
+ <entry>Header <code>&lt;array&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2.2</entry>
+ <entry>Class template <code>array</code></entry>
+ <entry>Y</entry>
+
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2.2.1</entry>
+ <entry><code>array</code> constructors, copy, and assignment</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2.2.2</entry>
+ <entry><code>array</code> specialized algorithms</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2.2.3</entry>
+ <entry><code>array</code> size</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2.2.4</entry>
+ <entry>Zero sized <code>array</code>s</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.2.2.5</entry>
+ <entry>Tuple interface to class template <code>array</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3</entry>
+ <entry>Unordered associative containers</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.1</entry>
+ <entry>Unordered associative container requirements</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.1.1</entry>
+ <entry>Exception safety guarantees</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.2</entry>
+ <entry>Additions to header <code>&lt;functional&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.3</entry>
+ <entry>Class template <code>hash</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4</entry>
+ <entry>Unordered associative container classes</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.1</entry>
+ <entry>Header <code>&lt;unordered_set&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.2</entry>
+ <entry>Header <code>&lt;unordered_map&gt;</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.3</entry>
+ <entry>Class template <code>unordered_set</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.3.1</entry>
+ <entry><code>unordered_set</code> constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.3.2</entry>
+ <entry><code>unordered_set</code> swap</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.4</entry>
+ <entry>Class template <code>unordered_map</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.4.1</entry>
+ <entry><code>unordered_map</code> constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.4.2</entry>
+ <entry><code>unordered_map</code> element access</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.4.3</entry>
+ <entry><code>unordered_map</code> swap</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.5</entry>
+ <entry>Class template <code>unordered_multiset</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.5.1</entry>
+ <entry><code>unordered_multiset</code> constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.5.2</entry>
+ <entry><code>unordered_multiset</code> swap</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.6</entry>
+ <entry>Class template <code>unordered_multimap</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.6.1</entry>
+ <entry><code>unordered_multimap</code> constructors</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>6.3.4.6.2</entry>
+ <entry><code>unordered_multimap</code> swap</entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.2</entry>
+ <entry>Requirements</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.3</entry>
+ <entry>Regular expressions summary</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.4</entry>
+ <entry>Header <code>&lt;regex&gt;</code> synopsis</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.5</entry>
+ <entry>Namespace <code>tr1::regex_constants</code></entry>
+ <entry>N</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/>
+ </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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.5.3</entry>
+ <entry>Implementation defined <code>error_type</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.6</entry>
+ <entry>Class <code>regex_error</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.7</entry>
+ <entry>Class template <code>regex_traits</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8</entry>
+ <entry>Class template <code>basic_regex</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8.1</entry>
+ <entry><code>basic_regex</code> constants</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8.2</entry>
+ <entry><code>basic_regex</code> constructors</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8.3</entry>
+ <entry><code>basic_regex</code> assign</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8.4</entry>
+ <entry><code>basic_regex</code> constant operations</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8.5</entry>
+ <entry><code>basic_regex</code> locale</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8.6</entry>
+ <entry><code>basic_regex</code> swap</entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.8.7.1</entry>
+ <entry><code>basic_regex</code> non-member swap</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.9</entry>
+ <entry>Class template <code>sub_match</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.9.1</entry>
+ <entry><code>sub_match</code> members</entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.10</entry>
+ <entry>Class template <code>match_results</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.10.1</entry>
+ <entry><code>match_results</code> constructors</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.10.2</entry>
+ <entry><code>match_results</code> size</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.10.3</entry>
+ <entry><code>match_results</code> element access</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.10.4</entry>
+ <entry><code>match_results</code> formatting</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.10.5</entry>
+ <entry><code>match_results</code> allocator</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.10.6</entry>
+ <entry><code>match_results</code> swap</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.11</entry>
+ <entry>Regular expression algorithms</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.11.1</entry>
+ <entry>exceptions</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.11.2</entry>
+ <entry><code>regex_match</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.11.3</entry>
+ <entry><code>regex_search</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.11.4</entry>
+ <entry><code>regex_replace</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12</entry>
+ <entry>Regular expression Iterators</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12.1</entry>
+ <entry>Class template <code>regex_iterator</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12.1.1</entry>
+ <entry><code>regex_iterator</code> constructors</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12.1.2</entry>
+ <entry><code>regex_iterator</code> comparisons</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12.1.3</entry>
+ <entry><code>regex_iterator</code> dereference</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12.1.4</entry>
+ <entry><code>regex_iterator</code> increment</entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12.2.1</entry>
+ <entry><code>regex_token_iterator</code> constructors</entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.12.2.3</entry>
+ <entry><code>regex_token_iterator</code> dereference</entry>
+ <entry>N</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/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>7.13</entry>
+ <entry>Modified ECMAScript regular expression grammar</entry>
+ <entry>N</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>&lt;complex&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.2</entry>
+ <entry>Function <code>acos</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.3</entry>
+ <entry>Function <code>asin</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.4</entry>
+ <entry>Function <code>atan</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.5</entry>
+ <entry>Function <code>acosh</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.6</entry>
+ <entry>Function <code>asinh</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.7</entry>
+ <entry>Function <code>atanh</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.8</entry>
+ <entry>Function <code>fabs</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.1.9</entry>
+ <entry>Additional Overloads</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>8.2</entry>
+ <entry>Header <code>&lt;ccomplex&gt;</code></entry>
+ <entry>N</entry>
+ <entry>DR 551</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>8.3</entry>
+ <entry>Header <code>&lt;complex.h&gt;</code></entry>
+ <entry>N</entry>
+ <entry>DR 551</entry>
+ </row>
+ <row>
+ <entry>8.4</entry>
+ <entry>Additions to header <code>&lt;cctype&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.4.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.4.2</entry>
+ <entry>Function <code>isblank</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.5</entry>
+ <entry>Additions to header <code>&lt;ctype.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.6</entry>
+ <entry>Header <code>&lt;cfenv&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.6.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.6.2</entry>
+ <entry>Definitions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.7</entry>
+ <entry>Header <code>&lt;fenv.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.8</entry>
+ <entry>Additions to header <code>&lt;cfloat&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.9</entry>
+ <entry>Additions to header <code>&lt;float.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>8.10</entry>
+ <entry>Additions to header <code>&lt;ios&gt;</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>8.10.1</entry>
+ <entry>Synopsis</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>8.10.2</entry>
+ <entry>Function <code>hexfloat</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.11</entry>
+ <entry>Header <code>&lt;cinttypes&gt;</code></entry>
+ <entry>Y</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/>
+ </row>
+ <row>
+ <entry>8.12</entry>
+ <entry>Header <code>&lt;inttypes.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.13</entry>
+ <entry>Additions to header <code>&lt;climits&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.14</entry>
+ <entry>Additions to header <code>&lt;limits.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>8.15</entry>
+ <entry>Additions to header <code>&lt;locale&gt;</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.16</entry>
+ <entry>Additions to header <code>&lt;cmath&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.16.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.16.2</entry>
+ <entry>Definitions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.16.3</entry>
+ <entry>Function template definitions</entry>
+ <entry>Y</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>&lt;math.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.18</entry>
+ <entry>Additions to header <code>&lt;cstdarg&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.19</entry>
+ <entry>Additions to header <code>&lt;stdarg.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.20</entry>
+ <entry>The header <code>&lt;cstdbool&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.21</entry>
+ <entry>The header <code>&lt;stdbool.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.22</entry>
+ <entry>The header <code>&lt;cstdint&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.22.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.22.2</entry>
+ <entry>Definitions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.23</entry>
+ <entry>The header <code>&lt;stdint.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.24</entry>
+ <entry>Additions to header <code>&lt;cstdio&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.24.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.24.2</entry>
+ <entry>Definitions</entry>
+ <entry>Y</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>&lt;stdio.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.25</entry>
+ <entry>Additions to header <code>&lt;cstdlib&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.25.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.25.2</entry>
+ <entry>Definitions</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.25.3</entry>
+ <entry>Function <code>abs</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.25.4</entry>
+ <entry>Function <code>div</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.26</entry>
+ <entry>Additions to header <code>&lt;stdlib.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.27</entry>
+ <entry>Header <code>&lt;ctgmath&gt;</code></entry>
+ <entry>Y</entry>
+ <entry>DR 551</entry>
+ </row>
+ <row>
+ <entry>8.28</entry>
+ <entry>Header <code>&lt;tgmath.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry>DR 551</entry>
+ </row>
+ <row>
+ <entry>8.29</entry>
+ <entry>Additions to header <code>&lt;ctime&gt;</code></entry>
+ <entry>Y</entry>
+ <entry>C library dependency</entry>
+ </row>
+ <row>
+ <entry>8.30</entry>
+ <entry>Additions to header <code>&lt;cwchar&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.30.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.30.2</entry>
+ <entry>Definitions</entry>
+ <entry>Y</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>&lt;wchar.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.32</entry>
+ <entry>Additions to header <code>&lt;cwctype&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.32.1</entry>
+ <entry>Synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.32.2</entry>
+ <entry>Function <code>iswblank</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>8.33</entry>
+ <entry>Additions to header <code>&lt;wctype.h&gt;</code></entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ </tbody>
+</tgroup>
+</table>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml b/libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml
new file mode 100644
index 000000000..997e76be1
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/status_cxxtr24733.xml
@@ -0,0 +1,299 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="status.iso.tr24733" xreflabel="Status C++ TR24733">
+<?dbhtml filename="status_iso_cxxtr24733.html"?>
+
+<info><title>C++ TR 24733</title>
+ <keywordset>
+ <keyword>
+ TR 24733
+ </keyword>
+ </keywordset>
+</info>
+
+<para>
+This table is based on the table of contents of
+ISO/IEC TR 24733 Date: 2009-08-28
+Extension for the programming language C++ to support
+decimal floating-point arithmetic
+</para>
+
+<para>
+This page describes the TR 24733 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++ TR 24733 Implementation Status</title>
+
+<tgroup cols="4" align="left" colsep="0" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+ <thead>
+ <row>
+ <entry>Section</entry>
+ <entry>Description</entry>
+ <entry>Status</entry>
+ <entry>Comments</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>
+ <emphasis>0</emphasis>
+ </entry>
+ <entry namest="c2" nameend="c4" align="left">
+ <emphasis>Introduction</emphasis>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <emphasis>1</emphasis>
+ </entry>
+ <entry namest="c2" nameend="c4" align="left">
+ <emphasis>Normative references</emphasis>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <emphasis>2</emphasis>
+ </entry>
+ <entry namest="c2" nameend="c4" align="left">
+ <emphasis>Conventions</emphasis>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <emphasis>3</emphasis>
+ </entry>
+ <entry namest="c2" nameend="c4" align="left">
+ <emphasis>Decimal floating-point types</emphasis>
+ </entry>
+ </row>
+
+ <row>
+ <entry>3.1</entry>
+ <entry>Characteristics of decimal floating-point types</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.2</entry>
+ <entry>Decimal Types</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>3.2.1</entry>
+ <entry>Class <code>decimal</code> synopsis</entry>
+ <entry>Partial</entry>
+ <entry>Missing declarations for formatted input/output; non-conforming extension for functions converting to integral type</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>3.2.2</entry>
+ <entry>Class <code>decimal32</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing 3.2.2.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>3.2.3</entry>
+ <entry>Class <code>decimal64</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing 3.2.3.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</entry>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>3.2.4</entry>
+ <entry>Class <code>decimal128</code></entry>
+ <entry>Partial</entry>
+ <entry>Missing 3.2.4.5 conversion to integral type; conforming extension for conversion from scalar decimal floating-point</entry>
+ </row>
+ <row>
+ <entry>3.2.5</entry>
+ <entry>Initialization from coefficient and exponent</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.2.6</entry>
+ <entry>Conversion to generic floating-point type</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.2.7</entry>
+ <entry>Unary arithmetic operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.2.8</entry>
+ <entry>Binary arithmetic operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.2.9</entry>
+ <entry>Comparison operators</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.2.10</entry>
+ <entry>Formatted input</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.2.11</entry>
+ <entry>Formatted output</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.3</entry>
+ <entry>Additions to header <code>limits</code></entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4</entry>
+ <entry>Headers <code>cfloat</code> and <code>float.h</code></entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4.2</entry>
+ <entry>Additions to header <code>cfloat</code> synopsis</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#B0B0B0" ?>
+ <entry>3.4.3</entry>
+ <entry>Additions to header <code>float.h</code> synopsis</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4.4</entry>
+ <entry>Maximum finite value</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4.5</entry>
+ <entry>Epsilon</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4.6</entry>
+ <entry>Minimum positive normal value</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4.7</entry>
+ <entry>Minimum positive subnormal value</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>3.4.8</entry>
+ <entry>Evaluation format</entry>
+ <entry>Y</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.5</entry>
+ <entry>Additions to <code>cfenv</code> and <code>fenv.h</code></entry>
+ <entry>Outside the scope of GCC</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.6</entry>
+ <entry>Additions to <code>cmath</code> and <code>math.h</code></entry>
+ <entry>Outside the scope of GCC</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.7</entry>
+ <entry>Additions to <code>cstdio</code> and <code>stdio.h</code></entry>
+ <entry>Outside the scope of GCC</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.8</entry>
+ <entry>Additions to <code>cstdlib</code> and <code>stdlib.h</code></entry>
+ <entry>Outside the scope of GCC</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.9</entry>
+ <entry>Additions to <code>cwchar</code> and <code>wchar.h</code></entry>
+ <entry>Outside the scope of GCC</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.10</entry>
+ <entry>Facets</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.11</entry>
+ <entry>Type traits</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+ <row>
+ <?dbhtml bgcolor="#C8B0B0" ?>
+ <entry>3.12</entry>
+ <entry>Hash functions</entry>
+ <entry>N</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry>
+ <emphasis>4</emphasis>
+ </entry>
+ <entry namest="c2" nameend="c4" align="left">
+ <emphasis>Notes on C compatibility</emphasis>
+ </entry>
+ </row>
+
+ </tbody>
+</tgroup>
+</table>
+
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/strings.xml b/libstdc++-v3/doc/xml/manual/strings.xml
new file mode 100644
index 000000000..4d9fc64f7
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/strings.xml
@@ -0,0 +1,486 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.strings" xreflabel="Strings">
+<?dbhtml filename="strings.html"?>
+
+<info><title>
+ Strings
+ <indexterm><primary>Strings</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+<!-- Sect1 01 : Character Traits -->
+
+<!-- Sect1 02 : String Classes -->
+<section xml:id="std.strings.string" xreflabel="string"><info><title>String Classes</title></info>
+
+
+ <section xml:id="strings.string.simple" xreflabel="Simple Transformations"><info><title>Simple Transformations</title></info>
+
+ <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&lt;&gt;</code> is used.
+ </para>
+ <para>
+ This code will go through some iterations. Here's a simple
+ version:
+ </para>
+ <programlisting>
+ #include &lt;string&gt;
+ #include &lt;algorithm&gt;
+ #include &lt;cctype&gt; // old &lt;ctype.h&gt;
+
+ 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>&lt;cctype&gt;</code> and
+ <code>&lt;locale&gt;</code>) so the template-arguments for
+ <code>transform&lt;&gt;</code> cannot be deduced, as explained in
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-11/msg00180.html">this
+ message</link>.
+ <!-- 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>(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>
+
+ </section>
+ <section xml:id="strings.string.case" xreflabel="Case Sensitivity"><info><title>Case Sensitivity</title></info>
+
+ <para>
+ </para>
+
+ <para>The well-known-and-if-it-isn't-well-known-it-ought-to-be
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gotw.ca/gotw/">Guru of the Week</link>
+ 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gotw.ca/gotw/029.htm">GotW 29</link>.
+ </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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://lafstern.org/matt/col2_new.pdf"> article</link> 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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.unicode.org/reports/tr21/tr21-5.html">Unicode
+ Technical Report discussing case handling</link>, which provides some
+ very good information.
+ </para>
+
+ </section>
+ <section xml:id="strings.string.character_types" xreflabel="Arbitrary Characters"><info><title>Arbitrary Character Types</title></info>
+
+ <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&lt;my_unicode_char&gt;</code>, or assuming
+ that integers are wider than characters on your platform, maybe just
+ declare variables of type <code>std::basic_string&lt;int&gt;</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 &lt;typename CharT,
+ typename Traits = char_traits&lt;CharT&gt;,
+ typename Alloc = allocator&lt;CharT&gt; &gt;
+ class basic_string { .... };</programlisting>
+ <para>Now, <code>allocator&lt;CharT&gt;</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 &lt;typename CharT&gt;
+ struct char_traits
+ {
+ static void foo (type1 x, type2 y);
+ ...
+ };</programlisting>
+ <para>and functions such as char_traits&lt;CharT&gt;::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&lt;char,char_traits&lt;char&gt;&gt;</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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html">a lot
+ of work to do</link>, 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html">on the
+ mailing list</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html">the
+ nice-looking first attempt</link> turned out to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00242.html">not
+ be conforming C++</link>, due to the rule that CharT must be a POD.
+ (See how tricky this is?)
+ </para>
+
+ </section>
+
+ <section xml:id="strings.string.token" xreflabel="Tokenizing"><info><title>Tokenizing</title></info>
+
+ <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 &lt;string&gt;
+template &lt;typename Container&gt;
+void
+stringtok(Container &amp;container, string const &amp;in,
+ const char * const delimiters = " \t\n")
+{
+ const string::size_type len = in.length();
+ string::size_type i = 0;
+
+ while (i &lt; 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&lt;string&gt; ls;
+ stringtok (ls, " this \t is\t\n a test ");
+ for (std::list&lt;string&gt;const_iterator i = ls.begin();
+ i != ls.end(); ++i)
+ {
+ std::cerr &lt;&lt; ':' &lt;&lt; (*i) &lt;&lt; ":\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.
+ </para>
+
+ <para><emphasis>Added February 2001:</emphasis> Mark Wilden pointed out that the
+ standard <code>std::getline()</code> function can be used with standard
+ <code>istringstreams</code> 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>
+
+
+ </section>
+ <section xml:id="strings.string.shrink" xreflabel="Shrink to Fit"><info><title>Shrink to Fit</title></info>
+
+ <para>
+ </para>
+ <para>From GCC 3.4 calling <code>s.reserve(res)</code> on a
+ <code>string s</code> with <code>res &lt; 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 <link linkend="faq.size_equals_capacity">this FAQ
+ entry</link>) but the regular copy constructor cannot be used
+ because libstdc++'s <code>string</code> is Copy-On-Write.
+ </para>
+ <para>In <link linkend="status.iso.200x">C++0x</link> mode you can call
+ <code>s.shrink_to_fit()</code> to achieve the same effect as
+ <code>s.reserve(s.size())</code>.
+ </para>
+
+
+ </section>
+
+ <section xml:id="strings.string.Cstring" xreflabel="CString (MFC)"><info><title>CString (MFC)</title></info>
+
+ <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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this
+ message</link>, 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 &lt;iostream&gt;
+ #include &lt;string&gt;
+ #include &lt;sstream&gt;
+
+ string f (string&amp; incoming) // incoming is "foo N"
+ {
+ istringstream incoming_stream(incoming);
+ string the_word;
+ int the_number;
+
+ incoming_stream &gt;&gt; the_word // extract "foo"
+ &gt;&gt; the_number; // extract N
+
+ ostringstream output_stream;
+ output_stream &lt;&lt; "The word was " &lt;&lt; the_word
+ &lt;&lt; " and 3*N was " &lt;&lt; (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&amp; foo, unsigned n)
+ {
+ CString tmp;
+ for (unsigned i = 0; i &lt; 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 chapters of the SGI STL are used in libstdc++, their
+ string class is not. The SGI <code>string</code> is essentially
+ <code>vector&lt;char&gt;</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>
+
+ </section>
+</section>
+
+<!-- Sect1 03 : Interacting with C -->
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/support.xml b/libstdc++-v3/doc/xml/manual/support.xml
new file mode 100644
index 000000000..2cb7205bd
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/support.xml
@@ -0,0 +1,443 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.support" xreflabel="Support">
+<?dbhtml filename="support.html"?>
+
+<info><title>
+ Support
+ <indexterm><primary>Support</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+ <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>
+
+<section xml:id="std.support.types" xreflabel="Types"><info><title>Types</title></info>
+ <?dbhtml filename="fundamental_types.html"?>
+
+ <section xml:id="std.support.types.fundamental" xreflabel="Fundamental Types"><info><title>Fundamental Types</title></info>
+
+ <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>
+
+ </section>
+ <section xml:id="std.support.types.numeric_limits" xreflabel="Numeric Properties"><info><title>Numeric Properties</title></info>
+
+
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00593.html">here</link>
+ and defined as follows:
+ </para>
+
+ <programlisting>
+ template&lt;typename T&gt;
+ 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>
+ </section>
+
+ <section xml:id="std.support.types.null" xreflabel="NULL"><info><title>NULL</title></info>
+
+ <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
+ <code>#define</code>'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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.awprofessional.com/titles/0-201-92488-9/"><emphasis>Effective
+ C++</emphasis></link>, 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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.awprofessional.com/titles/0-201-31015-5/">the
+ Effective C++ CD example</link>
+ </para>
+ </section>
+
+</section>
+
+<section xml:id="std.support.memory" xreflabel="Dynamic Memory"><info><title>Dynamic Memory</title></info>
+ <?dbhtml filename="dynamic_memory.html"?>
+
+ <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 (&amp;my_new_handler);
+ ...
+ }
+ </programlisting>
+ <para>
+ <classname>bad_alloc</classname> is derived from the base <classname>exception</classname>
+ class defined in Sect1 19.
+ </para>
+</section>
+
+<section xml:id="std.support.termination" xreflabel="Termination"><info><title>Termination</title></info>
+ <?dbhtml filename="termination.html"?>
+
+ <section xml:id="support.termination.handlers" xreflabel="Termination Handlers"><info><title>Termination Handlers</title></info>
+
+ <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 inheritnum="ignore" continuation="restarts">
+ <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>
+ </section>
+
+ <section xml:id="support.termination.verbose" xreflabel="Verbose Terminate Handler"><info><title>Verbose Terminate Handler</title></info>
+ <?dbhtml filename="verbose_termination.html"?>
+
+ <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 &lt;exception&gt;
+
+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 &lt;exception&gt;
+#include &lt;stdexcept&gt;
+
+struct argument_error : public std::runtime_error
+{
+ argument_error(const std::string&amp; s): std::runtime_error(s) { }
+};
+
+int main(int argc)
+{
+ std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
+ if (argc &gt; 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>
+
+ </section>
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/test.xml b/libstdc++-v3/doc/xml/manual/test.xml
new file mode 100644
index 000000000..006ff3320
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/test.xml
@@ -0,0 +1,1035 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.setup.test" xreflabel="Testing">
+<?dbhtml filename="test.html"?>
+
+<info><title>Test</title>
+ <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>
+</info>
+
+<para>
+The libstdc++ testsuite includes testing for standard conformance,
+regressions, ABI, and performance.
+</para>
+
+<section xml:id="test.organization" xreflabel="Test Organization"><info><title>Organization</title></info>
+
+
+<section xml:id="test.organization.layout" xreflabel="Directory Layout"><info><title>Directory Layout</title></info>
+
+
+<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
+28_regex
+29_atomics
+30_threads
+ </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.
+ </programlisting>
+
+ <para>
+ Some directories don't have test files, but instead contain
+ auxiliary information:
+ </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>
+</section>
+
+
+<section xml:id="test.organization.naming" xreflabel="Naming Conventions"><info><title>Naming Conventions</title></info>
+
+
+ <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>
+
+</section>
+</section>
+
+
+<section xml:id="test.run" xreflabel="Running the Testsuite"><info><title>Running the Testsuite</title></info>
+
+
+ <section xml:id="test.run.basic"><info><title>Basic</title></info>
+
+
+ <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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/gcc-4.3/buildstat.html">build
+ status</link> section of each individual release, and are also
+ archived on a daily basis on the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</link>
+ mailing list. Please check either of these places for a similar
+ combination of source version, operating system, and host CPU.
+ </para>
+ </section>
+
+ <section xml:id="test.run.variations"><info><title>Variations</title></info>
+
+ <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>
+ </section>
+
+ <section xml:id="test.run.permutations"><info><title>Permutations</title></info>
+
+ <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>
+ </section>
+</section>
+
+<section xml:id="test.new_tests"><info><title>Writing a new test case</title></info>
+
+
+ <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 &lt;regexp&gt; 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 &lt;regexp&gt; 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 &lt;regexp&gt; 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 &lt;regexp&gt;
+# (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>
+</section>
+
+
+<section xml:id="test.harness" xreflabel="Test Harness and Utilities"><info><title>Test Harness and Utilities</title></info>
+
+
+<section xml:id="test.harness.dejagnu"><info><title>Dejagnu Harness Details</title></info>
+
+ <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>
+
+</section>
+
+<section xml:id="test.harness.utils"><info><title>Utilities</title></info>
+
+ <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 <link linkend="appendix.porting.abi">here</link>
+ </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>
+</section>
+
+</section>
+
+<section xml:id="test.special"><info><title>Special Topics</title></info>
+
+
+<section xml:id="test.exception.safety"><info><title>
+ Qualifying Exception Safety Guarantees
+ <indexterm>
+ <primary>Test</primary>
+ <secondary>Exception Safety</secondary>
+ </indexterm>
+</title></info>
+
+
+<section xml:id="test.exception.safety.overview"><info><title>Overview</title></info>
+
+
+ <para>
+ Testing is composed of running a particular test sequence,
+ and looking at what happens to the surrounding code when
+ exceptions are thrown. Each test is composed of measuring
+ initial state, executing a particular sequence of code under
+ some instrumented conditions, measuring a final state, and
+ then examining the differences between the two states.
+ </para>
+
+ <para>
+ Test sequences are composed of constructed code sequences
+ that exercise a particular function or member function, and
+ either confirm no exceptions were generated, or confirm the
+ consistency/coherency of the test subject in the event of a
+ thrown exception.
+ </para>
+
+ <para>
+ Random code paths can be constructed using the basic test
+ sequences and instrumentation as above, only combined in a
+ random or pseudo-random way.
+ </para>
+
+ <para> To compute the code paths that throw, test instruments
+ are used that throw on allocation events
+ (<classname>__gnu_cxx::throw_allocator_random</classname>
+ and <classname>__gnu_cxx::throw_allocator_limit</classname>)
+ and copy, assignment, comparison, increment, swap, and
+ various operators
+ (<classname>__gnu_cxx::throw_type_random</classname>
+ and <classname>__gnu_cxx::throw_type_limit</classname>). Looping
+ through a given test sequence and conditionally throwing in
+ all instrumented places. Then, when the test sequence
+ completes without an exception being thrown, assume all
+ potential error paths have been exercised in a sequential
+ manner.
+ </para>
+</section>
+
+
+<section xml:id="test.exception.safety.status"><info><title>
+ Existing tests
+</title></info>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ad Hoc
+ </para>
+ <para>
+ For example,
+ <filename>testsuite/23_containers/list/modifiers/3.cc</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Policy Based Data Structures
+ </para>
+ <para>
+ For example, take the test
+ functor <classname>rand_reg_test</classname> in
+ in <filename>testsuite/ext/pb_ds/regression/tree_no_data_map_rand.cc</filename>. This uses <classname>container_rand_regression_test</classname> in
+<filename>testsuite/util/regression/rand/assoc/container_rand_regression_test.h</filename>.
+
+ </para>
+
+ <para>
+ Which has several tests for container member functions,
+Includes control and test container objects. Configuration includes
+random seed, iterations, number of distinct values, and the
+probability that an exception will be thrown. Assumes instantiating
+container uses an extension
+allocator, <classname>__gnu_cxx::throw_allocator_random</classname>,
+as the allocator type.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ C++0x Container Requirements.
+ </para>
+
+ <para>
+ Coverage is currently limited to testing container
+ requirements for exception safety,
+ although <classname>__gnu_cxx::throw_type</classname> meets
+ the additional type requirements for testing numeric data
+ structures and instantiating algorithms.
+ </para>
+
+ <para>
+ Of particular interest is extending testing to algorithms and
+ then to parallel algorithms. Also io and locales.
+ </para>
+
+ <para>
+ The test instrumentation should also be extended to add
+ instrumentation to <classname>iterator</classname>
+ and <classname>const_iterator</classname> types that throw
+ conditionally on iterator operations.
+ </para>
+ </listitem>
+ </itemizedlist>
+</section>
+
+
+<section xml:id="test.exception.safety.containers"><info><title>
+C++0x Requirements Test Sequence Descriptions
+</title></info>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Basic
+ </para>
+
+ <para>
+ Basic consistency on exception propagation tests. For
+ each container, an object of that container is constructed,
+ a specific member function is exercised in
+ a <literal>try</literal> block, and then any thrown
+ exceptions lead to error checking in the appropriate
+ <literal>catch</literal> block. The container's use of
+ resources is compared to the container's use prior to the
+ test block. Resource monitoring is limited to allocations
+ made through the container's <type>allocator_type</type>,
+ which should be sufficient for container data
+ structures. Included in these tests are member functions
+ are <type>iterator</type> and <type>const_iterator</type>
+ operations, <function>pop_front</function>, <function>pop_back</function>, <function>push_front</function>, <function>push_back</function>, <function>insert</function>, <function>erase</function>, <function>swap</function>, <function>clear</function>,
+ and <function>rehash</function>. The container in question is
+ instantiated with two instrumented template arguments,
+ with <classname>__gnu_cxx::throw_allocator_limit</classname>
+ as the allocator type, and
+ with <classname>__gnu_cxx::throw_type_limit</classname> as
+ the value type. This allows the test to loop through
+ conditional throw points.
+ </para>
+
+ <para>
+ The general form is demonstrated in
+ <filename>testsuite/23_containers/list/requirements/exception/basic.cc
+ </filename>. The instantiating test object is <classname>__gnu_test::basic_safety</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Generation Prohibited
+ </para>
+
+ <para>
+ Exception generation tests. For each container, an object of
+ that container is constructed and all member functions
+ required to not throw exceptions are exercised. Included in
+ these tests are member functions
+ are <type>iterator</type> and <type>const_iterator</type> operations, <function>erase</function>, <function>pop_front</function>, <function>pop_back</function>, <function>swap</function>,
+ and <function>clear</function>. The container in question is
+ instantiated with two instrumented template arguments,
+ with <classname>__gnu_cxx::throw_allocator_random</classname>
+ as the allocator type, and
+ with <classname>__gnu_cxx::throw_type_random</classname> as
+ the value type. This test does not loop, an instead is sudden
+ death: first error fails.
+ </para>
+ <para>
+ The general form is demonstrated in
+ <filename>testsuite/23_containers/list/requirements/exception/generation_prohibited.cc
+ </filename>. The instantiating test object is <classname>__gnu_test::generation_prohibited</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Propagation Consistent
+ </para>
+
+ <para>
+ Container rollback on exception propagation tests. For
+ each container, an object of that container is constructed,
+ a specific member function that requires rollback to a previous
+ known good state is exercised in
+ a <literal>try</literal> block, and then any thrown
+ exceptions lead to error checking in the appropriate
+ <literal>catch</literal> block. The container is compared to
+ the container's last known good state using such parameters
+ as size, contents, and iterator references. Included in these
+ tests are member functions
+ are <function>push_front</function>, <function>push_back</function>, <function>insert</function>,
+ and <function>rehash</function>. The container in question is
+ instantiated with two instrumented template arguments,
+ with <classname>__gnu_cxx::throw_allocator_limit</classname>
+ as the allocator type, and
+ with <classname>__gnu_cxx::throw_type_limit</classname> as
+ the value type. This allows the test to loop through
+ conditional throw points.
+ </para>
+
+ <para>
+ The general form demonstrated in
+ <filename>testsuite/23_containers/list/requirements/exception/propagation_coherent.cc
+ </filename>. The instantiating test object is <classname>__gnu_test::propagation_coherent</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+</section>
+
+</section>
+
+</section>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
new file mode 100644
index 000000000..02498e21c
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -0,0 +1,1543 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.using" xreflabel="Using">
+ <info><title>Using</title></info>
+ <?dbhtml filename="using.html"?>
+
+ <section xml:id="manual.intro.using.flags" xreflabel="Flags"><info><title>Command Options</title></info>
+
+ <para>
+ The set of features available in the GNU C++ library is shaped
+ by
+ several <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc-4.3.2//gcc/Invoking-GCC.html">GCC
+ Command Options</link>. Options that impact libstdc++ are
+ enumerated and detailed in the table below.
+ </para>
+
+ <para>
+ By default, <command>g++</command> is equivalent to <command>g++ -std=gnu++98</command>. The standard library also defaults to this dialect.
+ </para>
+
+ <table frame="all">
+<title>C++ Command Options</title>
+
+<tgroup cols="2" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+
+ <thead>
+ <row>
+ <entry>Option Flags</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>-std=c++98</literal></entry>
+ <entry>Use the 1998 ISO C++ standard plus amendments.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-std=gnu++98</literal></entry>
+ <entry>As directly above, with GNU extensions.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-std=c++0x</literal></entry>
+ <entry>Use the working draft of the upcoming ISO C++0x standard.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-std=gnu++0x</literal></entry>
+ <entry>As directly above, with GNU extensions.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-fexceptions</literal></entry>
+ <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry>
+ </row>
+
+ <row>
+ <entry><literal>-frtti</literal></entry>
+ <entry>As above, but RTTI-free dialect.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-pthread</literal> or <literal>-pthreads</literal></entry>
+ <entry>For ISO C++0x &lt;thread&gt;, &lt;future&gt;,
+ &lt;mutex&gt;, or &lt;condition_variable&gt;.</entry>
+ </row>
+
+ <row>
+ <entry><literal>-fopenmp</literal></entry>
+ <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
+ </row>
+ </tbody>
+
+</tgroup>
+</table>
+
+ </section>
+
+ <section xml:id="manual.intro.using.headers" xreflabel="Headers"><info><title>Headers</title></info>
+ <?dbhtml filename="using_headers.html"?>
+
+
+ <section xml:id="manual.intro.using.headers.all" xreflabel="Header Files"><info><title>Header Files</title></info>
+
+
+ <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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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/>
+<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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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/>
+<table frame="all">
+<title>C++ 200x Library Headers</title>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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">future</filename></entry>
+<entry><filename class="headerfile">initalizer_list</filename></entry>
+<entry><filename class="headerfile">iomanip</filename></entry>
+<entry><filename class="headerfile">ios</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">iosfwd</filename></entry>
+<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>
+</row>
+<row>
+<entry><filename class="headerfile">list</filename></entry>
+<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>
+</row>
+<row>
+<entry><filename class="headerfile">new</filename></entry>
+<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>
+</row>
+<row>
+<entry><filename class="headerfile">ratio</filename></entry>
+<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>
+</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">system_error</filename></entry>
+<entry><filename class="headerfile">thread</filename></entry>
+</row>
+<row>
+<entry><filename class="headerfile">tuple</filename></entry>
+<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>
+</row>
+<row>
+<entry><filename class="headerfile">utility</filename></entry>
+<entry><filename class="headerfile">valarray</filename></entry>
+<entry><filename class="headerfile">vector</filename></entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+
+<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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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">cstdbool</filename></entry>
+</row>
+<row>
+<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>
+<entry><filename class="headerfile">cstring</filename></entry>
+</row>
+<row>
+<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>
+<entry><filename class="headerfile">cwctype</filename></entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+
+<para>
+ In addition, TR1 includes as:
+</para>
+
+<table frame="all">
+<title>C++ TR 1 Library Headers</title>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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/>
+
+
+<table frame="all">
+<title>C++ TR 1 Library Headers for C Library Facilities</title>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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>Decimal floating-point arithmetic is available if the C++
+compiler supports scalar decimal floating-point types defined via
+<code>__attribute__((mode(SD|DD|LD)))</code>.
+</para>
+
+<table frame="all">
+<title>C++ TR 24733 Decimal Floating-Point Header</title>
+
+<tgroup cols="1" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<tbody>
+<row>
+<entry><filename class="headerfile">decimal/decimal</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 colname="c2"/>
+<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 colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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/>
+
+<table frame="all">
+<title>Extension Debug Headers</title>
+
+<tgroup cols="5" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<colspec colname="c5"/>
+<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/>
+
+<table frame="all">
+<title>Extension Profile Headers</title>
+
+<tgroup cols="4" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<colspec colname="c4"/>
+<tbody>
+
+<row>
+<entry><filename class="headerfile">profile/bitset</filename></entry>
+<entry><filename class="headerfile">profile/deque</filename></entry>
+<entry><filename class="headerfile">profile/list</filename></entry>
+<entry><filename class="headerfile">profile/map</filename></entry>
+</row>
+
+<row>
+<entry><filename class="headerfile">profile/set</filename></entry>
+<entry><filename class="headerfile">profile/unordered_map</filename></entry>
+<entry><filename class="headerfile">profile/unordered_set</filename></entry>
+<entry><filename class="headerfile">profile/vector</filename></entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+
+<para/>
+
+<table frame="all">
+<title>Extension Parallel Headers</title>
+
+<tgroup cols="2" align="left" colsep="1" rowsep="1">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<tbody>
+<row>
+<entry><filename class="headerfile">parallel/algorithm</filename></entry>
+<entry><filename class="headerfile">parallel/numeric</filename></entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+ </section>
+
+ <section xml:id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"><info><title>Mixing Headers</title></info>
+
+
+<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 &lt;array&gt;
+#include &lt;functional&gt;
+</programlisting>
+
+<para>Implies C++0x mode. To use the entities in &lt;array&gt;, the C++0x
+compilation mode must be used, which implies the C++0x functionality
+(and deprecations) in &lt;functional&gt; 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 &lt;tr1/type_traits&gt;
+#include &lt;type_traits&gt;
+</programlisting>
+
+<para> Several parts of C++0x diverge quite substantially from TR1 predecessors.
+</para>
+ </section>
+
+ <section xml:id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"><info><title>The C Headers and <code>namespace std</code></title></info>
+
+
+<para>
+ The standard specifies that if one includes the C-style header
+ (&lt;math.h&gt; 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.) On the other hand, including the C++-style
+ header (&lt;cmath&gt;) 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 &lt;cmath&gt;, 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>
+ </section>
+
+ <section xml:id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"><info><title>Precompiled Headers</title></info>
+
+
+
+<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 &lt;stdc++.h&gt;, and adds all the TR1 headers.
+</para>
+</listitem>
+
+<listitem><para>extc++.h</para>
+<para>Includes all of &lt;stdtr1c++.h&gt;, 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 &lt;...&gt; 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> Detailed information about creating precompiled header files can be found in the GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</link>.
+</para>
+
+ </section>
+ </section>
+
+
+ <section xml:id="manual.intro.using.macros" xreflabel="Macros"><info><title>Macros</title></info>
+ <?dbhtml filename="using_macros.html"?>
+
+
+ <para>
+ All library macros begin with <code>_GLIBCXX_</code>.
+ </para>
+
+ <para>
+ Furthermore, all pre-processor macros, switches, and
+ configuration options are gathered in the
+ file <filename class="headerfile">c++config.h</filename>, which
+ is generated during the libstdc++ configuration and build
+ process. This file is then included when needed by files part of
+ the public libstdc++ API, like &lt;ios&gt;. 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>.
+ </para>
+
+ <para>
+ A select handful of macros control libstdc++ extensions and extra
+ features, or provide versioning information for the API. Only
+ those macros listed below are offered for consideration by the
+ general public.
+ </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 <link linkend="appendix.porting.abi">
+ document</link>.
+ </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_USE_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 <link linkend="manual.ext.compile_checks">here</link>.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term><code>_GLIBCXX_DEBUG</code></term>
+ <listitem>
+ <para>
+ Undefined by default. When defined, compiles user code using
+ the <link linkend="manual.ext.debug_mode">debug mode</link>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
+ <listitem>
+ <para>
+ Undefined by default. When defined while compiling with
+ the <link linkend="manual.ext.debug_mode">debug mode</link>, 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 <link linkend="manual.ext.parallel_mode">parallel
+ mode</link>.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term><code>_GLIBCXX_PROFILE</code></term>
+ <listitem>
+ <para>Undefined by default. When defined, compiles user code
+ using the <link linkend="manual.ext.profile_mode">profile
+ mode</link>.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section xml:id="manual.intro.using.namespaces" xreflabel="Namespaces"><info><title>Namespaces</title></info>
+ <?dbhtml filename="using_namespaces.html"?>
+
+
+ <section xml:id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"><info><title>Available Namespaces</title></info>
+
+
+
+
+<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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</link>.
+</para>
+
+
+ </section>
+
+ <section xml:id="manual.intro.using.namespaces.std" xreflabel="namespace std"><info><title>namespace std</title></info>
+
+
+
+<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>
+
+ </section>
+
+ <section xml:id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"><info><title>Using Namespace Composition</title></info>
+
+
+<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
+ Llewelly and Karl Nelson)
+</para>
+
+
+ </section>
+ </section>
+
+ <section xml:id="manual.intro.using.linkage" xreflabel="Linkage"><info><title>Linking</title></info>
+ <?dbhtml filename="using_dynamic_or_shared.html"?>
+
+
+ <section xml:id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"><info><title>Almost Nothing</title></info>
+
+ <para>
+ Or as close as it gets: freestanding. This is a minimal
+ configuration, with only partial support for the standard
+ library. Assume only the following header files can be used:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename class="headerfile">cstdarg</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">cstddef</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">cstdlib</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">exception</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">limits</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">new</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">exception</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename class="headerfile">typeinfo</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ In addition, throw in
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename class="headerfile">cxxabi.h</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ In the
+ C++0x <link linkend="manual.intro.using.flags">dialect</link> add
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename class="headerfile">initializer_list</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class="headerfile">type_traits</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para> There exists a library that offers runtime support for
+ just these headers, and it is called
+ <filename class="libraryfile">libsupc++.a</filename>. To use it, compile with <command>gcc</command> instead of <command>g++</command>, like so:
+ </para>
+
+ <para>
+ <command>gcc foo.cc -lsupc++</command>
+ </para>
+
+ <para>
+ No attempt is made to verify that only the minimal subset
+ identified above is actually used at compile time. Violations
+ are diagnosed as undefined symbols at link time.
+ </para>
+ </section>
+
+ <section xml:id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"><info><title>Finding Dynamic or Shared Libraries</title></info>
+
+
+ <para>
+ If the only library built is the static library
+ (<filename class="libraryfile">libstdc++.a</filename>), or if
+ specifying static linking, this section is can be skipped. But
+ if building or using a shared library
+ (<filename class="libraryfile">libstdc++.so</filename>), then
+ additional location information will need to be provided.
+ </para>
+ <para>
+ But how?
+ </para>
+ <para>
+A quick read of the relevant part of the GCC
+ manual, <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b">Compiling
+ C++ Programs</link>, specifies linking against a C++
+ library. More details from the
+ GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/faq.html#rpath">FAQ</link>,
+ which states <emphasis>GCC does not, by default, specify a
+ location so that the dynamic linker can find dynamic libraries at
+ runtime.</emphasis>
+ </para>
+ <para>
+ Users will have to provide this information.
+ </para>
+ <para>
+ Methods vary for different platforms and different styles, and
+ are printed to the screen during installation. To summarize:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ At runtime set <literal>LD_LIBRARY_PATH</literal> 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 <literal>LD_LIBRARY_PATH</literal> first.
+ </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
+ <command>g++</command>, 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,</literal><filename class="directory">destdir/lib</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ IRIX ld:
+ <literal>-Wl,-rpath,</literal><filename class="directory">destdir/lib</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Solaris ld:
+ <literal>-Wl,-R</literal><filename class="directory">destdir/lib</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Some linkers allow you to specify the path to the library by
+ setting <literal>LD_RUN_PATH</literal> in your environment
+ when linking.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On some platforms the system administrator can configure the
+ dynamic linker to always look for libraries in
+ <filename class="directory">destdir/lib</filename>, for example
+ by using the <command>ldconfig</command> utility on Linux
+ or the <command>crle</command> utility on Solaris. This is a
+ system-wide change which can make the system unusable so if you
+ are unsure then use one of the other methods described above.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Use the <command>ldd</command> utility on the linked executable
+ to show
+ which <filename class="libraryfile">libstdc++.so</filename>
+ library the system will get at runtime.
+ </para>
+ <para>
+ A <filename class="libraryfile">libstdc++.la</filename> 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>
+ </section>
+ </section>
+
+
+ <section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
+ <?dbhtml filename="using_concurrency.html"?>
+
+
+ <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>
+
+ <section xml:id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"><info><title>Prerequisites</title></info>
+
+
+ <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>
+
+ </section>
+
+ <section xml:id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"><info><title>Thread Safety</title></info>
+
+
+
+<para>
+We currently use the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine
+ Dependent Options</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ An implementation of atomicity.h functions
+ exists for the architecture in question. See the internals documentation for more <link linkend="internals.thread_safety">details</link>.
+ </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>
+
+
+ </section>
+ <section xml:id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"><info><title>Atomics</title></info>
+
+ <para>
+ </para>
+ </section>
+
+ <section xml:id="manual.intro.using.concurrency.io" xreflabel="IO"><info><title>IO</title></info>
+
+ <para>This gets a bit tricky. Please read carefully, and bear with me.
+ </para>
+
+ <section xml:id="concurrency.io.structure" xreflabel="Structure"><info><title>Structure</title></info>
+
+ <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>
+ </section>
+
+ <section xml:id="concurrency.io.defaults" xreflabel="Defaults"><info><title>Defaults</title></info>
+
+ <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>
+ </section>
+
+ <section xml:id="concurrency.io.future" xreflabel="Future"><info><title>Future</title></info>
+
+ <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>
+ </section>
+
+ <section xml:id="concurrency.io.alt" xreflabel="Alt"><info><title>Alternatives</title></info>
+
+ <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>
+ </section>
+
+ </section>
+
+ <section xml:id="manual.intro.using.concurrency.containers" xreflabel="Containers"><info><title>Containers</title></info>
+
+
+ <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
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
+ http://www.sgi.com/tech/stl/thread_safety.html</link> and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/Allocators.html">SGI's
+ http://www.sgi.com/tech/stl/Allocators.html</link>.
+ </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
+ (<emphasis>For most clients...</emphasis>), 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 library implementation may be configured to use the
+ high-speed caching memory allocator, which complicates thread
+ safety issues. For all details about how to globally override
+ this at application run-time
+ see <link linkend="manual.intro.using.macros">here</link>. Also
+ useful are details
+ on <link linkend="std.util.memory.allocator">allocator</link>
+ options and capabilities.
+ </para>
+
+ </section>
+</section>
+
+<!-- Section 0x : Exception policies, expectations, topics -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="using_exceptions.xml">
+</xi:include>
+
+<!-- Section 0x : Debug -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="debug.xml">
+</xi:include>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/manual/using_exceptions.xml b/libstdc++-v3/doc/xml/manual/using_exceptions.xml
new file mode 100644
index 000000000..0ced13442
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/using_exceptions.xml
@@ -0,0 +1,548 @@
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.using.exceptions" xreflabel="Using Exceptions">
+<?dbhtml filename="using_exceptions.html"?>
+
+<info><title>Exceptions</title>
+ <keywordset>
+ <keyword>
+ C++
+ </keyword>
+ <keyword>
+ exception
+ </keyword>
+ <keyword>
+ error
+ </keyword>
+ <keyword>
+ exception neutrality
+ </keyword>
+ <keyword>
+ exception safety
+ </keyword>
+ <keyword>
+ exception propagation
+ </keyword>
+ <keyword>
+ -fno-exceptions
+ </keyword>
+ </keywordset>
+</info>
+
+<para>
+The C++ language provides language support for stack unwinding
+with <literal>try</literal> and <literal>catch</literal> blocks and
+the <literal>throw</literal> keyword.
+</para>
+
+<para>
+These are very powerful constructs, and require some thought when
+applied to the standard library in order to yield components that work
+efficiently while cleaning up resources when unexpectedly killed via
+exceptional circumstances.
+</para>
+
+<para>
+Two general topics of discussion follow:
+exception neutrality and exception safety.
+</para>
+
+
+<section xml:id="intro.using.exception.safety" xreflabel="Exception Safety"><info><title>Exception Safety</title></info>
+
+
+ <para>
+ What is exception-safe code?
+ </para>
+
+ <para>
+ Will define this as reasonable and well-defined behavior by classes
+ and functions from the standard library when used by user-defined
+ classes and functions that are themselves exception safe.
+ </para>
+
+ <para>
+ Please note that using exceptions in combination with templates
+ imposes an additional requirement for exception
+ safety. Instantiating types are required to have destructors that
+ do no throw.
+ </para>
+
+ <para>
+ Using the layered approach from Abrahams, can classify library
+ components as providing set levels of safety. These will be called
+ exception guarantees, and can be divided into three categories.
+ </para>
+
+<itemizedlist>
+
+ <listitem>
+ <para>
+ One. Don't throw.
+ </para>
+ <para>
+ As specified in 23.2.1 general container requirements. Applicable
+ to container and string classes.
+ </para>
+ <para>
+ Member
+ functions <function>erase</function>, <function>pop_back</function>, <function>pop_front</function>, <function>swap</function>, <function>clear</function>. And <type>iterator</type>
+ copy constructor and assignment operator.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Two. Don't leak resources when exceptions are thrown. This is
+ also referred to as the <quote>basic</quote> exception safety guarantee.
+ </para>
+
+ <para>
+ This applicable throughout the standard library.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Three. Commit-or-rollback semantics. This is
+ referred to as <quote>strong</quote> exception safety guarantee.
+ </para>
+
+ <para>
+ As specified in 23.2.1 general container requirements. Applicable
+ to container and string classes.
+ </para>
+ <para>
+ Member functions <function>insert</function> of a single
+ element, <function>push_back</function>, <function>push_front</function>,
+ and <function>rehash</function>.
+ </para>
+
+ </listitem>
+</itemizedlist>
+
+</section>
+
+
+<section xml:id="intro.using.exception.propagating" xreflabel="Exceptions Neutrality"><info><title>Exception Neutrality</title></info>
+
+ <para>
+ Simply put, once thrown an exception object should continue in
+ flight unless handled explicitly. In practice, this means
+ propagating exceptions should not be swallowed in
+ gratuitous <literal>catch(...)</literal> blocks. Instead,
+ matching <literal>try</literal> and <literal>catch</literal>
+ blocks should have specific catch handlers and allow un-handed
+ exception objects to propagate. If a
+ terminating <literal>catch(...)</literal> blocks exist then it
+ should end with a <literal>throw</literal> to re-throw the current
+ exception.
+ </para>
+
+ <para>
+ Why do this?
+ </para>
+
+ <para>
+ By allowing exception objects to propagate, a more flexible
+ approach to error handling is made possible (although not
+ required.) Instead of dealing with an error immediately, one can
+ allow the exception to propagate up until sufficient context is
+ available and the choice of exiting or retrying can be made in an
+ informed manner.
+ </para>
+
+ <para>
+ Unfortunately, this tends to be more of a guideline than a strict
+ rule as applied to the standard library. As such, the following is
+ a list of known problem areas where exceptions are not propagated.
+ </para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+ Input/Output
+ </para>
+ <para>
+ The destructor <function>ios_base::Init::~Init()</function>
+ swallows all exceptions from <function>flush</function> called on
+ all open streams at termination.
+ </para>
+
+ <para>
+ All formatted input in <classname>basic_istream</classname> or
+ formatted output in <classname>basic_ostream</classname> can be
+ configured to swallow exceptions
+ when <function>exceptions</function> is set to
+ ignore <type>ios_base::badbit</type>.
+ </para>
+
+ <para>
+ Functions that have been registered
+ with <function>ios_base::register_callback</function> swallow all
+ exceptions when called as part of a callback event.
+ </para>
+
+ <para>
+ When closing the underlying
+ file, <function>basic_filebuf::close</function> will swallow
+ (non-cancellation) exceptions thrown and return <literal>NULL</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Thread
+ </para>
+ <para>
+ The constructors of <classname>thread</classname> that take a
+ callable function argument swallow all exceptions resulting from
+ executing the function argument.
+ </para>
+ </listitem>
+</itemizedlist>
+
+</section>
+
+<section xml:id="intro.using.exception.no" xreflabel="-fno-exceptions"><info><title>Doing without</title></info>
+
+ <para>
+ C++ is a language that strives to be as efficient as is possible
+ in delivering features. As such, considerable care is used by both
+ language implementer and designers to make sure unused features
+ not impose hidden or unexpected costs. The GNU system tries to be
+ as flexible and as configurable as possible. So, it should come as
+ no surprise that GNU C++ provides an optional language extension,
+ spelled <literal>-fno-exceptions</literal>, as a way to excise the
+ implicitly generated magic necessary to
+ support <literal>try</literal> and <literal>catch</literal> blocks
+ and thrown objects. (Language support
+ for <literal>-fno-exceptions</literal> is documented in the GNU
+ GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options">manual</link>.)
+ </para>
+
+ <para>Before detailing the library support
+ for <literal>-fno-exceptions</literal>, first a passing note on
+ the things lost when this flag is used: it will break exceptions
+ trying to pass through code compiled
+ with <literal>-fno-exceptions</literal> whether or not that code
+ has any <literal>try</literal> or <literal>catch</literal>
+ constructs. If you might have some code that throws, you shouldn't
+ use <literal>-fno-exceptions</literal>. If you have some code that
+ uses <literal>try</literal> or <literal>catch</literal>, you
+ shouldn't use <literal>-fno-exceptions</literal>.
+ </para>
+
+ <para>
+ And what it to be gained, tinkering in the back alleys with a
+ language like this? Exception handling overhead can be measured
+ in the size of the executable binary, and varies with the
+ capabilities of the underlying operating system and specific
+ configuration of the C++ compiler. On recent hardware with GNU
+ system software of the same age, the combined code and data size
+ overhead for enabling exception handling is around 7%. Of course,
+ if code size is of singular concern than using the appropriate
+ optimizer setting with exception handling enabled
+ (ie, <literal>-Os -fexceptions</literal>) may save up to twice
+ that, and preserve error checking.
+ </para>
+
+ <para>
+ So. Hell bent, we race down the slippery track, knowing the brakes
+ are a little soft and that the right front wheel has a tendency to
+ wobble at speed. Go on: detail the standard library support
+ for <literal>-fno-exceptions</literal>.
+ </para>
+
+ <para>
+ In sum, valid C++ code with exception handling is transformed into
+ a dialect without exception handling. In detailed steps: all use
+ of the C++
+ keywords <literal>try</literal>, <literal>catch</literal>,
+ and <literal>throw</literal> in the standard library have been
+ permanently replaced with the pre-processor controlled equivalents
+ spelled <literal>__try</literal>, <literal>__catch</literal>,
+ and <literal>__throw_exception_again</literal>. They are defined
+ as follows.
+ </para>
+
+<programlisting>
+#ifdef __EXCEPTIONS
+# define __try try
+# define __catch(X) catch(X)
+# define __throw_exception_again throw
+#else
+# define __try if (true)
+# define __catch(X) if (false)
+# define __throw_exception_again
+#endif
+</programlisting>
+
+<para>
+ In addition, for every object derived from
+ class <classname>exception</classname>, there exists a corresponding
+ function with C language linkage. An example:
+</para>
+
+<programlisting>
+#ifdef __EXCEPTIONS
+ void __throw_bad_exception(void)
+ { throw bad_exception(); }
+#else
+ void __throw_bad_exception(void)
+ { abort(); }
+#endif
+</programlisting>
+
+<para>
+ The last language feature needing to be transformed
+ by <literal>-fno-exceptions</literal> is treatment of exception
+ specifications on member functions. Fortunately, the compiler deals
+ with this by ignoring exception specifications and so no alternate
+ source markup is needed.
+</para>
+
+<para>
+ By using this combination of language re-specification by the
+ compiler, and the pre-processor tricks and the functional
+ indirection layer for thrown exception objects by the library,
+ libstdc++ files can be compiled
+ with <literal>-fno-exceptions</literal>.
+</para>
+
+<para>
+ User code that uses C++ keywords
+ like <literal>throw</literal>, <literal>try</literal>,
+ and <literal>catch</literal> will produce errors even if the user
+ code has included libstdc++ headers and is using constructs
+ like <classname>basic_iostream</classname>. Even though the standard
+ library has been transformed, user code may need modification. User
+ code that attempts or expects to do error checking on standard
+ library components compiled with exception handling disabled should
+ be evaluated and potentially made conditional.
+</para>
+
+<para>
+ Some issues remain with this approach (see bugzilla entry
+ 25191). Code paths are not equivalent, in
+ particular <literal>catch</literal> blocks are not evaluated. Also
+ problematic are <literal>throw</literal> expressions expecting a
+ user-defined throw handler. Known problem areas in the standard
+ library include using an instance
+ of <classname>basic_istream</classname>
+ with <function>exceptions</function> set to specific
+ <type>ios_base::iostate</type> conditions, or
+ cascading <literal>catch</literal> blocks that dispatch error
+ handling or recovery efforts based on the type of exception object
+ thrown.
+</para>
+
+<para>
+ Oh, and by the way: none of this hackery is at all
+ special. (Although perhaps well-deserving of a raised eyebrow.)
+ Support continues to evolve and may change in the future. Similar
+ and even additional techniques are used in other C++ libraries and
+ compilers.
+</para>
+
+<para>
+ C++ hackers with a bent for language and control-flow purity have
+ been successfully consoled by grizzled C veterans lamenting the
+ substitution of the C language keyword
+ <literal>const</literal> with the uglified
+ doppelganger <literal>__const</literal>.
+</para>
+
+
+</section>
+
+<section xml:id="intro.using.exception.compat"><info><title>Compatibility</title></info>
+
+
+<section xml:id="using.exception.compat.c"><info><title>With <literal>C</literal></title></info>
+
+<para>
+ C language code that is expecting to interoperate with C++ should be
+ compiled with <literal>-fexceptions</literal>. This will make
+ debugging a C language function called as part of C++-induced stack
+ unwinding possible.
+</para>
+
+<para>
+ In particular, unwinding into a frame with no exception handling
+data will cause a runtime abort. If the unwinder runs out of unwind
+info before it finds a handler, <function>std::terminate()</function>
+is called.
+</para>
+
+<para>
+ Please note that most development environments should take care of
+ getting these details right. For GNU systems, all appropriate parts
+ of the GNU C library are already compiled
+ with <literal>-fexceptions</literal>.
+</para>
+
+</section>
+
+<section xml:id="using.exception.compat.posix"><info><title>With <literal>POSIX</literal> thread cancellation</title></info>
+
+
+<para>
+ GNU systems re-use some of the exception handling mechanisms to
+ track control flow for <literal>POSIX</literal> thread cancellation.
+</para>
+
+<para>
+ Cancellation points are functions defined by POSIX as worthy of
+ special treatment. The standard library may use some of these
+ functions to implement parts of the ISO C++ standard or depend on
+ them for extensions.
+</para>
+
+<para>
+ Of note:
+</para>
+
+<para>
+ <function>nanosleep</function>,
+ <function>read</function>, <function>write</function>, <function>open</function>, <function>close</function>,
+ and <function>wait</function>.
+</para>
+
+<para>
+ The parts of libstdc++ that use C library functions marked as
+ cancellation points should take pains to be exception neutral.
+ Failing this, <literal>catch</literal> blocks have been augmented to
+ show that the POSIX cancellation object is in flight.
+</para>
+
+<para>
+ This augmentation adds a <literal>catch</literal> block
+ for <classname>__cxxabiv1::__forced_unwind</classname>, which is the
+ object representing the POSIX cancellation object. Like so:
+</para>
+
+<programlisting>
+ catch(const __cxxabiv1::__forced_unwind&amp;)
+ {
+ this-&gt;_M_setstate(ios_base::badbit);
+ throw;
+ }
+ catch(...)
+ { this-&gt;_M_setstate(ios_base::badbit); }
+</programlisting>
+
+
+</section>
+</section>
+
+<bibliography xml:id="using.exceptions.biblio"><info><title>Bibliography</title></info>
+
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.opengroup.org/austin/" class="uri">
+ </biblioid>
+ <citetitle>
+ System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
+ </citetitle>
+
+ <pagenums>
+ 2.9.5 Thread Cancellation
+ </pagenums>
+ <copyright>
+ <year>2008</year>
+ <holder>
+ The Open Group/The Institute of Electrical and Electronics
+ Engineers, Inc.
+ </holder>
+ </copyright>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/community/error_handling.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Error and Exception Handling
+ </citetitle>
+
+ <author><personname><firstname>David</firstname><surname>Abrahams </surname></personname></author>
+ <publisher>
+ <publishername>
+ Boost
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/community/exception_safety.html" class="uri">
+ </biblioid>
+ <citetitle>
+ Exception-Safety in Generic Components
+ </citetitle>
+
+ <author><personname><firstname>David</firstname><surname>Abrahams</surname></personname></author>
+ <publisher>
+ <publishername>
+ Boost
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1077.pdf" class="uri">
+ </biblioid>
+ <citetitle>
+ Standard Library Exception Policy
+ </citetitle>
+ <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author>
+ <publisher>
+ <publishername>
+ WG21 N1077
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc-patches/2001-03/msg00661.html" class="uri">
+ </biblioid>
+ <citetitle>
+ ia64 c++ abi exception handling
+ </citetitle>
+
+ <author><personname><firstname>Richard</firstname><surname>Henderson</surname></personname></author>
+ <publisher>
+ <publishername>
+ GNU
+ </publishername>
+ </publisher>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.research.att.com/~bs/3rd_safe.pdf" class="uri">
+ </biblioid>
+ <citetitle>
+ Appendix E: Standard-Library Exception Safety
+ </citetitle>
+ <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <citetitle>
+ Exceptional C++
+ </citetitle>
+ <pagenums>
+ Exception-Safety Issues and Techniques
+ </pagenums>
+ <author><personname><firstname>Herb</firstname><surname>Sutter</surname></personname></author>
+ </biblioentry>
+
+ <biblioentry>
+ <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR25191" class="uri">
+ </biblioid>
+ <citetitle>
+ GCC Bug 25191: exception_defines.h #defines try/catch
+ </citetitle>
+ </biblioentry>
+
+</bibliography>
+
+</section>
diff --git a/libstdc++-v3/doc/xml/manual/utilities.xml b/libstdc++-v3/doc/xml/manual/utilities.xml
new file mode 100644
index 000000000..5c3a8fd48
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/utilities.xml
@@ -0,0 +1,124 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="std.util" xreflabel="Utilities">
+<?dbhtml filename="utilities.html"?>
+
+<info><title>
+ Utilities
+ <indexterm><primary>Utilities</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>
+ ISO C++
+ </keyword>
+ <keyword>
+ library
+ </keyword>
+ </keywordset>
+</info>
+
+
+
+<!-- Section 01 : Functors -->
+<section xml:id="std.util.functors" xreflabel="Functors"><info><title>Functors</title></info>
+<?dbhtml filename="functors.html"?>
+
+ <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 chapter of their STL, in
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/functors.html">their
+ http://www.sgi.com/tech/stl/functors.html</link>.
+ </para>
+</section>
+
+<!-- Section 02 : Pairs -->
+<section xml:id="std.util.pairs" xreflabel="Pairs"><info><title>Pairs</title></info>
+<?dbhtml filename="pairs.html"?>
+
+ <para>The <code>pair&lt;T1,T2&gt;</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&amp; x, const T2&amp; 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 &lt;class U, class V&gt; pair (const pair&lt;U,V&gt;&amp; 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&lt;T1,T2&gt;</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 &lt; y.first ||
+ ( !(y.first &lt; x.first) &amp;&amp; x.second &lt; 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&lt;int,MyClass&gt; p = make_pair(4,myobject);
+ </programlisting>
+
+</section>
+
+<!-- Section 03 : Memory -->
+<section xml:id="std.util.memory" xreflabel="Memory"><info><title>Memory</title></info>
+<?dbhtml filename="memory.html"?>
+
+ <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>
+
+</section>
+
+<!-- Section 04 : Traits -->
+<section xml:id="std.util.traits" xreflabel="Traits"><info><title>Traits</title></info>
+<?dbhtml filename="traits.html"?>
+
+ <para>
+ </para>
+</section>
+
+</chapter>
diff --git a/libstdc++-v3/doc/xml/spine.xml b/libstdc++-v3/doc/xml/spine.xml
new file mode 100644
index 000000000..5fb739fb2
--- /dev/null
+++ b/libstdc++-v3/doc/xml/spine.xml
@@ -0,0 +1,162 @@
+<set xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="set-index"
+ xreflabel="The GNU C++ Library">
+<?dbhtml filename="spine.html"?>
+
+ <title>The GNU C++ Library</title>
+
+<info>
+ <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>
+ <year>2010</year>
+ <holder>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org">FSF</link>
+ </holder>
+ </copyright>
+
+<authorgroup version="5.0">
+
+<!--
+ <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><personname><firstname/><surname/></personname><personblurb>
+ <para>
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Paolo</firstname><surname>Carlini</surname></personname><personblurb>
+ <para>
+ TR1, LWG Active, Closed, Defects lists.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Phil</firstname><surname>Edwards</surname></personname><personblurb>
+ <para>
+ Originating author, started HOWTO and FAQ, worked on sections
+ Demangling, Macros, Strings, Iterators, Backwards
+ Compatibility, SGI Extensions, Configure, Build, Install.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Doug</firstname><surname>Gregor</surname></personname><personblurb>
+ <para>
+ Debug Mode, TR1 function objects
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname><personblurb>
+ <para>
+ Allocators, ABI, API evolution and deprecation history,
+ Backwards Compatibility, Thread, Debug Support, Locales,
+ Facets, Parallel Mode, Headers, Namespaces, Construction and
+ Structure, Using Exceptions, DocBook conversion and layout.
+ </para>
+ </personblurb></author>
+
+
+ <author><personname><firstname>Dhruv</firstname><surname>Matani</surname></personname><personblurb>
+ <para>
+ bitmap_allocator
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Jason</firstname><surname>Merrill</surname></personname><personblurb>
+ <para>
+ License, __verbose_terminate_handler
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Mark</firstname><surname>Mitchell</surname></personname><personblurb>
+ <para>
+ Porting
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Nathan</firstname><surname>Myers</surname></personname><personblurb>
+ <para>
+ Referenced counted string, C++1998 implementation status.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Felix</firstname><surname>Natter</surname></personname><personblurb>
+ <para>
+ Namespace composition, Backwards Compatibility.
+ </para>
+ </personblurb></author>
+
+
+ <author><personname><firstname>Stefan</firstname><surname>Olsson</surname></personname><personblurb>
+ <para>
+ mt_allocator
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Silvius</firstname><surname>Rus</surname></personname><personblurb>
+ <para>
+ Profile mode
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname><personblurb>
+ <para>
+ Parallel mode
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Ami</firstname><surname>Tavory</surname></personname><personblurb>
+ <para>
+ Policy Based Data Structures, Associative Containers, Unordered
+ Containers.
+ </para>
+ </personblurb></author>
+
+ <author><personname><firstname>Jonathan</firstname><surname>Wakely</surname></personname><personblurb>
+ <para>
+ shared_ptr, markup editing and styling
+ </para>
+ </personblurb></author>
+
+</authorgroup>
+
+</info>
+
+
+<!-- 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>