l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.3.3/doc/html/manual/debug.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Debugging Support</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10;      C++&#10;    , &#10;      debug&#10;    " /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s06.html" title="Exception Safety" /><link rel="next" href="support.html" title="Part II. Support" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Debugging Support</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s06.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="support.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.debug"></a>Debugging Support</h2></div></div></div><p>
   4   There are numerous things that can be done to improve the ease with
   5   which C++ binaries are debugged when using the GNU tool chain. Here
   6   are some of them.
   7 </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compiler"></a>Using <span class="command"><strong>g++</strong></span></h3></div></div></div><p>
   8     Compiler flags determine how debug information is transmitted
   9     between compilation and debug or analysis tools.
  10   </p><p>
  11     The default optimizations and debug flags for a libstdc++ build
  12     are <code class="code">-g -O2</code>. However, both debug and optimization
  13     flags can be varied to change debugging characteristics. For
  14     instance, turning off all optimization via the <code class="code">-g -O0</code>
  15     flag will disable inlining, so that stepping through all
  16     functions, including inlined constructors and destructors, is
  17     possible. In addition,
  18     <code class="code">-fno-eliminate-unused-debug-types</code> can be used when
  19     additional debug information, such as nested class info, is
  20     desired.
  21 </p><p>
  22   Or, the debug format that the compiler and debugger use to
  23   communicate information about source constructs can be changed via
  24   <code class="code"> -gdwarf-2 </code> or <code class="code"> -gstabs </code> flags: some
  25   debugging formats permit more expressive type and scope information
  26   to be shown in gdb.  The default debug information for a particular
  27   platform can be identified via the value set by the
  28   PREFERRED_DEBUGGING_TYPE macro in the gcc sources.
  29 </p><p>
  30   Many other options are available: please see <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options" target="_top">"Options
  31   for Debugging Your Program"</a> in Using the GNU Compiler
  32   Collection (GCC) for a complete list.
  33 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug.req"></a>Debug Versions of Library Binary Files</h3></div></div></div><p>
  34   If you would like debug symbols in libstdc++, there are two ways to
  35   build libstdc++ with debug flags. The first is to run make from the
  36   toplevel in a freshly-configured tree with
  37 </p><pre class="programlisting">
  38      --enable-libstdcxx-debug
  39 </pre><p>and perhaps</p><pre class="programlisting">
  40      --enable-libstdcxx-debug-flags='...'
  41 </pre><p>
  42   to create a separate debug build. Both the normal build and the
  43   debug build will persist, without having to specify
  44   <code class="code">CXXFLAGS</code>, and the debug library will be installed in a
  45   separate directory tree, in <code class="code">(prefix)/lib/debug</code>. For
  46   more information, look at the <a class="ulink" href="configopts.html" target="_top">configuration options</a> document.
  47 </p><p>
  48   A second approach is to use the configuration flags
  49 </p><pre class="programlisting">
  50      make CXXFLAGS='-g3 -O0' all
  51 </pre><p>
  52   This quick and dirty approach is often sufficient for quick
  53   debugging tasks, when you cannot or don't want to recompile your
  54   application to use the <a class="ulink" href="#safe" target="_top">debug mode</a>.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug.memory"></a>Memory Leak Hunting</h3></div></div></div><p>
  55   There are various third party memory tracing and debug utilities
  56   that can be used to provide detailed memory allocation information
  57   about C++ code. An exhaustive list of tools is not going to be
  58   attempted, but includes <code class="code">mtrace</code>, <code class="code">valgrind</code>,
  59   <code class="code">mudflap</code>, and the non-free commercial product
  60   <code class="code">purify</code>. In addition, <code class="code">libcwd</code> has a
  61   replacement for the global new and delete operators that can track
  62   memory allocation and deallocation and provide useful memory
  63   statistics.
  64 </p><p>
  65   Regardless of the memory debugging tool being used, there is one
  66   thing of great importance to keep in mind when debugging C++ code
  67   that uses <code class="code">new</code> and <code class="code">delete</code>: there are
  68   different kinds of allocation schemes that can be used by <code class="code">
  69   std::allocator </code>. For implementation details, see the <a class="ulink" href="ext/mt_allocator.html" target="_top">mt allocator</a> documentation and
  70   look specifically for <code class="code">GLIBCXX_FORCE_NEW</code>.
  71 </p><p>
  72   In a nutshell, the default allocator used by <code class="code">
  73   std::allocator</code> is a high-performance pool allocator, and can
  74   give the mistaken impression that in a suspect executable, memory is
  75   being leaked, when in reality the memory "leak" is a pool being used
  76   by the library's allocator and is reclaimed after program
  77   termination.
  78 </p><p>
  79   For valgrind, there are some specific items to keep in mind. First
  80   of all, use a version of valgrind that will work with current GNU
  81   C++ tools: the first that can do this is valgrind 1.0.4, but later
  82   versions should work at least as well. Second of all, use a
  83   completely unoptimized build to avoid confusing valgrind. Third, use
  84   GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from
  85   cluttering debug information.
  86 </p><p>
  87   Fourth, it may be necessary to force deallocation in other libraries
  88   as well, namely the "C" library. On linux, this can be accomplished
  89   with the appropriate use of the <code class="code">__cxa_atexit</code> or
  90   <code class="code">atexit</code> functions.
  91 </p><pre class="programlisting">
  92    #include &lt;cstdlib&gt;
  93
  94    extern "C" void __libc_freeres(void);
  95
  96    void do_something() { }
  97
  98    int main()
  99    {
 100      atexit(__libc_freeres);
 101      do_something();
 102      return 0;
 103    }
 104 </pre><p>or, using <code class="code">__cxa_atexit</code>:</p><pre class="programlisting">
 105    extern "C" void __libc_freeres(void);
 106    extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
 107
 108    void do_something() { }
 109
 110    int main()
 111    {
 112       extern void* __dso_handle __attribute__ ((__weak__));
 113       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
 114                    &amp;__dso_handle ? __dso_handle : NULL);
 115       do_test();
 116       return 0;
 117    }
 118 </pre><p>
 119   Suggested valgrind flags, given the suggestions above about setting
 120   up the runtime environment, library, and test file, might be:
 121 </p><pre class="programlisting">
 122    valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
 123 </pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug.gdb"></a>Using <span class="command"><strong>gdb</strong></span></h3></div></div></div><p>
 124   </p><p>
 125   Many options are available for gdb itself: please see <a class="ulink" href="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109" target="_top">
 126   "GDB features for C++" </a> in the gdb documentation. Also
 127   recommended: the other parts of this manual.
 128 </p><p>
 129   These settings can either be switched on in at the gdb command line,
 130   or put into a .gdbint file to establish default debugging
 131   characteristics, like so:
 132 </p><pre class="programlisting">
 133    set print pretty on
 134    set print object on
 135    set print static-members on
 136    set print vtbl on
 137    set print demangle on
 138    set demangle-style gnu-v3
 139 </pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug.exceptions"></a>Tracking uncaught exceptions</h3></div></div></div><p>
 140   The <a class="link" href="bk01pt02ch06s02.html" title="Verbose Terminate Handler">verbose
 141   termination handler</a> gives information about uncaught
 142   exceptions which are killing the program.  It is described in the
 143   linked-to page.
 144 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug.debug_mode"></a>Debug Mode</h3></div></div></div><p> The <a class="link" href="debug_mode.html" title="Chapter 30. Debug Mode">Debug Mode</a>
 145   has compile and run-time checks for many containers.
 146   </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compile_time_checks"></a>Compile Time Checking</h3></div></div></div><p> The <a class="link" href="bk01pt12ch29.html" title="Chapter 29. Compile Time Checks">Compile-Time
 147   Checks</a> Extension has compile-time checks for many algorithms.
 148   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="support.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Exception Safety </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part II. Support</td></tr></table></div></body></html>