14fee23f9Smrg<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2d79abf08Smrg<!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> 34fee23f9Smrg There are numerous things that can be done to improve the ease with 44fee23f9Smrg which C++ binaries are debugged when using the GNU tool chain. Here 54fee23f9Smrg are some of them. 648fb7bfaSmrg</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> 74fee23f9Smrg Compiler flags determine how debug information is transmitted 84fee23f9Smrg between compilation and debug or analysis tools. 94fee23f9Smrg </p><p> 104fee23f9Smrg The default optimizations and debug flags for a libstdc++ build 114fee23f9Smrg are <code class="code">-g -O2</code>. However, both debug and optimization 124fee23f9Smrg flags can be varied to change debugging characteristics. For 134fee23f9Smrg instance, turning off all optimization via the <code class="code">-g -O0 144fee23f9Smrg -fno-inline</code> flags will disable inlining and optimizations, 154fee23f9Smrg and add debugging information, so that stepping through all functions, 164fee23f9Smrg (including inlined constructors and destructors) is possible. In 174fee23f9Smrg addition, <code class="code">-fno-eliminate-unused-debug-types</code> can be 184fee23f9Smrg used when additional debug information, such as nested class info, 194fee23f9Smrg is desired. 204fee23f9Smrg</p><p> 214fee23f9Smrg Or, the debug format that the compiler and debugger use to 224fee23f9Smrg communicate information about source constructs can be changed via 234fee23f9Smrg <code class="code">-gdwarf-2</code> or <code class="code">-gstabs</code> flags: some debugging 244fee23f9Smrg formats permit more expressive type and scope information to be 2548fb7bfaSmrg shown in GDB. Expressiveness can be enhanced by flags like 264fee23f9Smrg <code class="code">-g3</code>. The default debug information for a particular 274fee23f9Smrg platform can be identified via the value set by the 2848fb7bfaSmrg PREFERRED_DEBUGGING_TYPE macro in the GCC sources. 294fee23f9Smrg</p><p> 3048fb7bfaSmrg 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 314fee23f9Smrg for Debugging Your Program"</a> in Using the GNU Compiler 324fee23f9Smrg Collection (GCC) for a complete list. 3348fb7bfaSmrg</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> 344fee23f9Smrg If you would like debug symbols in libstdc++, there are two ways to 3548fb7bfaSmrg build libstdc++ with debug flags. The first is to create a separate 3648fb7bfaSmrg debug build by running make from the top-level of a tree 3748fb7bfaSmrg freshly-configured with 384fee23f9Smrg</p><pre class="programlisting"> 394fee23f9Smrg --enable-libstdcxx-debug 404fee23f9Smrg</pre><p>and perhaps</p><pre class="programlisting"> 414fee23f9Smrg --enable-libstdcxx-debug-flags='...' 424fee23f9Smrg</pre><p> 4348fb7bfaSmrg Both the normal build and the debug build will persist, without 4448fb7bfaSmrg having to specify <code class="code">CXXFLAGS</code>, and the debug library will 4548fb7bfaSmrg be installed in a separate directory tree, in <code class="code">(prefix)/lib/debug</code>. 4648fb7bfaSmrg For more information, look at the 4748fb7bfaSmrg <a class="link" href="configure.html" title="Configure">configuration</a> section. 484fee23f9Smrg</p><p> 494fee23f9Smrg A second approach is to use the configuration flags 504fee23f9Smrg</p><pre class="programlisting"> 514fee23f9Smrg make CXXFLAGS='-g3 -fno-inline -O0' all 524fee23f9Smrg</pre><p> 534fee23f9Smrg This quick and dirty approach is often sufficient for quick 544fee23f9Smrg debugging tasks, when you cannot or don't want to recompile your 5548fb7bfaSmrg 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> 56a3e9eb18Smrg On many targets GCC supports AddressSanitizer, a fast memory error detector, 57a3e9eb18Smrg which is enabled by the <code class="option">-fsanitize=address</code> option. 58a3e9eb18Smrg</p><p> 59a3e9eb18Smrg There are also various third party memory tracing and debug utilities 604fee23f9Smrg that can be used to provide detailed memory allocation information 614fee23f9Smrg about C++ code. An exhaustive list of tools is not going to be 624fee23f9Smrg attempted, but includes <code class="code">mtrace</code>, <code class="code">valgrind</code>, 63a3e9eb18Smrg <code class="code">mudflap</code> (no longer supported since GCC 4.9.0), ElectricFence, 64a3e9eb18Smrg and the non-free commercial product <code class="code">purify</code>. 65a3e9eb18Smrg In addition, <code class="code">libcwd</code>, jemalloc and TCMalloc have replacements 66a3e9eb18Smrg for the global <code class="code">new</code> and <code class="code">delete</code> operators 67a3e9eb18Smrg that can track memory allocation and deallocation and provide useful 68a3e9eb18Smrg memory statistics. 694fee23f9Smrg</p><p> 704fee23f9Smrg For valgrind, there are some specific items to keep in mind. First 714fee23f9Smrg of all, use a version of valgrind that will work with current GNU 724fee23f9Smrg C++ tools: the first that can do this is valgrind 1.0.4, but later 73a3e9eb18Smrg versions should work better. Second, using an unoptimized build 74a3e9eb18Smrg might avoid confusing valgrind. 754fee23f9Smrg</p><p> 76a3e9eb18Smrg Third, it may be necessary to force deallocation in other libraries 77a3e9eb18Smrg as well, namely the "C" library. On GNU/Linux, this can be accomplished 784fee23f9Smrg with the appropriate use of the <code class="code">__cxa_atexit</code> or 794fee23f9Smrg <code class="code">atexit</code> functions. 804fee23f9Smrg</p><pre class="programlisting"> 814fee23f9Smrg #include <cstdlib> 824fee23f9Smrg 834fee23f9Smrg extern "C" void __libc_freeres(void); 844fee23f9Smrg 854fee23f9Smrg void do_something() { } 864fee23f9Smrg 874fee23f9Smrg int main() 884fee23f9Smrg { 894fee23f9Smrg atexit(__libc_freeres); 904fee23f9Smrg do_something(); 914fee23f9Smrg return 0; 924fee23f9Smrg } 934fee23f9Smrg</pre><p>or, using <code class="code">__cxa_atexit</code>:</p><pre class="programlisting"> 944fee23f9Smrg extern "C" void __libc_freeres(void); 954fee23f9Smrg extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); 964fee23f9Smrg 974fee23f9Smrg void do_something() { } 984fee23f9Smrg 994fee23f9Smrg int main() 1004fee23f9Smrg { 1014fee23f9Smrg extern void* __dso_handle __attribute__ ((__weak__)); 1024fee23f9Smrg __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 1034fee23f9Smrg &__dso_handle ? __dso_handle : NULL); 1044fee23f9Smrg do_test(); 1054fee23f9Smrg return 0; 1064fee23f9Smrg } 1074fee23f9Smrg</pre><p> 1084fee23f9Smrg Suggested valgrind flags, given the suggestions above about setting 1094fee23f9Smrg up the runtime environment, library, and test file, might be: 1104fee23f9Smrg</p><pre class="programlisting"> 1114fee23f9Smrg valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out 112a3e9eb18Smrg</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> 113a3e9eb18Smrg There are different kinds of allocation schemes that can be used by 114a3e9eb18Smrg <code class="code">std::allocator</code>. Prior to GCC 3.4.0 the default was to use 115a3e9eb18Smrg a pooling allocator, <code class="classname">pool_allocator</code>, 116a3e9eb18Smrg which is still available as the optional 117a3e9eb18Smrg <code class="classname">__pool_alloc</code> extension. 118a3e9eb18Smrg Another optional extension, <code class="classname">__mt_alloc</code>, 119a3e9eb18Smrg is a high-performance pool allocator. 120a3e9eb18Smrg</p><p> 121a3e9eb18Smrg In a suspect executable these pooling allocators can give 122a3e9eb18Smrg the mistaken impression that memory is being leaked, 123a3e9eb18Smrg when in reality the memory "leak" is a pool being used 124a3e9eb18Smrg by the library's allocator and is reclaimed after program 125a3e9eb18Smrg termination. 126a3e9eb18Smrg</p><p> 127a3e9eb18Smrg If you're using memory debugging tools on a program that uses 128a3e9eb18Smrg one of these pooling allocators, you can set the environment variable 129a3e9eb18Smrg <code class="literal">GLIBCXX_FORCE_NEW</code> to keep extraneous pool allocation 130a3e9eb18Smrg noise from cluttering debug information. 131a3e9eb18Smrg For more details, see the 132fb8a8121Smrg <a class="link" href="mt_allocator.html" title="Chapter 19. The mt_allocator">mt allocator</a> 133a3e9eb18Smrg documentation and look specifically for <code class="code">GLIBCXX_FORCE_NEW</code>. 134a3e9eb18Smrg</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> 13548fb7bfaSmrg All synchronization primitives used in the library internals need to be 13648fb7bfaSmrg understood by race detectors so that they do not produce false reports. 1374fee23f9Smrg</p><p> 13848fb7bfaSmrg Two annotation macros are used to explain low-level synchronization 13948fb7bfaSmrg to race detectors: 14048fb7bfaSmrg <code class="code">_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and 14148fb7bfaSmrg <code class="code"> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>. 14248fb7bfaSmrg By default, these macros are defined empty -- anyone who wants 14348fb7bfaSmrg to use a race detector needs to redefine them to call an 14448fb7bfaSmrg appropriate API. 14548fb7bfaSmrg Since these macros are empty by default when the library is built, 14648fb7bfaSmrg redefining them will only affect inline functions and template 14748fb7bfaSmrg instantiations which are compiled in user code. This allows annotation 14848fb7bfaSmrg of templates such as <code class="code">shared_ptr</code>, but not code which is 14948fb7bfaSmrg only instantiated in the library. Code which is only instantiated in 15048fb7bfaSmrg the library needs to be recompiled with the annotation macros defined. 15148fb7bfaSmrg That can be done by rebuilding the entire 15248fb7bfaSmrg <code class="filename">libstdc++.so</code> file but a simpler 15348fb7bfaSmrg alternative exists for ELF platforms such as GNU/Linux, because ELF 15448fb7bfaSmrg symbol interposition allows symbols defined in the shared library to be 15548fb7bfaSmrg overridden by symbols with the same name that appear earlier in the 15648fb7bfaSmrg runtime search path. This means you only need to recompile the functions 15748fb7bfaSmrg that are affected by the annotation macros, which can be done by 15848fb7bfaSmrg recompiling individual files. 15948fb7bfaSmrg Annotating <code class="code">std::string</code> and <code class="code">std::wstring</code> 16048fb7bfaSmrg reference counting can be done by disabling extern templates (by defining 16148fb7bfaSmrg <code class="code">_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the 16248fb7bfaSmrg <code class="filename">src/string-inst.cc</code> file. 16348fb7bfaSmrg Annotating the remaining atomic operations (at the time of writing these 16448fb7bfaSmrg are in <code class="code">ios_base::Init::~Init</code>, <code class="code">locale::_Impl</code>, 16548fb7bfaSmrg <code class="code">locale::facet</code> and <code class="code">thread::_M_start_thread</code>) 16648fb7bfaSmrg requires rebuilding the relevant source files. 16748fb7bfaSmrg</p><p> 16848fb7bfaSmrg The approach described above is known to work with the following race 16948fb7bfaSmrg detection tools: 170*b1e83836Smrg <a class="link" href="https://valgrind.org/docs/manual/drd-manual.html" target="_top"> 17148fb7bfaSmrg DRD</a>, 172*b1e83836Smrg <a class="link" href="https://valgrind.org/docs/manual/hg-manual.html" target="_top"> 17348fb7bfaSmrg Helgrind</a>, and 174b17d1066Smrg <a class="link" href="https://github.com/google/sanitizers" target="_top"> 1754d5abbe8Smrg ThreadSanitizer</a> (this refers to ThreadSanitizer v1, not the 1764d5abbe8Smrg new "tsan" feature built-in to GCC itself). 17748fb7bfaSmrg</p><p> 17848fb7bfaSmrg With DRD, Helgrind and ThreadSanitizer you will need to define 17948fb7bfaSmrg the macros like this: 18048fb7bfaSmrg</p><pre class="programlisting"> 18148fb7bfaSmrg #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A) 18248fb7bfaSmrg #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A) 18348fb7bfaSmrg</pre><p> 18448fb7bfaSmrg Refer to the documentation of each particular tool for details. 18548fb7bfaSmrg</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> 18648fb7bfaSmrg </p><p> 18748fb7bfaSmrg Many options are available for GDB itself: please see <a class="link" href="http://sourceware.org/gdb/current/onlinedocs/gdb/" target="_top"> 18848fb7bfaSmrg "GDB features for C++" </a> in the GDB documentation. Also 1894fee23f9Smrg recommended: the other parts of this manual. 1904fee23f9Smrg</p><p> 19148fb7bfaSmrg These settings can either be switched on in at the GDB command line, 1924d5abbe8Smrg or put into a <code class="filename">.gdbinit</code> file to establish default 1934d5abbe8Smrg debugging characteristics, like so: 1944fee23f9Smrg</p><pre class="programlisting"> 1954fee23f9Smrg set print pretty on 1964fee23f9Smrg set print object on 1974fee23f9Smrg set print static-members on 1984fee23f9Smrg set print vtbl on 1994fee23f9Smrg set print demangle on 2004fee23f9Smrg set demangle-style gnu-v3 2014fee23f9Smrg</pre><p> 2024fee23f9Smrg Starting with version 7.0, GDB includes support for writing 2034d5abbe8Smrg pretty-printers in Python. Pretty printers for containers and other 2044d5abbe8Smrg classes are distributed with GCC from version 4.5.0 and should be installed 2054d5abbe8Smrg alongside the libstdc++ shared library files and found automatically by 2064d5abbe8Smrg GDB. 2074d5abbe8Smrg</p><p> 2084d5abbe8Smrg Depending where libstdc++ is installed, GDB might refuse to auto-load 2094d5abbe8Smrg the python printers and print a warning instead. 2104d5abbe8Smrg If this happens the python printers can be enabled by following the 2114d5abbe8Smrg instructions GDB gives for setting your <code class="code">auto-load safe-path</code> 2124d5abbe8Smrg in your <code class="filename">.gdbinit</code> configuration file. 2134d5abbe8Smrg</p><p> 2144d5abbe8Smrg Once loaded, standard library classes that the printers support 2154fee23f9Smrg should print in a more human-readable format. To print the classes 2164d5abbe8Smrg in the old style, use the <strong class="userinput"><code>/r</code></strong> (raw) switch in the 2174d5abbe8Smrg print command (i.e., <strong class="userinput"><code>print /r foo</code></strong>). This will 2184d5abbe8Smrg print the classes as if the Python pretty-printers were not loaded. 2194fee23f9Smrg</p><p> 2204fee23f9Smrg For additional information on STL support and GDB please visit: 22148fb7bfaSmrg <a class="link" href="http://sourceware.org/gdb/wiki/STLSupport" target="_top"> "GDB Support 2224fee23f9Smrg for STL" </a> in the GDB wiki. Additionally, in-depth 2234fee23f9Smrg documentation and discussion of the pretty printing feature can be 2244fee23f9Smrg found in "Pretty Printing" node in the GDB manual. You can find 2254fee23f9Smrg on-line versions of the GDB user manual in GDB's homepage, at 22648fb7bfaSmrg <a class="link" href="http://sourceware.org/gdb/" target="_top"> "GDB: The GNU Project 2274fee23f9Smrg Debugger" </a>. 22848fb7bfaSmrg</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> 22948fb7bfaSmrg The <a class="link" href="termination.html#support.termination.verbose" title="Verbose Terminate Handler">verbose 2304fee23f9Smrg termination handler</a> gives information about uncaught 2314d5abbe8Smrg exceptions which kill the program. 23248fb7bfaSmrg</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> 2334fee23f9Smrg has compile and run-time checks for many containers. 23448fb7bfaSmrg </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 2354d5abbe8Smrg Checks</a> extension has compile-time checks for many algorithms. 23648fb7bfaSmrg </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. 23748fb7bfaSmrg Standard Contents 2384fee23f9Smrg </td></tr></table></div></body></html>