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