index.html: Explain memory "leaks" due to allocators.

2003-03-12  Jonathan Wakely  <redi@gcc.gnu.org>

	* docs/html/faq/index.html: Explain memory "leaks" due to allocators.
	* docs/html/faq/index.txt: Regenerate.
	* docs/html/debug.html: Add a bit to allocator text and fix XHTML.

From-SVN: r64273

libstdc++-v3/ChangeLog

+2003-03-12  Jonathan Wakely  <redi@gcc.gnu.org>
+
+	* docs/html/faq/index.html: Explain memory "leaks" due to allocators.
+	* docs/html/faq/index.txt: Regenerate.
+	* docs/html/debug.html: Add a bit to allocator text and fix XHTML.
+
 2003-03-12  Andreas Schwab  <schwab@suse.de>
 
 	* acinclude.m4 (GLIBCPP_EXPORT_INSTALL_INFO): Avoid trailing /. in

libstdc++-v3/docs/html/debug.html

@@ -17,13 +17,13 @@
 <h1 class="centered"><a name="top">Debugging schemes and strategies</a></h1>
 
 <p class="fineprint"><em>
-<p>The latest version of this document is always available at
+   The latest version of this document is always available at
    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/debug.html">
    http://gcc.gnu.org/onlinedocs/libstdc++/debug.html</a>.
-</p>
+</em></p>
 
-<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
-</p>
+<p><em>
+   To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
 </em></p>
 
 <!-- ####################################################### -->
@@ -34,7 +34,7 @@
    code with GNU tools.
 </p>
 
-<h3 class="left"><a name="g++">Compiler flags determine debug info</a></h3>
+<h3 class="left"><a name="gplusplus">Compiler flags determine debug info</a></h3>
 <p>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,
@@ -52,7 +52,7 @@
 </p>
 
 <p>Many other options are available: please see
-<a href=http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options> "Options for Debugging Your Program" </a>
+<a href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options for Debugging Your Program"</a>
    in Using the GNU Compiler Collection (GCC) for a complete list.
 </p>
 
@@ -60,30 +60,31 @@
 <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 <dd> <code> make
-   CXXFLAGS='-g3 -O0' all </code></dd>
+   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>
-
-   <dd><code>--enable-debug</code></dd>
-
+<pre>
+     --enable-debug
+</pre>
 <p>and perhaps</p>
-
-   <dd><code>--enable-debug-flags='...'</code></dd>
-
+<pre>
+     --enable-debug-flags='...'
+</pre>
 <p>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 configuration options document 
-<a href=http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html>here</a>
+   more information, look at the <a href="configopts.html">configuration
+   options</a> document.
 </p>
 
 
@@ -92,7 +93,7 @@
 <p>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 include <code>mtrace</code>, <code>valgrind</code>,
+   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.
@@ -103,14 +104,15 @@
    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 this
-   <a href=http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3>
-   document </a> and look specifically for <code>GLIBCPP_FORCE_NEW</code>. 
+   <a href="ext/howto.html#3"> document</a> and look specifically for
+   <code>GLIBCPP_FORCE_NEW</code>. 
 </p>
 
 <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 reclaimed after program termination.
+   reality the memory is still being used by the library and is reclaimed
+   after program termination.
 </p>
 
 <p>For valgrind, there are some specific items to keep in mind. First
@@ -164,15 +166,15 @@
 
 <p>Suggested valgrind flags, given the suggestions above about setting
    up the runtime environment, library, and test file, might be:
- 
-   <dd><code>valgrind -v --num-callers=20 --leak-check=yes
-   --leak-resolution=high --show-reachable=yes a.out</code></dd>
 </p>
+<pre> 
+   valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
+</pre>
 
 
 <h3 class="left"><a name="gdb">Some gdb strategies</a></h3>
 <p>Many options are available for gdb itself: please see <a
-   href=http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109>
+   href="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109">
    "GDB features for C++" </a> in the gdb documentation. Also
    recommended: the other parts of this manual.
 </p>

libstdc++-v3/docs/html/faq/index.html

@@ -94,6 +94,7 @@
                                <em>constraints</em> in the STL...</a> </li>
            <li><a href="#4_4_dlsym">program crashes when using library code
                                in a dynamically-loaded library</a> </li>
+           <li><a href="#4_4_leak">"memory leaks" in containers</a> </li>
          </ul>
          </li>
          <li><a href="#4_5">Aw, that's easy to fix!</a> </li>
@@ -795,6 +796,18 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
 
     // link the executable
     g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl</pre>
+      <p><a name="4_4_leak"><strong>"memory leaks" in containers</strong></a>
+         A few people have reported that the standard containers appear
+         to leak memory when tested with memory checkers such as
+         <a href="http://developer.kde.org/~sewardj/">valgrind</a>.
+         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
+         <a href="../debug.html#mem">Tips for memory leak hunting</a>
+         first.
+      </p>
 
 <hr />
    <h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2>