[multiple changes]

2003-11-11  Doug Gregor  <gregod@cs.rpi.edu>

	* docs/html/debug.html: Document libstdc++ debug mode.
	* docs/html/debug_mode.html: Document libstdc++ debug mode design.
	* docs/html/test.html: Document how to test under debug mode.
	* docs/html/17_intro/howto.html: Document debug-mode macros.
	* include/Makefile.am: Install debug-mode headers.
	* src/Makefile.am: Include debug.cc.
	* include/bits/basic_string.tcc:
	  (basic_string::_S_construct): Fix NULL pointer check.
	  (__is_null_pointer): New.
	  Add precondition annotations.
	* include/bits/stream_iterator.h (istream_iterator,
	ostream_iterator): Added precondition annotations.
	* include/bits/streambuf_iterator.h (istreambuf_iterator): Ditto.
	* include/bits/stl_queue.h (queue, priority_queue): Ditto.
	* include/bits/stl_stack.h (stack): Ditto.
	* include/bits/basic_string.h (basic_string): Ditto.
	* include/bits/basic_string.tcc (basic_string): Ditto.
	* include/std/std_memory.h (auto_ptr): Ditto.
	* include/std/std_valarray.h (valarray): Ditto.
	* include/bits/stl_algo.h: Added algorithm precondition
	annotations.
	* include/bits/stl_algobase.h: Added algorithm precondition
	annotations.
	* include/bits/stl_numeric.h: Ditto.
	* include/ext/algorithm: Added algorithm precondition
	annotations.
	(__is_heap): Moved away from here.
	* include/bits/stl_heap.h: Added algorithm precondition
	annotations.
	(__is_heap): Moved to the top of this file.
	(__is_heap): Added iterator range overloads.
	* testsuite/20_util/auto_ptr_neg.cc: Fix line numbers to match up
	with changes in std_memory.h.
	* testsuite/23_containers/list/operators/4.cc: Don't verify
	performance guarantees when in debug mode.
	* testsuite/23_containers/bitset/invalidation/1.cc: New.
	* testsuite/23_containers/deque/invalidation/1.cc: New.
	* testsuite/23_containers/deque/invalidation/2.cc: New.
	* testsuite/23_containers/deque/invalidation/3.cc: New.
	* testsuite/23_containers/deque/invalidation/4.cc: New.
	* testsuite/23_containers/list/invalidation/1.cc: New.
	* testsuite/23_containers/list/invalidation/2.cc: New.
	* testsuite/23_containers/list/invalidation/3.cc: New.
	* testsuite/23_containers/list/invalidation/4.cc: New.
	* testsuite/23_containers/map/invalidation/1.cc: New.
	* testsuite/23_containers/map/invalidation/2.cc: New.
	* testsuite/23_containers/multimap/invalidation/1.cc: New.
	* testsuite/23_containers/multimap/invalidation/2.cc: New.
	* testsuite/23_containers/multiset/invalidation/1.cc: New.
	* testsuite/23_containers/multiset/invalidation/2.cc: New.
	* testsuite/23_containers/set/invalidation/1.cc: New.
	* testsuite/23_containers/set/invalidation/2.cc: New.
	* testsuite/23_containers/vector/invalidation/1.cc: New.
	* testsuite/23_containers/vector/invalidation/2.cc: New.
	* testsuite/23_containers/vector/invalidation/3.cc: New.
	* testsuite/23_containers/vector/invalidation/4.cc: New.
	* testsuite/25_algorithms/heap.cc: Don't verify
	performance guarantees when in debug mode.
	* include/debug/bitset: New.
	* include/debug/debug.h: New.
	* include/debug/deque: New.
	* include/debug/formatter.h: New.
	* include/debug/hash_map: New.
	* include/debug/hash_map.h: New.
	* include/debug/hash_multimap.h: New.
	* include/debug/hash_set: New.
	* include/debug/hash_set.h: New.
	* include/debug/hash_multiset.h: New.
	* include/debug/list: New.
	* include/debug/map: New.
	* include/debug/map.h: New.
	* include/debug/multimap.h: New.
	* include/debug/multiset.h: New.
	* include/debug/safe_base.h: New.
	* include/debug/safe_iterator.h: New.
	* include/debug/safe_iterator.tcc: New.
	* include/debug/safe_sequence.h: New.
	* include/debug/set: New.
	* include/debug/set.h: New.
	* include/debug/string: New.
	* include/debug/vector: New.
	* src/debug.cc: New.
	* config/linker-map.gnu: Add debug mode symbols.

