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" type="text/css" /> 14<link rel="Copyright" href="17_intro/license.html" type="text/html" /> 15</head> 16<body> 17 18<h1 class="centered"><a name="top">Debugging schemes and strategies</a></h1> 19 20<p class="fineprint"><em> 21 The latest version of this document is always available at 22 <a href="http://gcc.gnu.org/onlinedocs/libstdc++/debug.html"> 23 http://gcc.gnu.org/onlinedocs/libstdc++/debug.html</a>. 24</em></p> 25 26<p><em> 27 To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. 28</em></p> 29 30<!-- ####################################################### --> 31<hr /> 32<p>There are numerous things that can be done to improve the ease with 33 which C++ binaries are debugged when using the GNU 34 tool chain. Here are some of them. 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. In addition, 44 <code>-fno-eliminate-unused-debug-types</code> can be used when 45 additional debug information, such as nested class info, is desired. 46</p> 47 48<p>Or, the debug format that the compiler and debugger use to communicate 49 information about source constructs can be changed via <code> 50 -gdwarf-2 </code> or <code> -gstabs </code> flags: some debugging 51 formats permit more expressive type and scope information to be 52 shown in gdb. The default debug information for a particular 53 platform can be identified via the value set by the 54 PREFERRED_DEBUGGING_TYPE macro in the gcc sources. 55</p> 56 57<p>Many other options are available: please see 58<a href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options for Debugging Your Program"</a> 59 in Using the GNU Compiler Collection (GCC) for a complete list. 60</p> 61 62<h3 class="left"><a name="lib">Using special flags to make a debug binary</a></h3> 63<p>If you would like debug symbols in libstdc++, there are two ways to 64 build libstdc++ with debug flags. The first is to run make from the 65 toplevel in a freshly-configured tree with 66</p> 67<pre> 68 --enable-libstdcxx-debug 69</pre> 70<p>and perhaps</p> 71<pre> 72 --enable-libstdcxx-debug-flags='...' 73</pre> 74<p>to create a separate debug build. Both the normal build and the 75 debug build will persist, without having to specify 76 <code>CXXFLAGS</code>, and the debug library will be installed in a 77 separate directory tree, in <code>(prefix)/lib/debug</code>. For 78 more information, look at the <a href="configopts.html">configuration 79 options</a> document. 80</p> 81 82<p>A second approach is to use the configuration flags 83</p> 84<pre> 85 make CXXFLAGS='-g3 -O0' all 86</pre> 87 88<p>This quick and dirty approach is often sufficient for quick 89 debugging tasks, when you cannot or don't want to recompile your 90 application to use the <a href="#safe">debug mode</a>.</p> 91 92<h3 class="left"><a name="safe">The libstdc++ debug mode</a></h3> 93<p>By default, libstdc++ is built with efficiency in mind, and 94 therefore performs little or no error checking that is not required 95 by the C++ standard. This means that programs that incorrectly use 96 the C++ standard library will exhibit behavior that is not portable 97 and may not even be predictable, because they tread into 98 implementation-specific or undefined behavior. To detect some of 99 these errors before they can become problematic, libstdc++ offers a 100 debug mode that provides additional checking of library facilities, 101 and will report errors in the use of libstdc++ as soon as they can 102 be detected by emitting a description of the problem to standard 103 error and aborting the program. This debug mode is available with 104 GCC 3.4.0 and later versions. </p> 105 106<p>The libstdc++ debug mode performs checking for many areas of the C++ 107 standard, but the focus is on checking interactions among standard 108 iterators, containers, and algorithms, including:</p> 109 110 <ul> 111 <li><em>Safe iterators</em>: Iterators keep track of the 112 container whose elements they reference, so errors such as 113 incrementing a past-the-end iterator or dereferencing an iterator 114 that points to a container that has been destructed are diagnosed 115 immediately.</li> 116 117 <li><em>Algorithm preconditions</em>: Algorithms attempt to 118 validate their input parameters to detect errors as early as 119 possible. For instance, the <code>set_intersection</code> 120 algorithm requires that its iterator 121 parameters <code>first1</code> and <code>last1</code> form a valid 122 iterator range, and that the sequence 123 [<code>first1</code>, <code>last1</code>) is sorted according to 124 the same predicate that was passed 125 to <code>set_intersection</code>; the libstdc++ debug mode will 126 detect an error if the sequence is not sorted or was sorted by a 127 different predicate.</li> 128 </ul> 129 130<h4 class="left">Using the libstdc++ debug mode</h4> 131<p>To use the libstdc++ debug mode, compile your application with the 132 compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag 133 changes the sizes and behavior of standard class templates such 134 as <code>std::vector</code>, and therefore you can only link code 135 compiled with debug mode and code compiled without debug mode if no 136 instantiation of a container is passed between the two translation 137 units.</p> 138 139<p>For information about the design of the libstdc++ debug mode, 140 please see the <a href="debug_mode.html">libstdc++ debug mode design 141 document</a>.</p> 142 143<h4 class="left">Using the debugging containers without debug 144 mode</h4> 145<p>When it is not feasible to recompile your entire application, or 146 only specific containers need checking, debugging containers are 147 available as GNU extensions. These debugging containers are 148 functionally equivalent to the standard drop-in containers used in 149 debug mode, but they are available in a separate namespace as GNU 150 extensions and may be used in programs compiled with either release 151 mode or with debug mode. The 152 following table provides the names and headers of the debugging 153 containers: 154</p> 155 156<table title="Debugging containers" border="1"> 157 <tr> 158 <th>Container</th> 159 <th>Header</th> 160 <th>Debug container</th> 161 <th>Debug header</th> 162 </tr> 163 <tr> 164 <td>std::bitset</td> 165 <td><bitset></td> 166 <td>__gnu_debug::bitset</td> 167 <td><debug/bitset></td> 168 </tr> 169 <tr> 170 <td>std::deque</td> 171 <td><deque></td> 172 <td>__gnu_debug::deque</td> 173 <td><debug/deque></td> 174 </tr> 175 <tr> 176 <td>std::list</td> 177 <td><list></td> 178 <td>__gnu_debug::list</td> 179 <td><debug/list></td> 180 </tr> 181 <tr> 182 <td>std::map</td> 183 <td><map></td> 184 <td>__gnu_debug::map</td> 185 <td><debug/map></td> 186 </tr> 187 <tr> 188 <td>std::multimap</td> 189 <td><map></td> 190 <td>__gnu_debug::multimap</td> 191 <td><debug/map></td> 192 </tr> 193 <tr> 194 <td>std::multiset</td> 195 <td><set></td> 196 <td>__gnu_debug::multiset</td> 197 <td><debug/set></td> 198 </tr> 199 <tr> 200 <td>std::set</td> 201 <td><set></td> 202 <td>__gnu_debug::set</td> 203 <td><debug/set></td> 204 </tr> 205 <tr> 206 <td>std::string</td> 207 <td><string></td> 208 <td>__gnu_debug::string</td> 209 <td><debug/string></td> 210 </tr> 211 <tr> 212 <td>std::wstring</td> 213 <td><string></td> 214 <td>__gnu_debug::wstring</td> 215 <td><debug/string></td> 216 </tr> 217 <tr> 218 <td>std::basic_string</td> 219 <td><string></td> 220 <td>__gnu_debug::basic_string</td> 221 <td><debug/string></td> 222 </tr> 223 <tr> 224 <td>std::vector</td> 225 <td><vector></td> 226 <td>__gnu_debug::vector</td> 227 <td><debug/vector></td> 228 </tr> 229 <tr> 230 <td>__gnu_cxx::hash_map</td> 231 <td><ext/hash_map></td> 232 <td>__gnu_debug::hash_map</td> 233 <td><debug/hash_map></td> 234 </tr> 235 <tr> 236 <td>__gnu_cxx::hash_multimap</td> 237 <td><ext/hash_map></td> 238 <td>__gnu_debug::hash_multimap</td> 239 <td><debug/hash_map></td> 240 </tr> 241 <tr> 242 <td>__gnu_cxx::hash_set</td> 243 <td><ext/hash_set></td> 244 <td>__gnu_debug::hash_set</td> 245 <td><debug/hash_set></td> 246 </tr> 247 <tr> 248 <td>__gnu_cxx::hash_multiset</td> 249 <td><ext/hash_set></td> 250 <td>__gnu_debug::hash_multiset</td> 251 <td><debug/hash_set></td> 252 </tr> 253</table> 254 255<h4 class="left">Debug mode semantics</h4> 256<p>A program that uses the C++ standard library correctly 257 will maintain the same semantics under debug mode as it had with 258 the normal (release) library. All functional and exception-handling 259 guarantees made by the normal library also hold for the debug mode 260 library, with one exception: performance guarantees made by the 261 normal library may not hold in the debug mode library. For 262 instance, erasing an element in a <code>std::list</code> is a 263 constant-time operation in normal library, but in debug mode it is 264 linear in the number of iterators that reference that particular 265 list. So while your (correct) program won't change its results, it 266 is likely to execute more slowly.</p> 267 268<p>libstdc++ includes many extensions to the C++ standard library. In 269 some cases the extensions are obvious, such as the hashed 270 associative containers, whereas other extensions give predictable 271 results to behavior that would otherwise be undefined, such as 272 throwing an exception when a <code>std::basic_string</code> is 273 constructed from a NULL character pointer. This latter category also 274 includes implementation-defined and unspecified semantics, such as 275 the growth rate of a vector. Use of these extensions is not 276 considered incorrect, so code that relies on them will not be 277 rejected by debug mode. However, use of these extensions may affect 278 the portability of code to other implementations of the C++ standard 279 library, and is therefore somewhat hazardous. For this reason, the 280 libstdc++ debug mode offers a "pedantic" mode (similar to 281 GCC's <code>-pedantic</code> compiler flag) that attempts to emulate 282 the semantics guaranteed by the C++ standard. For 283 instance, constructing a <code>std::basic_string</code> with a NULL 284 character pointer would result in an exception under normal mode or 285 non-pedantic debug mode (this is a libstdc++ extension), whereas 286 under pedantic debug mode libstdc++ would signal an error. To enable 287 the pedantic debug mode, compile your program with 288 both <code>-D_GLIBCXX_DEBUG</code> 289 and <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> . 290 (N.B. In GCC 3.4.x and 4.0.0, due to a bug, 291 <code>-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has 292 been fixed in GCC 4.0.1 and later versions.) </p> 293 294<p>The following library components provide extra debugging 295 capabilities in debug mode:</p> 296<ul> 297 <li><code>std::basic_string</code> (no safe iterators)</li> 298 <li><code>std::bitset</code></li> 299 <li><code>std::deque</code></li> 300 <li><code>std::list</code></li> 301 <li><code>std::map</code></li> 302 <li><code>std::multimap</code></li> 303 <li><code>std::multiset</code></li> 304 <li><code>std::set</code></li> 305 <li><code>std::vector</code></li> 306 <li><code>__gnu_cxx::hash_map</code></li> 307 <li><code>__gnu_cxx::hash_multimap</code></li> 308 <li><code>__gnu_cxx::hash_multiset</code></li> 309 <li><code>__gnu_cxx::hash_set</code></li> 310</ul> 311 312 313<h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3> 314 315<p>There are various third party memory tracing and debug utilities 316 that can be used to provide detailed memory allocation information 317 about C++ code. An exhaustive list of tools is not going to be 318 attempted, but includes <code>mtrace</code>, <code>valgrind</code>, 319 <code>mudflap</code>, and the non-free commercial product 320 <code>purify</code>. In addition, <code>libcwd</code> has a 321 replacement for the global new and delete operators that can track 322 memory allocation and deallocation and provide useful memory 323 statistics. 324</p> 325 326<p>Regardless of the memory debugging tool being used, there is one 327 thing of great importance to keep in mind when debugging C++ code 328 that uses <code>new</code> and <code>delete</code>: 329 there are different kinds of allocation schemes that can be used by 330 <code> std::allocator </code>. For implementation details, see this 331 <a href="ext/howto.html#3"> document</a> and look specifically for 332 <code>GLIBCXX_FORCE_NEW</code>. 333</p> 334 335<p>In a nutshell, the default allocator used by <code> 336 std::allocator</code> is a high-performance pool allocator, and can 337 give the mistaken impression that in a suspect executable, memory 338 is being leaked, when in reality the memory "leak" is a pool being 339 used by the library's allocator and is reclaimed after program 340 termination. 341</p> 342 343<p>For valgrind, there are some specific items to keep in mind. First 344 of all, use a version of valgrind that will work with current GNU 345 C++ tools: the first that can do this is valgrind 1.0.4, but later 346 versions should work at least as well. Second of all, use a 347 completely unoptimized build to avoid confusing valgrind. Third, 348 use GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from 349 cluttering debug information. 350</p> 351 352<p>Fourth, it may be necessary to force deallocation in other 353 libraries as well, namely the "C" library. On linux, this can be 354 accomplished with the appropriate use of the 355 <code>__cxa_atexit</code> or <code>atexit</code> functions. 356</p> 357 358<pre> 359 #include <cstdlib> 360 361 extern "C" void __libc_freeres(void); 362 363 void do_something() { } 364 365 int main() 366 { 367 atexit(__libc_freeres); 368 do_something(); 369 return 0; 370 } 371</pre> 372 373 374<p>or, using <code>__cxa_atexit</code>:</p> 375 376<pre> 377 extern "C" void __libc_freeres(void); 378 extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); 379 380 void do_something() { } 381 382 int main() 383 { 384 extern void* __dso_handle __attribute__ ((__weak__)); 385 __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 386 &__dso_handle ? __dso_handle : NULL); 387 do_test(); 388 return 0; 389 } 390</pre> 391 392<p>Suggested valgrind flags, given the suggestions above about setting 393 up the runtime environment, library, and test file, might be: 394</p> 395<pre> 396 valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out 397</pre> 398 399 400<h3 class="left"><a name="gdb">Some gdb strategies</a></h3> 401<p>Many options are available for gdb itself: please see <a 402 href="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109"> 403 "GDB features for C++" </a> in the gdb documentation. Also 404 recommended: the other parts of this manual. 405</p> 406 407<p>These settings can either be switched on in at the gdb command 408 line, or put into a .gdbint file to establish default debugging 409 characteristics, like so: 410</p> 411 412<pre> 413 set print pretty on 414 set print object on 415 set print static-members on 416 set print vtbl on 417 set print demangle on 418 set demangle-style gnu-v3 419</pre> 420 421 422<h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3> 423<p>The <a href="18_support/howto.html#4">verbose termination handler</a> 424 gives information about uncaught exceptions which are killing the 425 program. It is described in the linked-to page. 426</p> 427 428 429<p>Return <a href="#top">to the top of the page</a> or 430 <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>. 431</p> 432 433 434<!-- ####################################################### --> 435 436<hr /> 437<p class="fineprint"><em> 438See <a href="17_intro/license.html">license.html</a> for copying conditions. 439Comments and suggestions are welcome, and may be sent to 440<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. 441</em></p> 442 443 444</body> 445</html> 446