This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[libstdc++] Additional documentation
- From: Phil Edwards <phil at jaj dot com>
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Thu, 26 Dec 2002 16:14:37 -0500
- Subject: [libstdc++] Additional documentation
Some HTML cleanups, updates to the verbose-terminate notes, and the comment
I promised in the default terminate() implementation.
2002-12-26 Phil Edwards <pme@gcc.gnu.org>
* libsupc++/eh_term_handler.cc: Add comment about embedded systems.
* docs/html/debug.html: Cosmetic and HTML changes. Point to
verb-term notes.
* docs/html/documentation.html: Link to the FAQ.
* docs/html/17_intro/howto.html: Mention use of isatty(3).
* docs/html/19_diagnostics/howto.html: Update verb-term description.
Index: libsupc++/eh_term_handler.cc
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/eh_term_handler.cc,v
retrieving revision 1.1
diff -u -3 -p -r1.1 eh_term_handler.cc
--- libsupc++/eh_term_handler.cc 26 Dec 2002 06:10:35 -0000 1.1
+++ libsupc++/eh_term_handler.cc 26 Dec 2002 21:12:12 -0000
@@ -29,6 +29,12 @@
#include "unwind-cxx.h"
+/* We default to the talkative, informative handler. This pulls in the
+ demangler, the dyn-string utilities, and elements of the I/O library.
+ For a low-memory environment, you can return to the earlier "silent death"
+ handler by including <cstdlib>, initializg to "std::abort", and rebuilding
+ the library. */
+
/* The current installed user handler. */
std::terminate_handler __cxxabiv1::__terminate_handler =
__gnu_cxx::__verbose_terminate_handler;
Index: docs/html/debug.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/debug.html,v
retrieving revision 1.1
diff -u -3 -p -r1.1 debug.html
--- docs/html/debug.html 19 Dec 2002 08:18:14 -0000 1.1
+++ docs/html/debug.html 26 Dec 2002 21:12:12 -0000
@@ -28,16 +28,14 @@
<!-- ####################################################### -->
<hr />
-<p>
- There are numerous things that can be done to improve the ease with
+<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.
</p>
<h3 class="left"><a name="g++">Compiler flags determine debug info</a></h3>
-<p>
- The default optimizations and debug flags for a libstdc++ build are
+<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,
turning off all optimization via the <code>-g -O0</code> flag will
@@ -53,53 +51,45 @@
in the gcc sources.
</p>
-<p>
- Many other options are available: please see
+<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>
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
+<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>
</p>
-<p>
- This quick and dirty approach is often sufficient for quick
+<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>A second approach is to use the configuration flags
</p>
- <dd><code>--enable-debug </code></dd>
+ <dd><code>--enable-debug</code></dd>
-<p>
- and perhaps
-</p>
+<p>and perhaps</p>
- <dd><code>--enable-debug-flags </code></dd>
+ <dd><code>--enable-debug-flags='...'</code></dd>
-<p>
- to create a separate debug build. Both the normal build and the
+<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>
+<a href=http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html>here</a>
</p>
<h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
-<p>
- There are various third party memory tracing and debug utilities
+<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>,
@@ -108,8 +98,7 @@
forget right now.
</p>
-<p>
- Regardless of the memory debugging tool being used, there is one
+<p>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
@@ -118,14 +107,13 @@
document </a> and look specifically for <code>GLIBCPP_FORCE_NEW</code>.
</p>
-<p>
- In a nutshell, the default allocator used by <code>
+<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.
</p>
-<p> For valgrind, there are some specific items to keep in mind. First
+<p>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
@@ -134,15 +122,14 @@
cluttering debug information.
</p>
-<p>
- Fourth, it may be necessary to force deallocation in other
+<p>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.
</p>
<pre>
- #include <cstdlib>
+ #include <cstdlib>
extern "C" void __libc_freeres(void);
@@ -151,15 +138,13 @@
int main()
{
atexit(__libc_freeres);
- do_test();
+ do_something();
return 0;
}
</pre>
-<p>
- or, using <code>__cxa_atexit</code>:
-</p>
+<p>or, using <code>__cxa_atexit</code>:</p>
<pre>
extern "C" void __libc_freeres(void);
@@ -171,14 +156,13 @@
{
extern void* __dso_handle __attribute__ ((__weak__));
__cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
- &__dso_handle ? __dso_handle : NULL);
+ &__dso_handle ? __dso_handle : NULL);
do_test();
return 0;
}
</pre>
-<p>
- Suggested valgrind flags, given the suggestions above about setting
+<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
@@ -187,14 +171,13 @@
<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>
-"GDB features for C++" </a> in the gdb documentation. Also
-recommended: the other parts of this manual.
+<p>Many options are available for gdb itself: please see <a
+ 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>
-<p>
- These settings can either be switched on in at the gdb command
+
+<p>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:
</p>
@@ -207,6 +190,13 @@ recommended: the other parts of this man
set print demangle on
set demangle-style gnu-v3
</pre>
+
+
+<h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3>
+<p>The <a href="19_diagnostics/howto.html#4">verbose termination handler</a>
+ gives information about uncaught exceptions which are killing the
+ program. It is described in the linked-to page.
+</p>
<p>Return <a href="#top">to the top of the page</a> or
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.26
diff -u -3 -p -r1.26 documentation.html
--- docs/html/documentation.html 19 Dec 2002 08:18:14 -0000 1.26
+++ docs/html/documentation.html 26 Dec 2002 21:12:12 -0000
@@ -39,6 +39,8 @@
- latest version info, recent changes and news</li>
<li><a href="17_intro/TODO">TODO</a>
- tasks yet undone</li>
+ <li><a href="faq/index.html">FAQ (HTML)</a>,
+ <a href="faq/index.txt">FAQ (text)</a></li>
</ul>
<hr />
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.27
diff -u -3 -p -r1.27 howto.html
--- docs/html/17_intro/howto.html 21 Nov 2002 07:15:57 -0000 1.27
+++ docs/html/17_intro/howto.html 26 Dec 2002 21:12:12 -0000
@@ -189,6 +189,9 @@
<p>For each entry, we give the section number of the standard, when
applicable. This list is probably incomplet and inkorrekt.
</p>
+ <p><strong>[1.9]/11 #3</strong> If <code>isatty(3)</code> is true, then
+ interactive stream support is implied.
+ </p>
<p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
discussed in the various sections on multithreading (see above).
</p>
Index: docs/html/19_diagnostics/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/19_diagnostics/howto.html,v
retrieving revision 1.18
diff -u -3 -p -r1.18 howto.html
--- docs/html/19_diagnostics/howto.html 7 Oct 2002 18:11:18 -0000 1.18
+++ docs/html/19_diagnostics/howto.html 26 Dec 2002 21:12:12 -0000
@@ -169,6 +169,13 @@
%</pre>
<p>The 'Aborted' line comes from the call to abort(), of course.
</p>
+ <p><strong>UPDATE:</strong> Starting with GCC 3.4, this is the default
+ termination handler; nothing need be done to use it. To go back to
+ the previous "silent death" method, simply include
+ <code><exception><code> and <code><cstdlib><code>, and call
+ </p>
+ <pre>
+ std::set_terminate (std::abort);</pre>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>