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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
   9    <meta name="KEYWORDS" content="c++, libstdc++, gdb, g++, debug" />
  10    <meta name="DESCRIPTION" content="Debugging C++ binaries" />
  11    <meta name="GENERATOR" content="vi and ten fingers" />
  12    <title>Debugging schemes and strategies</title>
  13 <link rel="StyleSheet" href="lib3styles.css" />
  14 </head>
  15 <body>
  16
  17 <h1 class="centered"><a name="top">Debugging schemes and strategies</a></h1>
  18
  19 <p class="fineprint"><em>
  20 <p>The latest version of this document is always available at
  21    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/debug.html">
  22    http://gcc.gnu.org/onlinedocs/libstdc++/debug.html</a>.
  23 </p>
  24
  25 <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
  26 </p>
  27 </em></p>
  28
  29 <!-- ####################################################### -->
  30 <hr />
  31 <p>There are numerous things that can be done to improve the ease with
  32    which C++ binaries are debugged when using the GNU C++
  33    tool chain. Here are some things to keep in mind when debugging C++
  34    code with GNU tools.
  35 </p>
  36
  37 <h3 class="left"><a name="g++">Compiler flags determine debug info</a></h3>
  38 <p>The default optimizations and debug flags for a libstdc++ build are
  39    <code>-g -O2</code>. However, both debug and optimization flags can
  40    be varied to change debugging characteristics. For instance,
  41    turning off all optimization via the <code>-g -O0</code> flag will
  42    disable inlining, so that stepping through all functions, including
  43    inlined constructors and destructors, is possible. Or, the debug
  44    format that the compiler and debugger use to communicate
  45    information about source constructs can be changed via <code>
  46    -gdwarf-2 </code> or <code> -gstabs </code> flags: some debugging
  47    formats permit more expressive type and scope information to be
  48    shown in gdb.
  49    The default debug information for a particular platform can be
  50    identified via the value set by the PREFERRED_DEBUGGING_TYPE macro
  51    in the gcc sources.
  52 </p>
  53
  54 <p>Many other options are available: please see
  55 <a href=http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options> "Options for Debugging Your Program" </a>
  56    in Using the GNU Compiler Collection (GCC) for a complete list.
  57 </p>
  58
  59
  60 <h3 class="left"><a name="lib">Using special flags to make a debug binary</a></h3>
  61 <p>There are two ways to build libstdc++ with debug flags. The first
  62    is to run make from the toplevel in a freshly-configured tree with
  63    specialized debug <code>CXXFLAGS</code>, as in <dd> <code> make
  64    CXXFLAGS='-g3 -O0' all </code></dd>
  65 </p>
  66
  67 <p>This quick and dirty approach is often sufficient for quick
  68    debugging tasks, but the lack of state can be confusing in the long
  69    term.
  70 </p>
  71
  72 <p>A second approach is to use the configuration flags
  73 </p>
  74
  75    <dd><code>--enable-debug</code></dd>
  76
  77 <p>and perhaps</p>
  78
  79    <dd><code>--enable-debug-flags='...'</code></dd>
  80
  81 <p>to create a separate debug build. Both the normal build and the
  82    debug build will persist, without having to specify
  83    <code>CXXFLAGS</code>, and the debug library will be installed in a
  84    separate directory tree, in <code>(prefix)/lib/debug</code>. For
  85    more information, look at the configuration options document
  86 <a href=http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html>here</a>
  87 </p>
  88
  89
  90 <h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
  91
  92 <p>There are various third party memory tracing and debug utilities
  93    that can be used to provide detailed memory allocation information
  94    about C++ code. An exhaustive list of tools is not going to be
  95    attempted, but include <code>mtrace</code>, <code>valgrind</code>,
  96    <code>mudflap</code>, and <code>purify</code>. Also highly
  97    recommended are <code>libcwd</code> and some other one that I
  98    forget right now.
  99 </p>
 100
 101 <p>Regardless of the memory debugging tool being used, there is one
 102    thing of great importance to keep in mind when debugging C++ code
 103    that uses <code>new</code> and <code>delete</code>:
 104    there are different kinds of allocation schemes that can be used by
 105    <code> std::allocator </code>. For implementation details, see this
 106    <a href=http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3>
 107    document </a> and look specifically for <code>GLIBCPP_FORCE_NEW</code>.
 108 </p>
 109
 110 <p>In a nutshell, the default allocator used by <code>
 111    std::allocator</code> is a high-performance pool allocator, and can
 112    give the mistaken impression that memory is being leaked, when in
 113    reality the memory is reclaimed after program termination.
 114 </p>
 115
 116 <p>For valgrind, there are some specific items to keep in mind. First
 117    of all, use a version of valgrind that will work with current GNU
 118    C++ tools: the first that can do this is valgrind 1.0.4, but later
 119    versions should work at least as well. Second of all, use a
 120    completely unoptimized build to avoid confusing valgrind. Third,
 121    use GLIBCPP_FORCE_NEW to keep extraneous pool allocation noise from
 122    cluttering debug information.
 123 </p>
 124
 125 <p>Fourth, it may be necessary to force deallocation in other
 126    libraries as well, namely the "C" library. On linux, this can be
 127    accomplished with the appropriate use of the
 128    <code>__cxa_atexit</code> or <code>atexit</code> functions.
 129 </p>
 130
 131 <pre>
 132    #include &lt;cstdlib&gt;
 133
 134    extern "C" void __libc_freeres(void);
 135
 136    void do_something() { }
 137
 138    int main()
 139    {
 140      atexit(__libc_freeres);
 141      do_something();
 142      return 0;
 143    }
 144 </pre>
 145
 146
 147 <p>or, using <code>__cxa_atexit</code>:</p>
 148
 149 <pre>
 150    extern "C" void __libc_freeres(void);
 151    extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
 152
 153    void do_something() { }
 154
 155    int main()
 156    {
 157       extern void* __dso_handle __attribute__ ((__weak__));
 158       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
 159                    &amp;__dso_handle ? __dso_handle : NULL);
 160       do_test();
 161       return 0;
 162    }
 163 </pre>
 164
 165 <p>Suggested valgrind flags, given the suggestions above about setting
 166    up the runtime environment, library, and test file, might be:
 167
 168    <dd><code>valgrind -v --num-callers=20 --leak-check=yes
 169    --leak-resolution=high --show-reachable=yes a.out</code></dd>
 170 </p>
 171
 172
 173 <h3 class="left"><a name="gdb">Some gdb strategies</a></h3>
 174 <p>Many options are available for gdb itself: please see <a
 175    href=http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109>
 176    "GDB features for C++" </a> in the gdb documentation. Also
 177    recommended: the other parts of this manual.
 178 </p>
 179
 180 <p>These settings can either be switched on in at the gdb command
 181    line, or put into a .gdbint file to establish default debugging
 182    characteristics, like so:
 183 </p>
 184
 185 <pre>
 186    set print pretty on
 187    set print object on
 188    set print static-members on
 189    set print vtbl on
 190    set print demangle on
 191    set demangle-style gnu-v3
 192 </pre>
 193
 194
 195 <h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3>
 196 <p>The <a href="19_diagnostics/howto.html#4">verbose termination handler</a>
 197    gives information about uncaught exceptions which are killing the
 198    program.  It is described in the linked-to page.
 199 </p>
 200
 201
 202 <p>Return <a href="#top">to the top of the page</a> or
 203    <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>.
 204 </p>
 205
 206
 207 <!-- ####################################################### -->
 208
 209 <hr />
 210 <p class="fineprint"><em>
 211 See <a href="17_intro/license.html">license.html</a> for copying conditions.
 212 Comments and suggestions are welcome, and may be sent to
 213 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 214 </em></p>
 215
 216
 217 </body>
 218 </html>