2003-11-11  Benjamin Kosnik  <bkoz@redhat.com>

	* src/string-inst.cc: Tweak namespaces.
	* src/misc-inst.cc: Same.
	* docs/html/debug.html: Edits.
	* config/link-map.gnu: Remove cruft.

	* include/bits/c++config: Add in namespace associations.
	* include/std/std_bitset.h: Adjust namespace to __gnu_norm,
	comment tweaks.
	* include/bits/deque.tcc: Same.
	* include/bits/list.tcc: Same.
	* include/bits/stl_bvector.h: Same.
	* include/bits/stl_deque.h: Same.
	* include/bits/stl_list.h: Same.
	* include/bits/stl_map.h: Same.
	* include/bits/stl_multimap.h: Same.
	* include/bits/stl_multiset.h: Same.
	* include/bits/stl_set.h: Same.
	* include/bits/stl_vector.h: Same.
	* include/bits/vector.tcc: Same.

	* include/std/std_algorithm.h: Remove markup comments.
	* include/std/std_functional.h: Same.
	* include/std/std_iterator.h: Same.
	* include/std/std_numeric.h: Same.
	* include/std/std_utility.h: Same.
	* include/bits/stl_queue.h: Formatting tweaks.
	* include/bits/stl_stack.h: Same.
	* include/std/std_deque.h: Include debugging version in debug mode.
	* include/std/std_list.h: Same.
	* include/std/std_map.h: Same.
	* include/std/std_set.h: Same.
	* include/std/std_vector.h: Same.
	* include/std/std_queue.h: Use deque, vector.
	* include/std/std_stack.h: Same.

From-SVN: r73459

4 files changed, 824 insertions, 33 deletions

diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html
index d1fc584..29d0db7 100644
--- a/libstdc++-v3/docs/html/17_intro/howto.html
+++ b/libstdc++-v3/docs/html/17_intro/howto.html
@@ -339,6 +339,18 @@
         violations of the requirements of the standard.  This is described
         in more detail <a href="../19_diagnostics/howto.html#3">here</a>.
     </dd>
+    <dt><code>_GLIBCXX_DEBUG</code></dt>
+    <dd>Undefined by default. Configurable. When defined, compiles
+    user code using the <a href="../debug.html#safe">libstdc++ debug
+    mode</a>.
+    </dd>
+    <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt>
+    <dd>Undefined by default. Configurable. When defined while
+    compiling with the <a href="../debug.html#safe">libstdc++ debug
+    mode</a>, makes the debug mode extremely picky by making the use
+    of libstdc++ extensions and libstdc++-specific behavior into
+    errors.
+    </dd>
     <!--
     <dt><code></code></dt>
     <dd>
diff --git a/libstdc++-v3/docs/html/debug.html b/libstdc++-v3/docs/html/debug.html
index dcd035c..be4a861 100644
--- a/libstdc++-v3/docs/html/debug.html
+++ b/libstdc++-v3/docs/html/debug.html
@@ -29,9 +29,8 @@
 <!-- ####################################################### -->
 <hr />
 <p>There are numerous things that can be done to improve the ease with
-   which C++ binaries are debugged when using the GNU C++
-   tool chain. Here are some things to keep in mind when debugging C++
-   code with GNU tools.
+   which C++ binaries are debugged when using the GNU 
+   tool chain. Here are some of them.
 </p>
 
 <h3 class="left"><a name="gplusplus">Compiler flags determine debug info</a></h3>
@@ -40,15 +39,18 @@
    be varied to change debugging characteristics. For instance,
    turning off all optimization via the <code>-g -O0</code> flag will
    disable inlining, so that stepping through all functions, including
