1 <sect1 id="manual.intro.using.debug" xreflabel="Debugging Support">
2 <?dbhtml filename="debug.html"?>
15 <title>Debugging Support</title>
18 There are numerous things that can be done to improve the ease with
19 which C++ binaries are debugged when using the GNU tool chain. Here
23 <sect2 id="debug.compiler" xreflabel="debug.compiler">
24 <title>Using <command>g++</command></title>
26 Compiler flags determine how debug information is transmitted
27 between compilation and debug or analysis tools.
31 The default optimizations and debug flags for a libstdc++ build
32 are <code>-g -O2</code>. However, both debug and optimization
33 flags can be varied to change debugging characteristics. For
34 instance, turning off all optimization via the <code>-g -O0</code>
35 flag will disable inlining, so that stepping through all
36 functions, including inlined constructors and destructors, is
37 possible. In addition,
38 <code>-fno-eliminate-unused-debug-types</code> can be used when
39 additional debug information, such as nested class info, is
44 Or, the debug format that the compiler and debugger use to
45 communicate information about source constructs can be changed via
46 <code> -gdwarf-2 </code> or <code> -gstabs </code> flags: some
47 debugging formats permit more expressive type and scope information
48 to be shown in gdb. The default debug information for a particular
49 platform can be identified via the value set by the
50 PREFERRED_DEBUGGING_TYPE macro in the gcc sources.
54 Many other options are available: please see <ulink
55 url="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options
56 for Debugging Your Program"</ulink> in Using the GNU Compiler
57 Collection (GCC) for a complete list.
61 <sect2 id="debug.req" xreflabel="debug.req">
62 <title>Debug Versions of Library Binary Files</title>
65 If you would like debug symbols in libstdc++, there are two ways to
66 build libstdc++ with debug flags. The first is to run make from the
67 toplevel in a freshly-configured tree with
70 --enable-libstdcxx-debug
72 <para>and perhaps</para>
74 --enable-libstdcxx-debug-flags='...'
77 to create a separate debug build. Both the normal build and the
78 debug build will persist, without having to specify
79 <code>CXXFLAGS</code>, and the debug library will be installed in a
80 separate directory tree, in <code>(prefix)/lib/debug</code>. For
81 more information, look at the <ulink
82 url="configopts.html">configuration options</ulink> document.
86 A second approach is to use the configuration flags
89 make CXXFLAGS='-g3 -O0' all
93 This quick and dirty approach is often sufficient for quick
94 debugging tasks, when you cannot or don't want to recompile your
95 application to use the <ulink url="#safe">debug mode</ulink>.</para>
98 <sect2 id="debug.memory" xreflabel="debug.memory">
99 <title>Memory Leak Hunting</title>
102 There are various third party memory tracing and debug utilities
103 that can be used to provide detailed memory allocation information
104 about C++ code. An exhaustive list of tools is not going to be
105 attempted, but includes <code>mtrace</code>, <code>valgrind</code>,
106 <code>mudflap</code>, and the non-free commercial product
107 <code>purify</code>. In addition, <code>libcwd</code> has a
108 replacement for the global new and delete operators that can track
109 memory allocation and deallocation and provide useful memory
114 Regardless of the memory debugging tool being used, there is one
115 thing of great importance to keep in mind when debugging C++ code
116 that uses <code>new</code> and <code>delete</code>: there are
117 different kinds of allocation schemes that can be used by <code>
118 std::allocator </code>. For implementation details, see the <ulink
119 url="ext/mt_allocator.html">mt allocator</ulink> documentation and
120 look specifically for <code>GLIBCXX_FORCE_NEW</code>.
124 In a nutshell, the default allocator used by <code>
125 std::allocator</code> is a high-performance pool allocator, and can
126 give the mistaken impression that in a suspect executable, memory is
127 being leaked, when in reality the memory "leak" is a pool being used
128 by the library's allocator and is reclaimed after program
133 For valgrind, there are some specific items to keep in mind. First
134 of all, use a version of valgrind that will work with current GNU
135 C++ tools: the first that can do this is valgrind 1.0.4, but later
136 versions should work at least as well. Second of all, use a
137 completely unoptimized build to avoid confusing valgrind. Third, use
138 GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from
139 cluttering debug information.
143 Fourth, it may be necessary to force deallocation in other libraries
144 as well, namely the "C" library. On linux, this can be accomplished
145 with the appropriate use of the <code>__cxa_atexit</code> or
146 <code>atexit</code> functions.
150 #include <cstdlib>
152 extern "C" void __libc_freeres(void);
154 void do_something() { }
158 atexit(__libc_freeres);
165 <para>or, using <code>__cxa_atexit</code>:</para>
168 extern "C" void __libc_freeres(void);
169 extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
171 void do_something() { }
175 extern void* __dso_handle __attribute__ ((__weak__));
176 __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
177 &__dso_handle ? __dso_handle : NULL);
184 Suggested valgrind flags, given the suggestions above about setting
185 up the runtime environment, library, and test file, might be:
188 valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
193 <sect2 id="debug.gdb" xreflabel="debug.gdb">
194 <title>Using <command>gdb</command></title>
199 Many options are available for gdb itself: please see <ulink
200 url="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109">
201 "GDB features for C++" </ulink> in the gdb documentation. Also
202 recommended: the other parts of this manual.
206 These settings can either be switched on in at the gdb command line,
207 or put into a .gdbint file to establish default debugging
208 characteristics, like so:
214 set print static-members on
216 set print demangle on
217 set demangle-style gnu-v3
221 <sect2 id="debug.exceptions" xreflabel="debug.exceptions">
222 <title>Tracking uncaught exceptions</title>
224 The <link linkend="support.termination.verbose">verbose
225 termination handler</link> gives information about uncaught
226 exceptions which are killing the program. It is described in the
231 <sect2 id="debug.debug_mode" xreflabel="debug.debug_mode">
232 <title>Debug Mode</title>
233 <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link>
234 has compile and run-time checks for many containers.
238 <sect2 id="debug.compile_time_checks" xreflabel="debug.compile_time_checks">
239 <title>Compile Time Checking</title>
240 <para> The <link linkend="manual.ext.compile_checks">Compile-Time
241 Checks</link> Extension has compile-time checks for many algorithms.