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    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 </em></p>
  24
  25 <p><em>
  26    To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
  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="gplusplus">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
  64 </p>
  65 <pre>
  66      make CXXFLAGS='-g3 -O0' all
  67 </pre>
  68
  69 <p>This quick and dirty approach is often sufficient for quick
  70    debugging tasks, but the lack of state can be confusing in the long
  71    term.
  72 </p>
  73 <p>A second approach is to use the configuration flags
  74 </p>
  75 <pre>
  76      --enable-debug
  77 </pre>
  78 <p>and perhaps</p>
  79 <pre>
  80      --enable-debug-flags='...'
  81 </pre>
  82 <p>to create a separate debug build. Both the normal build and the
  83    debug build will persist, without having to specify
  84    <code>CXXFLAGS</code>, and the debug library will be installed in a
  85    separate directory tree, in <code>(prefix)/lib/debug</code>. For
  86    more information, look at the <a href="configopts.html">configuration
  87    options</a> document.
  88 </p>
  89
  90
  91 <h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
  92
  93 <p>There are various third party memory tracing and debug utilities
  94    that can be used to provide detailed memory allocation information
  95    about C++ code. An exhaustive list of tools is not going to be
  96    attempted, but includes <code>mtrace</code>, <code>valgrind</code>,
  97    <code>mudflap</code>, and <code>purify</code>. Also highly
  98    recommended are <code>libcwd</code> and some other one that I
  99    forget right now.
 100 </p>
 101
 102 <p>Regardless of the memory debugging tool being used, there is one
 103    thing of great importance to keep in mind when debugging C++ code
 104    that uses <code>new</code> and <code>delete</code>:
 105    there are different kinds of allocation schemes that can be used by
 106    <code> std::allocator </code>. For implementation details, see this
 107    <a href="ext/howto.html#3"> document</a> and look specifically for
 108    <code>GLIBCPP_FORCE_NEW</code>.
 109 </p>
 110
 111 <p>In a nutshell, the default allocator used by <code>
 112    std::allocator</code> is a high-performance pool allocator, and can
 113    give the mistaken impression that memory is being leaked, when in
 114    reality the memory is still being used by the library and is reclaimed
 115    after program termination.
 116 </p>
 117
 118 <p>For valgrind, there are some specific items to keep in mind. First
 119    of all, use a version of valgrind that will work with current GNU
 120    C++ tools: the first that can do this is valgrind 1.0.4, but later
 121    versions should work at least as well. Second of all, use a
 122    completely unoptimized build to avoid confusing valgrind. Third,
 123    use GLIBCPP_FORCE_NEW to keep extraneous pool allocation noise from
 124    cluttering debug information.
 125 </p>
 126
 127 <p>Fourth, it may be necessary to force deallocation in other
 128    libraries as well, namely the "C" library. On linux, this can be
 129    accomplished with the appropriate use of the
 130    <code>__cxa_atexit</code> or <code>atexit</code> functions.
 131 </p>
 132
 133 <pre>
 134    #include &lt;cstdlib&gt;
 135
 136    extern "C" void __libc_freeres(void);
 137
 138    void do_something() { }
 139
 140    int main()
 141    {
 142      atexit(__libc_freeres);
 143      do_something();
 144      return 0;
 145    }
 146 </pre>
 147
 148
 149 <p>or, using <code>__cxa_atexit</code>:</p>
 150
 151 <pre>
 152    extern "C" void __libc_freeres(void);
 153    extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
 154
 155    void do_something() { }
 156
 157    int main()
 158    {
 159       extern void* __dso_handle __attribute__ ((__weak__));
 160       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
 161                    &amp;__dso_handle ? __dso_handle : NULL);
 162       do_test();
 163       return 0;
 164    }
 165 </pre>
 166
 167 <p>Suggested valgrind flags, given the suggestions above about setting
 168    up the runtime environment, library, and test file, might be:
 169 </p>
 170 <pre>
 171    valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
 172 </pre>
 173
 174
 175 <h3 class="left"><a name="gdb">Some gdb strategies</a></h3>
 176 <p>Many options are available for gdb itself: please see <a
 177    href="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109">
 178    "GDB features for C++" </a> in the gdb documentation. Also
 179    recommended: the other parts of this manual.
 180 </p>
 181
 182 <p>These settings can either be switched on in at the gdb command
 183    line, or put into a .gdbint file to establish default debugging
 184    characteristics, like so:
 185 </p>
 186
 187 <pre>
 188    set print pretty on
 189    set print object on
 190    set print static-members on
 191    set print vtbl on
 192    set print demangle on
 193    set demangle-style gnu-v3
 194 </pre>
 195
 196
 197 <h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3>
 198 <p>The <a href="19_diagnostics/howto.html#4">verbose termination handler</a>
 199    gives information about uncaught exceptions which are killing the
 200    program.  It is described in the linked-to page.
 201 </p>
 202
 203
 204 <p>Return <a href="#top">to the top of the page</a> or
 205    <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>.
 206 </p>
 207
 208
 209 <!-- ####################################################### -->
 210
 211 <hr />
 212 <p class="fineprint"><em>
 213 See <a href="17_intro/license.html">license.html</a> for copying conditions.
 214 Comments and suggestions are welcome, and may be sent to
 215 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 216 </em></p>
 217
 218
 219 </body>
 220 </html>