-   inlined constructors and destructors, is possible. Or, the debug
-   format that the compiler and debugger use to communicate
+   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.
+</p>
+
+<p>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.
-   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.
+   shown in gdb.  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.
 </p>
 
 <p>Many other options are available: please see
@@ -56,28 +58,16 @@
    in Using the GNU Compiler Collection (GCC) for a complete list.
 </p>
 
-
 <h3 class="left"><a name="lib">Using special flags to make a debug binary</a></h3>
-<p>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
-   specialized debug <code>CXXFLAGS</code>, as in
-</p>
-<pre>
-     make CXXFLAGS='-g3 -O0' all
-</pre>
-
-<p>This quick and dirty approach is often sufficient for quick
-   debugging tasks, but the lack of state can be confusing in the long
-   term.
-</p>
-<p>A second approach is to use the configuration flags 
-</p>
+<p>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
 <pre>
-     --enable-debug
+     --enable-libstdcxx-debug
 </pre>
 <p>and perhaps</p>
 <pre>
-     --enable-debug-flags='...'
+     --enable-libstdcxx-debug-flags='...'
 </pre>
 <p>to create a separate debug build. Both the normal build and the
    debug build will persist, without having to specify
@@ -87,6 +77,231 @@
    options</a> document.
 </p>
 
