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"><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 Vsnapshot" /><meta name="keywords" content="C++, debug" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter��3.��Using" /><link rel="prev" href="using_exceptions.html" title="Exceptions" /><link rel="next" href="std_contents.html" title="Part��II.�� Standard Contents" /></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="std_contents.html">Next</a></td></tr></table><hr /></div><div class="section"><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> 3 There are numerous things that can be done to improve the ease with 4 which C++ binaries are debugged when using the GNU tool chain. Here 5 are some of them. 6</p><div class="section"><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> 7 Compiler flags determine how debug information is transmitted 8 between compilation and debug or analysis tools. 9 </p><p> 10 The default optimizations and debug flags for a libstdc++ build 11 are <code class="code">-g -O2</code>. However, both debug and optimization 12 flags can be varied to change debugging characteristics. For 13 instance, turning off all optimization via the <code class="code">-g -O0 14 -fno-inline</code> flags will disable inlining and optimizations, 15 and add debugging information, so that stepping through all functions, 16 (including inlined constructors and destructors) is possible. In 17 addition, <code class="code">-fno-eliminate-unused-debug-types</code> can be 18 used when additional debug information, such as nested class info, 19 is desired. 20</p><p> 21 Or, the debug format that the compiler and debugger use to 22 communicate information about source constructs can be changed via 23 <code class="code">-gdwarf-2</code> or <code class="code">-gstabs</code> flags: some debugging 24 formats permit more expressive type and scope information to be 25 shown in GDB. Expressiveness can be enhanced by flags like 26 <code class="code">-g3</code>. 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="link" 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="section"><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 create a separate 36 debug build by running make from the top-level of a tree 37 freshly-configured 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 Both the normal build and the debug build will persist, without 44 having to specify <code class="code">CXXFLAGS</code>, and the debug library will 45 be installed in a separate directory tree, in <code class="code">(prefix)/lib/debug</code>. 46 For more information, look at the 47 <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��17.��Debug Mode">debug mode</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="debug.memory"></a>Memory Leak Hunting</h3></div></div></div><p> 56 On many targets GCC supports AddressSanitizer, a fast memory error detector, 57 which is enabled by the <code class="option">-fsanitize=address</code> option. 58</p><p> 59 There are also various third party memory tracing and debug utilities 60 that can be used to provide detailed memory allocation information 61 about C++ code. An exhaustive list of tools is not going to be 62 attempted, but includes <code class="code">mtrace</code>, <code class="code">valgrind</code>, 63 <code class="code">mudflap</code> (no longer supported since GCC 4.9.0), ElectricFence, 64 and the non-free commercial product <code class="code">purify</code>. 65 In addition, <code class="code">libcwd</code>, jemalloc and TCMalloc have replacements 66 for the global <code class="code">new</code> and <code class="code">delete</code> operators 67 that can track memory allocation and deallocation and provide useful 68 memory statistics. 69</p><p> 70 For valgrind, there are some specific items to keep in mind. First 71 of all, use a version of valgrind that will work with current GNU 72 C++ tools: the first that can do this is valgrind 1.0.4, but later 73 versions should work better. Second, using an unoptimized build 74 might avoid confusing valgrind. 75</p><p> 76 Third, it may be necessary to force deallocation in other libraries 77 as well, namely the "C" library. On GNU/Linux, this can be accomplished 78 with the appropriate use of the <code class="code">__cxa_atexit</code> or 79 <code class="code">atexit</code> functions. 80</p><pre class="programlisting"> 81 #include <cstdlib> 82 83 extern "C" void __libc_freeres(void); 84 85 void do_something() { } 86 87 int main() 88 { 89 atexit(__libc_freeres); 90 do_something(); 91 return 0; 92 } 93</pre><p>or, using <code class="code">__cxa_atexit</code>:</p><pre class="programlisting"> 94 extern "C" void __libc_freeres(void); 95 extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); 96 97 void do_something() { } 98 99 int main() 100 { 101 extern void* __dso_handle __attribute__ ((__weak__)); 102 __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 103 &__dso_handle ? __dso_handle : NULL); 104 do_test(); 105 return 0; 106 } 107</pre><p> 108 Suggested valgrind flags, given the suggestions above about setting 109 up the runtime environment, library, and test file, might be: 110</p><pre class="programlisting"> 111 valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out 112</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="debug.memory.mtalloc"></a>Non-memory leaks in Pool and MT allocators</h4></div></div></div><p> 113 There are different kinds of allocation schemes that can be used by 114 <code class="code">std::allocator</code>. Prior to GCC 3.4.0 the default was to use 115 a pooling allocator, <code class="classname">pool_allocator</code>, 116 which is still available as the optional 117 <code class="classname">__pool_alloc</code> extension. 118 Another optional extension, <code class="classname">__mt_alloc</code>, 119 is a high-performance pool allocator. 120</p><p> 121 In a suspect executable these pooling allocators can give 122 the mistaken impression that memory is being leaked, 123 when in reality the memory "leak" is a pool being used 124 by the library's allocator and is reclaimed after program 125 termination. 126</p><p> 127 If you're using memory debugging tools on a program that uses 128 one of these pooling allocators, you can set the environment variable 129 <code class="literal">GLIBCXX_FORCE_NEW</code> to keep extraneous pool allocation 130 noise from cluttering debug information. 131 For more details, see the 132 <a class="link" href="mt_allocator.html" title="Chapter��19.��The mt_allocator">mt allocator</a> 133 documentation and look specifically for <code class="code">GLIBCXX_FORCE_NEW</code>. 134</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="debug.races"></a>Data Race Hunting</h3></div></div></div><p> 135 All synchronization primitives used in the library internals need to be 136 understood by race detectors so that they do not produce false reports. 137</p><p> 138 Two annotation macros are used to explain low-level synchronization 139 to race detectors: 140 <code class="code">_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and 141 <code class="code"> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>. 142 By default, these macros are defined empty -- anyone who wants 143 to use a race detector needs to redefine them to call an 144 appropriate API. 145 Since these macros are empty by default when the library is built, 146 redefining them will only affect inline functions and template 147 instantiations which are compiled in user code. This allows annotation 148 of templates such as <code class="code">shared_ptr</code>, but not code which is 149 only instantiated in the library. Code which is only instantiated in 150 the library needs to be recompiled with the annotation macros defined. 151 That can be done by rebuilding the entire 152 <code class="filename">libstdc++.so</code> file but a simpler 153 alternative exists for ELF platforms such as GNU/Linux, because ELF 154 symbol interposition allows symbols defined in the shared library to be 155 overridden by symbols with the same name that appear earlier in the 156 runtime search path. This means you only need to recompile the functions 157 that are affected by the annotation macros, which can be done by 158 recompiling individual files. 159 Annotating <code class="code">std::string</code> and <code class="code">std::wstring</code> 160 reference counting can be done by disabling extern templates (by defining 161 <code class="code">_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the 162 <code class="filename">src/string-inst.cc</code> file. 163 Annotating the remaining atomic operations (at the time of writing these 164 are in <code class="code">ios_base::Init::~Init</code>, <code class="code">locale::_Impl</code>, 165 <code class="code">locale::facet</code> and <code class="code">thread::_M_start_thread</code>) 166 requires rebuilding the relevant source files. 167</p><p> 168 The approach described above is known to work with the following race 169 detection tools: 170 <a class="link" href="http://valgrind.org/docs/manual/drd-manual.html" target="_top"> 171 DRD</a>, 172 <a class="link" href="http://valgrind.org/docs/manual/hg-manual.html" target="_top"> 173 Helgrind</a>, and 174 <a class="link" href="https://github.com/google/sanitizers" target="_top"> 175 ThreadSanitizer</a> (this refers to ThreadSanitizer v1, not the 176 new "tsan" feature built-in to GCC itself). 177</p><p> 178 With DRD, Helgrind and ThreadSanitizer you will need to define 179 the macros like this: 180</p><pre class="programlisting"> 181 #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A) 182 #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A) 183</pre><p> 184 Refer to the documentation of each particular tool for details. 185</p></div><div class="section"><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> 186 </p><p> 187 Many options are available for GDB itself: please see <a class="link" href="http://sourceware.org/gdb/current/onlinedocs/gdb/" target="_top"> 188 "GDB features for C++" </a> in the GDB documentation. Also 189 recommended: the other parts of this manual. 190</p><p> 191 These settings can either be switched on in at the GDB command line, 192 or put into a <code class="filename">.gdbinit</code> file to establish default 193 debugging characteristics, like so: 194</p><pre class="programlisting"> 195 set print pretty on 196 set print object on 197 set print static-members on 198 set print vtbl on 199 set print demangle on 200 set demangle-style gnu-v3 201</pre><p> 202 Starting with version 7.0, GDB includes support for writing 203 pretty-printers in Python. Pretty printers for containers and other 204 classes are distributed with GCC from version 4.5.0 and should be installed 205 alongside the libstdc++ shared library files and found automatically by 206 GDB. 207</p><p> 208 Depending where libstdc++ is installed, GDB might refuse to auto-load 209 the python printers and print a warning instead. 210 If this happens the python printers can be enabled by following the 211 instructions GDB gives for setting your <code class="code">auto-load safe-path</code> 212 in your <code class="filename">.gdbinit</code> configuration file. 213</p><p> 214 Once loaded, standard library classes that the printers support 215 should print in a more human-readable format. To print the classes 216 in the old style, use the <strong class="userinput"><code>/r</code></strong> (raw) switch in the 217 print command (i.e., <strong class="userinput"><code>print /r foo</code></strong>). This will 218 print the classes as if the Python pretty-printers were not loaded. 219</p><p> 220 For additional information on STL support and GDB please visit: 221 <a class="link" href="http://sourceware.org/gdb/wiki/STLSupport" target="_top"> "GDB Support 222 for STL" </a> in the GDB wiki. Additionally, in-depth 223 documentation and discussion of the pretty printing feature can be 224 found in "Pretty Printing" node in the GDB manual. You can find 225 on-line versions of the GDB user manual in GDB's homepage, at 226 <a class="link" href="http://sourceware.org/gdb/" target="_top"> "GDB: The GNU Project 227 Debugger" </a>. 228</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="debug.exceptions"></a>Tracking uncaught exceptions</h3></div></div></div><p> 229 The <a class="link" href="termination.html#support.termination.verbose" title="Verbose Terminate Handler">verbose 230 termination handler</a> gives information about uncaught 231 exceptions which kill the program. 232</p></div><div class="section"><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��17.��Debug Mode">Debug Mode</a> 233 has compile and run-time checks for many containers. 234 </p></div><div class="section"><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��16.��Compile Time Checks">Compile-Time 235 Checks</a> extension has compile-time checks for many algorithms. 236 </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="std_contents.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Exceptions��</td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top">��Part��II.�� 237 Standard Contents 238 </td></tr></table></div></body></html>