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.75.2" /><meta name="keywords" content=" C++ , debug " /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_exceptions.html" title="Exceptions" /><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="using_exceptions.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" title="Debugging Support"><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" title="Using g++"><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 15 -fno-inline</code> flags will disable inlining and optimizations, 16 and add debugging information, so that stepping through all functions, 17 (including inlined constructors and destructors) is possible. In 18 addition, <code class="code">-fno-eliminate-unused-debug-types</code> can be 19 used when additional debug information, such as nested class info, 20 is 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 debugging 25 formats permit more expressive type and scope information to be 26 shown in gdb. Expressiveness can be enhanced by flags like 27 <code class="code">-g3</code>. The default debug information for a particular 28 platform can be identified via the value set by the 29 PREFERRED_DEBUGGING_TYPE macro in the gcc sources. 30</p><p> 31 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 32 for Debugging Your Program"</a> in Using the GNU Compiler 33 Collection (GCC) for a complete list. 34</p></div><div class="sect2" title="Debug Versions of Library Binary Files"><div class="titlepage"><div><div><h3 class="title"><a id="debug.req"></a>Debug Versions of Library Binary Files</h3></div></div></div><p> 35 If you would like debug symbols in libstdc++, there are two ways to 36 build libstdc++ with debug flags. The first is to run make from the 37 toplevel in a freshly-configured tree with 38</p><pre class="programlisting"> 39 --enable-libstdcxx-debug 40</pre><p>and perhaps</p><pre class="programlisting"> 41 --enable-libstdcxx-debug-flags='...' 42</pre><p> 43 to create a separate debug build. Both the normal build and the 44 debug build will persist, without having to specify 45 <code class="code">CXXFLAGS</code>, and the debug library will be installed in a 46 separate directory tree, in <code class="code">(prefix)/lib/debug</code>. For 47 more information, look at the <a class="link" href="configure.html" title="Configure">configuration</a> section. 48</p><p> 49 A second approach is to use the configuration flags 50</p><pre class="programlisting"> 51 make CXXFLAGS='-g3 -fno-inline -O0' all 52</pre><p> 53 This quick and dirty approach is often sufficient for quick 54 debugging tasks, when you cannot or don't want to recompile your 55 application to use the <a class="link" href="debug_mode.html" title="Chapter 30. Debug Mode">debug mode</a>.</p></div><div class="sect2" title="Memory Leak Hunting"><div class="titlepage"><div><div><h3 class="title"><a id="debug.memory"></a>Memory Leak Hunting</h3></div></div></div><p> 56 There are various third party memory tracing and debug utilities 57 that can be used to provide detailed memory allocation information 58 about C++ code. An exhaustive list of tools is not going to be 59 attempted, but includes <code class="code">mtrace</code>, <code class="code">valgrind</code>, 60 <code class="code">mudflap</code>, and the non-free commercial product 61 <code class="code">purify</code>. In addition, <code class="code">libcwd</code> has a 62 replacement for the global new and delete operators that can track 63 memory allocation and deallocation and provide useful memory 64 statistics. 65</p><p> 66 Regardless of the memory debugging tool being used, there is one 67 thing of great importance to keep in mind when debugging C++ code 68 that uses <code class="code">new</code> and <code class="code">delete</code>: there are 69 different kinds of allocation schemes that can be used by <code class="code"> 70 std::allocator </code>. For implementation details, see the <a class="link" href="ext_allocators.html#manual.ext.allocator.mt" title="mt_allocator">mt allocator</a> documentation and 71 look specifically for <code class="code">GLIBCXX_FORCE_NEW</code>. 72</p><p> 73 In a nutshell, the default allocator used by <code class="code"> 74 std::allocator</code> is a high-performance pool allocator, and can 75 give the mistaken impression that in a suspect executable, memory is 76 being leaked, when in reality the memory "leak" is a pool being used 77 by the library's allocator and is reclaimed after program 78 termination. 79</p><p> 80 For valgrind, there are some specific items to keep in mind. First 81 of all, use a version of valgrind that will work with current GNU 82 C++ tools: the first that can do this is valgrind 1.0.4, but later 83 versions should work at least as well. Second of all, use a 84 completely unoptimized build to avoid confusing valgrind. Third, use 85 GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from 86 cluttering debug information. 87</p><p> 88 Fourth, it may be necessary to force deallocation in other libraries 89 as well, namely the "C" library. On linux, this can be accomplished 90 with the appropriate use of the <code class="code">__cxa_atexit</code> or 91 <code class="code">atexit</code> functions. 92</p><pre class="programlisting"> 93 #include <cstdlib> 94 95 extern "C" void __libc_freeres(void); 96 97 void do_something() { } 98 99 int main() 100 { 101 atexit(__libc_freeres); 102 do_something(); 103 return 0; 104 } 105</pre><p>or, using <code class="code">__cxa_atexit</code>:</p><pre class="programlisting"> 106 extern "C" void __libc_freeres(void); 107 extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); 108 109 void do_something() { } 110 111 int main() 112 { 113 extern void* __dso_handle __attribute__ ((__weak__)); 114 __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 115 &__dso_handle ? __dso_handle : NULL); 116 do_test(); 117 return 0; 118 } 119</pre><p> 120 Suggested valgrind flags, given the suggestions above about setting 121 up the runtime environment, library, and test file, might be: 122</p><pre class="programlisting"> 123 valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out 124</pre></div><div class="sect2" title="Using gdb"><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> 125 </p><p> 126 Many options are available for gdb itself: please see <a class="ulink" href="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC125" target="_top"> 127 "GDB features for C++" </a> in the gdb documentation. Also 128 recommended: the other parts of this manual. 129</p><p> 130 These settings can either be switched on in at the gdb command line, 131 or put into a .gdbint file to establish default debugging 132 characteristics, like so: 133</p><pre class="programlisting"> 134 set print pretty on 135 set print object on 136 set print static-members on 137 set print vtbl on 138 set print demangle on 139 set demangle-style gnu-v3 140</pre><p> 141 Starting with version 7.0, GDB includes support for writing 142 pretty-printers in Python. Pretty printers for STL classes are 143 distributed with GCC from version 4.5.0. The most recent version of 144 these printers are always found in libstdc++ svn repository. 145 To enable these printers, check-out the latest printers to a local 146 directory: 147</p><pre class="programlisting"> 148 svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python 149</pre><p> 150 Next, add the following section to your ~/.gdbinit The path must 151 match the location where the Python module above was checked-out. 152 So if checked out to: /home/maude/gdb_printers/, the path would be as 153 written in the example below. 154</p><pre class="programlisting"> 155 python 156 import sys 157 sys.path.insert(0, '/home/maude/gdb_printers/python') 158 from libstdcxx.v6.printers import register_libstdcxx_printers 159 register_libstdcxx_printers (None) 160 end 161</pre><p> 162 The path should be the only element that needs to be adjusted in the 163 example. Once loaded, STL classes that the printers support 164 should print in a more human-readable format. To print the classes 165 in the old style, use the /r (raw) switch in the print command 166 (i.e., print /r foo). This will print the classes as if the Python 167 pretty-printers were not loaded. 168</p><p> 169 For additional information on STL support and GDB please visit: 170 <a class="ulink" href="http://sourceware.org/gdb/wiki/STLSupport" target="_top"> "GDB Support 171 for STL" </a> in the GDB wiki. Additionally, in-depth 172 documentation and discussion of the pretty printing feature can be 173 found in "Pretty Printing" node in the GDB manual. You can find 174 on-line versions of the GDB user manual in GDB's homepage, at 175 <a class="ulink" href="http://sourceware.org/gdb/" target="_top"> "GDB: The GNU Project 176 Debugger" </a>. 177</p></div><div class="sect2" title="Tracking uncaught exceptions"><div class="titlepage"><div><div><h3 class="title"><a id="debug.exceptions"></a>Tracking uncaught exceptions</h3></div></div></div><p> 178 The <a class="link" href="verbose_termination.html" title="Verbose Terminate Handler">verbose 179 termination handler</a> gives information about uncaught 180 exceptions which are killing the program. It is described in the 181 linked-to page. 182</p></div><div class="sect2" title="Debug Mode"><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> 183 has compile and run-time checks for many containers. 184 </p></div><div class="sect2" title="Compile Time Checking"><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="ext_compile_checks.html" title="Chapter 29. Compile Time Checks">Compile-Time 185 Checks</a> Extension has compile-time checks for many algorithms. 186 </p></div><div class="sect2" title="Profile-based Performance Analysis"><div class="titlepage"><div><div><h3 class="title"><a id="debug.profile_mode"></a>Profile-based Performance Analysis</h3></div></div></div><p> The <a class="link" href="profile_mode.html" title="Chapter 32. Profile Mode">Profile-based 187 Performance Analysis</a> Extension has performance checks for many 188 algorithms. 189 </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_exceptions.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">Exceptions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part II. 190 Support 191 192</td></tr></table></div></body></html> 193