+<p>A second approach is to use the configuration flags 
+</p>
+<pre>
+     make CXXFLAGS='-g3 -O0' all
+</pre>
+
+<p>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 <a href="#safe">debug mode</a>.</p>
+
+<h3 class="left"><a name="safe">The libstdc++ debug mode</a></h3>
+<p>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. </p>
+
+<p>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:</p>
+
+  <ul>
+    <li><em>Safe iterators</em>: 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.</li>
+    
+    <li><em>Algorithm preconditions</em>: 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.</li>
+  </ul>
+
+<h4 class="left">Using the libstdc++ debug mode</h4>
+<p>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.</p>
+
+<p>For information about the design of the libstdc++ debug mode,
+  please see the <a href="debug_mode.html">libstdc++ debug mode design
+  document</a>.</p>
+
+<h4 class="left">Using the debugging containers without debug
+  mode</h4>
+<p>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. However, unlike the containers in namespace
+  <code>std</code>, these containers may not be specialized. The
+  following table provides the names and headers of the debugging
+  containers:
+
+<table title="Debugging containers" border="1">
+  <tr>
+    <th>Container</th>
+    <th>Header</th>
+    <th>Debug container</th>
+    <th>Debug header</th>
+  </tr>
+  <tr>
+    <td>std::bitset</td>
+    <td>&lt;bitset&gt;</td>
+    <td>__gnu_debug::bitset</td>
+    <td>&lt;debug/bitset&gt;</td>
+  </tr>
+  <tr>
+    <td>std::deque</td>
+    <td>&lt;deque&gt;</td>
+    <td>__gnu_debug::deque</td>
+    <td>&lt;debug/deque&gt;</td>
+  </tr>
+  <tr>
+    <td>std::list</td>
+    <td>&lt;list&gt;</td>
+    <td>__gnu_debug::list</td>
+    <td>&lt;debug/list&gt;</td>
+  </tr>
+  <tr>
+    <td>std::map</td>
+    <td>&lt;map&gt;</td>
+    <td>__gnu_debug::map</td>
+    <td>&lt;debug/map&gt;</td>
+  </tr>
+  <tr>
+    <td>std::multimap</td>
+    <td>&lt;map&gt;</td>
+    <td>__gnu_debug::multimap</td>
+    <td>&lt;debug/map&gt;</td>
+  </tr>
+  <tr>
+    <td>std::multiset</td>
+    <td>&lt;set&gt;</td>
+    <td>__gnu_debug::multiset</td>
+    <td>&lt;debug/set&gt;</td>
+  </tr>
+  <tr>
+    <td>std::set</td>
+    <td>&lt;set&gt;</td>
+    <td>__gnu_debug::set</td>
+    <td>&lt;debug/set&gt;</td>
+  </tr>
+  <tr>
+    <td>std::string</td>
+    <td>&lt;string&gt;</td>
+    <td>__gnu_debug::string</td>
+    <td>&lt;debug/string&gt;</td>
+  </tr>
+  <tr>
+    <td>std::wstring</td>
+    <td>&lt;string&gt;</td>
+    <td>__gnu_debug::wstring</td>
+    <td>&lt;debug/string&gt;</td>
+  </tr>
+  <tr>
+    <td>std::basic_string</td>
+    <td>&lt;string&gt;</td>
+    <td>__gnu_debug::basic_string</td>
+    <td>&lt;debug/string&gt;</td>
+  </tr>
+  <tr>
+    <td>std::vector</td>
+    <td>&lt;vector&gt;</td>
+    <td>__gnu_debug::vector</td>
+    <td>&lt;debug/vector&gt;</td>
+  </tr>
+  <tr>
+    <td>__gnu_cxx::hash_map</td>
+    <td>&lt;ext/hash_map&gt;</td>
+    <td>__gnu_debug::hash_map</td>
+    <td>&lt;debug/hash_map&gt;</td>
+  </tr>
+  <tr>
+    <td>__gnu_cxx::hash_multimap</td>
+    <td>&lt;ext/hash_map&gt;</td>
+    <td>__gnu_debug::hash_multimap</td>
+    <td>&lt;debug/hash_map&gt;</td>
+  </tr>
+  <tr>
+    <td>__gnu_cxx::hash_set</td>
+    <td>&lt;ext/hash_set&gt;</td>
+    <td>__gnu_debug::hash_set</td>
+    <td>&lt;debug/hash_set&gt;</td>
+  </tr>
+  <tr>
+    <td>__gnu_cxx::hash_multiset</td>
+    <td>&lt;ext/hash_set&gt;</td>
+    <td>__gnu_debug::hash_multiset</td>
+    <td>&lt;debug/hash_set&gt;</td>
+  </tr>
+</table>
+
+<h4 class="left">Debug mode semantics</h4>
+<p>A program that does not use the C++ standard library incorrectly
+  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.</p>
+
+<p>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. In pedantic mode, 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> .</p>
+
+<p>The following library components provide extra debugging
+  capabilities in debug mode:</p>
+<ul>
+  <li><code>std::bitset</code></li>
+  <li><code>std::deque</code></li>
+  <li><code>__gnu_cxx::hash_map</code></li>
+  <li><code>__gnu_cxx::hash_multimap</code></li>
+  <li><code>__gnu_cxx::hash_multiset</code></li>
+  <li><code>__gnu_cxx::hash_set</code></li>
+  <li><code>std::list</code></li>
+  <li><code>std::map</code></li>
+  <li><code>std::multimap</code></li>
+  <li><code>std::multiset</code></li>
+  <li><code>std::set</code></li>
+  <li><code>std::vector</code></li>
+</ul>
+
 
 <h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
 
@@ -94,9 +309,11 @@
    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 <code>purify</code>. Also highly
-   recommended are <code>libcwd</code> and some other one that I
-   forget right now.
+   <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.
 </p>
 
 <p>Regardless of the memory debugging tool being used, there is one
@@ -110,9 +327,10 @@
 
 <p>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 memory is being leaked, when in
-   reality the memory is still being used by the library and is reclaimed
-   after program termination.
+   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.
 </p>
 
 <p>For valgrind, there are some specific items to keep in mind. First
@@ -121,7 +339,7 @@
    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. 
+   cluttering debug information.
 </p>
 
 <p>Fourth, it may be necessary to force deallocation in other
diff --git a/libstdc++-v3/docs/html/debug_mode.html b/libstdc++-v3/docs/html/debug_mode.html
new file mode 100644
index 0000000..6ec7c4b
--- /dev/null
+++ b/libstdc++-v3/docs/html/debug_mode.html
@@ -0,0 +1,547 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html
+          PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+   <meta name="AUTHOR" content="dgregor@apple.com (Doug Gregor)" />
+   <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, debug" />
+   <meta name="DESCRIPTION" content="Design of the libstdc++ debug mode." />
+   <meta name="GENERATOR" content="vi and eight fingers" />
+   <title>Design of the libstdc++ debug mode</title>
+<link rel="StyleSheet" href="lib3styles.css" />
+</head>
+<body>
+
+<h1 class="centered"><a name="top">Design of the libstdc++ debug mode</a></h1>
+
+<p class="fineprint"><em>
+   The latest version of this document is always available at
+   <a href="http://gcc.gnu.org/onlinedocs/libstdc++/debug_mode.html">
+   http://gcc.gnu.org/onlinedocs/libstdc++/debug_mode.html</a>.
+</em></p>
+
+<p><em>
+   To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
+</em></p>
+
+
+<!-- ####################################################### -->
+
+<hr />
+<h1>Debug mode design</h1>
+<p> 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:</p>
+
+  <ul>
+
+    <li><b>Correctness</b>: 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.</li>
+
+    <li><b>Performance</b>: 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).</li>
+
+    <li><b>Usability</b>: 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.</li>
+
+    <li><b>Minimize recompilation</b>: 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. 
+      <ol>
+	<li><b>Full recompilation</b>: 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.</li>
+
+	<li><b>Full user recompilation</b>: 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.</li>
+
+	<li><b>Partial recompilation</b>: 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.</li>
+
+	<li><b>Per-use recompilation</b>: 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 <em>A</em> that contains a
+	particular instantiation
+	(say, <code>std::vector&lt;int&gt;</code>) compiled in release
+	mode can be linked against a translation unit <em>B</em> 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. </li>
+
+	<li><b>Per-unit recompilation</b>: 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).</li>
+      </ol>
+    </li>
+  </ul>
+
+<h2><a name="other">Other implementations</a></h2>
+<p> 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:</p>
+<ul>
+  <li><a
+  href="http://www.mathcs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</a>:
+  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.</li>
+
+  <li><a href="http://www.stlport.org/">STLport</a>: STLport is a free
+  implementation of the C++ standard library derived from the <a
+  href="http://www.sgi.com/tech/stl/">SGI implementation</a>, and
+  ported to many other platforms. It includes a debug mode that uses a
+  wrapper model (that in some way inspired the libstdc++ debug mode
+  design), although at the time of this writing the debug mode is
+  somewhat incomplete and meets only the "Full user recompilation" (2)
+  recompilation guarantee by requiring the user to link against a
+  different library in debug mode vs. release mode.</li>
+
+  <li><a href="http://www.metrowerks.com/mw/default.htm">Metrowerks
+  CodeWarrior</a>: 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.</li>
+</ul>
+
+<h2><a name="design">Debug mode design methodology</a></h2>
+<p>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.</p>
+
+<h3><a name="wrappers">The wrapper model</a></h3>
+<p>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 <a
+  href="#mixing">mixing debug and release code</a> at link time,
+  although that will not be discussed at this time.</p>
+
+<p>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.</p>
+
+<h4><a name="safe_iterator">Safe iterators</a></h4>
+<p>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:</p>
+
+<ul>
+  <li><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.</li>
+  
+  <li><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.</li>
+</ul>
+
+<h4><a name="safe_sequence">Safe sequences (containers)</a></h4>
+<p>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).</p>
+
+<p>The iterators of a container wrapper will be 
+  <a href="#safe_iterator">safe iterators</a> 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.</p>
+
+<p> The debugging version of <code>std::list</code> will have the
+  following basic structure:</p>
+
+<pre>
+template&lt;typename _Tp, typename _Allocator = std::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
+  };
+</pre>
+
+<h3><a name="precondition">Precondition checking</a></h3>
+<p>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.</p>
+
+<p>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.</p>
+
+<h3><a name="coexistence">Release- and debug-mode coexistence</a></h3>
+<p>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 bughunting cycle
+  and making the debug mode easier to incorporate into development
+  environments by minimizing dependencies.</p>
+
+<p>Achieving link- and run-time coexistence is not a trivial
+  implementation task. To achieve this goal we required a small
+  extension to the GNU C++ compiler (described in the section on
+  <a href="#mixing">link- and run-time coexistence</a>) and 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).
+
+<h4><a name="compile_coexistence">Compile-time coexistence of release- and
+    debug-mode components</a></h4>
+<p>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>. 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 (except, perhaps, in <code>__gnu_debug</code>, if
+  requested via the separate debugging headers). This method leaves the
+  behavior of release mode completely unchanged from its behavior
+  prior to the introduction of the libstdc++ debug mode.</p>
+
+<p>In debug mode we include the release-mode container into its
+  natural namespace but perform renaming to an implementation-defined
+  name using preprocessor macros. Thus the
+  release-mode <code>std::list</code> will be renamed
+  to <code>std::_Release_list</code> during debug mode, and we will
+  automatically include the debugging version with the
+  name <code>std::list</code> for users to reference. This method
+  allows the debug- and release-mode versions of the same component to
+  coexist at compile-time without causing an unreasonable maintenance
+  burden.</p>
+
+<h4><a name="mixing">Link- and run-time coexistence of release- and
+    debug-mode components</a></h4>
+<p>There is a problem with the simple compile-time coexistence
+  mechanism: if a user compiles some modules with release mode and
+  some modules with debug mode, the debuggable components will differ
+  in different translation units, violating the C++ One Definition
+  Rule (ODR). This violation will likely be detected at link time,
+  because the sizes of debug-mode containers will differ from the
+  sizes of release-mode containers, although in some cases (such as
+  dynamic linking) the error may be detected much later (or not at
+  all!).</p>
+
+<p>Unfortunately, it is not possible to avoid violating the ODR with
+  most debug mode designs (see the section on <a
+  href="#coexistence_alt">alternatives for coexistence</a>), so the
+  philosophy of the libstdc++ debug mode is to acknowledge that there
+  is an unavoidable ODR violation in this case but to ensure that the
+  ODR violation does not affect execution. To accomplish this, the
+  libstdc++ debug mode uses the aforementioned preprocessor renaming
+  scheme but includes an additional renaming scheme that happens at
+  compile-time that essentially reverses the preprocessor
+  renaming <em>from the linker's point of view</em>. Thus, in debug
+  mode, the release-mode <code>list</code> container is
+  named <code>std::_Release_list</code> but will be mangled with the
+  name <code>std::list</code> (as it was in release mode). Similarly,
+  the debug-mode <code>list</code> is named <code>std::list</code>
+  (in debug mode) but will be mangled
+  as <code>std::_Debug_list</code>. Thus the
+  release-mode <code>list</code> always compiles down to code that
+  uses the name <code>std::list</code>, and the
+  debug-mode <code>list</code> always compiles down to code that uses
+  the name <code>std::_Debug_list</code>, independent of the use of
+  debug mode. This has several positive effects:</p>
+
+<ul>
+  <li>No linking conflicts between debug/release objects: because the
+  names of the debug- and release-mode containers are different in the
+  compiled object files, there are no link-time conflicts between the
+  two.</li>
+
+  <li>Release-mode code is shared: the release-mode code can be shared
+  within a program, even with it is compiled partly in release-mode
+  and partly in debug-mode, because the release-mode code is unchanged
+  in name and function. This can decrease the size of mixed
+  debug/release binaries.</li>
+
+  <li>Able to catch <em>most</em> invalid debug/release combinations:
+  because the names of debug- and release-mode containers are
+  different in the compiled object files, if a debug/release
+  interaction cannot occur (e.g., because a container a translation
+  unit compiled in debug mode is passed to a routine in a translation
+  unit compiled in release mode) the result will be an undefined
+  symbol at link time. The undefined symbol occurs because the mangled
+  name of the definition will contain the release-mode container type
+  and the mangled name of the reference will contain the debug-mode
+  container type. However, we cannot detect these collisions if the
+  only use of the container is in the return type, because the return
+  type is not part of the mangled name of a function.</li>
+</ul>
+
+<p>The new <code>link_name</code> class attribute facilities
+  renaming. It may be attached to any class type (or any class
+  template) to override the name of the class used for name
+  mangling. For instance, a class named <code>bar</code> would
+  generally mangle as <code>3bar</code>; if the class has
+  a <code>link_name</code> attribute that specifies the string
+  "wibble", then it would mangle as <code>6wibble</code>.</p>
+
+<p>Note that although we have hidden the ODR violation, it still
+  exists. 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:</p>
+
+<ol>
+  <li>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.</li>
+
+  <li>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.
+</ol>
+
+<p>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.</p>
+
+<h4><a name="coexistence_alt">Alternatives for Coexistence</a></h4>
+<p>The coexistence scheme 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.</p>
+
+<ul>
+  <li><em>Completely separate debug/release libraries</em>: 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 <b>usability</b> or <b>minimize recompilation</b> criteria
+  well.</li>
+
+  <li><em>Add a <code>Debug</code> boolean template parameter</em>:
+  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 <em>and</em> release modes. This would
+  not meet our <b>correctness</b> criteria. </li>
+
+  <li><em>Packaging a debug flag in the allocators</em>: 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&lr;&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 <b>correctness</b>
+    criteria.</li>
+
+  <li><em>Define debug containers in another namespace, and employ
+      a <code>using</code> declaration (or directive)</em>: This is an
+      enticing option, because it would eliminate the need for
+      the <code>link_name</code> extension by aliasing the
+      templates. However, there is no true template aliasing mechanism
+      is C++, because both <code>using</code> directives and using
+      declarations disallow specialization. This method fails
+      the <b>correctness</b> criteria.</li>
+
+  <li><em>Extension: allow template aliasing/renaming</em>: This is
+    the runner-up to the <code>link_name</code> solution, eliminated
+    only because it requires more extensive compiler changes
+    than <code>link_name</code>. In this model, we would define the
+    debug containers in a different namespace
+    (e.g., <code>__gnu_debug</code>) and then import them (e.g., with
+    an extended <code>using</code> declaration that aliases templates,
+    such as that of <a
+    href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1449.pdf">template
+    aliases</a> proposal). This solution is workable, and in fact
+    would be desirable in the long run, but requires a sizeable change
+    to the C++ compiler front-end that is not within the scope of
+    this project.</li>
+
+  <li><em>Extension: allow reopening on namespaces</em>: 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 <b>minimize
+    recompilation</b> requirement, because we would only be able to
+    support option (1) or (2).</li>
+  </li>
+</ul>
+
+<p>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.</p>
+
+<!-- ####################################################### -->
+
+<hr />
+<p class="fineprint"><em>
+See <a href="17_intro/license.html">license.html</a> for copying conditions.
+Comments and suggestions are welcome, and may be sent to
+<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
+</em></p>
+
+
+</body>
+</html>
diff --git a/libstdc++-v3/docs/html/test.html b/libstdc++-v3/docs/html/test.html
index 07d585f..6fb2c3a 100644
--- a/libstdc++-v3/docs/html/test.html
+++ b/libstdc++-v3/docs/html/test.html
@@ -34,6 +34,7 @@
    <li><a href="#util">Utilities: abicheck and libv3test</a></li>
    <li><a href="#new">How to write a new test case</a></li>
    <li><a href="#check">Options for running the tests</a></li>
+   <li><a href="#debug">Running debug-mode tests</a></li>
    <li><a href="#future">Future</a></li>
    <li><a href="#internals">DejaGNU internals</a></li>
 </ul>
@@ -544,6 +545,19 @@ make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
       for which files to examine.
    </p>
 
+<hr/>
+<h2><a name="debug">Running debug-mode tests</a></h2>
+<p>To run the libstdc++ test suite under the <a
+  href="debug.html#safe">debug mode</a>,
+  edit <code>libstdc++/scripts/testsuite_flags</code> to add the
+  compile-time flag <code>-D_GLIBCXX_DEBUG</code> to the result
+  printed by the <code>--build-cxx</code> option. Additionally, add
+  the <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> 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.</p>
+
 <hr />
 <h2><a name="future">Future</a></h2>