1 This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo.
3 Copyright (C) 1988-2014 Free Software Foundation, Inc.
5 Permission is granted to copy, distribute and/or modify this document
6 under the terms of the GNU Free Documentation License, Version 1.3 or
7 any later version published by the Free Software Foundation; with the
8 Invariant Sections being "Free Software" and "Free Software Needs Free
9 Documentation", with the Front-Cover Texts being "A GNU Manual," and
10 with the Back-Cover Texts as in (a) below.
12 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
13 this GNU Manual. Buying copies from GNU Press supports the FSF in
14 developing GNU and promoting software freedom."
15 INFO-DIR-SECTION Software development
17 * Gdb: (gdb). The GNU debugger.
18 * gdbserver: (gdb) Server. The GNU debugging server.
21 This file documents the GNU debugger GDB.
23 This is the Tenth Edition, of 'Debugging with GDB: the GNU
24 Source-Level Debugger' for GDB (GDB) Version 7.8.1.
26 Copyright (C) 1988-2014 Free Software Foundation, Inc.
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the GNU Free Documentation License, Version 1.3 or
30 any later version published by the Free Software Foundation; with the
31 Invariant Sections being "Free Software" and "Free Software Needs Free
32 Documentation", with the Front-Cover Texts being "A GNU Manual," and
33 with the Back-Cover Texts as in (a) below.
35 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
36 this GNU Manual. Buying copies from GNU Press supports the FSF in
37 developing GNU and promoting software freedom."
40 File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir)
45 This file describes GDB, the GNU symbolic debugger.
47 This is the Tenth Edition, for GDB (GDB) Version 7.8.1.
49 Copyright (C) 1988-2014 Free Software Foundation, Inc.
51 This edition of the GDB manual is dedicated to the memory of Fred
52 Fish. Fred was a long-standing contributor to GDB and to Free software
53 in general. We will miss him.
57 * Summary:: Summary of GDB
58 * Sample Session:: A sample GDB session
60 * Invocation:: Getting in and out of GDB
61 * Commands:: GDB commands
62 * Running:: Running programs under GDB
63 * Stopping:: Stopping and continuing
64 * Reverse Execution:: Running programs backward
65 * Process Record and Replay:: Recording inferior's execution and replaying it
66 * Stack:: Examining the stack
67 * Source:: Examining source files
68 * Data:: Examining data
69 * Optimized Code:: Debugging optimized code
70 * Macros:: Preprocessor Macros
71 * Tracepoints:: Debugging remote targets non-intrusively
72 * Overlays:: Debugging programs that use overlays
74 * Languages:: Using GDB with different languages
76 * Symbols:: Examining the symbol table
77 * Altering:: Altering execution
78 * GDB Files:: GDB files
79 * Targets:: Specifying a debugging target
80 * Remote Debugging:: Debugging remote programs
81 * Configurations:: Configuration-specific information
82 * Controlling GDB:: Controlling GDB
83 * Extending GDB:: Extending GDB
84 * Interpreters:: Command Interpreters
85 * TUI:: GDB Text User Interface
86 * Emacs:: Using GDB under GNU Emacs
87 * GDB/MI:: GDB's Machine Interface.
88 * Annotations:: GDB's annotation interface.
89 * JIT Interface:: Using the JIT debugging interface.
90 * In-Process Agent:: In-Process Agent
92 * GDB Bugs:: Reporting bugs in GDB
94 * Command Line Editing:: Command Line Editing
95 * Using History Interactively:: Using History Interactively
96 * In Memoriam:: In Memoriam
97 * Formatting Documentation:: How to format and print GDB documentation
98 * Installing GDB:: Installing GDB
99 * Maintenance Commands:: Maintenance Commands
100 * Remote Protocol:: GDB Remote Serial Protocol
101 * Agent Expressions:: The GDB Agent Expression Mechanism
102 * Target Descriptions:: How targets can describe themselves to
104 * Operating System Information:: Getting additional information from
106 * Trace File Format:: GDB trace file format
107 * Index Section Format:: .gdb_index section format
108 * Man Pages:: Manual pages
109 * Copying:: GNU General Public License says
110 how you can copy and share GDB
111 * GNU Free Documentation License:: The license for this documentation
112 * Concept Index:: Index of GDB concepts
113 * Command and Variable Index:: Index of GDB commands, variables,
114 functions, and Python data types
117 File: gdb.info, Node: Summary, Next: Sample Session, Up: Top
122 The purpose of a debugger such as GDB is to allow you to see what is
123 going on "inside" another program while it executes--or what another
124 program was doing at the moment it crashed.
126 GDB can do four main kinds of things (plus other things in support of
127 these) to help you catch bugs in the act:
129 * Start your program, specifying anything that might affect its
132 * Make your program stop on specified conditions.
134 * Examine what has happened, when your program has stopped.
136 * Change things in your program, so you can experiment with
137 correcting the effects of one bug and go on to learn about another.
139 You can use GDB to debug programs written in C and C++. For more
140 information, see *note Supported Languages: Supported Languages. For
141 more information, see *note C and C++: C.
143 Support for D is partial. For information on D, see *note D: D.
145 Support for Modula-2 is partial. For information on Modula-2, see
146 *note Modula-2: Modula-2.
148 Support for OpenCL C is partial. For information on OpenCL C, see
149 *note OpenCL C: OpenCL C.
151 Debugging Pascal programs which use sets, subranges, file variables,
152 or nested functions does not currently work. GDB does not support
153 entering expressions, printing values, or similar features using Pascal
156 GDB can be used to debug programs written in Fortran, although it may
157 be necessary to refer to some variables with a trailing underscore.
159 GDB can be used to debug programs written in Objective-C, using
160 either the Apple/NeXT or the GNU Objective-C runtime.
164 * Free Software:: Freely redistributable software
165 * Free Documentation:: Free Software Needs Free Documentation
166 * Contributors:: Contributors to GDB
169 File: gdb.info, Node: Free Software, Next: Free Documentation, Up: Summary
174 GDB is "free software", protected by the GNU General Public License
175 (GPL). The GPL gives you the freedom to copy or adapt a licensed
176 program--but every person getting a copy also gets with it the freedom
177 to modify that copy (which means that they must get access to the source
178 code), and the freedom to distribute further copies. Typical software
179 companies use copyrights to limit your freedoms; the Free Software
180 Foundation uses the GPL to preserve these freedoms.
182 Fundamentally, the General Public License is a license which says
183 that you have these freedoms and that you cannot take these freedoms
184 away from anyone else.
187 File: gdb.info, Node: Free Documentation, Next: Contributors, Prev: Free Software, Up: Summary
189 Free Software Needs Free Documentation
190 ======================================
192 The biggest deficiency in the free software community today is not in
193 the software--it is the lack of good free documentation that we can
194 include with the free software. Many of our most important programs do
195 not come with free reference manuals and free introductory texts.
196 Documentation is an essential part of any software package; when an
197 important free software package does not come with a free manual and a
198 free tutorial, that is a major gap. We have many such gaps today.
200 Consider Perl, for instance. The tutorial manuals that people
201 normally use are non-free. How did this come about? Because the
202 authors of those manuals published them with restrictive terms--no
203 copying, no modification, source files not available--which exclude them
204 from the free software world.
206 That wasn't the first time this sort of thing happened, and it was
207 far from the last. Many times we have heard a GNU user eagerly describe
208 a manual that he is writing, his intended contribution to the community,
209 only to learn that he had ruined everything by signing a publication
210 contract to make it non-free.
212 Free documentation, like free software, is a matter of freedom, not
213 price. The problem with the non-free manual is not that publishers
214 charge a price for printed copies--that in itself is fine. (The Free
215 Software Foundation sells printed copies of manuals, too.) The problem
216 is the restrictions on the use of the manual. Free manuals are
217 available in source code form, and give you permission to copy and
218 modify. Non-free manuals do not allow this.
220 The criteria of freedom for a free manual are roughly the same as for
221 free software. Redistribution (including the normal kinds of commercial
222 redistribution) must be permitted, so that the manual can accompany
223 every copy of the program, both on-line and on paper.
225 Permission for modification of the technical content is crucial too.
226 When people modify the software, adding or changing features, if they
227 are conscientious they will change the manual too--so they can provide
228 accurate and clear documentation for the modified program. A manual
229 that leaves you no choice but to write a new manual to document a
230 changed version of the program is not really available to our community.
232 Some kinds of limits on the way modification is handled are
233 acceptable. For example, requirements to preserve the original author's
234 copyright notice, the distribution terms, or the list of authors, are
235 ok. It is also no problem to require modified versions to include
236 notice that they were modified. Even entire sections that may not be
237 deleted or changed are acceptable, as long as they deal with
238 nontechnical topics (like this one). These kinds of restrictions are
239 acceptable because they don't obstruct the community's normal use of the
242 However, it must be possible to modify all the _technical_ content of
243 the manual, and then distribute the result in all the usual media,
244 through all the usual channels. Otherwise, the restrictions obstruct
245 the use of the manual, it is not free, and we need another manual to
248 Please spread the word about this issue. Our community continues to
249 lose manuals to proprietary publishing. If we spread the word that free
250 software needs free reference manuals and free tutorials, perhaps the
251 next person who wants to contribute by writing documentation will
252 realize, before it is too late, that only free manuals contribute to the
253 free software community.
255 If you are writing documentation, please insist on publishing it
256 under the GNU Free Documentation License or another free documentation
257 license. Remember that this decision requires your approval--you don't
258 have to let the publisher decide. Some commercial publishers will use a
259 free license if you insist, but they will not propose the option; it is
260 up to you to raise the issue and say firmly that this is what you want.
261 If the publisher you are dealing with refuses, please try other
262 publishers. If you're not sure whether a proposed license is free,
263 write to <licensing@gnu.org>.
265 You can encourage commercial publishers to sell more free, copylefted
266 manuals and tutorials by buying them, and particularly by buying copies
267 from the publishers that paid for their writing or for major
268 improvements. Meanwhile, try to avoid buying non-free documentation at
269 all. Check the distribution terms of a manual before you buy it, and
270 insist that whoever seeks your business must respect your freedom.
271 Check the history of the book, and try to reward the publishers that
272 have paid or pay the authors to work on it.
274 The Free Software Foundation maintains a list of free documentation
275 published by other publishers, at
276 <http://www.fsf.org/doc/other-free-books.html>.
279 File: gdb.info, Node: Contributors, Prev: Free Documentation, Up: Summary
284 Richard Stallman was the original author of GDB, and of many other GNU
285 programs. Many others have contributed to its development. This
286 section attempts to credit major contributors. One of the virtues of
287 free software is that everyone is free to contribute to it; with regret,
288 we cannot actually acknowledge everyone here. The file 'ChangeLog' in
289 the GDB distribution approximates a blow-by-blow account.
291 Changes much prior to version 2.0 are lost in the mists of time.
293 _Plea:_ Additions to this section are particularly welcome. If you
294 or your friends (or enemies, to be evenhanded) have been unfairly
295 omitted from this list, we would like to add your names!
297 So that they may not regard their many labors as thankless, we
298 particularly thank those who shepherded GDB through major releases:
299 Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim
300 Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release
301 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
302 Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
303 John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon
304 (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and
307 Richard Stallman, assisted at various times by Peter TerMaat, Chris
308 Hanson, and Richard Mlynarik, handled releases through 2.8.
310 Michael Tiemann is the author of most of the GNU C++ support in GDB,
311 with significant additional contributions from Per Bothner and Daniel
312 Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ was
313 by Peter TerMaat (who also did much general update work leading to
316 GDB uses the BFD subroutine library to examine multiple object-file
317 formats; BFD was a joint project of David V. Henkel-Wallace, Rich
318 Pixley, Steve Chamberlain, and John Gilmore.
320 David Johnson wrote the original COFF support; Pace Willison did the
321 original support for encapsulated COFF.
323 Brent Benson of Harris Computer Systems contributed DWARF 2 support.
325 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
326 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
327 support. Jean-Daniel Fekete contributed Sun 386i support. Chris Hanson
328 improved the HP9000 support. Noboyuki Hikichi and Tomoyuki Hasei
329 contributed Sony/News OS 3 support. David Johnson contributed Encore
330 Umax support. Jyrki Kuoppala contributed Altos 3068 support. Jeff Law
331 contributed HP PA and SOM support. Keith Packard contributed NS32K
332 support. Doug Rabson contributed Acorn Risc Machine support. Bob Rusk
333 contributed Harris Nighthawk CX-UX support. Chris Smith contributed
334 Convex support (and Fortran debugging). Jonathan Stone contributed
335 Pyramid support. Michael Tiemann contributed SPARC support. Tim Tucker
336 contributed support for the Gould NP1 and Gould Powernode. Pace
337 Willison contributed Intel 386 support. Jay Vosburgh contributed
338 Symmetry support. Marko Mlinar contributed OpenRISC 1000 support.
340 Andreas Schwab contributed M68K GNU/Linux support.
342 Rich Schaefer and Peter Schauer helped with support of SunOS shared
345 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
346 several machine instruction sets.
348 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
349 develop remote debugging. Intel Corporation, Wind River Systems, AMD,
350 and ARM contributed remote debugging modules for the i960, VxWorks, A29K
351 UDI, and RDI targets, respectively.
353 Brian Fox is the author of the readline libraries providing
354 command-line editing and command history.
356 Andrew Beers of SUNY Buffalo wrote the language-switching code, the
357 Modula-2 support, and contributed the Languages chapter of this manual.
359 Fred Fish wrote most of the support for Unix System Vr4. He also
360 enhanced the command-completion support to cover C++ overloaded symbols.
362 Hitachi America (now Renesas America), Ltd. sponsored the support
363 for H8/300, H8/500, and Super-H processors.
365 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx
368 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and
371 Toshiba sponsored the support for the TX39 Mips processor.
373 Matsushita sponsored the support for the MN10200 and MN10300
376 Fujitsu sponsored the support for SPARClite and FR30 processors.
378 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
381 Michael Snyder added support for tracepoints.
383 Stu Grossman wrote gdbserver.
385 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly
386 innumerable bug fixes and cleanups throughout GDB.
388 The following people at the Hewlett-Packard Company contributed
389 support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
390 (narrow mode), HP's implementation of kernel threads, HP's aC++
391 compiler, and the Text User Interface (nee Terminal User Interface): Ben
392 Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish
393 Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided
394 HP-specific information in this manual.
396 DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert
397 Hoehne made significant contributions to the DJGPP port.
399 Cygnus Solutions has sponsored GDB maintenance and much of its
400 development since 1991. Cygnus engineers who have worked on GDB
401 fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
402 Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
403 Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
404 Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
405 Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
406 addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
407 JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
408 Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
409 Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
410 Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
411 Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
412 Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
413 Zuhn have made contributions both large and small.
415 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
416 Cygnus Solutions, implemented the original GDB/MI interface.
418 Jim Blandy added support for preprocessor macros, while working for
421 Andrew Cagney designed GDB's architecture vector. Many people
422 including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek,
423 Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto,
424 Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna
425 Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration
426 of old architectures to this new framework.
428 Andrew Cagney completely re-designed and re-implemented GDB's
429 unwinder framework, this consisting of a fresh new design featuring
430 frame IDs, independent frame sniffers, and the sentinel frame. Mark
431 Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind
432 unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad
433 unwinders. The architecture-specific changes, each involving a complete
434 rewrite of the architecture's frame code, were carried out by Jim
435 Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane Carrez,
436 Randolph Chung, Orjan Friberg, Richard Henderson, Daniel Jacobowitz,
437 Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei Sakamoto, Yoshinori
438 Sato, Michael Snyder, Corinna Vinschen, and Ulrich Weigand.
440 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
441 Tensilica, Inc. contributed support for Xtensa processors. Others who
442 have worked on the Xtensa port of GDB in the past include Steve Tjiang,
443 John Newlin, and Scott Foehner.
445 Michael Eager and staff of Xilinx, Inc., contributed support for the
446 Xilinx MicroBlaze architecture.
449 File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
451 1 A Sample GDB Session
452 **********************
454 You can use this manual at your leisure to read all about GDB. However,
455 a handful of commands are enough to get started using the debugger.
456 This chapter illustrates those commands.
458 One of the preliminary versions of GNU 'm4' (a generic macro
459 processor) exhibits the following bug: sometimes, when we change its
460 quote strings from the default, the commands used to capture one macro
461 definition within another stop working. In the following short 'm4'
462 session, we define a macro 'foo' which expands to '0000'; we then use
463 the 'm4' built-in 'defn' to define 'bar' as the same thing. However,
464 when we change the open quote string to '<QUOTE>' and the close quote
465 string to '<UNQUOTE>', the same procedure fails to define a new synonym
474 define(bar,defn('foo'))
478 changequote(<QUOTE>,<UNQUOTE>)
480 define(baz,defn(<QUOTE>foo<UNQUOTE>))
483 m4: End of input: 0: fatal error: EOF in string
485 Let us use GDB to try to see what is going on.
488 GDB is free software and you are welcome to distribute copies
489 of it under certain conditions; type "show copying" to see
491 There is absolutely no warranty for GDB; type "show warranty"
494 GDB 7.8.1, Copyright 1999 Free Software Foundation, Inc...
497 GDB reads only enough symbol data to know where to find the rest when
498 needed; as a result, the first prompt comes up very quickly. We now
499 tell GDB to use a narrower display width than usual, so that examples
504 We need to see how the 'm4' built-in 'changequote' works. Having looked
505 at the source, we know the relevant subroutine is 'm4_changequote', so
506 we set a breakpoint there with the GDB 'break' command.
508 (gdb) break m4_changequote
509 Breakpoint 1 at 0x62f4: file builtin.c, line 879.
511 Using the 'run' command, we start 'm4' running under GDB control; as
512 long as control does not reach the 'm4_changequote' subroutine, the
513 program runs as usual:
516 Starting program: /work/Editorial/gdb/gnu/m4/m4
522 To trigger the breakpoint, we call 'changequote'. GDB suspends
523 execution of 'm4', displaying information about the context where it
526 changequote(<QUOTE>,<UNQUOTE>)
528 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
530 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
532 Now we use the command 'n' ('next') to advance execution to the next
533 line of the current function.
536 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
539 'set_quotes' looks like a promising subroutine. We can go into it by
540 using the command 's' ('step') instead of 'next'. 'step' goes to the
541 next line to be executed in _any_ subroutine, so it steps into
545 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
547 530 if (lquote != def_lquote)
549 The display that shows the subroutine where 'm4' is now suspended (and
550 its arguments) is called a stack frame display. It shows a summary of
551 the stack. We can use the 'backtrace' command (which can also be
552 spelled 'bt'), to see where we are in the stack as a whole: the
553 'backtrace' command displays a stack frame for each active subroutine.
556 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
558 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
560 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
561 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
563 #4 0x79dc in expand_input () at macro.c:40
564 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
566 We step through a few more lines to see what happens. The first two
567 times, we can use 's'; the next two times we use 'n' to avoid falling
568 into the 'xstrdup' subroutine.
571 0x3b5c 532 if (rquote != def_rquote)
573 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
574 def_lquote : xstrdup(lq);
576 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
579 538 len_lquote = strlen(rquote);
581 The last line displayed looks a little odd; we can examine the variables
582 'lquote' and 'rquote' to see if they are in fact the new left and right
583 quotes we specified. We use the command 'p' ('print') to see their
587 $1 = 0x35d40 "<QUOTE>"
589 $2 = 0x35d50 "<UNQUOTE>"
591 'lquote' and 'rquote' are indeed the new left and right quotes. To look
592 at some context, we can display ten lines of source surrounding the
593 current line with the 'l' ('list') command.
598 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
600 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
603 538 len_lquote = strlen(rquote);
604 539 len_rquote = strlen(lquote);
609 Let us step past the two lines that set 'len_lquote' and 'len_rquote',
610 and then examine the values of those variables.
613 539 len_rquote = strlen(lquote);
621 That certainly looks wrong, assuming 'len_lquote' and 'len_rquote' are
622 meant to be the lengths of 'lquote' and 'rquote' respectively. We can
623 set them to better values using the 'p' command, since it can print the
624 value of any expression--and that expression can include subroutine
625 calls and assignments.
627 (gdb) p len_lquote=strlen(lquote)
629 (gdb) p len_rquote=strlen(rquote)
632 Is that enough to fix the problem of using the new quotes with the 'm4'
633 built-in 'defn'? We can allow 'm4' to continue executing with the 'c'
634 ('continue') command, and then try the example that caused trouble
640 define(baz,defn(<QUOTE>foo<UNQUOTE>))
645 Success! The new quotes now work just as well as the default ones. The
646 problem seems to have been just the two typos defining the wrong
647 lengths. We allow 'm4' exit by giving it an EOF as input:
650 Program exited normally.
652 The message 'Program exited normally.' is from GDB; it indicates 'm4'
653 has finished executing. We can end our GDB session with the GDB 'quit'
659 File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top
661 2 Getting In and Out of GDB
662 ***************************
664 This chapter discusses how to start GDB, and how to get out of it. The
666 * type 'gdb' to start GDB.
667 * type 'quit' or 'Ctrl-d' to exit.
671 * Invoking GDB:: How to start GDB
672 * Quitting GDB:: How to quit GDB
673 * Shell Commands:: How to use shell commands inside GDB
674 * Logging Output:: How to log GDB's output to a file
677 File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
682 Invoke GDB by running the program 'gdb'. Once started, GDB reads
683 commands from the terminal until you tell it to exit.
685 You can also run 'gdb' with a variety of arguments and options, to
686 specify more of your debugging environment at the outset.
688 The command-line options described here are designed to cover a
689 variety of situations; in some environments, some of these options may
690 effectively be unavailable.
692 The most usual way to start GDB is with one argument, specifying an
697 You can also start with both an executable program and a core file
702 You can, instead, specify a process ID as a second argument, if you
703 want to debug a running process:
707 would attach GDB to process '1234' (unless you also have a file named
708 '1234'; GDB does check for a core file first).
710 Taking advantage of the second command-line argument requires a
711 fairly complete operating system; when you use GDB as a remote debugger
712 attached to a bare board, there may not be any notion of "process", and
713 there is often no way to get a core dump. GDB will warn you if it is
714 unable to attach or to read core dumps.
716 You can optionally have 'gdb' pass any arguments after the executable
717 file to the inferior using '--args'. This option stops option
719 gdb --args gcc -O2 -c foo.c
720 This will cause 'gdb' to debug 'gcc', and to set 'gcc''s command-line
721 arguments (*note Arguments::) to '-O2 -c foo.c'.
723 You can run 'gdb' without printing the front material, which
724 describes GDB's non-warranty, by specifying '--silent' (or
729 You can further control how GDB starts up by using command-line options.
730 GDB itself can remind you of the options available.
736 to display all available options and briefly describe their use ('gdb
737 -h' is a shorter equivalent).
739 All options and command line arguments you give are processed in
740 sequential order. The order makes a difference when the '-x' option is
745 * File Options:: Choosing files
746 * Mode Options:: Choosing modes
747 * Startup:: What GDB does during startup
750 File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
755 When GDB starts, it reads any arguments other than options as specifying
756 an executable file and core file (or process ID). This is the same as if
757 the arguments were specified by the '-se' and '-c' (or '-p') options
758 respectively. (GDB reads the first argument that does not have an
759 associated option flag as equivalent to the '-se' option followed by
760 that argument; and the second argument that does not have an associated
761 option flag, if any, as equivalent to the '-c'/'-p' option followed by
762 that argument.) If the second argument begins with a decimal digit, GDB
763 will first attempt to attach to it as a process, and if that fails,
764 attempt to open it as a corefile. If you have a corefile whose name
765 begins with a digit, you can prevent GDB from treating it as a pid by
766 prefixing it with './', e.g. './12345'.
768 If GDB has not been configured to included core file support, such as
769 for most embedded targets, then it will complain about a second argument
772 Many options have both long and short forms; both are shown in the
773 following list. GDB also recognizes the long forms if you truncate
774 them, so long as enough of the option is present to be unambiguous. (If
775 you prefer, you can flag option arguments with '--' rather than '-',
776 though we illustrate the more usual convention.)
780 Read symbol table from file FILE.
784 Use file FILE as the executable file to execute when appropriate,
785 and for examining pure data in conjunction with a core dump.
788 Read symbol table from file FILE and use it as the executable file.
792 Use file FILE as a core dump to examine.
796 Connect to process ID NUMBER, as with the 'attach' command.
800 Execute commands from file FILE. The contents of this file is
801 evaluated exactly as the 'source' command would. *Note Command
802 files: Command Files.
804 '-eval-command COMMAND'
806 Execute a single GDB command.
808 This option may be used multiple times to call multiple commands.
809 It may also be interleaved with '-command' as required.
811 gdb -ex 'target sim' -ex 'load' \
812 -x setbreakpoints -ex 'run' a.out
816 Execute commands from file FILE before loading the inferior (but
817 after loading gdbinit files). *Note Startup::.
819 '-init-eval-command COMMAND'
821 Execute a single GDB command before loading the inferior (but after
822 loading gdbinit files). *Note Startup::.
824 '-directory DIRECTORY'
826 Add DIRECTORY to the path to search for source and script files.
830 Read each symbol file's entire symbol table immediately, rather
831 than the default, which is to read it incrementally as it is
832 needed. This makes startup slower, but makes future operations
836 File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB
841 You can run GDB in various alternative modes--for example, in batch mode
846 Do not execute commands found in any initialization file. There
847 are three init files, loaded in the following order:
850 This is the system-wide init file. Its location is specified
851 with the '--with-system-gdbinit' configure option (*note
852 System-wide configuration::). It is loaded first when GDB
853 starts, before command line options have been processed.
855 This is the init file in your home directory. It is loaded
856 next, after 'system.gdbinit', and before command options have
859 This is the init file in the current directory. It is loaded
860 last, after command line options other than '-x' and '-ex'
861 have been processed. Command line options '-x' and '-ex' are
862 processed last, after './.gdbinit' has been loaded.
864 For further documentation on startup processing, *Note Startup::.
865 For documentation on how to write command files, *Note Command
866 Files: Command Files.
869 Do not execute commands found in '~/.gdbinit', the init file in
870 your home directory. *Note Startup::.
875 "Quiet". Do not print the introductory and copyright messages.
876 These messages are also suppressed in batch mode.
879 Run in batch mode. Exit with status '0' after processing all the
880 command files specified with '-x' (and all commands from
881 initialization files, if not inhibited with '-n'). Exit with
882 nonzero status if an error occurs in executing the GDB commands in
883 the command files. Batch mode also disables pagination, sets
884 unlimited terminal width and height *note Screen Size::, and acts
885 as if 'set confirm off' were in effect (*note Messages/Warnings::).
887 Batch mode may be useful for running GDB as a filter, for example
888 to download and run a program on another computer; in order to make
889 this more useful, the message
891 Program exited normally.
893 (which is ordinarily issued whenever a program running under GDB
894 control terminates) is not issued when running in batch mode.
897 Run in batch mode exactly like '-batch', but totally silently. All
898 GDB output to 'stdout' is prevented ('stderr' is unaffected). This
899 is much quieter than '-silent' and would be useless for an
902 This is particularly useful when using targets that give 'Loading
903 section' messages, for example.
905 Note that targets that give their output via GDB, as opposed to
906 writing directly to 'stdout', will also be made silent.
908 '-return-child-result'
909 The return code from GDB will be the return code from the child
910 process (the process being debugged), with the following
913 * GDB exits abnormally. E.g., due to an incorrect argument or
914 an internal error. In this case the exit code is the same as
915 it would have been without '-return-child-result'.
916 * The user quits with an explicit value. E.g., 'quit 1'.
917 * The child process never runs, or is not allowed to terminate,
918 in which case the exit code will be -1.
920 This option is useful in conjunction with '-batch' or
921 '-batch-silent', when GDB is being used as a remote program loader
922 or simulator interface.
926 "No windows". If GDB comes with a graphical user interface (GUI)
927 built in, then this option tells GDB to only use the command-line
928 interface. If no GUI is available, this option has no effect.
932 If GDB includes a GUI, then this option requires it to be used if
936 Run GDB using DIRECTORY as its working directory, instead of the
939 '-data-directory DIRECTORY'
941 Run GDB using DIRECTORY as its data directory. The data directory
942 is where GDB searches for its auxiliary files. *Note Data Files::.
946 GNU Emacs sets this option when it runs GDB as a subprocess. It
947 tells GDB to output the full file name and line number in a
948 standard, recognizable fashion each time a stack frame is displayed
949 (which includes each time your program stops). This recognizable
950 format looks like two '\032' characters, followed by the file name,
951 line number and character position separated by colons, and a
952 newline. The Emacs-to-GDB interface program uses the two '\032'
953 characters as a signal to display the source code for the frame.
956 This option sets the "annotation level" inside GDB. Its effect is
957 identical to using 'set annotate LEVEL' (*note Annotations::). The
958 annotation LEVEL controls how much information GDB prints together
959 with its prompt, values of expressions, source lines, and other
960 types of output. Level 0 is the normal, level 1 is for use when
961 GDB is run as a subprocess of GNU Emacs, level 3 is the maximum
962 annotation suitable for programs that control GDB, and level 2 has
965 The annotation mechanism has largely been superseded by GDB/MI
969 Change interpretation of command line so that arguments following
970 the executable file are passed as command line arguments to the
971 inferior. This option stops option processing.
975 Set the line speed (baud rate or bits per second) of any serial
976 interface used by GDB for remote debugging.
979 Set the timeout (in seconds) of any communication used by GDB for
984 Run using DEVICE for your program's standard input and output.
987 Activate the "Text User Interface" when starting. The Text User
988 Interface manages several text windows on the terminal, showing
989 source, assembly, registers and GDB command outputs (*note GDB Text
990 User Interface: TUI.). Do not use this option if you run GDB from
991 Emacs (*note Using GDB under GNU Emacs: Emacs.).
993 '-interpreter INTERP'
994 Use the interpreter INTERP for interface with the controlling
995 program or device. This option is meant to be set by programs
996 which communicate with GDB using it as a back end. *Note Command
997 Interpreters: Interpreters.
999 '--interpreter=mi' (or '--interpreter=mi2') causes GDB to use the
1000 "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included
1001 since GDB version 6.0. The previous GDB/MI interface, included in
1002 GDB version 5.3 and selected with '--interpreter=mi1', is
1003 deprecated. Earlier GDB/MI interfaces are no longer supported.
1006 Open the executable and core files for both reading and writing.
1007 This is equivalent to the 'set write on' command inside GDB (*note
1011 This option causes GDB to print statistics about time and memory
1012 usage after it completes each command and returns to the prompt.
1015 This option causes GDB to print its version number and no-warranty
1019 This option causes GDB to print details about its build-time
1020 configuration parameters, and then exit. These details can be
1021 important when reporting GDB bugs (*note GDB Bugs::).
1024 File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB
1026 2.1.3 What GDB Does During Startup
1027 ----------------------------------
1029 Here's the description of what GDB does during session startup:
1031 1. Sets up the command interpreter as specified by the command line
1032 (*note interpreter: Mode Options.).
1034 2. Reads the system-wide "init file" (if '--with-system-gdbinit' was
1035 used when building GDB; *note System-wide configuration and
1036 settings: System-wide configuration.) and executes all the commands
1039 3. Reads the init file (if any) in your home directory(1) and executes
1040 all the commands in that file.
1042 4. Executes commands and command files specified by the '-iex' and
1043 '-ix' options in their specified order. Usually you should use the
1044 '-ex' and '-x' options instead, but this way you can apply settings
1045 before GDB init files get executed and before inferior gets loaded.
1047 5. Processes command line options and operands.
1049 6. Reads and executes the commands from init file (if any) in the
1050 current working directory as long as 'set auto-load local-gdbinit'
1051 is set to 'on' (*note Init File in the Current Directory::). This
1052 is only done if the current directory is different from your home
1053 directory. Thus, you can have more than one init file, one generic
1054 in your home directory, and another, specific to the program you
1055 are debugging, in the directory where you invoke GDB.
1057 7. If the command line specified a program to debug, or a process to
1058 attach to, or a core file, GDB loads any auto-loaded scripts
1059 provided for the program or for its loaded shared libraries. *Note
1062 If you wish to disable the auto-loading during startup, you must do
1063 something like the following:
1065 $ gdb -iex "set auto-load python-scripts off" myprogram
1067 Option '-ex' does not work because the auto-loading is then turned
1070 8. Executes commands and command files specified by the '-ex' and '-x'
1071 options in their specified order. *Note Command Files::, for more
1072 details about GDB command files.
1074 9. Reads the command history recorded in the "history file". *Note
1075 Command History::, for more details about the command history and
1076 the files where GDB records it.
1078 Init files use the same syntax as "command files" (*note Command
1079 Files::) and are processed by GDB in the same way. The init file in
1080 your home directory can set options (such as 'set complaints') that
1081 affect subsequent processing of command line options and operands. Init
1082 files are not executed if you use the '-nx' option (*note Choosing
1083 Modes: Mode Options.).
1085 To display the list of init files loaded by gdb at startup, you can
1088 The GDB init files are normally called '.gdbinit'. The DJGPP port of
1089 GDB uses the name 'gdb.ini', due to the limitations of file names
1090 imposed by DOS filesystems. The Windows port of GDB uses the standard
1091 name, but if it finds a 'gdb.ini' file in your home directory, it warns
1092 you about that and suggests to rename the file to the standard name.
1094 ---------- Footnotes ----------
1096 (1) On DOS/Windows systems, the home directory is the one pointed to
1097 by the 'HOME' environment variable.
1100 File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation
1107 To exit GDB, use the 'quit' command (abbreviated 'q'), or type an
1108 end-of-file character (usually 'Ctrl-d'). If you do not supply
1109 EXPRESSION, GDB will terminate normally; otherwise it will
1110 terminate using the result of EXPRESSION as the error code.
1112 An interrupt (often 'Ctrl-c') does not exit from GDB, but rather
1113 terminates the action of any GDB command that is in progress and returns
1114 to GDB command level. It is safe to type the interrupt character at any
1115 time because GDB does not allow it to take effect until a time when it
1118 If you have been using GDB to control an attached process or device,
1119 you can release it with the 'detach' command (*note Debugging an
1120 Already-running Process: Attach.).
1123 File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation
1128 If you need to execute occasional shell commands during your debugging
1129 session, there is no need to leave or suspend GDB; you can just use the
1132 'shell COMMAND-STRING'
1134 Invoke a standard shell to execute COMMAND-STRING. Note that no
1135 space is needed between '!' and COMMAND-STRING. If it exists, the
1136 environment variable 'SHELL' determines which shell to run.
1137 Otherwise GDB uses the default shell ('/bin/sh' on Unix systems,
1138 'COMMAND.COM' on MS-DOS, etc.).
1140 The utility 'make' is often needed in development environments. You
1141 do not have to use the 'shell' command for this purpose in GDB:
1144 Execute the 'make' program with the specified arguments. This is
1145 equivalent to 'shell make MAKE-ARGS'.
1148 File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation
1153 You may want to save the output of GDB commands to a file. There are
1154 several commands to control GDB's logging.
1160 'set logging file FILE'
1161 Change the name of the current logfile. The default logfile is
1163 'set logging overwrite [on|off]'
1164 By default, GDB will append to the logfile. Set 'overwrite' if you
1165 want 'set logging on' to overwrite the logfile instead.
1166 'set logging redirect [on|off]'
1167 By default, GDB output will go to both the terminal and the
1168 logfile. Set 'redirect' if you want output to go only to the log
1171 Show the current values of the logging settings.
1174 File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
1179 You can abbreviate a GDB command to the first few letters of the command
1180 name, if that abbreviation is unambiguous; and you can repeat certain
1181 GDB commands by typing just <RET>. You can also use the <TAB> key to
1182 get GDB to fill out the rest of a word in a command (or to show you the
1183 alternatives available, if there is more than one possibility).
1187 * Command Syntax:: How to give commands to GDB
1188 * Completion:: Command completion
1189 * Help:: How to ask GDB for help
1192 File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands
1197 A GDB command is a single line of input. There is no limit on how long
1198 it can be. It starts with a command name, which is followed by
1199 arguments whose meaning depends on the command name. For example, the
1200 command 'step' accepts an argument which is the number of times to step,
1201 as in 'step 5'. You can also use the 'step' command with no arguments.
1202 Some commands do not allow any arguments.
1204 GDB command names may always be truncated if that abbreviation is
1205 unambiguous. Other possible command abbreviations are listed in the
1206 documentation for individual commands. In some cases, even ambiguous
1207 abbreviations are allowed; for example, 's' is specially defined as
1208 equivalent to 'step' even though there are other commands whose names
1209 start with 's'. You can test abbreviations by using them as arguments
1210 to the 'help' command.
1212 A blank line as input to GDB (typing just <RET>) means to repeat the
1213 previous command. Certain commands (for example, 'run') will not repeat
1214 this way; these are commands whose unintentional repetition might cause
1215 trouble and which you are unlikely to want to repeat. User-defined
1216 commands can disable this feature; see *note dont-repeat: Define.
1218 The 'list' and 'x' commands, when you repeat them with <RET>,
1219 construct new arguments rather than repeating exactly as typed. This
1220 permits easy scanning of source or memory.
1222 GDB can also use <RET> in another way: to partition lengthy output,
1223 in a way similar to the common utility 'more' (*note Screen Size: Screen
1224 Size.). Since it is easy to press one <RET> too many in this situation,
1225 GDB disables command repetition after any command that generates this
1228 Any text from a '#' to the end of the line is a comment; it does
1229 nothing. This is useful mainly in command files (*note Command Files:
1232 The 'Ctrl-o' binding is useful for repeating a complex sequence of
1233 commands. This command accepts the current line, like <RET>, and then
1234 fetches the next line relative to the current line from the history for
1238 File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
1240 3.2 Command Completion
1241 ======================
1243 GDB can fill in the rest of a word in a command for you, if there is
1244 only one possibility; it can also show you what the valid possibilities
1245 are for the next word in a command, at any time. This works for GDB
1246 commands, GDB subcommands, and the names of symbols in your program.
1248 Press the <TAB> key whenever you want GDB to fill out the rest of a
1249 word. If there is only one possibility, GDB fills in the word, and
1250 waits for you to finish the command (or press <RET> to enter it). For
1251 example, if you type
1253 (gdb) info bre <TAB>
1255 GDB fills in the rest of the word 'breakpoints', since that is the only
1256 'info' subcommand beginning with 'bre':
1258 (gdb) info breakpoints
1260 You can either press <RET> at this point, to run the 'info breakpoints'
1261 command, or backspace and enter something else, if 'breakpoints' does
1262 not look like the command you expected. (If you were sure you wanted
1263 'info breakpoints' in the first place, you might as well just type <RET>
1264 immediately after 'info bre', to exploit command abbreviations rather
1265 than command completion).
1267 If there is more than one possibility for the next word when you
1268 press <TAB>, GDB sounds a bell. You can either supply more characters
1269 and try again, or just press <TAB> a second time; GDB displays all the
1270 possible completions for that word. For example, you might want to set
1271 a breakpoint on a subroutine whose name begins with 'make_', but when
1272 you type 'b make_<TAB>' GDB just sounds the bell. Typing <TAB> again
1273 displays all the function names in your program that begin with those
1274 characters, for example:
1277 GDB sounds bell; press <TAB> again, to see:
1278 make_a_section_from_file make_environ
1279 make_abs_section make_function_type
1280 make_blockvector make_pointer_type
1281 make_cleanup make_reference_type
1282 make_command make_symbol_completion_list
1285 After displaying the available possibilities, GDB copies your partial
1286 input ('b make_' in the example) so you can finish the command.
1288 If you just want to see the list of alternatives in the first place,
1289 you can press 'M-?' rather than pressing <TAB> twice. 'M-?' means
1290 '<META> ?'. You can type this either by holding down a key designated
1291 as the <META> shift on your keyboard (if there is one) while typing '?',
1292 or as <ESC> followed by '?'.
1294 Sometimes the string you need, while logically a "word", may contain
1295 parentheses or other characters that GDB normally excludes from its
1296 notion of a word. To permit word completion to work in this situation,
1297 you may enclose words in ''' (single quote marks) in GDB commands.
1299 The most likely situation where you might need this is in typing the
1300 name of a C++ function. This is because C++ allows function overloading
1301 (multiple definitions of the same function, distinguished by argument
1302 type). For example, when you want to set a breakpoint you may need to
1303 distinguish whether you mean the version of 'name' that takes an 'int'
1304 parameter, 'name(int)', or the version that takes a 'float' parameter,
1305 'name(float)'. To use the word-completion facilities in this situation,
1306 type a single quote ''' at the beginning of the function name. This
1307 alerts GDB that it may need to consider more information than usual when
1308 you press <TAB> or 'M-?' to request word completion:
1310 (gdb) b 'bubble( M-?
1311 bubble(double,double) bubble(int,int)
1314 In some cases, GDB can tell that completing a name requires using
1315 quotes. When this happens, GDB inserts the quote for you (while
1316 completing as much as it can) if you do not type the quote in the first
1320 GDB alters your input line to the following, and rings a bell:
1323 In general, GDB can tell that a quote is needed (and inserts it) if you
1324 have not yet started typing the argument list when you ask for
1325 completion on an overloaded symbol.
1327 For more information about overloaded functions, see *note C++
1328 Expressions: C Plus Plus Expressions. You can use the command 'set
1329 overload-resolution off' to disable overload resolution; see *note GDB
1330 Features for C++: Debugging C Plus Plus.
1332 When completing in an expression which looks up a field in a
1333 structure, GDB also tries(1) to limit completions to the field names
1334 available in the type of the left-hand-side:
1336 (gdb) p gdb_stdout.M-?
1337 magic to_fputs to_rewind
1338 to_data to_isatty to_write
1339 to_delete to_put to_write_async_safe
1342 This is because the 'gdb_stdout' is a variable of the type 'struct
1343 ui_file' that is defined in GDB sources as follows:
1348 ui_file_flush_ftype *to_flush;
1349 ui_file_write_ftype *to_write;
1350 ui_file_write_async_safe_ftype *to_write_async_safe;
1351 ui_file_fputs_ftype *to_fputs;
1352 ui_file_read_ftype *to_read;
1353 ui_file_delete_ftype *to_delete;
1354 ui_file_isatty_ftype *to_isatty;
1355 ui_file_rewind_ftype *to_rewind;
1356 ui_file_put_ftype *to_put;
1360 ---------- Footnotes ----------
1362 (1) The completer can be confused by certain kinds of invalid
1363 expressions. Also, it only examines the static type of the expression,
1364 not the dynamic type.
1367 File: gdb.info, Node: Help, Prev: Completion, Up: Commands
1372 You can always ask GDB itself for information on its commands, using the
1377 You can use 'help' (abbreviated 'h') with no arguments to display a
1378 short list of named classes of commands:
1381 List of classes of commands:
1383 aliases -- Aliases of other commands
1384 breakpoints -- Making program stop at certain points
1385 data -- Examining data
1386 files -- Specifying and examining files
1387 internals -- Maintenance commands
1388 obscure -- Obscure features
1389 running -- Running the program
1390 stack -- Examining the stack
1391 status -- Status inquiries
1392 support -- Support facilities
1393 tracepoints -- Tracing of program execution without
1394 stopping the program
1395 user-defined -- User-defined commands
1397 Type "help" followed by a class name for a list of
1398 commands in that class.
1399 Type "help" followed by command name for full
1401 Command name abbreviations are allowed if unambiguous.
1405 Using one of the general help classes as an argument, you can get a
1406 list of the individual commands in that class. For example, here
1407 is the help display for the class 'status':
1414 info -- Generic command for showing things
1415 about the program being debugged
1416 show -- Generic command for showing things
1419 Type "help" followed by command name for full
1421 Command name abbreviations are allowed if unambiguous.
1425 With a command name as 'help' argument, GDB displays a short
1426 paragraph on how to use that command.
1429 The 'apropos' command searches through all of the GDB commands, and
1430 their documentation, for the regular expression specified in ARGS.
1431 It prints out all matches found. For example:
1437 alias -- Define a new command that is an alias of an existing command
1438 aliases -- Aliases of other commands
1439 d -- Delete some breakpoints or auto-display expressions
1440 del -- Delete some breakpoints or auto-display expressions
1441 delete -- Delete some breakpoints or auto-display expressions
1444 The 'complete ARGS' command lists all the possible completions for
1445 the beginning of a command. Use ARGS to specify the beginning of
1446 the command you want completed. For example:
1457 This is intended for use by GNU Emacs.
1459 In addition to 'help', you can use the GDB commands 'info' and 'show'
1460 to inquire about the state of your program, or the state of GDB itself.
1461 Each command supports many topics of inquiry; this manual introduces
1462 each of them in the appropriate context. The listings under 'info' and
1463 under 'show' in the Command, Variable, and Function Index point to all
1464 the sub-commands. *Note Command and Variable Index::.
1467 This command (abbreviated 'i') is for describing the state of your
1468 program. For example, you can show the arguments passed to a
1469 function with 'info args', list the registers currently in use with
1470 'info registers', or list the breakpoints you have set with 'info
1471 breakpoints'. You can get a complete list of the 'info'
1472 sub-commands with 'help info'.
1475 You can assign the result of an expression to an environment
1476 variable with 'set'. For example, you can set the GDB prompt to a
1477 $-sign with 'set prompt $'.
1480 In contrast to 'info', 'show' is for describing the state of GDB
1481 itself. You can change most of the things you can 'show', by using
1482 the related command 'set'; for example, you can control what number
1483 system is used for displays with 'set radix', or simply inquire
1484 which is currently in use with 'show radix'.
1486 To display all the settable parameters and their current values,
1487 you can use 'show' with no arguments; you may also use 'info set'.
1488 Both commands produce the same display.
1490 Here are several miscellaneous 'show' subcommands, all of which are
1491 exceptional in lacking corresponding 'set' commands:
1494 Show what version of GDB is running. You should include this
1495 information in GDB bug-reports. If multiple versions of GDB are in
1496 use at your site, you may need to determine which version of GDB
1497 you are running; as GDB evolves, new commands are introduced, and
1498 old ones may wither away. Also, many system vendors ship variant
1499 versions of GDB, and there are variant versions of GDB in GNU/Linux
1500 distributions as well. The version number is the same as the one
1501 announced when you start GDB.
1505 Display information about permission for copying GDB.
1509 Display the GNU "NO WARRANTY" statement, or a warranty, if your
1510 version of GDB comes with one.
1512 'show configuration'
1513 Display detailed information about the way GDB was configured when
1514 it was built. This displays the optional arguments passed to the
1515 'configure' script and also configuration parameters detected
1516 automatically by 'configure'. When reporting a GDB bug (*note GDB
1517 Bugs::), it is important to include this information in your
1521 File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top
1523 4 Running Programs Under GDB
1524 ****************************
1526 When you run a program under GDB, you must first generate debugging
1527 information when you compile it.
1529 You may start GDB with its arguments, if any, in an environment of
1530 your choice. If you are doing native debugging, you may redirect your
1531 program's input and output, debug an already running process, or kill a
1536 * Compilation:: Compiling for debugging
1537 * Starting:: Starting your program
1538 * Arguments:: Your program's arguments
1539 * Environment:: Your program's environment
1541 * Working Directory:: Your program's working directory
1542 * Input/Output:: Your program's input and output
1543 * Attach:: Debugging an already-running process
1544 * Kill Process:: Killing the child process
1546 * Inferiors and Programs:: Debugging multiple inferiors and programs
1547 * Threads:: Debugging programs with multiple threads
1548 * Forks:: Debugging forks
1549 * Checkpoint/Restart:: Setting a _bookmark_ to return to later
1552 File: gdb.info, Node: Compilation, Next: Starting, Up: Running
1554 4.1 Compiling for Debugging
1555 ===========================
1557 In order to debug a program effectively, you need to generate debugging
1558 information when you compile it. This debugging information is stored
1559 in the object file; it describes the data type of each variable or
1560 function and the correspondence between source line numbers and
1561 addresses in the executable code.
1563 To request debugging information, specify the '-g' option when you
1566 Programs that are to be shipped to your customers are compiled with
1567 optimizations, using the '-O' compiler option. However, some compilers
1568 are unable to handle the '-g' and '-O' options together. Using those
1569 compilers, you cannot generate optimized executables containing
1570 debugging information.
1572 GCC, the GNU C/C++ compiler, supports '-g' with or without '-O',
1573 making it possible to debug optimized code. We recommend that you
1574 _always_ use '-g' whenever you compile a program. You may think your
1575 program is correct, but there is no sense in pushing your luck. For
1576 more information, see *note Optimized Code::.
1578 Older versions of the GNU C compiler permitted a variant option '-gg'
1579 for debugging information. GDB no longer supports this format; if your
1580 GNU C compiler has this option, do not use it.
1582 GDB knows about preprocessor macros and can show you their expansion
1583 (*note Macros::). Most compilers do not include information about
1584 preprocessor macros in the debugging information if you specify the '-g'
1585 flag alone. Version 3.1 and later of GCC, the GNU C compiler, provides
1586 macro information if you are using the DWARF debugging format, and
1587 specify the option '-g3'.
1589 *Note Options for Debugging Your Program or GCC: (gcc.info)Debugging
1590 Options, for more information on GCC options affecting debug
1593 You will have the best debugging experience if you use the latest
1594 version of the DWARF debugging format that your compiler supports.
1595 DWARF is currently the most expressive and best supported debugging
1599 File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
1601 4.2 Starting your Program
1602 =========================
1606 Use the 'run' command to start your program under GDB. You must
1607 first specify the program name (except on VxWorks) with an argument
1608 to GDB (*note Getting In and Out of GDB: Invocation.), or by using
1609 the 'file' or 'exec-file' command (*note Commands to Specify Files:
1612 If you are running your program in an execution environment that
1613 supports processes, 'run' creates an inferior process and makes that
1614 process run your program. In some environments without processes, 'run'
1615 jumps to the start of your program. Other targets, like 'remote', are
1616 always running. If you get an error message like this one:
1618 The "remote" target does not support "run".
1619 Try "help target" or "continue".
1621 then use 'continue' to run your program. You may need 'load' first
1624 The execution of a program is affected by certain information it
1625 receives from its superior. GDB provides ways to specify this
1626 information, which you must do _before_ starting your program. (You can
1627 change it after starting your program, but such changes only affect your
1628 program the next time you start it.) This information may be divided
1629 into four categories:
1632 Specify the arguments to give your program as the arguments of the
1633 'run' command. If a shell is available on your target, the shell
1634 is used to pass the arguments, so that you may use normal
1635 conventions (such as wildcard expansion or variable substitution)
1636 in describing the arguments. In Unix systems, you can control
1637 which shell is used with the 'SHELL' environment variable. If you
1638 do not define 'SHELL', GDB uses the default shell ('/bin/sh'). You
1639 can disable use of any shell with the 'set startup-with-shell'
1640 command (see below for details).
1643 Your program normally inherits its environment from GDB, but you
1644 can use the GDB commands 'set environment' and 'unset environment'
1645 to change parts of the environment that affect your program. *Note
1646 Your Program's Environment: Environment.
1648 The _working directory._
1649 Your program inherits its working directory from GDB. You can set
1650 the GDB working directory with the 'cd' command in GDB. *Note Your
1651 Program's Working Directory: Working Directory.
1653 The _standard input and output._
1654 Your program normally uses the same device for standard input and
1655 standard output as GDB is using. You can redirect input and output
1656 in the 'run' command line, or you can use the 'tty' command to set
1657 a different device for your program. *Note Your Program's Input
1658 and Output: Input/Output.
1660 _Warning:_ While input and output redirection work, you cannot use
1661 pipes to pass the output of the program you are debugging to
1662 another program; if you attempt this, GDB is likely to wind up
1663 debugging the wrong program.
1665 When you issue the 'run' command, your program begins to execute
1666 immediately. *Note Stopping and Continuing: Stopping, for discussion of
1667 how to arrange for your program to stop. Once your program has stopped,
1668 you may call functions in your program, using the 'print' or 'call'
1669 commands. *Note Examining Data: Data.
1671 If the modification time of your symbol file has changed since the
1672 last time GDB read its symbols, GDB discards its symbol table, and reads
1673 it again. When it does this, GDB tries to retain your current
1677 The name of the main procedure can vary from language to language.
1678 With C or C++, the main procedure name is always 'main', but other
1679 languages such as Ada do not require a specific name for their main
1680 procedure. The debugger provides a convenient way to start the
1681 execution of the program and to stop at the beginning of the main
1682 procedure, depending on the language used.
1684 The 'start' command does the equivalent of setting a temporary
1685 breakpoint at the beginning of the main procedure and then invoking
1688 Some programs contain an "elaboration" phase where some startup
1689 code is executed before the main procedure is called. This depends
1690 on the languages used to write your program. In C++, for instance,
1691 constructors for static and global objects are executed before
1692 'main' is called. It is therefore possible that the debugger stops
1693 before reaching the main procedure. However, the temporary
1694 breakpoint will remain to halt execution.
1696 Specify the arguments to give to your program as arguments to the
1697 'start' command. These arguments will be given verbatim to the
1698 underlying 'run' command. Note that the same arguments will be
1699 reused if no argument is provided during subsequent calls to
1702 It is sometimes necessary to debug the program during elaboration.
1703 In these cases, using the 'start' command would stop the execution
1704 of your program too late, as the program would have already
1705 completed the elaboration phase. Under these circumstances, insert
1706 breakpoints in your elaboration code before running your program.
1708 'set exec-wrapper WRAPPER'
1710 'unset exec-wrapper'
1711 When 'exec-wrapper' is set, the specified wrapper is used to launch
1712 programs for debugging. GDB starts your program with a shell
1713 command of the form 'exec WRAPPER PROGRAM'. Quoting is added to
1714 PROGRAM and its arguments, but not to WRAPPER, so you should add
1715 quotes if appropriate for your shell. The wrapper runs until it
1716 executes your program, and then GDB takes control.
1718 You can use any program that eventually calls 'execve' with its
1719 arguments as a wrapper. Several standard Unix utilities do this,
1720 e.g. 'env' and 'nohup'. Any Unix shell script ending with 'exec
1721 "$@"' will also work.
1723 For example, you can use 'env' to pass an environment variable to
1724 the debugged program, without setting the variable in your shell's
1727 (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
1730 This command is available when debugging locally on most targets,
1731 excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.
1733 'set startup-with-shell'
1734 'set startup-with-shell on'
1735 'set startup-with-shell off'
1736 'show set startup-with-shell'
1737 On Unix systems, by default, if a shell is available on your
1738 target, GDB) uses it to start your program. Arguments of the 'run'
1739 command are passed to the shell, which does variable substitution,
1740 expands wildcard characters and performs redirection of I/O. In
1741 some circumstances, it may be useful to disable such use of a
1742 shell, for example, when debugging the shell itself or diagnosing
1743 startup failures such as:
1746 Starting program: ./a.out
1747 During startup program terminated with signal SIGSEGV, Segmentation fault.
1749 which indicates the shell or the wrapper specified with
1750 'exec-wrapper' crashed, not your program. Most often, this is
1751 caused by something odd in your shell's non-interactive mode
1752 initialization file--such as '.cshrc' for C-shell, $'.zshenv' for
1753 the Z shell, or the file specified in the 'BASH_ENV' environment
1756 'set auto-connect-native-target'
1757 'set auto-connect-native-target on'
1758 'set auto-connect-native-target off'
1759 'show auto-connect-native-target'
1761 By default, if not connected to any target yet (e.g., with 'target
1762 remote'), the 'run' command starts your program as a native process
1763 under GDB, on your local machine. If you're sure you don't want to
1764 debug programs on your local machine, you can tell GDB to not
1765 connect to the native target automatically with the 'set
1766 auto-connect-native-target off' command.
1768 If 'on', which is the default, and if GDB is not connected to a
1769 target already, the 'run' command automaticaly connects to the
1770 native target, if one is available.
1772 If 'off', and if GDB is not connected to a target already, the
1773 'run' command fails with an error:
1776 Don't know how to run. Try "help target".
1778 If GDB is already connected to a target, GDB always uses it with
1781 In any case, you can explicitly connect to the native target with
1782 the 'target native' command. For example,
1784 (gdb) set auto-connect-native-target off
1786 Don't know how to run. Try "help target".
1789 Starting program: ./a.out
1790 [Inferior 1 (process 10421) exited normally]
1792 In case you connected explicitly to the 'native' target, GDB
1793 remains connected even if all inferiors exit, ready for the next
1794 'run' command. Use the 'disconnect' command to disconnect.
1796 Examples of other commands that likewise respect the
1797 'auto-connect-native-target' setting: 'attach', 'info proc', 'info
1800 'set disable-randomization'
1801 'set disable-randomization on'
1802 This option (enabled by default in GDB) will turn off the native
1803 randomization of the virtual address space of the started program.
1804 This option is useful for multiple debugging sessions to make the
1805 execution better reproducible and memory addresses reusable across
1808 This feature is implemented only on certain targets, including
1809 GNU/Linux. On GNU/Linux you can get the same behavior using
1811 (gdb) set exec-wrapper setarch `uname -m` -R
1813 'set disable-randomization off'
1814 Leave the behavior of the started executable unchanged. Some bugs
1815 rear their ugly heads only when the program is loaded at certain
1816 addresses. If your bug disappears when you run the program under
1817 GDB, that might be because GDB by default disables the address
1818 randomization on platforms, such as GNU/Linux, which do that for
1819 stand-alone programs. Use 'set disable-randomization off' to try
1820 to reproduce such elusive bugs.
1822 On targets where it is available, virtual address space
1823 randomization protects the programs against certain kinds of
1824 security attacks. In these cases the attacker needs to know the
1825 exact location of a concrete executable code. Randomizing its
1826 location makes it impossible to inject jumps misusing a code at its
1829 Prelinking shared libraries provides a startup performance
1830 advantage but it makes addresses in these libraries predictable for
1831 privileged processes by having just unprivileged access at the
1832 target system. Reading the shared library binary gives enough
1833 information for assembling the malicious code misusing it. Still
1834 even a prelinked shared library can get loaded at a new random
1835 address just requiring the regular relocation process during the
1836 startup. Shared libraries not already prelinked are always loaded
1837 at a randomly chosen address.
1839 Position independent executables (PIE) contain position independent
1840 code similar to the shared libraries and therefore such executables
1841 get loaded at a randomly chosen address upon startup. PIE
1842 executables always load even already prelinked shared libraries at
1843 a random address. You can build such executable using 'gcc -fPIE
1846 Heap (malloc storage), stack and custom mmap areas are always
1847 placed randomly (as long as the randomization is enabled).
1849 'show disable-randomization'
1850 Show the current setting of the explicit disable of the native
1851 randomization of the virtual address space of the started program.
1854 File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
1856 4.3 Your Program's Arguments
1857 ============================
1859 The arguments to your program can be specified by the arguments of the
1860 'run' command. They are passed to a shell, which expands wildcard
1861 characters and performs redirection of I/O, and thence to your program.
1862 Your 'SHELL' environment variable (if it exists) specifies what shell
1863 GDB uses. If you do not define 'SHELL', GDB uses the default shell
1864 ('/bin/sh' on Unix).
1866 On non-Unix systems, the program is usually invoked directly by GDB,
1867 which emulates I/O redirection via the appropriate system calls, and the
1868 wildcard characters are expanded by the startup code of the program, not
1871 'run' with no arguments uses the same arguments used by the previous
1872 'run', or those set by the 'set args' command.
1875 Specify the arguments to be used the next time your program is run.
1876 If 'set args' has no arguments, 'run' executes your program with no
1877 arguments. Once you have run your program with arguments, using
1878 'set args' before the next 'run' is the only way to run it again
1882 Show the arguments to give your program when it is started.
1885 File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running
1887 4.4 Your Program's Environment
1888 ==============================
1890 The "environment" consists of a set of environment variables and their
1891 values. Environment variables conventionally record such things as your
1892 user name, your home directory, your terminal type, and your search path
1893 for programs to run. Usually you set up environment variables with the
1894 shell and they are inherited by all the other programs you run. When
1895 debugging, it can be useful to try running your program with a modified
1896 environment without having to start GDB over again.
1899 Add DIRECTORY to the front of the 'PATH' environment variable (the
1900 search path for executables) that will be passed to your program.
1901 The value of 'PATH' used by GDB does not change. You may specify
1902 several directory names, separated by whitespace or by a
1903 system-dependent separator character (':' on Unix, ';' on MS-DOS
1904 and MS-Windows). If DIRECTORY is already in the path, it is moved
1905 to the front, so it is searched sooner.
1907 You can use the string '$cwd' to refer to whatever is the current
1908 working directory at the time GDB searches the path. If you use
1909 '.' instead, it refers to the directory where you executed the
1910 'path' command. GDB replaces '.' in the DIRECTORY argument (with
1911 the current path) before adding DIRECTORY to the search path.
1914 Display the list of search paths for executables (the 'PATH'
1915 environment variable).
1917 'show environment [VARNAME]'
1918 Print the value of environment variable VARNAME to be given to your
1919 program when it starts. If you do not supply VARNAME, print the
1920 names and values of all environment variables to be given to your
1921 program. You can abbreviate 'environment' as 'env'.
1923 'set environment VARNAME [=VALUE]'
1924 Set environment variable VARNAME to VALUE. The value changes for
1925 your program (and the shell GDB uses to launch it), not for GDB
1926 itself. The VALUE may be any string; the values of environment
1927 variables are just strings, and any interpretation is supplied by
1928 your program itself. The VALUE parameter is optional; if it is
1929 eliminated, the variable is set to a null value.
1931 For example, this command:
1935 tells the debugged program, when subsequently run, that its user is
1936 named 'foo'. (The spaces around '=' are used for clarity here;
1937 they are not actually required.)
1939 Note that on Unix systems, GDB runs your program via a shell, which
1940 also inherits the environment set with 'set environment'. If
1941 necessary, you can avoid that by using the 'env' program as a
1942 wrapper instead of using 'set environment'. *Note set
1943 exec-wrapper::, for an example doing just that.
1945 'unset environment VARNAME'
1946 Remove variable VARNAME from the environment to be passed to your
1947 program. This is different from 'set env VARNAME ='; 'unset
1948 environment' removes the variable from the environment, rather than
1949 assigning it an empty value.
1951 _Warning:_ On Unix systems, GDB runs your program using the shell
1952 indicated by your 'SHELL' environment variable if it exists (or
1953 '/bin/sh' if not). If your 'SHELL' variable names a shell that runs an
1954 initialization file when started non-interactively--such as '.cshrc' for
1955 C-shell, $'.zshenv' for the Z shell, or the file specified in the
1956 'BASH_ENV' environment variable for BASH--any variables you set in that
1957 file affect your program. You may wish to move setting of environment
1958 variables to files that are only run when you sign on, such as '.login'
1962 File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running
1964 4.5 Your Program's Working Directory
1965 ====================================
1967 Each time you start your program with 'run', it inherits its working
1968 directory from the current working directory of GDB. The GDB working
1969 directory is initially whatever it inherited from its parent process
1970 (typically the shell), but you can specify a new working directory in
1971 GDB with the 'cd' command.
1973 The GDB working directory also serves as a default for the commands
1974 that specify files for GDB to operate on. *Note Commands to Specify
1978 Set the GDB working directory to DIRECTORY. If not given,
1979 DIRECTORY uses ''~''.
1982 Print the GDB working directory.
1984 It is generally impossible to find the current working directory of
1985 the process being debugged (since a program can change its directory
1986 during its run). If you work on a system where GDB is configured with
1987 the '/proc' support, you can use the 'info proc' command (*note SVR4
1988 Process Information::) to find out the current working directory of the
1992 File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running
1994 4.6 Your Program's Input and Output
1995 ===================================
1997 By default, the program you run under GDB does input and output to the
1998 same terminal that GDB uses. GDB switches the terminal to its own
1999 terminal modes to interact with you, but it records the terminal modes
2000 your program was using and switches back to them when you continue
2001 running your program.
2004 Displays information recorded by GDB about the terminal modes your
2007 You can redirect your program's input and/or output using shell
2008 redirection with the 'run' command. For example,
2012 starts your program, diverting its output to the file 'outfile'.
2014 Another way to specify where your program should do input and output
2015 is with the 'tty' command. This command accepts a file name as
2016 argument, and causes this file to be the default for future 'run'
2017 commands. It also resets the controlling terminal for the child
2018 process, for future 'run' commands. For example,
2022 directs that processes started with subsequent 'run' commands default to
2023 do input and output on the terminal '/dev/ttyb' and have that as their
2024 controlling terminal.
2026 An explicit redirection in 'run' overrides the 'tty' command's effect
2027 on the input/output device, but not its effect on the controlling
2030 When you use the 'tty' command or redirect input in the 'run'
2031 command, only the input _for your program_ is affected. The input for
2032 GDB still comes from your terminal. 'tty' is an alias for 'set
2035 You can use the 'show inferior-tty' command to tell GDB to display
2036 the name of the terminal that will be used for future runs of your
2039 'set inferior-tty /dev/ttyb'
2040 Set the tty for the program being debugged to /dev/ttyb.
2043 Show the current tty for the program being debugged.
2046 File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running
2048 4.7 Debugging an Already-running Process
2049 ========================================
2052 This command attaches to a running process--one that was started
2053 outside GDB. ('info files' shows your active targets.) The
2054 command takes as argument a process ID. The usual way to find out
2055 the PROCESS-ID of a Unix process is with the 'ps' utility, or with
2056 the 'jobs -l' shell command.
2058 'attach' does not repeat if you press <RET> a second time after
2059 executing the command.
2061 To use 'attach', your program must be running in an environment which
2062 supports processes; for example, 'attach' does not work for programs on
2063 bare-board targets that lack an operating system. You must also have
2064 permission to send the process a signal.
2066 When you use 'attach', the debugger finds the program running in the
2067 process first by looking in the current working directory, then (if the
2068 program is not found) by using the source file search path (*note
2069 Specifying Source Directories: Source Path.). You can also use the
2070 'file' command to load the program. *Note Commands to Specify Files:
2073 The first thing GDB does after arranging to debug the specified
2074 process is to stop it. You can examine and modify an attached process
2075 with all the GDB commands that are ordinarily available when you start
2076 processes with 'run'. You can insert breakpoints; you can step and
2077 continue; you can modify storage. If you would rather the process
2078 continue running, you may use the 'continue' command after attaching GDB
2082 When you have finished debugging the attached process, you can use
2083 the 'detach' command to release it from GDB control. Detaching the
2084 process continues its execution. After the 'detach' command, that
2085 process and GDB become completely independent once more, and you
2086 are ready to 'attach' another process or start one with 'run'.
2087 'detach' does not repeat if you press <RET> again after executing
2090 If you exit GDB while you have an attached process, you detach that
2091 process. If you use the 'run' command, you kill that process. By
2092 default, GDB asks for confirmation if you try to do either of these
2093 things; you can control whether or not you need to confirm by using the
2094 'set confirm' command (*note Optional Warnings and Messages:
2095 Messages/Warnings.).
2098 File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running
2100 4.8 Killing the Child Process
2101 =============================
2104 Kill the child process in which your program is running under GDB.
2106 This command is useful if you wish to debug a core dump instead of a
2107 running process. GDB ignores any core dump file while your program is
2110 On some operating systems, a program cannot be executed outside GDB
2111 while you have breakpoints set on it inside GDB. You can use the 'kill'
2112 command in this situation to permit running your program outside the
2115 The 'kill' command is also useful if you wish to recompile and relink
2116 your program, since on many systems it is impossible to modify an
2117 executable file while it is running in a process. In this case, when
2118 you next type 'run', GDB notices that the file has changed, and reads
2119 the symbol table again (while trying to preserve your current breakpoint
2123 File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running
2125 4.9 Debugging Multiple Inferiors and Programs
2126 =============================================
2128 GDB lets you run and debug multiple programs in a single session. In
2129 addition, GDB on some systems may let you run several programs
2130 simultaneously (otherwise you have to exit from one before starting
2131 another). In the most general case, you can have multiple threads of
2132 execution in each of multiple processes, launched from multiple
2135 GDB represents the state of each program execution with an object
2136 called an "inferior". An inferior typically corresponds to a process,
2137 but is more general and applies also to targets that do not have
2138 processes. Inferiors may be created before a process runs, and may be
2139 retained after a process exits. Inferiors have unique identifiers that
2140 are different from process ids. Usually each inferior will also have
2141 its own distinct address space, although some embedded targets may have
2142 several inferiors running in different parts of a single address space.
2143 Each inferior may in turn have multiple threads running in it.
2145 To find out what inferiors exist at any moment, use 'info inferiors':
2148 Print a list of all inferiors currently being managed by GDB.
2150 GDB displays for each inferior (in this order):
2152 1. the inferior number assigned by GDB
2154 2. the target system's inferior identifier
2156 3. the name of the executable the inferior is running.
2158 An asterisk '*' preceding the GDB inferior number indicates the
2163 (gdb) info inferiors
2164 Num Description Executable
2165 2 process 2307 hello
2166 * 1 process 3401 goodbye
2168 To switch focus between inferiors, use the 'inferior' command:
2171 Make inferior number INFNO the current inferior. The argument
2172 INFNO is the inferior number assigned by GDB, as shown in the first
2173 field of the 'info inferiors' display.
2175 You can get multiple executables into a debugging session via the
2176 'add-inferior' and 'clone-inferior' commands. On some systems GDB can
2177 add inferiors to the debug session automatically by following calls to
2178 'fork' and 'exec'. To remove inferiors from the debugging session use
2179 the 'remove-inferiors' command.
2181 'add-inferior [ -copies N ] [ -exec EXECUTABLE ]'
2182 Adds N inferiors to be run using EXECUTABLE as the executable; N
2183 defaults to 1. If no executable is specified, the inferiors begins
2184 empty, with no program. You can still assign or change the program
2185 assigned to the inferior at any time by using the 'file' command
2186 with the executable name as its argument.
2188 'clone-inferior [ -copies N ] [ INFNO ]'
2189 Adds N inferiors ready to execute the same program as inferior
2190 INFNO; N defaults to 1, and INFNO defaults to the number of the
2191 current inferior. This is a convenient command when you want to
2192 run another instance of the inferior you are debugging.
2194 (gdb) info inferiors
2195 Num Description Executable
2196 * 1 process 29964 helloworld
2197 (gdb) clone-inferior
2200 (gdb) info inferiors
2201 Num Description Executable
2203 * 1 process 29964 helloworld
2205 You can now simply switch focus to inferior 2 and run it.
2207 'remove-inferiors INFNO...'
2208 Removes the inferior or inferiors INFNO.... It is not possible to
2209 remove an inferior that is running with this command. For those,
2210 use the 'kill' or 'detach' command first.
2212 To quit debugging one of the running inferiors that is not the
2213 current inferior, you can either detach from it by using the 'detach inferior'
2214 command (allowing it to run independently), or kill it using the 'kill inferiors'
2217 'detach inferior INFNO...'
2218 Detach from the inferior or inferiors identified by GDB inferior
2219 number(s) INFNO.... Note that the inferior's entry still stays on
2220 the list of inferiors shown by 'info inferiors', but its
2221 Description will show '<null>'.
2223 'kill inferiors INFNO...'
2224 Kill the inferior or inferiors identified by GDB inferior number(s)
2225 INFNO.... Note that the inferior's entry still stays on the list
2226 of inferiors shown by 'info inferiors', but its Description will
2229 After the successful completion of a command such as 'detach',
2230 'detach inferiors', 'kill' or 'kill inferiors', or after a normal
2231 process exit, the inferior is still valid and listed with 'info
2232 inferiors', ready to be restarted.
2234 To be notified when inferiors are started or exit under GDB's control
2235 use 'set print inferior-events':
2237 'set print inferior-events'
2238 'set print inferior-events on'
2239 'set print inferior-events off'
2240 The 'set print inferior-events' command allows you to enable or
2241 disable printing of messages when GDB notices that new inferiors
2242 have started or that inferiors have exited or have been detached.
2243 By default, these messages will not be printed.
2245 'show print inferior-events'
2246 Show whether messages will be printed when GDB detects that
2247 inferiors have started, exited or have been detached.
2249 Many commands will work the same with multiple programs as with a
2250 single program: e.g., 'print myglobal' will simply display the value of
2251 'myglobal' in the current inferior.
2253 Occasionaly, when debugging GDB itself, it may be useful to get more
2254 info about the relationship of inferiors, programs, address spaces in a
2255 debug session. You can do that with the 'maint info program-spaces'
2258 'maint info program-spaces'
2259 Print a list of all program spaces currently being managed by GDB.
2261 GDB displays for each program space (in this order):
2263 1. the program space number assigned by GDB
2265 2. the name of the executable loaded into the program space, with
2266 e.g., the 'file' command.
2268 An asterisk '*' preceding the GDB program space number indicates
2269 the current program space.
2271 In addition, below each program space line, GDB prints extra
2272 information that isn't suitable to display in tabular form. For
2273 example, the list of inferiors bound to the program space.
2275 (gdb) maint info program-spaces
2278 Bound inferiors: ID 1 (process 21561)
2281 Here we can see that no inferior is running the program 'hello',
2282 while 'process 21561' is running the program 'goodbye'. On some
2283 targets, it is possible that multiple inferiors are bound to the
2284 same program space. The most common example is that of debugging
2285 both the parent and child processes of a 'vfork' call. For
2288 (gdb) maint info program-spaces
2291 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
2293 Here, both inferior 2 and inferior 1 are running in the same
2294 program space as a result of inferior 1 having executed a 'vfork'
2298 File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running
2300 4.10 Debugging Programs with Multiple Threads
2301 =============================================
2303 In some operating systems, such as HP-UX and Solaris, a single program
2304 may have more than one "thread" of execution. The precise semantics of
2305 threads differ from one operating system to another, but in general the
2306 threads of a single program are akin to multiple processes--except that
2307 they share one address space (that is, they can all examine and modify
2308 the same variables). On the other hand, each thread has its own
2309 registers and execution stack, and perhaps private memory.
2311 GDB provides these facilities for debugging multi-thread programs:
2313 * automatic notification of new threads
2314 * 'thread THREADNO', a command to switch among threads
2315 * 'info threads', a command to inquire about existing threads
2316 * 'thread apply [THREADNO] [ALL] ARGS', a command to apply a command
2317 to a list of threads
2318 * thread-specific breakpoints
2319 * 'set print thread-events', which controls printing of messages on
2320 thread start and exit.
2321 * 'set libthread-db-search-path PATH', which lets the user specify
2322 which 'libthread_db' to use if the default choice isn't compatible
2325 _Warning:_ These facilities are not yet available on every GDB
2326 configuration where the operating system supports threads. If your
2327 GDB does not support threads, these commands have no effect. For
2328 example, a system without thread support shows no output from 'info
2329 threads', and always rejects the 'thread' command, like this:
2333 Thread ID 1 not known. Use the "info threads" command to
2334 see the IDs of currently known threads.
2336 The GDB thread debugging facility allows you to observe all threads
2337 while your program runs--but whenever GDB takes control, one thread in
2338 particular is always the focus of debugging. This thread is called the
2339 "current thread". Debugging commands show program information from the
2340 perspective of the current thread.
2342 Whenever GDB detects a new thread in your program, it displays the
2343 target system's identification for the thread with a message in the form
2344 '[New SYSTAG]', where SYSTAG is a thread identifier whose form varies
2345 depending on the particular system. For example, on GNU/Linux, you
2348 [New Thread 0x41e02940 (LWP 25582)]
2350 when GDB notices a new thread. In contrast, on an SGI system, the
2351 SYSTAG is simply something like 'process 368', with no further
2354 For debugging purposes, GDB associates its own thread number--always
2355 a single integer--with each thread in your program.
2357 'info threads [ID...]'
2358 Display a summary of all threads currently in your program.
2359 Optional argument ID... is one or more thread ids separated by
2360 spaces, and means to print information only about the specified
2361 thread or threads. GDB displays for each thread (in this order):
2363 1. the thread number assigned by GDB
2365 2. the target system's thread identifier (SYSTAG)
2367 3. the thread's name, if one is known. A thread can either be
2368 named by the user (see 'thread name', below), or, in some
2369 cases, by the program itself.
2371 4. the current stack frame summary for that thread
2373 An asterisk '*' to the left of the GDB thread number indicates the
2380 3 process 35 thread 27 0x34e5 in sigpause ()
2381 2 process 35 thread 23 0x34e5 in sigpause ()
2382 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2385 On Solaris, you can display more information about user threads with
2386 a Solaris-specific command:
2388 'maint info sol-threads'
2389 Display info on Solaris user threads.
2392 Make thread number THREADNO the current thread. The command
2393 argument THREADNO is the internal GDB thread number, as shown in
2394 the first field of the 'info threads' display. GDB responds by
2395 displaying the system identifier of the thread you selected, and
2396 its current stack frame summary:
2399 [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
2400 #0 some_function (ignore=0x0) at example.c:8
2401 8 printf ("hello\n");
2403 As with the '[New ...]' message, the form of the text after
2404 'Switching to' depends on your system's conventions for identifying
2407 The debugger convenience variable '$_thread' contains the number of
2408 the current thread. You may find this useful in writing breakpoint
2409 conditional expressions, command scripts, and so forth. See *Note
2410 Convenience Variables: Convenience Vars, for general information on
2411 convenience variables.
2413 'thread apply [THREADNO | all] COMMAND'
2414 The 'thread apply' command allows you to apply the named COMMAND to
2415 one or more threads. Specify the numbers of the threads that you
2416 want affected with the command argument THREADNO. It can be a
2417 single thread number, one of the numbers shown in the first field
2418 of the 'info threads' display; or it could be a range of thread
2419 numbers, as in '2-4'. To apply a command to all threads, type
2420 'thread apply all COMMAND'.
2422 'thread name [NAME]'
2423 This command assigns a name to the current thread. If no argument
2424 is given, any existing user-specified name is removed. The thread
2425 name appears in the 'info threads' display.
2427 On some systems, such as GNU/Linux, GDB is able to determine the
2428 name of the thread as given by the OS. On these systems, a name
2429 specified with 'thread name' will override the system-give name,
2430 and removing the user-specified name will cause GDB to once again
2431 display the system-specified name.
2433 'thread find [REGEXP]'
2434 Search for and display thread ids whose name or SYSTAG matches the
2435 supplied regular expression.
2437 As well as being the complement to the 'thread name' command, this
2438 command also allows you to identify a thread by its target SYSTAG.
2439 For instance, on GNU/Linux, the target SYSTAG is the LWP id.
2441 (GDB) thread find 26688
2442 Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
2445 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
2447 'set print thread-events'
2448 'set print thread-events on'
2449 'set print thread-events off'
2450 The 'set print thread-events' command allows you to enable or
2451 disable printing of messages when GDB notices that new threads have
2452 started or that threads have exited. By default, these messages
2453 will be printed if detection of these events is supported by the
2454 target. Note that these messages cannot be disabled on all
2457 'show print thread-events'
2458 Show whether messages will be printed when GDB detects that threads
2459 have started and exited.
2461 *Note Stopping and Starting Multi-thread Programs: Thread Stops, for
2462 more information about how GDB behaves when you stop and start programs
2463 with multiple threads.
2465 *Note Setting Watchpoints: Set Watchpoints, for information about
2466 watchpoints in programs with multiple threads.
2468 'set libthread-db-search-path [PATH]'
2469 If this variable is set, PATH is a colon-separated list of
2470 directories GDB will use to search for 'libthread_db'. If you omit
2471 PATH, 'libthread-db-search-path' will be reset to its default value
2472 ('$sdir:$pdir' on GNU/Linux and Solaris systems). Internally, the
2473 default value comes from the 'LIBTHREAD_DB_SEARCH_PATH' macro.
2475 On GNU/Linux and Solaris systems, GDB uses a "helper"
2476 'libthread_db' library to obtain information about threads in the
2477 inferior process. GDB will use 'libthread-db-search-path' to find
2478 'libthread_db'. GDB also consults first if inferior specific
2479 thread debugging library loading is enabled by 'set auto-load
2480 libthread-db' (*note libthread_db.so.1 file::).
2482 A special entry '$sdir' for 'libthread-db-search-path' refers to
2483 the default system directories that are normally searched for
2484 loading shared libraries. The '$sdir' entry is the only kind not
2485 needing to be enabled by 'set auto-load libthread-db' (*note
2486 libthread_db.so.1 file::).
2488 A special entry '$pdir' for 'libthread-db-search-path' refers to
2489 the directory from which 'libpthread' was loaded in the inferior
2492 For any 'libthread_db' library GDB finds in above directories, GDB
2493 attempts to initialize it with the current inferior process. If
2494 this initialization fails (which could happen because of a version
2495 mismatch between 'libthread_db' and 'libpthread'), GDB will unload
2496 'libthread_db', and continue with the next directory. If none of
2497 'libthread_db' libraries initialize successfully, GDB will issue a
2498 warning and thread debugging will be disabled.
2500 Setting 'libthread-db-search-path' is currently implemented only on
2503 'show libthread-db-search-path'
2504 Display current libthread_db search path.
2506 'set debug libthread-db'
2507 'show debug libthread-db'
2508 Turns on or off display of 'libthread_db'-related events. Use '1'
2509 to enable, '0' to disable.
2512 File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running
2514 4.11 Debugging Forks
2515 ====================
2517 On most systems, GDB has no special support for debugging programs which
2518 create additional processes using the 'fork' function. When a program
2519 forks, GDB will continue to debug the parent process and the child
2520 process will run unimpeded. If you have set a breakpoint in any code
2521 which the child then executes, the child will get a 'SIGTRAP' signal
2522 which (unless it catches the signal) will cause it to terminate.
2524 However, if you want to debug the child process there is a workaround
2525 which isn't too painful. Put a call to 'sleep' in the code which the
2526 child process executes after the fork. It may be useful to sleep only
2527 if a certain environment variable is set, or a certain file exists, so
2528 that the delay need not occur when you don't want to run GDB on the
2529 child. While the child is sleeping, use the 'ps' program to get its
2530 process ID. Then tell GDB (a new invocation of GDB if you are also
2531 debugging the parent process) to attach to the child process (*note
2532 Attach::). From that point on you can debug the child process just like
2533 any other process which you attached to.
2535 On some systems, GDB provides support for debugging programs that
2536 create additional processes using the 'fork' or 'vfork' functions.
2537 Currently, the only platforms with this feature are HP-UX (11.x and
2538 later only?) and GNU/Linux (kernel version 2.5.60 and later).
2540 By default, when a program forks, GDB will continue to debug the
2541 parent process and the child process will run unimpeded.
2543 If you want to follow the child process instead of the parent
2544 process, use the command 'set follow-fork-mode'.
2546 'set follow-fork-mode MODE'
2547 Set the debugger response to a program call of 'fork' or 'vfork'.
2548 A call to 'fork' or 'vfork' creates a new process. The MODE
2552 The original process is debugged after a fork. The child
2553 process runs unimpeded. This is the default.
2556 The new process is debugged after a fork. The parent process
2559 'show follow-fork-mode'
2560 Display the current debugger response to a 'fork' or 'vfork' call.
2562 On Linux, if you want to debug both the parent and child processes,
2563 use the command 'set detach-on-fork'.
2565 'set detach-on-fork MODE'
2566 Tells gdb whether to detach one of the processes after a fork, or
2567 retain debugger control over them both.
2570 The child process (or parent process, depending on the value
2571 of 'follow-fork-mode') will be detached and allowed to run
2572 independently. This is the default.
2575 Both processes will be held under the control of GDB. One
2576 process (child or parent, depending on the value of
2577 'follow-fork-mode') is debugged as usual, while the other is
2580 'show detach-on-fork'
2581 Show whether detach-on-fork mode is on/off.
2583 If you choose to set 'detach-on-fork' mode off, then GDB will retain
2584 control of all forked processes (including nested forks). You can list
2585 the forked processes under the control of GDB by using the 'info inferiors'
2586 command, and switch from one fork to another by using the 'inferior'
2587 command (*note Debugging Multiple Inferiors and Programs: Inferiors and
2590 To quit debugging one of the forked processes, you can either detach
2591 from it by using the 'detach inferiors' command (allowing it to run
2592 independently), or kill it using the 'kill inferiors' command. *Note
2593 Debugging Multiple Inferiors and Programs: Inferiors and Programs.
2595 If you ask to debug a child process and a 'vfork' is followed by an
2596 'exec', GDB executes the new target up to the first breakpoint in the
2597 new target. If you have a breakpoint set on 'main' in your original
2598 program, the breakpoint will also be set on the child process's 'main'.
2600 On some systems, when a child process is spawned by 'vfork', you
2601 cannot debug the child or parent until an 'exec' call completes.
2603 If you issue a 'run' command to GDB after an 'exec' call executes,
2604 the new target restarts. To restart the parent process, use the 'file'
2605 command with the parent executable name as its argument. By default,
2606 after an 'exec' call executes, GDB discards the symbols of the previous
2607 executable image. You can change this behaviour with the 'set follow-exec-mode'
2610 'set follow-exec-mode MODE'
2612 Set debugger response to a program call of 'exec'. An 'exec' call
2613 replaces the program image of a process.
2615 'follow-exec-mode' can be:
2618 GDB creates a new inferior and rebinds the process to this new
2619 inferior. The program the process was running before the
2620 'exec' call can be restarted afterwards by restarting the
2625 (gdb) info inferiors
2627 Id Description Executable
2630 process 12020 is executing new program: prog2
2631 Program exited normally.
2632 (gdb) info inferiors
2633 Id Description Executable
2638 GDB keeps the process bound to the same inferior. The new
2639 executable image replaces the previous executable loaded in
2640 the inferior. Restarting the inferior after the 'exec' call,
2641 with e.g., the 'run' command, restarts the executable the
2642 process was running after the 'exec' call. This is the
2647 (gdb) info inferiors
2648 Id Description Executable
2651 process 12020 is executing new program: prog2
2652 Program exited normally.
2653 (gdb) info inferiors
2654 Id Description Executable
2657 You can use the 'catch' command to make GDB stop whenever a 'fork',
2658 'vfork', or 'exec' call is made. *Note Setting Catchpoints: Set
2662 File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running
2664 4.12 Setting a _Bookmark_ to Return to Later
2665 ============================================
2667 On certain operating systems(1), GDB is able to save a "snapshot" of a
2668 program's state, called a "checkpoint", and come back to it later.
2670 Returning to a checkpoint effectively undoes everything that has
2671 happened in the program since the 'checkpoint' was saved. This includes
2672 changes in memory, registers, and even (within some limits) system
2673 state. Effectively, it is like going back in time to the moment when
2674 the checkpoint was saved.
2676 Thus, if you're stepping thru a program and you think you're getting
2677 close to the point where things go wrong, you can save a checkpoint.
2678 Then, if you accidentally go too far and miss the critical statement,
2679 instead of having to restart your program from the beginning, you can
2680 just go back to the checkpoint and start again from there.
2682 This can be especially useful if it takes a lot of time or steps to
2683 reach the point where you think the bug occurs.
2685 To use the 'checkpoint'/'restart' method of debugging:
2688 Save a snapshot of the debugged program's current execution state.
2689 The 'checkpoint' command takes no arguments, but each checkpoint is
2690 assigned a small integer id, similar to a breakpoint id.
2693 List the checkpoints that have been saved in the current debugging
2694 session. For each checkpoint, the following information will be
2700 'Source line, or label'
2702 'restart CHECKPOINT-ID'
2703 Restore the program state that was saved as checkpoint number
2704 CHECKPOINT-ID. All program variables, registers, stack frames etc.
2705 will be returned to the values that they had when the checkpoint
2706 was saved. In essence, gdb will "wind back the clock" to the point
2707 in time when the checkpoint was saved.
2709 Note that breakpoints, GDB variables, command history etc. are not
2710 affected by restoring a checkpoint. In general, a checkpoint only
2711 restores things that reside in the program being debugged, not in
2714 'delete checkpoint CHECKPOINT-ID'
2715 Delete the previously-saved checkpoint identified by CHECKPOINT-ID.
2717 Returning to a previously saved checkpoint will restore the user
2718 state of the program being debugged, plus a significant subset of the
2719 system (OS) state, including file pointers. It won't "un-write" data
2720 from a file, but it will rewind the file pointer to the previous
2721 location, so that the previously written data can be overwritten. For
2722 files opened in read mode, the pointer will also be restored so that the
2723 previously read data can be read again.
2725 Of course, characters that have been sent to a printer (or other
2726 external device) cannot be "snatched back", and characters received from
2727 eg. a serial device can be removed from internal program buffers, but
2728 they cannot be "pushed back" into the serial pipeline, ready to be
2729 received again. Similarly, the actual contents of files that have been
2730 changed cannot be restored (at this time).
2732 However, within those constraints, you actually can "rewind" your
2733 program to a previously saved point in time, and begin debugging it
2734 again -- and you can change the course of events so as to debug a
2735 different execution path this time.
2737 Finally, there is one bit of internal program state that will be
2738 different when you return to a checkpoint -- the program's process id.
2739 Each checkpoint will have a unique process id (or PID), and each will be
2740 different from the program's original PID. If your program has saved a
2741 local copy of its process id, this could potentially pose a problem.
2743 4.12.1 A Non-obvious Benefit of Using Checkpoints
2744 -------------------------------------------------
2746 On some systems such as GNU/Linux, address space randomization is
2747 performed on new processes for security reasons. This makes it
2748 difficult or impossible to set a breakpoint, or watchpoint, on an
2749 absolute address if you have to restart the program, since the absolute
2750 location of a symbol will change from one execution to the next.
2752 A checkpoint, however, is an _identical_ copy of a process.
2753 Therefore if you create a checkpoint at (eg.) the start of main, and
2754 simply return to that checkpoint instead of restarting the process, you
2755 can avoid the effects of address randomization and your symbols will all
2756 stay in the same place.
2758 ---------- Footnotes ----------
2760 (1) Currently, only GNU/Linux.
2763 File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top
2765 5 Stopping and Continuing
2766 *************************
2768 The principal purposes of using a debugger are so that you can stop your
2769 program before it terminates; or so that, if your program runs into
2770 trouble, you can investigate and find out why.
2772 Inside GDB, your program may stop for any of several reasons, such as
2773 a signal, a breakpoint, or reaching a new line after a GDB command such
2774 as 'step'. You may then examine and change variables, set new
2775 breakpoints or remove old ones, and then continue execution. Usually,
2776 the messages shown by GDB provide ample explanation of the status of
2777 your program--but you can also explicitly request this information at
2781 Display information about the status of your program: whether it is
2782 running or not, what process it is, and why it stopped.
2786 * Breakpoints:: Breakpoints, watchpoints, and catchpoints
2787 * Continuing and Stepping:: Resuming execution
2788 * Skipping Over Functions and Files::
2789 Skipping over functions and files
2791 * Thread Stops:: Stopping and starting multi-thread programs
2794 File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping
2796 5.1 Breakpoints, Watchpoints, and Catchpoints
2797 =============================================
2799 A "breakpoint" makes your program stop whenever a certain point in the
2800 program is reached. For each breakpoint, you can add conditions to
2801 control in finer detail whether your program stops. You can set
2802 breakpoints with the 'break' command and its variants (*note Setting
2803 Breakpoints: Set Breaks.), to specify the place where your program
2804 should stop by line number, function name or exact address in the
2807 On some systems, you can set breakpoints in shared libraries before
2808 the executable is run. There is a minor limitation on HP-UX systems:
2809 you must wait until the executable is run in order to set breakpoints in
2810 shared library routines that are not called directly by the program (for
2811 example, routines that are arguments in a 'pthread_create' call).
2813 A "watchpoint" is a special breakpoint that stops your program when
2814 the value of an expression changes. The expression may be a value of a
2815 variable, or it could involve values of one or more variables combined
2816 by operators, such as 'a + b'. This is sometimes called "data
2817 breakpoints". You must use a different command to set watchpoints
2818 (*note Setting Watchpoints: Set Watchpoints.), but aside from that, you
2819 can manage a watchpoint like any other breakpoint: you enable, disable,
2820 and delete both breakpoints and watchpoints using the same commands.
2822 You can arrange to have values from your program displayed
2823 automatically whenever GDB stops at a breakpoint. *Note Automatic
2824 Display: Auto Display.
2826 A "catchpoint" is another special breakpoint that stops your program
2827 when a certain kind of event occurs, such as the throwing of a C++
2828 exception or the loading of a library. As with watchpoints, you use a
2829 different command to set a catchpoint (*note Setting Catchpoints: Set
2830 Catchpoints.), but aside from that, you can manage a catchpoint like any
2831 other breakpoint. (To stop when your program receives a signal, use the
2832 'handle' command; see *note Signals: Signals.)
2834 GDB assigns a number to each breakpoint, watchpoint, or catchpoint
2835 when you create it; these numbers are successive integers starting with
2836 one. In many of the commands for controlling various features of
2837 breakpoints you use the breakpoint number to say which breakpoint you
2838 want to change. Each breakpoint may be "enabled" or "disabled"; if
2839 disabled, it has no effect on your program until you enable it again.
2841 Some GDB commands accept a range of breakpoints on which to operate.
2842 A breakpoint range is either a single breakpoint number, like '5', or
2843 two such numbers, in increasing order, separated by a hyphen, like
2844 '5-7'. When a breakpoint range is given to a command, all breakpoints
2845 in that range are operated on.
2849 * Set Breaks:: Setting breakpoints
2850 * Set Watchpoints:: Setting watchpoints
2851 * Set Catchpoints:: Setting catchpoints
2852 * Delete Breaks:: Deleting breakpoints
2853 * Disabling:: Disabling breakpoints
2854 * Conditions:: Break conditions
2855 * Break Commands:: Breakpoint command lists
2856 * Dynamic Printf:: Dynamic printf
2857 * Save Breakpoints:: How to save breakpoints in a file
2858 * Static Probe Points:: Listing static probe points
2859 * Error in Breakpoints:: "Cannot insert breakpoints"
2860 * Breakpoint-related Warnings:: "Breakpoint address adjusted..."
2863 File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints
2865 5.1.1 Setting Breakpoints
2866 -------------------------
2868 Breakpoints are set with the 'break' command (abbreviated 'b'). The
2869 debugger convenience variable '$bpnum' records the number of the
2870 breakpoint you've set most recently; see *note Convenience Variables:
2871 Convenience Vars, for a discussion of what you can do with convenience
2875 Set a breakpoint at the given LOCATION, which can specify a
2876 function name, a line number, or an address of an instruction.
2877 (*Note Specify Location::, for a list of all the possible ways to
2878 specify a LOCATION.) The breakpoint will stop your program just
2879 before it executes any of the code in the specified LOCATION.
2881 When using source languages that permit overloading of symbols,
2882 such as C++, a function name may refer to more than one possible
2883 place to break. *Note Ambiguous Expressions: Ambiguous
2884 Expressions, for a discussion of that situation.
2886 It is also possible to insert a breakpoint that will stop the
2887 program only if a specific thread (*note Thread-Specific
2888 Breakpoints::) or a specific task (*note Ada Tasks::) hits that
2892 When called without any arguments, 'break' sets a breakpoint at the
2893 next instruction to be executed in the selected stack frame (*note
2894 Examining the Stack: Stack.). In any selected frame but the
2895 innermost, this makes your program stop as soon as control returns
2896 to that frame. This is similar to the effect of a 'finish' command
2897 in the frame inside the selected frame--except that 'finish' does
2898 not leave an active breakpoint. If you use 'break' without an
2899 argument in the innermost frame, GDB stops the next time it reaches
2900 the current location; this may be useful inside loops.
2902 GDB normally ignores breakpoints when it resumes execution, until
2903 at least one instruction has been executed. If it did not do this,
2904 you would be unable to proceed past a breakpoint without first
2905 disabling the breakpoint. This rule applies whether or not the
2906 breakpoint already existed when your program stopped.
2909 Set a breakpoint with condition COND; evaluate the expression COND
2910 each time the breakpoint is reached, and stop only if the value is
2911 nonzero--that is, if COND evaluates as true. '...' stands for one
2912 of the possible arguments described above (or no argument)
2913 specifying where to break. *Note Break Conditions: Conditions, for
2914 more information on breakpoint conditions.
2917 Set a breakpoint enabled only for one stop. The ARGS are the same
2918 as for the 'break' command, and the breakpoint is set in the same
2919 way, but the breakpoint is automatically deleted after the first
2920 time your program stops there. *Note Disabling Breakpoints:
2924 Set a hardware-assisted breakpoint. The ARGS are the same as for
2925 the 'break' command and the breakpoint is set in the same way, but
2926 the breakpoint requires hardware support and some target hardware
2927 may not have this support. The main purpose of this is EPROM/ROM
2928 code debugging, so you can set a breakpoint at an instruction
2929 without changing the instruction. This can be used with the new
2930 trap-generation provided by SPARClite DSU and most x86-based
2931 targets. These targets will generate traps when a program accesses
2932 some data or instruction address that is assigned to the debug
2933 registers. However the hardware breakpoint registers can take a
2934 limited number of breakpoints. For example, on the DSU, only two
2935 data breakpoints can be set at a time, and GDB will reject this
2936 command if more than two are used. Delete or disable unused
2937 hardware breakpoints before setting new ones (*note Disabling
2938 Breakpoints: Disabling.). *Note Break Conditions: Conditions. For
2939 remote targets, you can restrict the number of hardware breakpoints
2940 GDB will use, see *note set remote hardware-breakpoint-limit::.
2943 Set a hardware-assisted breakpoint enabled only for one stop. The
2944 ARGS are the same as for the 'hbreak' command and the breakpoint is
2945 set in the same way. However, like the 'tbreak' command, the
2946 breakpoint is automatically deleted after the first time your
2947 program stops there. Also, like the 'hbreak' command, the
2948 breakpoint requires hardware support and some target hardware may
2949 not have this support. *Note Disabling Breakpoints: Disabling.
2950 See also *note Break Conditions: Conditions.
2953 Set breakpoints on all functions matching the regular expression
2954 REGEX. This command sets an unconditional breakpoint on all
2955 matches, printing a list of all breakpoints it set. Once these
2956 breakpoints are set, they are treated just like the breakpoints set
2957 with the 'break' command. You can delete them, disable them, or
2958 make them conditional the same way as any other breakpoint.
2960 The syntax of the regular expression is the standard one used with
2961 tools like 'grep'. Note that this is different from the syntax
2962 used by shells, so for instance 'foo*' matches all functions that
2963 include an 'fo' followed by zero or more 'o's. There is an
2964 implicit '.*' leading and trailing the regular expression you
2965 supply, so to match only functions that begin with 'foo', use
2968 When debugging C++ programs, 'rbreak' is useful for setting
2969 breakpoints on overloaded functions that are not members of any
2972 The 'rbreak' command can be used to set breakpoints in *all* the
2973 functions in a program, like this:
2978 If 'rbreak' is called with a filename qualification, it limits the
2979 search for functions matching the given regular expression to the
2980 specified FILE. This can be used, for example, to set breakpoints
2981 on every function in a given file:
2983 (gdb) rbreak file.c:.
2985 The colon separating the filename qualifier from the regex may
2986 optionally be surrounded by spaces.
2988 'info breakpoints [N...]'
2990 Print a table of all breakpoints, watchpoints, and catchpoints set
2991 and not deleted. Optional argument N means print information only
2992 about the specified breakpoint(s) (or watchpoint(s) or
2993 catchpoint(s)). For each breakpoint, following columns are
2996 _Breakpoint Numbers_
2998 Breakpoint, watchpoint, or catchpoint.
3000 Whether the breakpoint is marked to be disabled or deleted
3002 _Enabled or Disabled_
3003 Enabled breakpoints are marked with 'y'. 'n' marks
3004 breakpoints that are not enabled.
3006 Where the breakpoint is in your program, as a memory address.
3007 For a pending breakpoint whose address is not yet known, this
3008 field will contain '<PENDING>'. Such breakpoint won't fire
3009 until a shared library that has the symbol or line referred by
3010 breakpoint is loaded. See below for details. A breakpoint
3011 with several locations will have '<MULTIPLE>' in this
3012 field--see below for details.
3014 Where the breakpoint is in the source for your program, as a
3015 file and line number. For a pending breakpoint, the original
3016 string passed to the breakpoint command will be listed as it
3017 cannot be resolved until the appropriate shared library is
3018 loaded in the future.
3020 If a breakpoint is conditional, there are two evaluation modes:
3021 "host" and "target". If mode is "host", breakpoint condition
3022 evaluation is done by GDB on the host's side. If it is "target",
3023 then the condition is evaluated by the target. The 'info break'
3024 command shows the condition on the line following the affected
3025 breakpoint, together with its condition evaluation mode in between
3028 Breakpoint commands, if any, are listed after that. A pending
3029 breakpoint is allowed to have a condition specified for it. The
3030 condition is not parsed for validity until a shared library is
3031 loaded that allows the pending breakpoint to resolve to a valid
3034 'info break' with a breakpoint number N as argument lists only that
3035 breakpoint. The convenience variable '$_' and the default
3036 examining-address for the 'x' command are set to the address of the
3037 last breakpoint listed (*note Examining Memory: Memory.).
3039 'info break' displays a count of the number of times the breakpoint
3040 has been hit. This is especially useful in conjunction with the
3041 'ignore' command. You can ignore a large number of breakpoint
3042 hits, look at the breakpoint info to see how many times the
3043 breakpoint was hit, and then run again, ignoring one less than that
3044 number. This will get you quickly to the last hit of that
3047 For a breakpoints with an enable count (xref) greater than 1, 'info
3048 break' also displays that count.
3050 GDB allows you to set any number of breakpoints at the same place in
3051 your program. There is nothing silly or meaningless about this. When
3052 the breakpoints are conditional, this is even useful (*note Break
3053 Conditions: Conditions.).
3055 It is possible that a breakpoint corresponds to several locations in
3056 your program. Examples of this situation are:
3058 * Multiple functions in the program may have the same name.
3060 * For a C++ constructor, the GCC compiler generates several instances
3061 of the function body, used in different cases.
3063 * For a C++ template function, a given line in the function can
3064 correspond to any number of instantiations.
3066 * For an inlined function, a given source line can correspond to
3067 several places where that function is inlined.
3069 In all those cases, GDB will insert a breakpoint at all the relevant
3072 A breakpoint with multiple locations is displayed in the breakpoint
3073 table using several rows--one header row, followed by one row for each
3074 breakpoint location. The header row has '<MULTIPLE>' in the address
3075 column. The rows for individual locations contain the actual addresses
3076 for locations, and show the functions to which those locations belong.
3077 The number column for a location is of the form
3078 BREAKPOINT-NUMBER.LOCATION-NUMBER.
3082 Num Type Disp Enb Address What
3083 1 breakpoint keep y <MULTIPLE>
3085 breakpoint already hit 1 time
3086 1.1 y 0x080486a2 in void foo<int>() at t.cc:8
3087 1.2 y 0x080486ca in void foo<double>() at t.cc:8
3089 Each location can be individually enabled or disabled by passing
3090 BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the 'enable' and
3091 'disable' commands. Note that you cannot delete the individual
3092 locations from the list, you can only delete the entire list of
3093 locations that belong to their parent breakpoint (with the 'delete NUM'
3094 command, where NUM is the number of the parent breakpoint, 1 in the
3095 above example). Disabling or enabling the parent breakpoint (*note
3096 Disabling::) affects all of the locations that belong to that
3099 It's quite common to have a breakpoint inside a shared library.
3100 Shared libraries can be loaded and unloaded explicitly, and possibly
3101 repeatedly, as the program is executed. To support this use case, GDB
3102 updates breakpoint locations whenever any shared library is loaded or
3103 unloaded. Typically, you would set a breakpoint in a shared library at
3104 the beginning of your debugging session, when the library is not loaded,
3105 and when the symbols from the library are not available. When you try
3106 to set breakpoint, GDB will ask you if you want to set a so called
3107 "pending breakpoint"--breakpoint whose address is not yet resolved.
3109 After the program is run, whenever a new shared library is loaded,
3110 GDB reevaluates all the breakpoints. When a newly loaded shared library
3111 contains the symbol or line referred to by some pending breakpoint, that
3112 breakpoint is resolved and becomes an ordinary breakpoint. When a
3113 library is unloaded, all breakpoints that refer to its symbols or source
3114 lines become pending again.
3116 This logic works for breakpoints with multiple locations, too. For
3117 example, if you have a breakpoint in a C++ template function, and a
3118 newly loaded shared library has an instantiation of that template, a new
3119 location is added to the list of locations for the breakpoint.
3121 Except for having unresolved address, pending breakpoints do not
3122 differ from regular breakpoints. You can set conditions or commands,
3123 enable and disable them and perform other breakpoint operations.
3125 GDB provides some additional commands for controlling what happens
3126 when the 'break' command cannot resolve breakpoint address specification
3129 'set breakpoint pending auto'
3130 This is the default behavior. When GDB cannot find the breakpoint
3131 location, it queries you whether a pending breakpoint should be
3134 'set breakpoint pending on'
3135 This indicates that an unrecognized breakpoint location should
3136 automatically result in a pending breakpoint being created.
3138 'set breakpoint pending off'
3139 This indicates that pending breakpoints are not to be created. Any
3140 unrecognized breakpoint location results in an error. This setting
3141 does not affect any pending breakpoints previously created.
3143 'show breakpoint pending'
3144 Show the current behavior setting for creating pending breakpoints.
3146 The settings above only affect the 'break' command and its variants.
3147 Once breakpoint is set, it will be automatically updated as shared
3148 libraries are loaded and unloaded.
3150 For some targets, GDB can automatically decide if hardware or
3151 software breakpoints should be used, depending on whether the breakpoint
3152 address is read-only or read-write. This applies to breakpoints set
3153 with the 'break' command as well as to internal breakpoints set by
3154 commands like 'next' and 'finish'. For breakpoints set with 'hbreak',
3155 GDB will always use hardware breakpoints.
3157 You can control this automatic behaviour with the following
3160 'set breakpoint auto-hw on'
3161 This is the default behavior. When GDB sets a breakpoint, it will
3162 try to use the target memory map to decide if software or hardware
3163 breakpoint must be used.
3165 'set breakpoint auto-hw off'
3166 This indicates GDB should not automatically select breakpoint type.
3167 If the target provides a memory map, GDB will warn when trying to
3168 set software breakpoint at a read-only address.
3170 GDB normally implements breakpoints by replacing the program code at
3171 the breakpoint address with a special instruction, which, when executed,
3172 given control to the debugger. By default, the program code is so
3173 modified only when the program is resumed. As soon as the program
3174 stops, GDB restores the original instructions. This behaviour guards
3175 against leaving breakpoints inserted in the target should gdb abrubptly
3176 disconnect. However, with slow remote targets, inserting and removing
3177 breakpoint can reduce the performance. This behavior can be controlled
3178 with the following commands::
3180 'set breakpoint always-inserted off'
3181 All breakpoints, including newly added by the user, are inserted in
3182 the target only when the target is resumed. All breakpoints are
3183 removed from the target when it stops.
3185 'set breakpoint always-inserted on'
3186 Causes all breakpoints to be inserted in the target at all times.
3187 If the user adds a new breakpoint, or changes an existing
3188 breakpoint, the breakpoints in the target are updated immediately.
3189 A breakpoint is removed from the target only when breakpoint itself
3192 'set breakpoint always-inserted auto'
3193 This is the default mode. If GDB is controlling the inferior in
3194 non-stop mode (*note Non-Stop Mode::), gdb behaves as if
3195 'breakpoint always-inserted' mode is on. If GDB is controlling the
3196 inferior in all-stop mode, GDB behaves as if 'breakpoint
3197 always-inserted' mode is off.
3199 GDB handles conditional breakpoints by evaluating these conditions
3200 when a breakpoint breaks. If the condition is true, then the process
3201 being debugged stops, otherwise the process is resumed.
3203 If the target supports evaluating conditions on its end, GDB may
3204 download the breakpoint, together with its conditions, to it.
3206 This feature can be controlled via the following commands:
3208 'set breakpoint condition-evaluation host'
3209 This option commands GDB to evaluate the breakpoint conditions on
3210 the host's side. Unconditional breakpoints are sent to the target
3211 which in turn receives the triggers and reports them back to GDB
3212 for condition evaluation. This is the standard evaluation mode.
3214 'set breakpoint condition-evaluation target'
3215 This option commands GDB to download breakpoint conditions to the
3216 target at the moment of their insertion. The target is responsible
3217 for evaluating the conditional expression and reporting breakpoint
3218 stop events back to GDB whenever the condition is true. Due to
3219 limitations of target-side evaluation, some conditions cannot be
3220 evaluated there, e.g., conditions that depend on local data that is
3221 only known to the host. Examples include conditional expressions
3222 involving convenience variables, complex types that cannot be
3223 handled by the agent expression parser and expressions that are too
3224 long to be sent over to the target, specially when the target is a
3225 remote system. In these cases, the conditions will be evaluated by
3228 'set breakpoint condition-evaluation auto'
3229 This is the default mode. If the target supports evaluating
3230 breakpoint conditions on its end, GDB will download breakpoint
3231 conditions to the target (limitations mentioned previously apply).
3232 If the target does not support breakpoint condition evaluation,
3233 then GDB will fallback to evaluating all these conditions on the
3236 GDB itself sometimes sets breakpoints in your program for special
3237 purposes, such as proper handling of 'longjmp' (in C programs). These
3238 internal breakpoints are assigned negative numbers, starting with '-1';
3239 'info breakpoints' does not display them. You can see these breakpoints
3240 with the GDB maintenance command 'maint info breakpoints' (*note maint
3241 info breakpoints::).
3244 File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints
3246 5.1.2 Setting Watchpoints
3247 -------------------------
3249 You can use a watchpoint to stop execution whenever the value of an
3250 expression changes, without having to predict a particular place where
3251 this may happen. (This is sometimes called a "data breakpoint".) The
3252 expression may be as simple as the value of a single variable, or as
3253 complex as many variables combined by operators. Examples include:
3255 * A reference to the value of a single variable.
3257 * An address cast to an appropriate data type. For example, '*(int
3258 *)0x12345678' will watch a 4-byte region at the specified address
3259 (assuming an 'int' occupies 4 bytes).
3261 * An arbitrarily complex expression, such as 'a*b + c/d'. The
3262 expression can use any operators valid in the program's native
3263 language (*note Languages::).
3265 You can set a watchpoint on an expression even if the expression can
3266 not be evaluated yet. For instance, you can set a watchpoint on
3267 '*global_ptr' before 'global_ptr' is initialized. GDB will stop when
3268 your program sets 'global_ptr' and the expression produces a valid
3269 value. If the expression becomes valid in some other way than changing
3270 a variable (e.g. if the memory pointed to by '*global_ptr' becomes
3271 readable as the result of a 'malloc' call), GDB may not stop until the
3272 next time the expression changes.
3274 Depending on your system, watchpoints may be implemented in software
3275 or hardware. GDB does software watchpointing by single-stepping your
3276 program and testing the variable's value each time, which is hundreds of
3277 times slower than normal execution. (But this may still be worth it, to
3278 catch errors where you have no clue what part of your program is the
3281 On some systems, such as HP-UX, PowerPC, GNU/Linux and most other
3282 x86-based targets, GDB includes support for hardware watchpoints, which
3283 do not slow down the running of your program.
3285 'watch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]'
3286 Set a watchpoint for an expression. GDB will break when the
3287 expression EXPR is written into by the program and its value
3288 changes. The simplest (and the most popular) use of this command
3289 is to watch the value of a single variable:
3293 If the command includes a '[thread THREADNUM]' argument, GDB breaks
3294 only when the thread identified by THREADNUM changes the value of
3295 EXPR. If any other threads change the value of EXPR, GDB will not
3296 break. Note that watchpoints restricted to a single thread in this
3297 way only work with Hardware Watchpoints.
3299 Ordinarily a watchpoint respects the scope of variables in EXPR
3300 (see below). The '-location' argument tells GDB to instead watch
3301 the memory referred to by EXPR. In this case, GDB will evaluate
3302 EXPR, take the address of the result, and watch the memory at that
3303 address. The type of the result is used to determine the size of
3304 the watched memory. If the expression's result does not have an
3305 address, then GDB will print an error.
3307 The '[mask MASKVALUE]' argument allows creation of masked
3308 watchpoints, if the current architecture supports this feature
3309 (e.g., PowerPC Embedded architecture, see *note PowerPC
3310 Embedded::.) A "masked watchpoint" specifies a mask in addition to
3311 an address to watch. The mask specifies that some bits of an
3312 address (the bits which are reset in the mask) should be ignored
3313 when matching the address accessed by the inferior against the
3314 watchpoint address. Thus, a masked watchpoint watches many
3315 addresses simultaneously--those addresses whose unmasked bits are
3316 identical to the unmasked bits in the watchpoint address. The
3317 'mask' argument implies '-location'. Examples:
3319 (gdb) watch foo mask 0xffff00ff
3320 (gdb) watch *0xdeadbeef mask 0xffffff00
3322 'rwatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]'
3323 Set a watchpoint that will break when the value of EXPR is read by
3326 'awatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]'
3327 Set a watchpoint that will break when EXPR is either read from or
3328 written into by the program.
3330 'info watchpoints [N...]'
3331 This command prints a list of watchpoints, using the same format as
3332 'info break' (*note Set Breaks::).
3334 If you watch for a change in a numerically entered address you need
3335 to dereference it, as the address itself is just a constant number which
3336 will never change. GDB refuses to create a watchpoint that watches a
3337 never-changing value:
3339 (gdb) watch 0x600850
3340 Cannot watch constant value 0x600850.
3341 (gdb) watch *(int *) 0x600850
3342 Watchpoint 1: *(int *) 6293584
3344 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints
3345 execute very quickly, and the debugger reports a change in value at the
3346 exact instruction where the change occurs. If GDB cannot set a hardware
3347 watchpoint, it sets a software watchpoint, which executes more slowly
3348 and reports the change in value at the next _statement_, not the
3349 instruction, after the change occurs.
3351 You can force GDB to use only software watchpoints with the 'set
3352 can-use-hw-watchpoints 0' command. With this variable set to zero, GDB
3353 will never try to use hardware watchpoints, even if the underlying
3354 system supports them. (Note that hardware-assisted watchpoints that
3355 were set _before_ setting 'can-use-hw-watchpoints' to zero will still
3356 use the hardware mechanism of watching expression values.)
3358 'set can-use-hw-watchpoints'
3359 Set whether or not to use hardware watchpoints.
3361 'show can-use-hw-watchpoints'
3362 Show the current mode of using hardware watchpoints.
3364 For remote targets, you can restrict the number of hardware
3365 watchpoints GDB will use, see *note set remote
3366 hardware-breakpoint-limit::.
3368 When you issue the 'watch' command, GDB reports
3370 Hardware watchpoint NUM: EXPR
3372 if it was able to set a hardware watchpoint.
3374 Currently, the 'awatch' and 'rwatch' commands can only set hardware
3375 watchpoints, because accesses to data that don't change the value of the
3376 watched expression cannot be detected without examining every
3377 instruction as it is being executed, and GDB does not do that currently.
3378 If GDB finds that it is unable to set a hardware breakpoint with the
3379 'awatch' or 'rwatch' command, it will print a message like this:
3381 Expression cannot be implemented with read/access watchpoint.
3383 Sometimes, GDB cannot set a hardware watchpoint because the data type
3384 of the watched expression is wider than what a hardware watchpoint on
3385 the target machine can handle. For example, some systems can only watch
3386 regions that are up to 4 bytes wide; on such systems you cannot set
3387 hardware watchpoints for an expression that yields a double-precision
3388 floating-point number (which is typically 8 bytes wide). As a
3389 work-around, it might be possible to break the large region into a
3390 series of smaller ones and watch them with separate watchpoints.
3392 If you set too many hardware watchpoints, GDB might be unable to
3393 insert all of them when you resume the execution of your program. Since
3394 the precise number of active watchpoints is unknown until such time as
3395 the program is about to be resumed, GDB might not be able to warn you
3396 about this when you set the watchpoints, and the warning will be printed
3397 only when the program is resumed:
3399 Hardware watchpoint NUM: Could not insert watchpoint
3401 If this happens, delete or disable some of the watchpoints.
3403 Watching complex expressions that reference many variables can also
3404 exhaust the resources available for hardware-assisted watchpoints.
3405 That's because GDB needs to watch every variable in the expression with
3406 separately allocated resources.
3408 If you call a function interactively using 'print' or 'call', any
3409 watchpoints you have set will be inactive until GDB reaches another kind
3410 of breakpoint or the call completes.
3412 GDB automatically deletes watchpoints that watch local (automatic)
3413 variables, or expressions that involve such variables, when they go out
3414 of scope, that is, when the execution leaves the block in which these
3415 variables were defined. In particular, when the program being debugged
3416 terminates, _all_ local variables go out of scope, and so only
3417 watchpoints that watch global variables remain set. If you rerun the
3418 program, you will need to set all such watchpoints again. One way of
3419 doing that would be to set a code breakpoint at the entry to the 'main'
3420 function and when it breaks, set all the watchpoints.
3422 In multi-threaded programs, watchpoints will detect changes to the
3423 watched expression from every thread.
3425 _Warning:_ In multi-threaded programs, software watchpoints have
3426 only limited usefulness. If GDB creates a software watchpoint, it
3427 can only watch the value of an expression _in a single thread_. If
3428 you are confident that the expression can only change due to the
3429 current thread's activity (and if you are also confident that no
3430 other thread can become current), then you can use software
3431 watchpoints as usual. However, GDB may not notice when a
3432 non-current thread's activity changes the expression. (Hardware
3433 watchpoints, in contrast, watch an expression in all threads.)
3435 *Note set remote hardware-watchpoint-limit::.
3438 File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints
3440 5.1.3 Setting Catchpoints
3441 -------------------------
3443 You can use "catchpoints" to cause the debugger to stop for certain
3444 kinds of program events, such as C++ exceptions or the loading of a
3445 shared library. Use the 'catch' command to set a catchpoint.
3448 Stop when EVENT occurs. The EVENT can be any of the following:
3453 The throwing, re-throwing, or catching of a C++ exception.
3455 If REGEXP is given, then only exceptions whose type matches
3456 the regular expression will be caught.
3458 The convenience variable '$_exception' is available at an
3459 exception-related catchpoint, on some systems. This holds the
3460 exception being thrown.
3462 There are currently some limitations to C++ exception handling
3465 * The support for these commands is system-dependent.
3466 Currently, only systems using the 'gnu-v3' C++ ABI (*note
3467 ABI::) are supported.
3469 * The regular expression feature and the '$_exception'
3470 convenience variable rely on the presence of some SDT
3471 probes in 'libstdc++'. If these probes are not present,
3472 then these features cannot be used. These probes were
3473 first available in the GCC 4.8 release, but whether or
3474 not they are available in your GCC also depends on how it
3477 * The '$_exception' convenience variable is only valid at
3478 the instruction at which an exception-related catchpoint
3481 * When an exception-related catchpoint is hit, GDB stops at
3482 a location in the system library which implements runtime
3483 exception support for C++, usually 'libstdc++'. You can
3484 use 'up' (*note Selection::) to get to your code.
3486 * If you call a function interactively, GDB normally
3487 returns control to you when the function has finished
3488 executing. If the call raises an exception, however, the
3489 call may bypass the mechanism that returns control to you
3490 and cause your program either to abort or to simply
3491 continue running until it hits a breakpoint, catches a
3492 signal that GDB is listening for, or exits. This is the
3493 case even if you set a catchpoint for the exception;
3494 catchpoints on exceptions are disabled within interactive
3495 calls. *Note Calling::, for information on controlling
3496 this with 'set unwind-on-terminating-exception'.
3498 * You cannot raise an exception interactively.
3500 * You cannot install an exception handler interactively.
3503 An Ada exception being raised. If an exception name is
3504 specified at the end of the command (eg 'catch exception
3505 Program_Error'), the debugger will stop only when this
3506 specific exception is raised. Otherwise, the debugger stops
3507 execution when any Ada exception is raised.
3509 When inserting an exception catchpoint on a user-defined
3510 exception whose name is identical to one of the exceptions
3511 defined by the language, the fully qualified name must be used
3512 as the exception name. Otherwise, GDB will assume that it
3513 should stop on the pre-defined exception rather than the
3514 user-defined one. For instance, assuming an exception called
3515 'Constraint_Error' is defined in package 'Pck', then the
3516 command to use to catch such exceptions is 'catch exception
3517 Pck.Constraint_Error'.
3519 'exception unhandled'
3520 An exception that was raised but is not handled by the
3524 A failed Ada assertion.
3527 A call to 'exec'. This is currently only available for HP-UX
3531 'syscall [NAME | NUMBER] ...'
3532 A call to or return from a system call, a.k.a. "syscall". A
3533 syscall is a mechanism for application programs to request a
3534 service from the operating system (OS) or one of the OS system
3535 services. GDB can catch some or all of the syscalls issued by
3536 the debuggee, and show the related information for each
3537 syscall. If no argument is specified, calls to and returns
3538 from all system calls will be caught.
3540 NAME can be any system call name that is valid for the
3541 underlying OS. Just what syscalls are valid depends on the OS.
3542 On GNU and Unix systems, you can find the full list of valid
3543 syscall names on '/usr/include/asm/unistd.h'.
3545 Normally, GDB knows in advance which syscalls are valid for
3546 each OS, so you can use the GDB command-line completion
3547 facilities (*note command completion: Completion.) to list the
3550 You may also specify the system call numerically. A syscall's
3551 number is the value passed to the OS's syscall dispatcher to
3552 identify the requested service. When you specify the syscall
3553 by its name, GDB uses its database of syscalls to convert the
3554 name into the corresponding numeric code, but using the number
3555 directly may be useful if GDB's database does not have the
3556 complete list of syscalls on your system (e.g., because GDB
3557 lags behind the OS upgrades).
3559 The example below illustrates how this command works if you
3560 don't provide arguments to it:
3563 Catchpoint 1 (syscall)
3565 Starting program: /tmp/catch-syscall
3567 Catchpoint 1 (call to syscall 'close'), \
3568 0xffffe424 in __kernel_vsyscall ()
3572 Catchpoint 1 (returned from syscall 'close'), \
3573 0xffffe424 in __kernel_vsyscall ()
3576 Here is an example of catching a system call by name:
3578 (gdb) catch syscall chroot
3579 Catchpoint 1 (syscall 'chroot' [61])
3581 Starting program: /tmp/catch-syscall
3583 Catchpoint 1 (call to syscall 'chroot'), \
3584 0xffffe424 in __kernel_vsyscall ()
3588 Catchpoint 1 (returned from syscall 'chroot'), \
3589 0xffffe424 in __kernel_vsyscall ()
3592 An example of specifying a system call numerically. In the
3593 case below, the syscall number has a corresponding entry in
3594 the XML file, so GDB finds its name and prints it:
3596 (gdb) catch syscall 252
3597 Catchpoint 1 (syscall(s) 'exit_group')
3599 Starting program: /tmp/catch-syscall
3601 Catchpoint 1 (call to syscall 'exit_group'), \
3602 0xffffe424 in __kernel_vsyscall ()
3606 Program exited normally.
3609 However, there can be situations when there is no
3610 corresponding name in XML file for that syscall number. In
3611 this case, GDB prints a warning message saying that it was not
3612 able to find the syscall name, but the catchpoint will be set
3613 anyway. See the example below:
3615 (gdb) catch syscall 764
3616 warning: The number '764' does not represent a known syscall.
3617 Catchpoint 2 (syscall 764)
3620 If you configure GDB using the '--without-expat' option, it
3621 will not be able to display syscall names. Also, if your
3622 architecture does not have an XML file describing its system
3623 calls, you will not be able to see the syscall names. It is
3624 important to notice that these two features are used for
3625 accessing the syscall name database. In either case, you will
3626 see a warning like this:
3629 warning: Could not open "syscalls/i386-linux.xml"
3630 warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
3631 GDB will not be able to display syscall names.
3632 Catchpoint 1 (syscall)
3635 Of course, the file name will change depending on your
3636 architecture and system.
3638 Still using the example above, you can also try to catch a
3639 syscall by its number. In this case, you would see something
3642 (gdb) catch syscall 252
3643 Catchpoint 1 (syscall(s) 252)
3645 Again, in this case GDB would not be able to display syscall's
3649 A call to 'fork'. This is currently only available for HP-UX
3653 A call to 'vfork'. This is currently only available for HP-UX
3658 The loading or unloading of a shared library. If REGEXP is
3659 given, then the catchpoint will stop only if the regular
3660 expression matches one of the affected libraries.
3662 'signal [SIGNAL... | 'all']'
3663 The delivery of a signal.
3665 With no arguments, this catchpoint will catch any signal that
3666 is not used internally by GDB, specifically, all signals
3667 except 'SIGTRAP' and 'SIGINT'.
3669 With the argument 'all', all signals, including those used by
3670 GDB, will be caught. This argument cannot be used with other
3673 Otherwise, the arguments are a list of signal names as given
3674 to 'handle' (*note Signals::). Only signals specified in this
3675 list will be caught.
3677 One reason that 'catch signal' can be more useful than
3678 'handle' is that you can attach commands and conditions to the
3681 When a signal is caught by a catchpoint, the signal's 'stop'
3682 and 'print' settings, as specified by 'handle', are ignored.
3683 However, whether the signal is still delivered to the inferior
3684 depends on the 'pass' setting; this can be changed in the
3685 catchpoint's commands.
3688 Set a catchpoint that is enabled only for one stop. The catchpoint
3689 is automatically deleted after the first time the event is caught.
3691 Use the 'info break' command to list the current catchpoints.
3694 File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints
3696 5.1.4 Deleting Breakpoints
3697 --------------------------
3699 It is often necessary to eliminate a breakpoint, watchpoint, or
3700 catchpoint once it has done its job and you no longer want your program
3701 to stop there. This is called "deleting" the breakpoint. A breakpoint
3702 that has been deleted no longer exists; it is forgotten.
3704 With the 'clear' command you can delete breakpoints according to
3705 where they are in your program. With the 'delete' command you can
3706 delete individual breakpoints, watchpoints, or catchpoints by specifying
3707 their breakpoint numbers.
3709 It is not necessary to delete a breakpoint to proceed past it. GDB
3710 automatically ignores breakpoints on the first instruction to be
3711 executed when you continue execution without changing the execution
3715 Delete any breakpoints at the next instruction to be executed in
3716 the selected stack frame (*note Selecting a Frame: Selection.).
3717 When the innermost frame is selected, this is a good way to delete
3718 a breakpoint where your program just stopped.
3721 Delete any breakpoints set at the specified LOCATION. *Note
3722 Specify Location::, for the various forms of LOCATION; the most
3723 useful ones are listed below:
3726 'clear FILENAME:FUNCTION'
3727 Delete any breakpoints set at entry to the named FUNCTION.
3730 'clear FILENAME:LINENUM'
3731 Delete any breakpoints set at or within the code of the
3732 specified LINENUM of the specified FILENAME.
3734 'delete [breakpoints] [RANGE...]'
3735 Delete the breakpoints, watchpoints, or catchpoints of the
3736 breakpoint ranges specified as arguments. If no argument is
3737 specified, delete all breakpoints (GDB asks confirmation, unless
3738 you have 'set confirm off'). You can abbreviate this command as
3742 File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints
3744 5.1.5 Disabling Breakpoints
3745 ---------------------------
3747 Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
3748 prefer to "disable" it. This makes the breakpoint inoperative as if it
3749 had been deleted, but remembers the information on the breakpoint so
3750 that you can "enable" it again later.
3752 You disable and enable breakpoints, watchpoints, and catchpoints with
3753 the 'enable' and 'disable' commands, optionally specifying one or more
3754 breakpoint numbers as arguments. Use 'info break' to print a list of
3755 all breakpoints, watchpoints, and catchpoints if you do not know which
3758 Disabling and enabling a breakpoint that has multiple locations
3759 affects all of its locations.
3761 A breakpoint, watchpoint, or catchpoint can have any of several
3762 different states of enablement:
3764 * Enabled. The breakpoint stops your program. A breakpoint set with
3765 the 'break' command starts out in this state.
3766 * Disabled. The breakpoint has no effect on your program.
3767 * Enabled once. The breakpoint stops your program, but then becomes
3769 * Enabled for a count. The breakpoint stops your program for the
3770 next N times, then becomes disabled.
3771 * Enabled for deletion. The breakpoint stops your program, but
3772 immediately after it does so it is deleted permanently. A
3773 breakpoint set with the 'tbreak' command starts out in this state.
3775 You can use the following commands to enable or disable breakpoints,
3776 watchpoints, and catchpoints:
3778 'disable [breakpoints] [RANGE...]'
3779 Disable the specified breakpoints--or all breakpoints, if none are
3780 listed. A disabled breakpoint has no effect but is not forgotten.
3781 All options such as ignore-counts, conditions and commands are
3782 remembered in case the breakpoint is enabled again later. You may
3783 abbreviate 'disable' as 'dis'.
3785 'enable [breakpoints] [RANGE...]'
3786 Enable the specified breakpoints (or all defined breakpoints).
3787 They become effective once again in stopping your program.
3789 'enable [breakpoints] once RANGE...'
3790 Enable the specified breakpoints temporarily. GDB disables any of
3791 these breakpoints immediately after stopping your program.
3793 'enable [breakpoints] count COUNT RANGE...'
3794 Enable the specified breakpoints temporarily. GDB records COUNT
3795 with each of the specified breakpoints, and decrements a
3796 breakpoint's count when it is hit. When any count reaches 0, GDB
3797 disables that breakpoint. If a breakpoint has an ignore count
3798 (*note Break Conditions: Conditions.), that will be decremented to
3799 0 before COUNT is affected.
3801 'enable [breakpoints] delete RANGE...'
3802 Enable the specified breakpoints to work once, then die. GDB
3803 deletes any of these breakpoints as soon as your program stops
3804 there. Breakpoints set by the 'tbreak' command start out in this
3807 Except for a breakpoint set with 'tbreak' (*note Setting Breakpoints:
3808 Set Breaks.), breakpoints that you set are initially enabled;
3809 subsequently, they become disabled or enabled only when you use one of
3810 the commands above. (The command 'until' can set and delete a
3811 breakpoint of its own, but it does not change the state of your other
3812 breakpoints; see *note Continuing and Stepping: Continuing and
3816 File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints
3818 5.1.6 Break Conditions
3819 ----------------------
3821 The simplest sort of breakpoint breaks every time your program reaches a
3822 specified place. You can also specify a "condition" for a breakpoint.
3823 A condition is just a Boolean expression in your programming language
3824 (*note Expressions: Expressions.). A breakpoint with a condition
3825 evaluates the expression each time your program reaches it, and your
3826 program stops only if the condition is _true_.
3828 This is the converse of using assertions for program validation; in
3829 that situation, you want to stop when the assertion is violated--that
3830 is, when the condition is false. In C, if you want to test an assertion
3831 expressed by the condition ASSERT, you should set the condition '!
3832 ASSERT' on the appropriate breakpoint.
3834 Conditions are also accepted for watchpoints; you may not need them,
3835 since a watchpoint is inspecting the value of an expression anyhow--but
3836 it might be simpler, say, to just set a watchpoint on a variable name,
3837 and specify a condition that tests whether the new value is an
3840 Break conditions can have side effects, and may even call functions
3841 in your program. This can be useful, for example, to activate functions
3842 that log program progress, or to use your own print functions to format
3843 special data structures. The effects are completely predictable unless
3844 there is another enabled breakpoint at the same address. (In that case,
3845 GDB might see the other breakpoint first and stop your program without
3846 checking the condition of this one.) Note that breakpoint commands are
3847 usually more convenient and flexible than break conditions for the
3848 purpose of performing side effects when a breakpoint is reached (*note
3849 Breakpoint Command Lists: Break Commands.).
3851 Breakpoint conditions can also be evaluated on the target's side if
3852 the target supports it. Instead of evaluating the conditions locally,
3853 GDB encodes the expression into an agent expression (*note Agent
3854 Expressions::) suitable for execution on the target, independently of
3855 GDB. Global variables become raw memory locations, locals become stack
3856 accesses, and so forth.
3858 In this case, GDB will only be notified of a breakpoint trigger when
3859 its condition evaluates to true. This mechanism may provide faster
3860 response times depending on the performance characteristics of the
3861 target since it does not need to keep GDB informed about every
3862 breakpoint trigger, even those with false conditions.
3864 Break conditions can be specified when a breakpoint is set, by using
3865 'if' in the arguments to the 'break' command. *Note Setting
3866 Breakpoints: Set Breaks. They can also be changed at any time with the
3867 'condition' command.
3869 You can also use the 'if' keyword with the 'watch' command. The
3870 'catch' command does not recognize the 'if' keyword; 'condition' is the
3871 only way to impose a further condition on a catchpoint.
3873 'condition BNUM EXPRESSION'
3874 Specify EXPRESSION as the break condition for breakpoint,
3875 watchpoint, or catchpoint number BNUM. After you set a condition,
3876 breakpoint BNUM stops your program only if the value of EXPRESSION
3877 is true (nonzero, in C). When you use 'condition', GDB checks
3878 EXPRESSION immediately for syntactic correctness, and to determine
3879 whether symbols in it have referents in the context of your
3880 breakpoint. If EXPRESSION uses symbols not referenced in the
3881 context of the breakpoint, GDB prints an error message:
3883 No symbol "foo" in current context.
3885 GDB does not actually evaluate EXPRESSION at the time the
3886 'condition' command (or a command that sets a breakpoint with a
3887 condition, like 'break if ...') is given, however. *Note
3888 Expressions: Expressions.
3891 Remove the condition from breakpoint number BNUM. It becomes an
3892 ordinary unconditional breakpoint.
3894 A special case of a breakpoint condition is to stop only when the
3895 breakpoint has been reached a certain number of times. This is so
3896 useful that there is a special way to do it, using the "ignore count" of
3897 the breakpoint. Every breakpoint has an ignore count, which is an
3898 integer. Most of the time, the ignore count is zero, and therefore has
3899 no effect. But if your program reaches a breakpoint whose ignore count
3900 is positive, then instead of stopping, it just decrements the ignore
3901 count by one and continues. As a result, if the ignore count value is
3902 N, the breakpoint does not stop the next N times your program reaches
3906 Set the ignore count of breakpoint number BNUM to COUNT. The next
3907 COUNT times the breakpoint is reached, your program's execution
3908 does not stop; other than to decrement the ignore count, GDB takes
3911 To make the breakpoint stop the next time it is reached, specify a
3914 When you use 'continue' to resume execution of your program from a
3915 breakpoint, you can specify an ignore count directly as an argument
3916 to 'continue', rather than using 'ignore'. *Note Continuing and
3917 Stepping: Continuing and Stepping.
3919 If a breakpoint has a positive ignore count and a condition, the
3920 condition is not checked. Once the ignore count reaches zero, GDB
3921 resumes checking the condition.
3923 You could achieve the effect of the ignore count with a condition
3924 such as '$foo-- <= 0' using a debugger convenience variable that is
3925 decremented each time. *Note Convenience Variables: Convenience
3928 Ignore counts apply to breakpoints, watchpoints, and catchpoints.
3931 File: gdb.info, Node: Break Commands, Next: Dynamic Printf, Prev: Conditions, Up: Breakpoints
3933 5.1.7 Breakpoint Command Lists
3934 ------------------------------
3936 You can give any breakpoint (or watchpoint or catchpoint) a series of
3937 commands to execute when your program stops due to that breakpoint. For
3938 example, you might want to print the values of certain expressions, or
3939 enable other breakpoints.
3941 'commands [RANGE...]'
3942 '... COMMAND-LIST ...'
3944 Specify a list of commands for the given breakpoints. The commands
3945 themselves appear on the following lines. Type a line containing
3946 just 'end' to terminate the commands.
3948 To remove all commands from a breakpoint, type 'commands' and
3949 follow it immediately with 'end'; that is, give no commands.
3951 With no argument, 'commands' refers to the last breakpoint,
3952 watchpoint, or catchpoint set (not to the breakpoint most recently
3953 encountered). If the most recent breakpoints were set with a
3954 single command, then the 'commands' will apply to all the
3955 breakpoints set by that command. This applies to breakpoints set
3956 by 'rbreak', and also applies when a single 'break' command creates
3957 multiple breakpoints (*note Ambiguous Expressions: Ambiguous
3960 Pressing <RET> as a means of repeating the last GDB command is
3961 disabled within a COMMAND-LIST.
3963 You can use breakpoint commands to start your program up again.
3964 Simply use the 'continue' command, or 'step', or any other command that
3967 Any other commands in the command list, after a command that resumes
3968 execution, are ignored. This is because any time you resume execution
3969 (even with a simple 'next' or 'step'), you may encounter another
3970 breakpoint--which could have its own command list, leading to
3971 ambiguities about which list to execute.
3973 If the first command you specify in a command list is 'silent', the
3974 usual message about stopping at a breakpoint is not printed. This may
3975 be desirable for breakpoints that are to print a specific message and
3976 then continue. If none of the remaining commands print anything, you
3977 see no sign that the breakpoint was reached. 'silent' is meaningful
3978 only at the beginning of a breakpoint command list.
3980 The commands 'echo', 'output', and 'printf' allow you to print
3981 precisely controlled output, and are often useful in silent breakpoints.
3982 *Note Commands for Controlled Output: Output.
3984 For example, here is how you could use breakpoint commands to print
3985 the value of 'x' at entry to 'foo' whenever 'x' is positive.
3990 printf "x is %d\n",x
3994 One application for breakpoint commands is to compensate for one bug
3995 so you can test for another. Put a breakpoint just after the erroneous
3996 line of code, give it a condition to detect the case in which something
3997 erroneous has been done, and give it commands to assign correct values
3998 to any variables that need them. End with the 'continue' command so
3999 that your program does not stop, and start with the 'silent' command so
4000 that no output is produced. Here is an example:
4010 File: gdb.info, Node: Dynamic Printf, Next: Save Breakpoints, Prev: Break Commands, Up: Breakpoints
4012 5.1.8 Dynamic Printf
4013 --------------------
4015 The dynamic printf command 'dprintf' combines a breakpoint with
4016 formatted printing of your program's data to give you the effect of
4017 inserting 'printf' calls into your program on-the-fly, without having to
4020 In its most basic form, the output goes to the GDB console. However,
4021 you can set the variable 'dprintf-style' for alternate handling. For
4022 instance, you can ask to format the output by calling your program's
4023 'printf' function. This has the advantage that the characters go to the
4024 program's output device, so they can recorded in redirects to files and
4027 If you are doing remote debugging with a stub or agent, you can also
4028 ask to have the printf handled by the remote agent. In addition to
4029 ensuring that the output goes to the remote program's device along with
4030 any other output the program might produce, you can also ask that the
4031 dprintf remain active even after disconnecting from the remote target.
4032 Using the stub/agent is also more efficient, as it can do everything
4033 without needing to communicate with GDB.
4035 'dprintf LOCATION,TEMPLATE,EXPRESSION[,EXPRESSION...]'
4036 Whenever execution reaches LOCATION, print the values of one or
4037 more EXPRESSIONS under the control of the string TEMPLATE. To
4038 print several values, separate them with commas.
4040 'set dprintf-style STYLE'
4041 Set the dprintf output to be handled in one of several different
4042 styles enumerated below. A change of style affects all existing
4043 dynamic printfs immediately. (If you need individual control over
4044 the print commands, simply define normal breakpoints with
4045 explicitly-supplied command lists.)
4048 Handle the output using the GDB 'printf' command.
4051 Handle the output by calling a function in your program (normally
4055 Have the remote debugging agent (such as 'gdbserver') handle the
4056 output itself. This style is only available for agents that
4057 support running commands on the target.
4059 'set dprintf-function FUNCTION'
4060 Set the function to call if the dprintf style is 'call'. By
4061 default its value is 'printf'. You may set it to any expression.
4062 that GDB can evaluate to a function, as per the 'call' command.
4064 'set dprintf-channel CHANNEL'
4065 Set a "channel" for dprintf. If set to a non-empty value, GDB will
4066 evaluate it as an expression and pass the result as a first
4067 argument to the 'dprintf-function', in the manner of 'fprintf' and
4068 similar functions. Otherwise, the dprintf format string will be
4069 the first argument, in the manner of 'printf'.
4071 As an example, if you wanted 'dprintf' output to go to a logfile
4072 that is a standard I/O stream assigned to the variable 'mylog', you
4073 could do the following:
4075 (gdb) set dprintf-style call
4076 (gdb) set dprintf-function fprintf
4077 (gdb) set dprintf-channel mylog
4078 (gdb) dprintf 25,"at line 25, glob=%d\n",glob
4079 Dprintf 1 at 0x123456: file main.c, line 25.
4081 1 dprintf keep y 0x00123456 in main at main.c:25
4082 call (void) fprintf (mylog,"at line 25, glob=%d\n",glob)
4086 Note that the 'info break' displays the dynamic printf commands as
4087 normal breakpoint commands; you can thus easily see the effect of
4088 the variable settings.
4090 'set disconnected-dprintf on'
4091 'set disconnected-dprintf off'
4092 Choose whether 'dprintf' commands should continue to run if GDB has
4093 disconnected from the target. This only applies if the
4094 'dprintf-style' is 'agent'.
4096 'show disconnected-dprintf off'
4097 Show the current choice for disconnected 'dprintf'.
4099 GDB does not check the validity of function and channel, relying on
4100 you to supply values that are meaningful for the contexts in which they
4101 are being used. For instance, the function and channel may be the
4102 values of local variables, but if that is the case, then all enabled
4103 dynamic prints must be at locations within the scope of those locals.
4104 If evaluation fails, GDB will report an error.
4107 File: gdb.info, Node: Save Breakpoints, Next: Static Probe Points, Prev: Dynamic Printf, Up: Breakpoints
4109 5.1.9 How to save breakpoints to a file
4110 ---------------------------------------
4112 To save breakpoint definitions to a file use the 'save breakpoints'
4115 'save breakpoints [FILENAME]'
4116 This command saves all current breakpoint definitions together with
4117 their commands and ignore counts, into a file 'FILENAME' suitable
4118 for use in a later debugging session. This includes all types of
4119 breakpoints (breakpoints, watchpoints, catchpoints, tracepoints).
4120 To read the saved breakpoint definitions, use the 'source' command
4121 (*note Command Files::). Note that watchpoints with expressions
4122 involving local variables may fail to be recreated because it may
4123 not be possible to access the context where the watchpoint is valid
4124 anymore. Because the saved breakpoint definitions are simply a
4125 sequence of GDB commands that recreate the breakpoints, you can
4126 edit the file in your favorite editing program, and remove the
4127 breakpoint definitions you're not interested in, or that can no
4128 longer be recreated.
4131 File: gdb.info, Node: Static Probe Points, Next: Error in Breakpoints, Prev: Save Breakpoints, Up: Breakpoints
4133 5.1.10 Static Probe Points
4134 --------------------------
4136 GDB supports "SDT" probes in the code. SDT stands for Statically
4137 Defined Tracing, and the probes are designed to have a tiny runtime code
4138 and data footprint, and no dynamic relocations. They are usable from
4139 assembly, C and C++ languages. See
4140 <http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation> for
4141 a good reference on how the SDT probes are implemented.
4143 Currently, 'SystemTap' (<http://sourceware.org/systemtap/>) SDT
4144 probes are supported on ELF-compatible systems. See
4145 <http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps> for
4146 more information on how to add 'SystemTap' SDT probes in your
4149 Some probes have an associated semaphore variable; for instance, this
4150 happens automatically if you defined your probe using a DTrace-style
4151 '.d' file. If your probe has a semaphore, GDB will automatically enable
4152 it when you specify a breakpoint using the '-probe-stap' notation. But,
4153 if you put a breakpoint at a probe's location by some other method
4154 (e.g., 'break file:line'), then GDB will not automatically set the
4157 You can examine the available static static probes using 'info
4158 probes', with optional arguments:
4160 'info probes stap [PROVIDER [NAME [OBJFILE]]]'
4161 If given, PROVIDER is a regular expression used to match against
4162 provider names when selecting which probes to list. If omitted,
4163 probes by all probes from all providers are listed.
4165 If given, NAME is a regular expression to match against probe names
4166 when selecting which probes to list. If omitted, probe names are
4167 not considered when deciding whether to display them.
4169 If given, OBJFILE is a regular expression used to select which
4170 object files (executable or shared libraries) to examine. If not
4171 given, all object files are considered.
4174 List the available static probes, from all types.
4176 A probe may specify up to twelve arguments. These are available at
4177 the point at which the probe is defined--that is, when the current PC is
4178 at the probe's location. The arguments are available using the
4179 convenience variables (*note Convenience Vars::)
4180 '$_probe_arg0'...'$_probe_arg11'. Each probe argument is an integer of
4181 the appropriate size; types are not preserved. The convenience variable
4182 '$_probe_argc' holds the number of arguments at the current probe point.
4184 These variables are always available, but attempts to access them at
4185 any location other than a probe point will cause GDB to give an error
4189 File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Static Probe Points, Up: Breakpoints
4191 5.1.11 "Cannot insert breakpoints"
4192 ----------------------------------
4194 If you request too many active hardware-assisted breakpoints and
4195 watchpoints, you will see this error message:
4197 Stopped; cannot insert breakpoints.
4198 You may have requested too many hardware breakpoints and watchpoints.
4200 This message is printed when you attempt to resume the program, since
4201 only then GDB knows exactly how many hardware breakpoints and
4202 watchpoints it needs to insert.
4204 When this message is printed, you need to disable or remove some of
4205 the hardware-assisted breakpoints and watchpoints, and then continue.
4208 File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints
4210 5.1.12 "Breakpoint address adjusted..."
4211 ---------------------------------------
4213 Some processor architectures place constraints on the addresses at which
4214 breakpoints may be placed. For architectures thus constrained, GDB will
4215 attempt to adjust the breakpoint's address to comply with the
4216 constraints dictated by the architecture.
4218 One example of such an architecture is the Fujitsu FR-V. The FR-V is
4219 a VLIW architecture in which a number of RISC-like instructions may be
4220 bundled together for parallel execution. The FR-V architecture
4221 constrains the location of a breakpoint instruction within such a bundle
4222 to the instruction with the lowest address. GDB honors this constraint
4223 by adjusting a breakpoint's address to the first in the bundle.
4225 It is not uncommon for optimized code to have bundles which contain
4226 instructions from different source statements, thus it may happen that a
4227 breakpoint's address will be adjusted from one source statement to
4228 another. Since this adjustment may significantly alter GDB's breakpoint
4229 related behavior from what the user expects, a warning is printed when
4230 the breakpoint is first set and also when the breakpoint is hit.
4232 A warning like the one below is printed when setting a breakpoint
4233 that's been subject to address adjustment:
4235 warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
4237 Such warnings are printed both for user settable and GDB's internal
4238 breakpoints. If you see one of these warnings, you should verify that a
4239 breakpoint set at the adjusted address will have the desired affect. If
4240 not, the breakpoint in question may be removed and other breakpoints may
4241 be set which will have the desired behavior. E.g., it may be sufficient
4242 to place the breakpoint at a later instruction. A conditional
4243 breakpoint may also be useful in some cases to prevent the breakpoint
4244 from triggering too often.
4246 GDB will also issue a warning when stopping at one of these adjusted
4249 warning: Breakpoint 1 address previously adjusted from 0x00010414
4252 When this warning is encountered, it may be too late to take remedial
4253 action except in cases where the breakpoint is hit earlier or more
4254 frequently than expected.
4257 File: gdb.info, Node: Continuing and Stepping, Next: Skipping Over Functions and Files, Prev: Breakpoints, Up: Stopping
4259 5.2 Continuing and Stepping
4260 ===========================
4262 "Continuing" means resuming program execution until your program
4263 completes normally. In contrast, "stepping" means executing just one
4264 more "step" of your program, where "step" may mean either one line of
4265 source code, or one machine instruction (depending on what particular
4266 command you use). Either when continuing or when stepping, your program
4267 may stop even sooner, due to a breakpoint or a signal. (If it stops due
4268 to a signal, you may want to use 'handle', or use 'signal 0' to resume
4269 execution. *Note Signals: Signals.)
4271 'continue [IGNORE-COUNT]'
4274 Resume program execution, at the address where your program last
4275 stopped; any breakpoints set at that address are bypassed. The
4276 optional argument IGNORE-COUNT allows you to specify a further
4277 number of times to ignore a breakpoint at this location; its effect
4278 is like that of 'ignore' (*note Break Conditions: Conditions.).
4280 The argument IGNORE-COUNT is meaningful only when your program
4281 stopped due to a breakpoint. At other times, the argument to
4282 'continue' is ignored.
4284 The synonyms 'c' and 'fg' (for "foreground", as the debugged
4285 program is deemed to be the foreground program) are provided purely
4286 for convenience, and have exactly the same behavior as 'continue'.
4288 To resume execution at a different place, you can use 'return' (*note
4289 Returning from a Function: Returning.) to go back to the calling
4290 function; or 'jump' (*note Continuing at a Different Address: Jumping.)
4291 to go to an arbitrary location in your program.
4293 A typical technique for using stepping is to set a breakpoint (*note
4294 Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the
4295 beginning of the function or the section of your program where a problem
4296 is believed to lie, run your program until it stops at that breakpoint,
4297 and then step through the suspect area, examining the variables that are
4298 interesting, until you see the problem happen.
4301 Continue running your program until control reaches a different
4302 source line, then stop it and return control to GDB. This command
4305 _Warning:_ If you use the 'step' command while control is
4306 within a function that was compiled without debugging
4307 information, execution proceeds until control reaches a
4308 function that does have debugging information. Likewise, it
4309 will not step into a function which is compiled without
4310 debugging information. To step through functions without
4311 debugging information, use the 'stepi' command, described
4314 The 'step' command only stops at the first instruction of a source
4315 line. This prevents the multiple stops that could otherwise occur
4316 in 'switch' statements, 'for' loops, etc. 'step' continues to stop
4317 if a function that has debugging information is called within the
4318 line. In other words, 'step' _steps inside_ any functions called
4321 Also, the 'step' command only enters a function if there is line
4322 number information for the function. Otherwise it acts like the
4323 'next' command. This avoids problems when using 'cc -gl' on MIPS
4324 machines. Previously, 'step' entered subroutines if there was any
4325 debugging information about the routine.
4328 Continue running as in 'step', but do so COUNT times. If a
4329 breakpoint is reached, or a signal not related to stepping occurs
4330 before COUNT steps, stepping stops right away.
4333 Continue to the next source line in the current (innermost) stack
4334 frame. This is similar to 'step', but function calls that appear
4335 within the line of code are executed without stopping. Execution
4336 stops when control reaches a different line of code at the original
4337 stack level that was executing when you gave the 'next' command.
4338 This command is abbreviated 'n'.
4340 An argument COUNT is a repeat count, as for 'step'.
4342 The 'next' command only stops at the first instruction of a source
4343 line. This prevents multiple stops that could otherwise occur in
4344 'switch' statements, 'for' loops, etc.
4348 The 'set step-mode on' command causes the 'step' command to stop at
4349 the first instruction of a function which contains no debug line
4350 information rather than stepping over it.
4352 This is useful in cases where you may be interested in inspecting
4353 the machine instructions of a function which has no symbolic info
4354 and do not want GDB to automatically skip over this function.
4357 Causes the 'step' command to step over any functions which contains
4358 no debug information. This is the default.
4361 Show whether GDB will stop in or step over functions without source
4362 line debug information.
4365 Continue running until just after function in the selected stack
4366 frame returns. Print the returned value (if any). This command
4367 can be abbreviated as 'fin'.
4369 Contrast this with the 'return' command (*note Returning from a
4370 Function: Returning.).
4374 Continue running until a source line past the current line, in the
4375 current stack frame, is reached. This command is used to avoid
4376 single stepping through a loop more than once. It is like the
4377 'next' command, except that when 'until' encounters a jump, it
4378 automatically continues execution until the program counter is
4379 greater than the address of the jump.
4381 This means that when you reach the end of a loop after single
4382 stepping though it, 'until' makes your program continue execution
4383 until it exits the loop. In contrast, a 'next' command at the end
4384 of a loop simply steps back to the beginning of the loop, which
4385 forces you to step through the next iteration.
4387 'until' always stops your program if it attempts to exit the
4388 current stack frame.
4390 'until' may produce somewhat counterintuitive results if the order
4391 of machine code does not match the order of the source lines. For
4392 example, in the following excerpt from a debugging session, the 'f'
4393 ('frame') command shows that execution is stopped at line '206';
4394 yet when we use 'until', we get to line '195':
4397 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206
4400 195 for ( ; argc > 0; NEXTARG) {
4402 This happened because, for execution efficiency, the compiler had
4403 generated code for the loop closure test at the end, rather than
4404 the start, of the loop--even though the test in a C 'for'-loop is
4405 written before the body of the loop. The 'until' command appeared
4406 to step back to the beginning of the loop when it advanced to this
4407 expression; however, it has not really gone to an earlier
4408 statement--not in terms of the actual machine code.
4410 'until' with no argument works by means of single instruction
4411 stepping, and hence is slower than 'until' with an argument.
4415 Continue running your program until either the specified LOCATION
4416 is reached, or the current stack frame returns. The location is
4417 any of the forms described in *note Specify Location::. This form
4418 of the command uses temporary breakpoints, and hence is quicker
4419 than 'until' without an argument. The specified location is
4420 actually reached only if it is in the current frame. This implies
4421 that 'until' can be used to skip over recursive function
4422 invocations. For instance in the code below, if the current
4423 location is line '96', issuing 'until 99' will execute the program
4424 up to line '99' in the same invocation of factorial, i.e., after
4425 the inner invocations have returned.
4427 94 int factorial (int value)
4430 97 value *= factorial (value - 1);
4436 Continue running the program up to the given LOCATION. An argument
4437 is required, which should be of one of the forms described in *note
4438 Specify Location::. Execution will also stop upon exit from the
4439 current stack frame. This command is similar to 'until', but
4440 'advance' will not skip over recursive function calls, and the
4441 target location doesn't have to be in the same frame as the current
4447 Execute one machine instruction, then stop and return to the
4450 It is often useful to do 'display/i $pc' when stepping by machine
4451 instructions. This makes GDB automatically display the next
4452 instruction to be executed, each time your program stops. *Note
4453 Automatic Display: Auto Display.
4455 An argument is a repeat count, as in 'step'.
4460 Execute one machine instruction, but if it is a function call,
4461 proceed until the function returns.
4463 An argument is a repeat count, as in 'next'.
4465 By default, and if available, GDB makes use of target-assisted "range
4466 stepping". In other words, whenever you use a stepping command (e.g.,
4467 'step', 'next'), GDB tells the target to step the corresponding range of
4468 instruction addresses instead of issuing multiple single-steps. This
4469 speeds up line stepping, particularly for remote targets. Ideally,
4470 there should be no reason you would want to turn range stepping off.
4471 However, it's possible that a bug in the debug info, a bug in the remote
4472 stub (for remote targets), or even a bug in GDB could make line stepping
4473 behave incorrectly when target-assisted range stepping is enabled. You
4474 can use the following command to turn off range stepping if necessary:
4476 'set range-stepping'
4477 'show range-stepping'
4478 Control whether range stepping is enabled.
4480 If 'on', and the target supports it, GDB tells the target to step a
4481 range of addresses itself, instead of issuing multiple
4482 single-steps. If 'off', GDB always issues single-steps, even if
4483 range stepping is supported by the target. The default is 'on'.
4486 File: gdb.info, Node: Skipping Over Functions and Files, Next: Signals, Prev: Continuing and Stepping, Up: Stopping
4488 5.3 Skipping Over Functions and Files
4489 =====================================
4491 The program you are debugging may contain some functions which are
4492 uninteresting to debug. The 'skip' comand lets you tell GDB to skip a
4493 function or all functions in a file when stepping.
4495 For example, consider the following C function:
4503 Suppose you wish to step into the functions 'foo' and 'bar', but you are
4504 not interested in stepping through 'boring'. If you run 'step' at line
4505 103, you'll enter 'boring()', but if you run 'next', you'll step over
4506 both 'foo' and 'boring'!
4508 One solution is to 'step' into 'boring' and use the 'finish' command
4509 to immediately exit it. But this can become tedious if 'boring' is
4510 called from many places.
4512 A more flexible solution is to execute 'skip boring'. This instructs
4513 GDB never to step into 'boring'. Now when you execute 'step' at line
4514 103, you'll step over 'boring' and directly into 'foo'.
4516 You can also instruct GDB to skip all functions in a file, with, for
4517 example, 'skip file boring.c'.
4520 'skip function [LINESPEC]'
4521 After running this command, the function named by LINESPEC or the
4522 function containing the line named by LINESPEC will be skipped over
4523 when stepping. *Note Specify Location::.
4525 If you do not specify LINESPEC, the function you're currently
4526 debugging will be skipped.
4528 (If you have a function called 'file' that you want to skip, use
4529 'skip function file'.)
4531 'skip file [FILENAME]'
4532 After running this command, any function whose source lives in
4533 FILENAME will be skipped over when stepping.
4535 If you do not specify FILENAME, functions whose source lives in the
4536 file you're currently debugging will be skipped.
4538 Skips can be listed, deleted, disabled, and enabled, much like
4539 breakpoints. These are the commands for managing your list of skips:
4542 Print details about the specified skip(s). If RANGE is not
4543 specified, print a table with details about all functions and files
4544 marked for skipping. 'info skip' prints the following information
4548 A number identifying this skip.
4550 The type of this skip, either 'function' or 'file'.
4551 _Enabled or Disabled_
4552 Enabled skips are marked with 'y'. Disabled skips are marked
4555 For function skips, this column indicates the address in
4556 memory of the function being skipped. If you've set a
4557 function skip on a function which has not yet been loaded,
4558 this field will contain '<PENDING>'. Once a shared library
4559 which has the function is loaded, 'info skip' will show the
4560 function's address here.
4562 For file skips, this field contains the filename being
4563 skipped. For functions skips, this field contains the
4564 function name and its line number in the file where it is
4567 'skip delete [RANGE]'
4568 Delete the specified skip(s). If RANGE is not specified, delete
4571 'skip enable [RANGE]'
4572 Enable the specified skip(s). If RANGE is not specified, enable
4575 'skip disable [RANGE]'
4576 Disable the specified skip(s). If RANGE is not specified, disable
4580 File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Skipping Over Functions and Files, Up: Stopping
4585 A signal is an asynchronous event that can happen in a program. The
4586 operating system defines the possible kinds of signals, and gives each
4587 kind a name and a number. For example, in Unix 'SIGINT' is the signal a
4588 program gets when you type an interrupt character (often 'Ctrl-c');
4589 'SIGSEGV' is the signal a program gets from referencing a place in
4590 memory far away from all the areas in use; 'SIGALRM' occurs when the
4591 alarm clock timer goes off (which happens only if your program has
4592 requested an alarm).
4594 Some signals, including 'SIGALRM', are a normal part of the
4595 functioning of your program. Others, such as 'SIGSEGV', indicate
4596 errors; these signals are "fatal" (they kill your program immediately)
4597 if the program has not specified in advance some other way to handle the
4598 signal. 'SIGINT' does not indicate an error in your program, but it is
4599 normally fatal so it can carry out the purpose of the interrupt: to kill
4602 GDB has the ability to detect any occurrence of a signal in your
4603 program. You can tell GDB in advance what to do for each kind of
4606 Normally, GDB is set up to let the non-erroneous signals like
4607 'SIGALRM' be silently passed to your program (so as not to interfere
4608 with their role in the program's functioning) but to stop your program
4609 immediately whenever an error signal happens. You can change these
4610 settings with the 'handle' command.
4614 Print a table of all the kinds of signals and how GDB has been told
4615 to handle each one. You can use this to see the signal numbers of
4616 all the defined types of signals.
4619 Similar, but print information only about the specified signal
4622 'info handle' is an alias for 'info signals'.
4624 'catch signal [SIGNAL... | 'all']'
4625 Set a catchpoint for the indicated signals. *Note Set
4626 Catchpoints::, for details about this command.
4628 'handle SIGNAL [KEYWORDS...]'
4629 Change the way GDB handles signal SIGNAL. The SIGNAL can be the
4630 number of a signal or its name (with or without the 'SIG' at the
4631 beginning); a list of signal numbers of the form 'LOW-HIGH'; or the
4632 word 'all', meaning all the known signals. Optional arguments
4633 KEYWORDS, described below, say what change to make.
4635 The keywords allowed by the 'handle' command can be abbreviated.
4636 Their full names are:
4639 GDB should not stop your program when this signal happens. It may
4640 still print a message telling you that the signal has come in.
4643 GDB should stop your program when this signal happens. This
4644 implies the 'print' keyword as well.
4647 GDB should print a message when this signal happens.
4650 GDB should not mention the occurrence of the signal at all. This
4651 implies the 'nostop' keyword as well.
4655 GDB should allow your program to see this signal; your program can
4656 handle the signal, or else it may terminate if the signal is fatal
4657 and not handled. 'pass' and 'noignore' are synonyms.
4661 GDB should not allow your program to see this signal. 'nopass' and
4662 'ignore' are synonyms.
4664 When a signal stops your program, the signal is not visible to the
4665 program until you continue. Your program sees the signal then, if
4666 'pass' is in effect for the signal in question _at that time_. In other
4667 words, after GDB reports a signal, you can use the 'handle' command with
4668 'pass' or 'nopass' to control whether your program sees that signal when
4671 The default is set to 'nostop', 'noprint', 'pass' for non-erroneous
4672 signals such as 'SIGALRM', 'SIGWINCH' and 'SIGCHLD', and to 'stop',
4673 'print', 'pass' for the erroneous signals.
4675 You can also use the 'signal' command to prevent your program from
4676 seeing a signal, or cause it to see a signal it normally would not see,
4677 or to give it any signal at any time. For example, if your program
4678 stopped due to some sort of memory reference error, you might store
4679 correct values into the erroneous variables and continue, hoping to see
4680 more execution; but your program would probably terminate immediately as
4681 a result of the fatal signal once it saw the signal. To prevent this,
4682 you can continue with 'signal 0'. *Note Giving your Program a Signal:
4685 On some targets, GDB can inspect extra signal information associated
4686 with the intercepted signal, before it is actually delivered to the
4687 program being debugged. This information is exported by the convenience
4688 variable '$_siginfo', and consists of data that is passed by the kernel
4689 to the signal handler at the time of the receipt of a signal. The data
4690 type of the information itself is target dependent. You can see the
4691 data type using the 'ptype $_siginfo' command. On Unix systems, it
4692 typically corresponds to the standard 'siginfo_t' type, as defined in
4693 the 'signal.h' system header.
4695 Here's an example, on a GNU/Linux system, printing the stray
4696 referenced address that raised a segmentation fault.
4699 Program received signal SIGSEGV, Segmentation fault.
4700 0x0000000000400766 in main ()
4702 (gdb) ptype $_siginfo
4710 struct {...} _timer;
4712 struct {...} _sigchld;
4713 struct {...} _sigfault;
4714 struct {...} _sigpoll;
4717 (gdb) ptype $_siginfo._sifields._sigfault
4721 (gdb) p $_siginfo._sifields._sigfault.si_addr
4722 $1 = (void *) 0x7ffff7ff7000
4724 Depending on target support, '$_siginfo' may also be writable.
4727 File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping
4729 5.5 Stopping and Starting Multi-thread Programs
4730 ===============================================
4732 GDB supports debugging programs with multiple threads (*note Debugging
4733 Programs with Multiple Threads: Threads.). There are two modes of
4734 controlling execution of your program within the debugger. In the
4735 default mode, referred to as "all-stop mode", when any thread in your
4736 program stops (for example, at a breakpoint or while being stepped), all
4737 other threads in the program are also stopped by GDB. On some targets,
4738 GDB also supports "non-stop mode", in which other threads can continue
4739 to run freely while you examine the stopped thread in the debugger.
4743 * All-Stop Mode:: All threads stop when GDB takes control
4744 * Non-Stop Mode:: Other threads continue to execute
4745 * Background Execution:: Running your program asynchronously
4746 * Thread-Specific Breakpoints:: Controlling breakpoints
4747 * Interrupted System Calls:: GDB may interfere with system calls
4748 * Observer Mode:: GDB does not alter program behavior
4751 File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops
4756 In all-stop mode, whenever your program stops under GDB for any reason,
4757 _all_ threads of execution stop, not just the current thread. This
4758 allows you to examine the overall state of the program, including
4759 switching between threads, without worrying that things may change
4762 Conversely, whenever you restart the program, _all_ threads start
4763 executing. _This is true even when single-stepping_ with commands like
4766 In particular, GDB cannot single-step all threads in lockstep. Since
4767 thread scheduling is up to your debugging target's operating system (not
4768 controlled by GDB), other threads may execute more than one statement
4769 while the current thread completes a single step. Moreover, in general
4770 other threads stop in the middle of a statement, rather than at a clean
4771 statement boundary, when the program stops.
4773 You might even find your program stopped in another thread after
4774 continuing or even single-stepping. This happens whenever some other
4775 thread runs into a breakpoint, a signal, or an exception before the
4776 first thread completes whatever you requested.
4778 Whenever GDB stops your program, due to a breakpoint or a signal, it
4779 automatically selects the thread where that breakpoint or signal
4780 happened. GDB alerts you to the context switch with a message such as
4781 '[Switching to Thread N]' to identify the thread.
4783 On some OSes, you can modify GDB's default behavior by locking the OS
4784 scheduler to allow only a single thread to run.
4786 'set scheduler-locking MODE'
4787 Set the scheduler locking mode. If it is 'off', then there is no
4788 locking and any thread may run at any time. If 'on', then only the
4789 current thread may run when the inferior is resumed. The 'step'
4790 mode optimizes for single-stepping; it prevents other threads from
4791 preempting the current thread while you are stepping, so that the
4792 focus of debugging does not change unexpectedly. Other threads
4793 only rarely (or never) get a chance to run when you step. They are
4794 more likely to run when you 'next' over a function call, and they
4795 are completely free to run when you use commands like 'continue',
4796 'until', or 'finish'. However, unless another thread hits a
4797 breakpoint during its timeslice, GDB does not change the current
4798 thread away from the thread that you are debugging.
4800 'show scheduler-locking'
4801 Display the current scheduler locking mode.
4803 By default, when you issue one of the execution commands such as
4804 'continue', 'next' or 'step', GDB allows only threads of the current
4805 inferior to run. For example, if GDB is attached to two inferiors, each
4806 with two threads, the 'continue' command resumes only the two threads of
4807 the current inferior. This is useful, for example, when you debug a
4808 program that forks and you want to hold the parent stopped (so that, for
4809 instance, it doesn't run to exit), while you debug the child. In other
4810 situations, you may not be interested in inspecting the current state of
4811 any of the processes GDB is attached to, and you may want to resume them
4812 all until some breakpoint is hit. In the latter case, you can instruct
4813 GDB to allow all threads of all the inferiors to run with the 'set schedule-multiple'
4816 'set schedule-multiple'
4817 Set the mode for allowing threads of multiple processes to be
4818 resumed when an execution command is issued. When 'on', all
4819 threads of all processes are allowed to run. When 'off', only the
4820 threads of the current process are resumed. The default is 'off'.
4821 The 'scheduler-locking' mode takes precedence when set to 'on', or
4822 while you are stepping and set to 'step'.
4824 'show schedule-multiple'
4825 Display the current mode for resuming the execution of threads of
4829 File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops
4834 For some multi-threaded targets, GDB supports an optional mode of
4835 operation in which you can examine stopped program threads in the
4836 debugger while other threads continue to execute freely. This minimizes
4837 intrusion when debugging live systems, such as programs where some
4838 threads have real-time constraints or must continue to respond to
4839 external events. This is referred to as "non-stop" mode.
4841 In non-stop mode, when a thread stops to report a debugging event,
4842 _only_ that thread is stopped; GDB does not stop other threads as well,
4843 in contrast to the all-stop mode behavior. Additionally, execution
4844 commands such as 'continue' and 'step' apply by default only to the
4845 current thread in non-stop mode, rather than all threads as in all-stop
4846 mode. This allows you to control threads explicitly in ways that are
4847 not possible in all-stop mode -- for example, stepping one thread while
4848 allowing others to run freely, stepping one thread while holding all
4849 others stopped, or stepping several threads independently and
4852 To enter non-stop mode, use this sequence of commands before you run
4853 or attach to your program:
4855 # If using the CLI, pagination breaks non-stop.
4858 # Finally, turn it on!
4861 You can use these commands to manipulate the non-stop mode setting:
4864 Enable selection of non-stop mode.
4866 Disable selection of non-stop mode.
4868 Show the current non-stop enablement setting.
4870 Note these commands only reflect whether non-stop mode is enabled,
4871 not whether the currently-executing program is being run in non-stop
4872 mode. In particular, the 'set non-stop' preference is only consulted
4873 when GDB starts or connects to the target program, and it is generally
4874 not possible to switch modes once debugging has started. Furthermore,
4875 since not all targets support non-stop mode, even when you have enabled
4876 non-stop mode, GDB may still fall back to all-stop operation by default.
4878 In non-stop mode, all execution commands apply only to the current
4879 thread by default. That is, 'continue' only continues one thread. To
4880 continue all threads, issue 'continue -a' or 'c -a'.
4882 You can use GDB's background execution commands (*note Background
4883 Execution::) to run some threads in the background while you continue to
4884 examine or step others from GDB. The MI execution commands (*note
4885 GDB/MI Program Execution::) are always executed asynchronously in
4888 Suspending execution is done with the 'interrupt' command when
4889 running in the background, or 'Ctrl-c' during foreground execution. In
4890 all-stop mode, this stops the whole process; but in non-stop mode the
4891 interrupt applies only to the current thread. To stop the whole
4892 program, use 'interrupt -a'.
4894 Other execution commands do not currently support the '-a' option.
4896 In non-stop mode, when a thread stops, GDB doesn't automatically make
4897 that thread current, as it does in all-stop mode. This is because the
4898 thread stop notifications are asynchronous with respect to GDB's command
4899 interpreter, and it would be confusing if GDB unexpectedly changed to a
4900 different thread just as you entered a command to operate on the
4901 previously current thread.
4904 File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops
4906 5.5.3 Background Execution
4907 --------------------------
4909 GDB's execution commands have two variants: the normal foreground
4910 (synchronous) behavior, and a background (asynchronous) behavior. In
4911 foreground execution, GDB waits for the program to report that some
4912 thread has stopped before prompting for another command. In background
4913 execution, GDB immediately gives a command prompt so that you can issue
4914 other commands while your program runs.
4916 If the target doesn't support async mode, GDB issues an error message
4917 if you attempt to use the background execution commands.
4919 To specify background execution, add a '&' to the command. For
4920 example, the background form of the 'continue' command is 'continue&',
4921 or just 'c&'. The execution commands that accept background execution
4925 *Note Starting your Program: Starting.
4928 *Note Debugging an Already-running Process: Attach.
4931 *Note step: Continuing and Stepping.
4934 *Note stepi: Continuing and Stepping.
4937 *Note next: Continuing and Stepping.
4940 *Note nexti: Continuing and Stepping.
4943 *Note continue: Continuing and Stepping.
4946 *Note finish: Continuing and Stepping.
4949 *Note until: Continuing and Stepping.
4951 Background execution is especially useful in conjunction with
4952 non-stop mode for debugging programs with multiple threads; see *note
4953 Non-Stop Mode::. However, you can also use these commands in the normal
4954 all-stop mode with the restriction that you cannot issue another
4955 execution command until the previous one finishes. Examples of commands
4956 that are valid in all-stop mode while the program is running include
4957 'help' and 'info break'.
4959 You can interrupt your program while it is running in the background
4960 by using the 'interrupt' command.
4965 Suspend execution of the running program. In all-stop mode,
4966 'interrupt' stops the whole process, but in non-stop mode, it stops
4967 only the current thread. To stop the whole program in non-stop
4968 mode, use 'interrupt -a'.
4971 File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops
4973 5.5.4 Thread-Specific Breakpoints
4974 ---------------------------------
4976 When your program has multiple threads (*note Debugging Programs with
4977 Multiple Threads: Threads.), you can choose whether to set breakpoints
4978 on all threads, or on a particular thread.
4980 'break LINESPEC thread THREADNO'
4981 'break LINESPEC thread THREADNO if ...'
4982 LINESPEC specifies source lines; there are several ways of writing
4983 them (*note Specify Location::), but the effect is always to
4984 specify some source line.
4986 Use the qualifier 'thread THREADNO' with a breakpoint command to
4987 specify that you only want GDB to stop the program when a
4988 particular thread reaches this breakpoint. The THREADNO specifier
4989 is one of the numeric thread identifiers assigned by GDB, shown in
4990 the first column of the 'info threads' display.
4992 If you do not specify 'thread THREADNO' when you set a breakpoint,
4993 the breakpoint applies to _all_ threads of your program.
4995 You can use the 'thread' qualifier on conditional breakpoints as
4996 well; in this case, place 'thread THREADNO' before or after the
4997 breakpoint condition, like this:
4999 (gdb) break frik.c:13 thread 28 if bartab > lim
5001 Thread-specific breakpoints are automatically deleted when GDB
5002 detects the corresponding thread is no longer in the thread list. For
5006 Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list.
5008 There are several ways for a thread to disappear, such as a regular
5009 thread exit, but also when you detach from the process with the 'detach'
5010 command (*note Debugging an Already-running Process: Attach.), or if GDB
5011 loses the remote connection (*note Remote Debugging::), etc. Note that
5012 with some targets, GDB is only able to detect a thread has exited when
5013 the user explictly asks for the thread list with the 'info threads'
5017 File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops
5019 5.5.5 Interrupted System Calls
5020 ------------------------------
5022 There is an unfortunate side effect when using GDB to debug
5023 multi-threaded programs. If one thread stops for a breakpoint, or for
5024 some other reason, and another thread is blocked in a system call, then
5025 the system call may return prematurely. This is a consequence of the
5026 interaction between multiple threads and the signals that GDB uses to
5027 implement breakpoints and other events that stop execution.
5029 To handle this problem, your program should check the return value of
5030 each system call and react appropriately. This is good programming
5033 For example, do not write code like this:
5037 The call to 'sleep' will return early if a different thread stops at
5038 a breakpoint or for some other reason.
5040 Instead, write this:
5044 unslept = sleep (unslept);
5046 A system call is allowed to return early, so the system is still
5047 conforming to its specification. But GDB does cause your multi-threaded
5048 program to behave differently than it would without GDB.
5050 Also, GDB uses internal breakpoints in the thread library to monitor
5051 certain events such as thread creation and thread destruction. When
5052 such an event happens, a system call in another thread may return
5053 prematurely, even though your program does not appear to stop.
5056 File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops
5061 If you want to build on non-stop mode and observe program behavior
5062 without any chance of disruption by GDB, you can set variables to
5063 disable all of the debugger's attempts to modify state, whether by
5064 writing memory, inserting breakpoints, etc. These operate at a low
5065 level, intercepting operations from all commands.
5067 When all of these are set to 'off', then GDB is said to be "observer
5068 mode". As a convenience, the variable 'observer' can be set to disable
5069 these, plus enable non-stop mode.
5071 Note that GDB will not prevent you from making nonsensical
5072 combinations of these settings. For instance, if you have enabled
5073 'may-insert-breakpoints' but disabled 'may-write-memory', then
5074 breakpoints that work by writing trap instructions into the code stream
5075 will still not be able to be placed.
5079 When set to 'on', this disables all the permission variables below
5080 (except for 'insert-fast-tracepoints'), plus enables non-stop
5081 debugging. Setting this to 'off' switches back to normal
5082 debugging, though remaining in non-stop mode.
5085 Show whether observer mode is on or off.
5087 'set may-write-registers on'
5088 'set may-write-registers off'
5089 This controls whether GDB will attempt to alter the values of
5090 registers, such as with assignment expressions in 'print', or the
5091 'jump' command. It defaults to 'on'.
5093 'show may-write-registers'
5094 Show the current permission to write registers.
5096 'set may-write-memory on'
5097 'set may-write-memory off'
5098 This controls whether GDB will attempt to alter the contents of
5099 memory, such as with assignment expressions in 'print'. It
5102 'show may-write-memory'
5103 Show the current permission to write memory.
5105 'set may-insert-breakpoints on'
5106 'set may-insert-breakpoints off'
5107 This controls whether GDB will attempt to insert breakpoints. This
5108 affects all breakpoints, including internal breakpoints defined by
5109 GDB. It defaults to 'on'.
5111 'show may-insert-breakpoints'
5112 Show the current permission to insert breakpoints.
5114 'set may-insert-tracepoints on'
5115 'set may-insert-tracepoints off'
5116 This controls whether GDB will attempt to insert (regular)
5117 tracepoints at the beginning of a tracing experiment. It affects
5118 only non-fast tracepoints, fast tracepoints being under the control
5119 of 'may-insert-fast-tracepoints'. It defaults to 'on'.
5121 'show may-insert-tracepoints'
5122 Show the current permission to insert tracepoints.
5124 'set may-insert-fast-tracepoints on'
5125 'set may-insert-fast-tracepoints off'
5126 This controls whether GDB will attempt to insert fast tracepoints
5127 at the beginning of a tracing experiment. It affects only fast
5128 tracepoints, regular (non-fast) tracepoints being under the control
5129 of 'may-insert-tracepoints'. It defaults to 'on'.
5131 'show may-insert-fast-tracepoints'
5132 Show the current permission to insert fast tracepoints.
5134 'set may-interrupt on'
5135 'set may-interrupt off'
5136 This controls whether GDB will attempt to interrupt or stop program
5137 execution. When this variable is 'off', the 'interrupt' command
5138 will have no effect, nor will 'Ctrl-c'. It defaults to 'on'.
5140 'show may-interrupt'
5141 Show the current permission to interrupt or stop the program.
5144 File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top
5146 6 Running programs backward
5147 ***************************
5149 When you are debugging a program, it is not unusual to realize that you
5150 have gone too far, and some event of interest has already happened. If
5151 the target environment supports it, GDB can allow you to "rewind" the
5152 program by running it backward.
5154 A target environment that supports reverse execution should be able
5155 to "undo" the changes in machine state that have taken place as the
5156 program was executing normally. Variables, registers etc. should revert
5157 to their previous values. Obviously this requires a great deal of
5158 sophistication on the part of the target environment; not all target
5159 environments can support reverse execution.
5161 When a program is executed in reverse, the instructions that have
5162 most recently been executed are "un-executed", in reverse order. The
5163 program counter runs backward, following the previous thread of
5164 execution in reverse. As each instruction is "un-executed", the values
5165 of memory and/or registers that were changed by that instruction are
5166 reverted to their previous states. After executing a piece of source
5167 code in reverse, all side effects of that code should be "undone", and
5168 all variables should be returned to their prior values(1).
5170 If you are debugging in a target environment that supports reverse
5171 execution, GDB provides the following commands.
5173 'reverse-continue [IGNORE-COUNT]'
5175 Beginning at the point where your program last stopped, start
5176 executing in reverse. Reverse execution will stop for breakpoints
5177 and synchronous exceptions (signals), just like normal execution.
5178 Behavior of asynchronous signals depends on the target environment.
5180 'reverse-step [COUNT]'
5181 Run the program backward until control reaches the start of a
5182 different source line; then stop it, and return control to GDB.
5184 Like the 'step' command, 'reverse-step' will only stop at the
5185 beginning of a source line. It "un-executes" the previously
5186 executed source line. If the previous source line included calls
5187 to debuggable functions, 'reverse-step' will step (backward) into
5188 the called function, stopping at the beginning of the _last_
5189 statement in the called function (typically a return statement).
5191 Also, as with the 'step' command, if non-debuggable functions are
5192 called, 'reverse-step' will run thru them backward without
5195 'reverse-stepi [COUNT]'
5196 Reverse-execute one machine instruction. Note that the instruction
5197 to be reverse-executed is _not_ the one pointed to by the program
5198 counter, but the instruction executed prior to that one. For
5199 instance, if the last instruction was a jump, 'reverse-stepi' will
5200 take you back from the destination of the jump to the jump
5203 'reverse-next [COUNT]'
5204 Run backward to the beginning of the previous line executed in the
5205 current (innermost) stack frame. If the line contains function
5206 calls, they will be "un-executed" without stopping. Starting from
5207 the first line of a function, 'reverse-next' will take you back to
5208 the caller of that function, _before_ the function was called, just
5209 as the normal 'next' command would take you from the last line of a
5210 function back to its return to its caller (2).
5212 'reverse-nexti [COUNT]'
5213 Like 'nexti', 'reverse-nexti' executes a single instruction in
5214 reverse, except that called functions are "un-executed" atomically.
5215 That is, if the previously executed instruction was a return from
5216 another function, 'reverse-nexti' will continue to execute in
5217 reverse until the call to that function (from the current stack
5221 Just as the 'finish' command takes you to the point where the
5222 current function returns, 'reverse-finish' takes you to the point
5223 where it was called. Instead of ending up at the end of the
5224 current function invocation, you end up at the beginning.
5226 'set exec-direction'
5227 Set the direction of target execution.
5228 'set exec-direction reverse'
5229 GDB will perform all execution commands in reverse, until the
5230 exec-direction mode is changed to "forward". Affected commands
5231 include 'step, stepi, next, nexti, continue, and finish'. The
5232 'return' command cannot be used in reverse mode.
5233 'set exec-direction forward'
5234 GDB will perform all execution commands in the normal fashion.
5235 This is the default.
5237 ---------- Footnotes ----------
5239 (1) Note that some side effects are easier to undo than others. For
5240 instance, memory and registers are relatively easy, but device I/O is
5241 hard. Some targets may be able undo things like device I/O, and some
5244 The contract between GDB and the reverse executing target requires
5245 only that the target do something reasonable when GDB tells it to
5246 execute backwards, and then report the results back to GDB. Whatever
5247 the target reports back to GDB, GDB will report back to the user. GDB
5248 assumes that the memory and registers that the target reports are in a
5249 consistant state, but GDB accepts whatever it is given.
5251 (2) Unless the code is too heavily optimized.
5254 File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top
5256 7 Recording Inferior's Execution and Replaying It
5257 *************************************************
5259 On some platforms, GDB provides a special "process record and replay"
5260 target that can record a log of the process execution, and replay it
5261 later with both forward and reverse execution commands.
5263 When this target is in use, if the execution log includes the record
5264 for the next instruction, GDB will debug in "replay mode". In the
5265 replay mode, the inferior does not really execute code instructions.
5266 Instead, all the events that normally happen during code execution are
5267 taken from the execution log. While code is not really executed in
5268 replay mode, the values of registers (including the program counter
5269 register) and the memory of the inferior are still changed as they
5270 normally would. Their contents are taken from the execution log.
5272 If the record for the next instruction is not in the execution log,
5273 GDB will debug in "record mode". In this mode, the inferior executes
5274 normally, and GDB records the execution log for future replay.
5276 The process record and replay target supports reverse execution
5277 (*note Reverse Execution::), even if the platform on which the inferior
5278 runs does not. However, the reverse execution is limited in this case
5279 by the range of the instructions recorded in the execution log. In
5280 other words, reverse execution on platforms that don't support it
5281 directly can only be done in the replay mode.
5283 When debugging in the reverse direction, GDB will work in replay mode
5284 as long as the execution log includes the record for the previous
5285 instruction; otherwise, it will work in record mode, if the platform
5286 supports reverse execution, or stop if not.
5288 For architecture environments that support process record and replay,
5289 GDB provides the following commands:
5292 This command starts the process record and replay target. The
5293 recording method can be specified as parameter. Without a
5294 parameter the command uses the 'full' recording method. The
5295 following recording methods are available:
5298 Full record/replay recording using GDB's software record and
5299 replay implementation. This method allows replaying and
5303 Hardware-supported instruction recording. This method does
5304 not record data. Further, the data is collected in a ring
5305 buffer so old data will be overwritten when the buffer is
5306 full. It allows limited replay and reverse execution.
5308 This recording method may not be available on all processors.
5310 The process record and replay target can only debug a process that
5311 is already running. Therefore, you need first to start the process
5312 with the 'run' or 'start' commands, and then start the recording
5313 with the 'record METHOD' command.
5315 Both 'record METHOD' and 'rec METHOD' are aliases of 'target
5318 Displaced stepping (*note displaced stepping: Maintenance
5319 Commands.) will be automatically disabled when process record and
5320 replay target is started. That's because the process record and
5321 replay target doesn't support displaced stepping.
5323 If the inferior is in the non-stop mode (*note Non-Stop Mode::) or
5324 in the asynchronous execution mode (*note Background Execution::),
5325 not all recording methods are available. The 'full' recording
5326 method does not support these two modes.
5329 Stop the process record and replay target. When process record and
5330 replay target stops, the entire execution log will be deleted and
5331 the inferior will either be terminated, or will remain in its final
5334 When you stop the process record and replay target in record mode
5335 (at the end of the execution log), the inferior will be stopped at
5336 the next instruction that would have been recorded. In other
5337 words, if you record for a while and then stop recording, the
5338 inferior process will be left in the same state as if the recording
5341 On the other hand, if the process record and replay target is
5342 stopped while in replay mode (that is, not at the end of the
5343 execution log, but at some earlier point), the inferior process
5344 will become "live" at that earlier state, and it will then be
5345 possible to continue the usual "live" debugging of the process from
5348 When the inferior process exits, or GDB detaches from it, process
5349 record and replay target will automatically stop itself.
5352 Go to a specific location in the execution log. There are several
5353 ways to specify the location to go to:
5357 Go to the beginning of the execution log.
5360 Go to the end of the execution log.
5363 Go to instruction number N in the execution log.
5365 'record save FILENAME'
5366 Save the execution log to a file 'FILENAME'. Default filename is
5367 'gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the
5370 This command may not be available for all recording methods.
5372 'record restore FILENAME'
5373 Restore the execution log from a file 'FILENAME'. File must have
5374 been created with 'record save'.
5376 'set record full insn-number-max LIMIT'
5377 'set record full insn-number-max unlimited'
5378 Set the limit of instructions to be recorded for the 'full'
5379 recording method. Default value is 200000.
5381 If LIMIT is a positive number, then GDB will start deleting
5382 instructions from the log once the number of the record
5383 instructions becomes greater than LIMIT. For every new recorded
5384 instruction, GDB will delete the earliest recorded instruction to
5385 keep the number of recorded instructions at the limit. (Since
5386 deleting recorded instructions loses information, GDB lets you
5387 control what happens when the limit is reached, by means of the
5388 'stop-at-limit' option, described below.)
5390 If LIMIT is 'unlimited' or zero, GDB will never delete recorded
5391 instructions from the execution log. The number of recorded
5392 instructions is limited only by the available memory.
5394 'show record full insn-number-max'
5395 Show the limit of instructions to be recorded with the 'full'
5398 'set record full stop-at-limit'
5399 Control the behavior of the 'full' recording method when the number
5400 of recorded instructions reaches the limit. If ON (the default),
5401 GDB will stop when the limit is reached for the first time and ask
5402 you whether you want to stop the inferior or continue running it
5403 and recording the execution log. If you decide to continue
5404 recording, each new recorded instruction will cause the oldest one
5407 If this option is OFF, GDB will automatically delete the oldest
5408 record to make room for each new one, without asking.
5410 'show record full stop-at-limit'
5411 Show the current setting of 'stop-at-limit'.
5413 'set record full memory-query'
5414 Control the behavior when GDB is unable to record memory changes
5415 caused by an instruction for the 'full' recording method. If ON,
5416 GDB will query whether to stop the inferior in that case.
5418 If this option is OFF (the default), GDB will automatically ignore
5419 the effect of such instructions on memory. Later, when GDB replays
5420 this execution log, it will mark the log of this instruction as not
5421 accessible, and it will not affect the replay results.
5423 'show record full memory-query'
5424 Show the current setting of 'memory-query'.
5426 The 'btrace' record target does not trace data. As a convenience,
5427 when replaying, GDB reads read-only memory off the live program
5428 directly, assuming that the addresses of the read-only areas don't
5429 change. This for example makes it possible to disassemble code
5430 while replaying, but not to print variables. In some cases, being
5431 able to inspect variables might be useful. You can use the
5432 following command for that:
5434 'set record btrace replay-memory-access'
5435 Control the behavior of the 'btrace' recording method when
5436 accessing memory during replay. If 'read-only' (the default), GDB
5437 will only allow accesses to read-only memory. If 'read-write', GDB
5438 will allow accesses to read-only and to read-write memory. Beware
5439 that the accessed memory corresponds to the live target and not
5440 necessarily to the current replay position.
5442 'show record btrace replay-memory-access'
5443 Show the current setting of 'replay-memory-access'.
5446 Show various statistics about the recording depending on the
5450 For the 'full' recording method, it shows the state of process
5451 record and its in-memory execution log buffer, including:
5453 * Whether in record mode or replay mode.
5454 * Lowest recorded instruction number (counting from when
5455 the current execution log started recording
5457 * Highest recorded instruction number.
5458 * Current instruction about to be replayed (if in replay
5460 * Number of instructions contained in the execution log.
5461 * Maximum number of instructions that may be contained in
5465 For the 'btrace' recording method, it shows the number of
5466 instructions that have been recorded and the number of blocks
5467 of sequential control-flow that is formed by the recorded
5471 When record target runs in replay mode ("in the past"), delete the
5472 subsequent execution log and begin to record a new execution log
5473 starting from the current address. This means you will abandon the
5474 previously recorded "future" and begin recording a new "future".
5476 'record instruction-history'
5477 Disassembles instructions from the recorded execution log. By
5478 default, ten instructions are disassembled. This can be changed
5479 using the 'set record instruction-history-size' command.
5480 Instructions are printed in execution order. There are several
5481 ways to specify what part of the execution log to disassemble:
5483 'record instruction-history INSN'
5484 Disassembles ten instructions starting from instruction number
5487 'record instruction-history INSN, +/-N'
5488 Disassembles N instructions around instruction number INSN.
5489 If N is preceded with '+', disassembles N instructions after
5490 instruction number INSN. If N is preceded with '-',
5491 disassembles N instructions before instruction number INSN.
5493 'record instruction-history'
5494 Disassembles ten more instructions after the last disassembly.
5496 'record instruction-history -'
5497 Disassembles ten more instructions before the last
5500 'record instruction-history BEGIN END'
5501 Disassembles instructions beginning with instruction number
5502 BEGIN until instruction number END. The instruction number
5505 This command may not be available for all recording methods.
5507 'set record instruction-history-size SIZE'
5508 'set record instruction-history-size unlimited'
5509 Define how many instructions to disassemble in the 'record
5510 instruction-history' command. The default value is 10. A SIZE of
5511 'unlimited' means unlimited instructions.
5513 'show record instruction-history-size'
5514 Show how many instructions to disassemble in the 'record
5515 instruction-history' command.
5517 'record function-call-history'
5518 Prints the execution history at function granularity. It prints
5519 one line for each sequence of instructions that belong to the same
5520 function giving the name of that function, the source lines for
5521 this instruction sequence (if the '/l' modifier is specified), and
5522 the instructions numbers that form the sequence (if the '/i'
5523 modifier is specified). The function names are indented to reflect
5524 the call stack depth if the '/c' modifier is specified. The '/l',
5525 '/i', and '/c' modifiers can be given together.
5538 (gdb) record function-call-history /ilc
5539 1 bar inst 1,4 at foo.c:6,8
5540 2 foo inst 5,10 at foo.c:2,3
5541 3 bar inst 11,13 at foo.c:9,10
5543 By default, ten lines are printed. This can be changed using the
5544 'set record function-call-history-size' command. Functions are
5545 printed in execution order. There are several ways to specify what
5548 'record function-call-history FUNC'
5549 Prints ten functions starting from function number FUNC.
5551 'record function-call-history FUNC, +/-N'
5552 Prints N functions around function number FUNC. If N is
5553 preceded with '+', prints N functions after function number
5554 FUNC. If N is preceded with '-', prints N functions before
5555 function number FUNC.
5557 'record function-call-history'
5558 Prints ten more functions after the last ten-line print.
5560 'record function-call-history -'
5561 Prints ten more functions before the last ten-line print.
5563 'record function-call-history BEGIN END'
5564 Prints functions beginning with function number BEGIN until
5565 function number END. The function number END is included.
5567 This command may not be available for all recording methods.
5569 'set record function-call-history-size SIZE'
5570 'set record function-call-history-size unlimited'
5571 Define how many lines to print in the 'record
5572 function-call-history' command. The default value is 10. A size
5573 of 'unlimited' means unlimited lines.
5575 'show record function-call-history-size'
5576 Show how many lines to print in the 'record function-call-history'
5580 File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top
5582 8 Examining the Stack
5583 *********************
5585 When your program has stopped, the first thing you need to know is where
5586 it stopped and how it got there.
5588 Each time your program performs a function call, information about
5589 the call is generated. That information includes the location of the
5590 call in your program, the arguments of the call, and the local variables
5591 of the function being called. The information is saved in a block of
5592 data called a "stack frame". The stack frames are allocated in a region
5593 of memory called the "call stack".
5595 When your program stops, the GDB commands for examining the stack
5596 allow you to see all of this information.
5598 One of the stack frames is "selected" by GDB and many GDB commands
5599 refer implicitly to the selected frame. In particular, whenever you ask
5600 GDB for the value of a variable in your program, the value is found in
5601 the selected frame. There are special GDB commands to select whichever
5602 frame you are interested in. *Note Selecting a Frame: Selection.
5604 When your program stops, GDB automatically selects the currently
5605 executing frame and describes it briefly, similar to the 'frame' command
5606 (*note Information about a Frame: Frame Info.).
5610 * Frames:: Stack frames
5611 * Backtrace:: Backtraces
5612 * Frame Filter Management:: Managing frame filters
5613 * Selection:: Selecting a frame
5614 * Frame Info:: Information on a frame
5617 File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack
5622 The call stack is divided up into contiguous pieces called "stack
5623 frames", or "frames" for short; each frame is the data associated with
5624 one call to one function. The frame contains the arguments given to the
5625 function, the function's local variables, and the address at which the
5626 function is executing.
5628 When your program is started, the stack has only one frame, that of
5629 the function 'main'. This is called the "initial" frame or the
5630 "outermost" frame. Each time a function is called, a new frame is made.
5631 Each time a function returns, the frame for that function invocation is
5632 eliminated. If a function is recursive, there can be many frames for
5633 the same function. The frame for the function in which execution is
5634 actually occurring is called the "innermost" frame. This is the most
5635 recently created of all the stack frames that still exist.
5637 Inside your program, stack frames are identified by their addresses.
5638 A stack frame consists of many bytes, each of which has its own address;
5639 each kind of computer has a convention for choosing one byte whose
5640 address serves as the address of the frame. Usually this address is
5641 kept in a register called the "frame pointer register" (*note $fp:
5642 Registers.) while execution is going on in that frame.
5644 GDB assigns numbers to all existing stack frames, starting with zero
5645 for the innermost frame, one for the frame that called it, and so on
5646 upward. These numbers do not really exist in your program; they are
5647 assigned by GDB to give you a way of designating stack frames in GDB
5650 Some compilers provide a way to compile functions so that they
5651 operate without stack frames. (For example, the GCC option
5652 '-fomit-frame-pointer'
5653 generates functions without a frame.) This is occasionally done with
5654 heavily used library functions to save the frame setup time. GDB has
5655 limited facilities for dealing with these function invocations. If the
5656 innermost function invocation has no stack frame, GDB nevertheless
5657 regards it as though it had a separate frame, which is numbered zero as
5658 usual, allowing correct tracing of the function call chain. However,
5659 GDB has no provision for frameless functions elsewhere in the stack.
5662 The 'frame' command allows you to move from one stack frame to
5663 another, and to print the stack frame you select. The FRAMESPEC
5664 may be either the address of the frame or the stack frame number.
5665 Without an argument, 'frame' prints the current stack frame.
5668 The 'select-frame' command allows you to move from one stack frame
5669 to another without printing the frame. This is the silent version
5673 File: gdb.info, Node: Backtrace, Next: Frame Filter Management, Prev: Frames, Up: Stack
5678 A backtrace is a summary of how your program got where it is. It shows
5679 one line per frame, for many frames, starting with the currently
5680 executing frame (frame zero), followed by its caller (frame one), and on
5685 Print a backtrace of the entire stack: one line per frame for all
5686 frames in the stack.
5688 You can stop the backtrace at any time by typing the system
5689 interrupt character, normally 'Ctrl-c'.
5693 Similar, but print only the innermost N frames.
5697 Similar, but print only the outermost N frames.
5703 Print the values of the local variables also. As described above,
5704 N specifies the number of frames to print.
5706 'backtrace no-filters'
5710 'bt no-filters full'
5711 'bt no-filters full N'
5712 'bt no-filters full -N'
5713 Do not run Python frame filters on this backtrace. *Note Frame
5714 Filter API::, for more information. Additionally use *note disable
5715 frame-filter all:: to turn off all frame filters. This is only
5716 relevant when GDB has been configured with 'Python' support.
5718 The names 'where' and 'info stack' (abbreviated 'info s') are
5719 additional aliases for 'backtrace'.
5721 In a multi-threaded program, GDB by default shows the backtrace only
5722 for the current thread. To display the backtrace for several or all of
5723 the threads, use the command 'thread apply' (*note thread apply:
5724 Threads.). For example, if you type 'thread apply all backtrace', GDB
5725 will display the backtrace for all the threads; this is handy when you
5726 debug a core dump of a multi-threaded program.
5728 Each line in the backtrace shows the frame number and the function
5729 name. The program counter value is also shown--unless you use 'set
5730 print address off'. The backtrace also shows the source file name and
5731 line number, as well as the arguments to the function. The program
5732 counter value is omitted if it is at the beginning of the code for that
5735 Here is an example of a backtrace. It was made with the command 'bt
5736 3', so it shows the innermost three frames.
5738 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
5740 #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
5741 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
5743 (More stack frames follow...)
5745 The display for frame zero does not begin with a program counter value,
5746 indicating that your program has stopped at the beginning of the code
5747 for line '993' of 'builtin.c'.
5749 The value of parameter 'data' in frame 1 has been replaced by '...'. By
5750 default, GDB prints the value of a parameter only if it is a scalar
5751 (integer, pointer, enumeration, etc). See command 'set print
5752 frame-arguments' in *note Print Settings:: for more details on how to
5753 configure the way function parameter values are printed.
5755 If your program was compiled with optimizations, some compilers will
5756 optimize away arguments passed to functions if those arguments are never
5757 used after the call. Such optimizations generate code that passes
5758 arguments through registers, but doesn't store those arguments in the
5759 stack frame. GDB has no way of displaying such arguments in stack
5760 frames other than the innermost one. Here's what such a backtrace might
5763 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
5765 #1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242
5766 #2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08)
5768 (More stack frames follow...)
5770 The values of arguments that were not saved in their stack frames are
5771 shown as '<optimized out>'.
5773 If you need to display the values of such optimized-out arguments,
5774 either deduce that from other variables whose values depend on the one
5775 you are interested in, or recompile without optimizations.
5777 Most programs have a standard user entry point--a place where system
5778 libraries and startup code transition into user code. For C this is
5779 'main'(1). When GDB finds the entry function in a backtrace it will
5780 terminate the backtrace, to avoid tracing into highly system-specific
5781 (and generally uninteresting) code.
5783 If you need to examine the startup code, or limit the number of
5784 levels in a backtrace, you can change this behavior:
5786 'set backtrace past-main'
5787 'set backtrace past-main on'
5788 Backtraces will continue past the user entry point.
5790 'set backtrace past-main off'
5791 Backtraces will stop when they encounter the user entry point.
5792 This is the default.
5794 'show backtrace past-main'
5795 Display the current user entry point backtrace policy.
5797 'set backtrace past-entry'
5798 'set backtrace past-entry on'
5799 Backtraces will continue past the internal entry point of an
5800 application. This entry point is encoded by the linker when the
5801 application is built, and is likely before the user entry point
5802 'main' (or equivalent) is called.
5804 'set backtrace past-entry off'
5805 Backtraces will stop when they encounter the internal entry point
5806 of an application. This is the default.
5808 'show backtrace past-entry'
5809 Display the current internal entry point backtrace policy.
5811 'set backtrace limit N'
5812 'set backtrace limit 0'
5813 'set backtrace limit unlimited'
5814 Limit the backtrace to N levels. A value of 'unlimited' or zero
5815 means unlimited levels.
5817 'show backtrace limit'
5818 Display the current limit on backtrace levels.
5820 You can control how file names are displayed.
5822 'set filename-display'
5823 'set filename-display relative'
5824 Display file names relative to the compilation directory. This is
5827 'set filename-display basename'
5828 Display only basename of a filename.
5830 'set filename-display absolute'
5831 Display an absolute filename.
5833 'show filename-display'
5834 Show the current way to display filenames.
5836 ---------- Footnotes ----------
5838 (1) Note that embedded programs (the so-called "free-standing"
5839 environment) are not required to have a 'main' function as the entry
5840 point. They could even have multiple entry points.
5843 File: gdb.info, Node: Frame Filter Management, Next: Selection, Prev: Backtrace, Up: Stack
5845 8.3 Management of Frame Filters.
5846 ================================
5848 Frame filters are Python based utilities to manage and decorate the
5849 output of frames. *Note Frame Filter API::, for further information.
5851 Managing frame filters is performed by several commands available
5852 within GDB, detailed here.
5855 Print a list of installed frame filters from all dictionaries,
5856 showing their name, priority and enabled status.
5858 'disable frame-filter FILTER-DICTIONARY FILTER-NAME'
5859 Disable a frame filter in the dictionary matching FILTER-DICTIONARY
5860 and FILTER-NAME. The FILTER-DICTIONARY may be 'all', 'global',
5861 'progspace', or the name of the object file where the frame filter
5862 dictionary resides. When 'all' is specified, all frame filters
5863 across all dictionaries are disabled. The FILTER-NAME is the name
5864 of the frame filter and is used when 'all' is not the option for
5865 FILTER-DICTIONARY. A disabled frame-filter is not deleted, it may
5866 be enabled again later.
5868 'enable frame-filter FILTER-DICTIONARY FILTER-NAME'
5869 Enable a frame filter in the dictionary matching FILTER-DICTIONARY
5870 and FILTER-NAME. The FILTER-DICTIONARY may be 'all', 'global',
5871 'progspace' or the name of the object file where the frame filter
5872 dictionary resides. When 'all' is specified, all frame filters
5873 across all dictionaries are enabled. The FILTER-NAME is the name
5874 of the frame filter and is used when 'all' is not the option for
5879 (gdb) info frame-filter
5881 global frame-filters:
5882 Priority Enabled Name
5883 1000 No PrimaryFunctionFilter
5886 progspace /build/test frame-filters:
5887 Priority Enabled Name
5888 100 Yes ProgspaceFilter
5890 objfile /build/test frame-filters:
5891 Priority Enabled Name
5892 999 Yes BuildProgra Filter
5894 (gdb) disable frame-filter /build/test BuildProgramFilter
5895 (gdb) info frame-filter
5897 global frame-filters:
5898 Priority Enabled Name
5899 1000 No PrimaryFunctionFilter
5902 progspace /build/test frame-filters:
5903 Priority Enabled Name
5904 100 Yes ProgspaceFilter
5906 objfile /build/test frame-filters:
5907 Priority Enabled Name
5908 999 No BuildProgramFilter
5910 (gdb) enable frame-filter global PrimaryFunctionFilter
5911 (gdb) info frame-filter
5913 global frame-filters:
5914 Priority Enabled Name
5915 1000 Yes PrimaryFunctionFilter
5918 progspace /build/test frame-filters:
5919 Priority Enabled Name
5920 100 Yes ProgspaceFilter
5922 objfile /build/test frame-filters:
5923 Priority Enabled Name
5924 999 No BuildProgramFilter
5926 'set frame-filter priority FILTER-DICTIONARY FILTER-NAME PRIORITY'
5927 Set the PRIORITY of a frame filter in the dictionary matching
5928 FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME.
5929 The FILTER-DICTIONARY may be 'global', 'progspace' or the name of
5930 the object file where the frame filter dictionary resides. The
5931 PRIORITY is an integer.
5933 'show frame-filter priority FILTER-DICTIONARY FILTER-NAME'
5934 Show the PRIORITY of a frame filter in the dictionary matching
5935 FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME.
5936 The FILTER-DICTIONARY may be 'global', 'progspace' or the name of
5937 the object file where the frame filter dictionary resides.
5941 (gdb) info frame-filter
5943 global frame-filters:
5944 Priority Enabled Name
5945 1000 Yes PrimaryFunctionFilter
5948 progspace /build/test frame-filters:
5949 Priority Enabled Name
5950 100 Yes ProgspaceFilter
5952 objfile /build/test frame-filters:
5953 Priority Enabled Name
5954 999 No BuildProgramFilter
5956 (gdb) set frame-filter priority global Reverse 50
5957 (gdb) info frame-filter
5959 global frame-filters:
5960 Priority Enabled Name
5961 1000 Yes PrimaryFunctionFilter
5964 progspace /build/test frame-filters:
5965 Priority Enabled Name
5966 100 Yes ProgspaceFilter
5968 objfile /build/test frame-filters:
5969 Priority Enabled Name
5970 999 No BuildProgramFilter
5973 File: gdb.info, Node: Selection, Next: Frame Info, Prev: Frame Filter Management, Up: Stack
5975 8.4 Selecting a Frame
5976 =====================
5978 Most commands for examining the stack and other data in your program
5979 work on whichever stack frame is selected at the moment. Here are the
5980 commands for selecting a stack frame; all of them finish by printing a
5981 brief description of the stack frame just selected.
5985 Select frame number N. Recall that frame zero is the innermost
5986 (currently executing) frame, frame one is the frame that called the
5987 innermost one, and so on. The highest-numbered frame is the one
5992 Select the frame at address ADDR. This is useful mainly if the
5993 chaining of stack frames has been damaged by a bug, making it
5994 impossible for GDB to assign numbers properly to all frames. In
5995 addition, this can be useful when your program has multiple stacks
5996 and switches between them.
5998 On the SPARC architecture, 'frame' needs two addresses to select an
5999 arbitrary frame: a frame pointer and a stack pointer.
6001 On the MIPS and Alpha architecture, it needs two addresses: a stack
6002 pointer and a program counter.
6004 On the 29k architecture, it needs three addresses: a register stack
6005 pointer, a program counter, and a memory stack pointer.
6008 Move N frames up the stack; N defaults to 1. For positive numbers
6009 N, this advances toward the outermost frame, to higher frame
6010 numbers, to frames that have existed longer.
6013 Move N frames down the stack; N defaults to 1. For positive
6014 numbers N, this advances toward the innermost frame, to lower frame
6015 numbers, to frames that were created more recently. You may
6016 abbreviate 'down' as 'do'.
6018 All of these commands end by printing two lines of output describing
6019 the frame. The first line shows the frame number, the function name,
6020 the arguments, and the source file and line number of execution in that
6021 frame. The second line shows the text of that source line.
6026 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
6028 10 read_input_file (argv[i]);
6030 After such a printout, the 'list' command with no arguments prints
6031 ten lines centered on the point of execution in the frame. You can also
6032 edit the program at the point of execution with your favorite editing
6033 program by typing 'edit'. *Note Printing Source Lines: List, for
6038 These two commands are variants of 'up' and 'down', respectively;
6039 they differ in that they do their work silently, without causing
6040 display of the new frame. They are intended primarily for use in
6041 GDB command scripts, where the output might be unnecessary and
6045 File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack
6047 8.5 Information About a Frame
6048 =============================
6050 There are several other commands to print information about the selected
6055 When used without any argument, this command does not change which
6056 frame is selected, but prints a brief description of the currently
6057 selected stack frame. It can be abbreviated 'f'. With an
6058 argument, this command is used to select a stack frame. *Note
6059 Selecting a Frame: Selection.
6063 This command prints a verbose description of the selected stack
6066 * the address of the frame
6067 * the address of the next frame down (called by this frame)
6068 * the address of the next frame up (caller of this frame)
6069 * the language in which the source code corresponding to this
6071 * the address of the frame's arguments
6072 * the address of the frame's local variables
6073 * the program counter saved in it (the address of execution in
6075 * which registers were saved in the frame
6077 The verbose description is useful when something has gone wrong
6078 that has made the stack format fail to fit the usual conventions.
6082 Print a verbose description of the frame at address ADDR, without
6083 selecting that frame. The selected frame remains unchanged by this
6084 command. This requires the same kind of address (more than one for
6085 some architectures) that you specify in the 'frame' command. *Note
6086 Selecting a Frame: Selection.
6089 Print the arguments of the selected frame, each on a separate line.
6092 Print the local variables of the selected frame, each on a separate
6093 line. These are all variables (declared either static or
6094 automatic) accessible at the point of execution of the selected
6098 File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top
6100 9 Examining Source Files
6101 ************************
6103 GDB can print parts of your program's source, since the debugging
6104 information recorded in the program tells GDB what source files were
6105 used to build it. When your program stops, GDB spontaneously prints the
6106 line where it stopped. Likewise, when you select a stack frame (*note
6107 Selecting a Frame: Selection.), GDB prints the line where execution in
6108 that frame has stopped. You can print other portions of source files by
6111 If you use GDB through its GNU Emacs interface, you may prefer to use
6112 Emacs facilities to view source; see *note Using GDB under GNU Emacs:
6117 * List:: Printing source lines
6118 * Specify Location:: How to specify code locations
6119 * Edit:: Editing source files
6120 * Search:: Searching source files
6121 * Source Path:: Specifying source directories
6122 * Machine Code:: Source and machine code
6125 File: gdb.info, Node: List, Next: Specify Location, Up: Source
6127 9.1 Printing Source Lines
6128 =========================
6130 To print lines from a source file, use the 'list' command (abbreviated
6131 'l'). By default, ten lines are printed. There are several ways to
6132 specify what part of the file you want to print; see *note Specify
6133 Location::, for the full list.
6135 Here are the forms of the 'list' command most commonly used:
6138 Print lines centered around line number LINENUM in the current
6142 Print lines centered around the beginning of function FUNCTION.
6145 Print more lines. If the last lines printed were printed with a
6146 'list' command, this prints lines following the last lines printed;
6147 however, if the last line printed was a solitary line printed as
6148 part of displaying a stack frame (*note Examining the Stack:
6149 Stack.), this prints lines centered around that line.
6152 Print lines just before the lines last printed.
6154 By default, GDB prints ten source lines with any of these forms of
6155 the 'list' command. You can change this using 'set listsize':
6157 'set listsize COUNT'
6158 'set listsize unlimited'
6159 Make the 'list' command display COUNT source lines (unless the
6160 'list' argument explicitly specifies some other number). Setting
6161 COUNT to 'unlimited' or 0 means there's no limit.
6164 Display the number of lines that 'list' prints.
6166 Repeating a 'list' command with <RET> discards the argument, so it is
6167 equivalent to typing just 'list'. This is more useful than listing the
6168 same lines again. An exception is made for an argument of '-'; that
6169 argument is preserved in repetition so that each repetition moves up in
6172 In general, the 'list' command expects you to supply zero, one or two
6173 "linespecs". Linespecs specify source lines; there are several ways of
6174 writing them (*note Specify Location::), but the effect is always to
6175 specify some source line.
6177 Here is a complete description of the possible arguments for 'list':
6180 Print lines centered around the line specified by LINESPEC.
6183 Print lines from FIRST to LAST. Both arguments are linespecs.
6184 When a 'list' command has two linespecs, and the source file of the
6185 second linespec is omitted, this refers to the same source file as
6189 Print lines ending with LAST.
6192 Print lines starting with FIRST.
6195 Print lines just after the lines last printed.
6198 Print lines just before the lines last printed.
6201 As described in the preceding table.
6204 File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source
6206 9.2 Specifying a Location
6207 =========================
6209 Several GDB commands accept arguments that specify a location of your
6210 program's code. Since GDB is a source-level debugger, a location
6211 usually specifies some line in the source code; for that reason,
6212 locations are also known as "linespecs".
6214 Here are all the different ways of specifying a code location that
6218 Specifies the line number LINENUM of the current source file.
6222 Specifies the line OFFSET lines before or after the "current line".
6223 For the 'list' command, the current line is the last one printed;
6224 for the breakpoint commands, this is the line at which execution
6225 stopped in the currently selected "stack frame" (*note Frames:
6226 Frames, for a description of stack frames.) When used as the
6227 second of the two linespecs in a 'list' command, this specifies the
6228 line OFFSET lines up or down from the first linespec.
6231 Specifies the line LINENUM in the source file FILENAME. If
6232 FILENAME is a relative file name, then it will match any source
6233 file name with the same trailing components. For example, if
6234 FILENAME is 'gcc/expr.c', then it will match source file name of
6235 '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or
6236 '/build/trunk/gcc/x-expr.c'.
6239 Specifies the line that begins the body of the function FUNCTION.
6240 For example, in C, this is the line with the open brace.
6243 Specifies the line where LABEL appears in FUNCTION.
6246 Specifies the line that begins the body of the function FUNCTION in
6247 the file FILENAME. You only need the file name with a function
6248 name to avoid ambiguity when there are identically named functions
6249 in different source files.
6252 Specifies the line at which the label named LABEL appears. GDB
6253 searches for the label in the function corresponding to the
6254 currently selected stack frame. If there is no current selected
6255 stack frame (for instance, if the inferior is not running), then
6256 GDB will not search for a label.
6259 Specifies the program address ADDRESS. For line-oriented commands,
6260 such as 'list' and 'edit', this specifies a source line that
6261 contains ADDRESS. For 'break' and other breakpoint oriented
6262 commands, this can be used to set breakpoints in parts of your
6263 program which do not have debugging information or source files.
6265 Here ADDRESS may be any expression valid in the current working
6266 language (*note working language: Languages.) that specifies a code
6267 address. In addition, as a convenience, GDB extends the semantics
6268 of expressions used in locations to cover the situations that
6269 frequently happen during debugging. Here are the various forms of
6273 Any expression valid in the current working language.
6276 An address of a function or procedure derived from its name.
6277 In C, C++, Java, Objective-C, Fortran, minimal, and assembly,
6278 this is simply the function's name FUNCTION (and actually a
6279 special case of a valid expression). In Pascal and Modula-2,
6280 this is '&FUNCTION'. In Ada, this is 'FUNCTION'Address'
6281 (although the Pascal form also works).
6283 This form specifies the address of the function's first
6284 instruction, before the stack frame and arguments have been
6287 ''FILENAME'::FUNCADDR'
6288 Like FUNCADDR above, but also specifies the name of the source
6289 file explicitly. This is useful if the name of the function
6290 does not specify the function unambiguously, e.g., if there
6291 are several functions with identical names in different source
6294 '-pstap|-probe-stap [OBJFILE:[PROVIDER:]]NAME'
6295 The GNU/Linux tool 'SystemTap' provides a way for applications to
6296 embed static probes. *Note Static Probe Points::, for more
6297 information on finding and using static probes. This form of
6298 linespec specifies the location of such a static probe.
6300 If OBJFILE is given, only probes coming from that shared library or
6301 executable matching OBJFILE as a regular expression are considered.
6302 If PROVIDER is given, then only probes from that provider are
6303 considered. If several probes match the spec, GDB will insert a
6304 breakpoint at each one of those probes.
6307 File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source
6309 9.3 Editing Source Files
6310 ========================
6312 To edit the lines in a source file, use the 'edit' command. The editing
6313 program of your choice is invoked with the current line set to the
6314 active line in the program. Alternatively, there are several ways to
6315 specify what part of the file you want to print if you want to see other
6316 parts of the program:
6319 Edit the source file specified by 'location'. Editing starts at
6320 that LOCATION, e.g., at the specified source line of the specified
6321 file. *Note Specify Location::, for all the possible forms of the
6322 LOCATION argument; here are the forms of the 'edit' command most
6326 Edit the current source file with NUMBER as the active line
6330 Edit the file containing FUNCTION at the beginning of its
6333 9.3.1 Choosing your Editor
6334 --------------------------
6336 You can customize GDB to use any editor you want (1). By default, it is
6337 '/bin/ex', but you can change this by setting the environment variable
6338 'EDITOR' before using GDB. For example, to configure GDB to use the
6339 'vi' editor, you could use these commands with the 'sh' shell:
6343 or in the 'csh' shell,
6344 setenv EDITOR /usr/bin/vi
6347 ---------- Footnotes ----------
6349 (1) The only restriction is that your editor (say 'ex'), recognizes
6350 the following command-line syntax:
6352 The optional numeric value +NUMBER specifies the number of the line
6353 in the file where to start editing.
6356 File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source
6358 9.4 Searching Source Files
6359 ==========================
6361 There are two commands for searching through the current source file for
6362 a regular expression.
6364 'forward-search REGEXP'
6366 The command 'forward-search REGEXP' checks each line, starting with
6367 the one following the last line listed, for a match for REGEXP. It
6368 lists the line that is found. You can use the synonym 'search
6369 REGEXP' or abbreviate the command name as 'fo'.
6371 'reverse-search REGEXP'
6372 The command 'reverse-search REGEXP' checks each line, starting with
6373 the one before the last line listed and going backward, for a match
6374 for REGEXP. It lists the line that is found. You can abbreviate
6375 this command as 'rev'.
6378 File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source
6380 9.5 Specifying Source Directories
6381 =================================
6383 Executable programs sometimes do not record the directories of the
6384 source files from which they were compiled, just the names. Even when
6385 they do, the directories could be moved between the compilation and your
6386 debugging session. GDB has a list of directories to search for source
6387 files; this is called the "source path". Each time GDB wants a source
6388 file, it tries all the directories in the list, in the order they are
6389 present in the list, until it finds a file with the desired name.
6391 For example, suppose an executable references the file
6392 '/usr/src/foo-1.0/lib/foo.c', and our source path is '/mnt/cross'. The
6393 file is first looked up literally; if this fails,
6394 '/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails,
6395 '/mnt/cross/foo.c' is opened; if this fails, an error message is
6396 printed. GDB does not look up the parts of the source file name, such
6397 as '/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of
6398 the source path are not searched: if the source path is '/mnt/cross',
6399 and the binary refers to 'foo.c', GDB would not find it under
6400 '/mnt/cross/usr/src/foo-1.0/lib'.
6402 Plain file names, relative file names with leading directories, file
6403 names containing dots, etc. are all treated as described above; for
6404 instance, if the source path is '/mnt/cross', and the source file is
6405 recorded as '../lib/foo.c', GDB would first try '../lib/foo.c', then
6406 '/mnt/cross/../lib/foo.c', and after that--'/mnt/cross/foo.c'.
6408 Note that the executable search path is _not_ used to locate the
6411 Whenever you reset or rearrange the source path, GDB clears out any
6412 information it has cached about where source files are found and where
6413 each line is in the file.
6415 When you start GDB, its source path includes only 'cdir' and 'cwd',
6416 in that order. To add other directories, use the 'directory' command.
6418 The search path is used to find both program source files and GDB
6419 script files (read using the '-command' option and 'source' command).
6421 In addition to the source path, GDB provides a set of commands that
6422 manage a list of source path substitution rules. A "substitution rule"
6423 specifies how to rewrite source directories stored in the program's
6424 debug information in case the sources were moved to a different
6425 directory between compilation and debugging. A rule is made of two
6426 strings, the first specifying what needs to be rewritten in the path,
6427 and the second specifying how it should be rewritten. In *note set
6428 substitute-path::, we name these two parts FROM and TO respectively.
6429 GDB does a simple string replacement of FROM with TO at the start of the
6430 directory part of the source file name, and uses that result instead of
6431 the original file name to look up the sources.
6433 Using the previous example, suppose the 'foo-1.0' tree has been moved
6434 from '/usr/src' to '/mnt/cross', then you can tell GDB to replace
6435 '/usr/src' in all source path names with '/mnt/cross'. The first lookup
6436 will then be '/mnt/cross/foo-1.0/lib/foo.c' in place of the original
6437 location of '/usr/src/foo-1.0/lib/foo.c'. To define a source path
6438 substitution rule, use the 'set substitute-path' command (*note set
6441 To avoid unexpected substitution results, a rule is applied only if
6442 the FROM part of the directory name ends at a directory separator. For
6443 instance, a rule substituting '/usr/source' into '/mnt/cross' will be
6444 applied to '/usr/source/foo-1.0' but not to '/usr/sourceware/foo-2.0'.
6445 And because the substitution is applied only at the beginning of the
6446 directory name, this rule will not be applied to
6447 '/root/usr/source/baz.c' either.
6449 In many cases, you can achieve the same result using the 'directory'
6450 command. However, 'set substitute-path' can be more efficient in the
6451 case where the sources are organized in a complex tree with multiple
6452 subdirectories. With the 'directory' command, you need to add each
6453 subdirectory of your project. If you moved the entire tree while
6454 preserving its internal organization, then 'set substitute-path' allows
6455 you to direct the debugger to all the sources with one single command.
6457 'set substitute-path' is also more than just a shortcut command. The
6458 source path is only used if the file at the original location no longer
6459 exists. On the other hand, 'set substitute-path' modifies the debugger
6460 behavior to look at the rewritten location instead. So, if for any
6461 reason a source file that is not relevant to your executable is located
6462 at the original location, a substitution rule is the only method
6463 available to point GDB at the new location.
6465 You can configure a default source path substitution rule by
6466 configuring GDB with the '--with-relocated-sources=DIR' option. The DIR
6467 should be the name of a directory under GDB's configured prefix (set
6468 with '--prefix' or '--exec-prefix'), and directory names in debug
6469 information under DIR will be adjusted automatically if the installed
6470 GDB is moved to a new location. This is useful if GDB, libraries or
6471 executables with debug information and corresponding source code are
6472 being moved together.
6474 'directory DIRNAME ...'
6476 Add directory DIRNAME to the front of the source path. Several
6477 directory names may be given to this command, separated by ':' (';'
6478 on MS-DOS and MS-Windows, where ':' usually appears as part of
6479 absolute file names) or whitespace. You may specify a directory
6480 that is already in the source path; this moves it forward, so GDB
6483 You can use the string '$cdir' to refer to the compilation
6484 directory (if one is recorded), and '$cwd' to refer to the current
6485 working directory. '$cwd' is not the same as '.'--the former
6486 tracks the current working directory as it changes during your GDB
6487 session, while the latter is immediately expanded to the current
6488 directory at the time you add an entry to the source path.
6491 Reset the source path to its default value ('$cdir:$cwd' on Unix
6492 systems). This requires confirmation.
6494 'set directories PATH-LIST'
6495 Set the source path to PATH-LIST. '$cdir:$cwd' are added if
6499 Print the source path: show which directories it contains.
6501 'set substitute-path FROM TO'
6502 Define a source path substitution rule, and add it at the end of
6503 the current list of existing substitution rules. If a rule with
6504 the same FROM was already defined, then the old rule is also
6507 For example, if the file '/foo/bar/baz.c' was moved to
6508 '/mnt/cross/baz.c', then the command
6510 (gdb) set substitute-path /usr/src /mnt/cross
6512 will tell GDB to replace '/usr/src' with '/mnt/cross', which will
6513 allow GDB to find the file 'baz.c' even though it was moved.
6515 In the case when more than one substitution rule have been defined,
6516 the rules are evaluated one by one in the order where they have
6517 been defined. The first one matching, if any, is selected to
6518 perform the substitution.
6520 For instance, if we had entered the following commands:
6522 (gdb) set substitute-path /usr/src/include /mnt/include
6523 (gdb) set substitute-path /usr/src /mnt/src
6525 GDB would then rewrite '/usr/src/include/defs.h' into
6526 '/mnt/include/defs.h' by using the first rule. However, it would
6527 use the second rule to rewrite '/usr/src/lib/foo.c' into
6528 '/mnt/src/lib/foo.c'.
6530 'unset substitute-path [path]'
6531 If a path is specified, search the current list of substitution
6532 rules for a rule that would rewrite that path. Delete that rule if
6533 found. A warning is emitted by the debugger if no rule could be
6536 If no path is specified, then all substitution rules are deleted.
6538 'show substitute-path [path]'
6539 If a path is specified, then print the source path substitution
6540 rule which would rewrite that path, if any.
6542 If no path is specified, then print all existing source path
6545 If your source path is cluttered with directories that are no longer
6546 of interest, GDB may sometimes cause confusion by finding the wrong
6547 versions of source. You can correct the situation as follows:
6549 1. Use 'directory' with no argument to reset the source path to its
6552 2. Use 'directory' with suitable arguments to reinstall the
6553 directories you want in the source path. You can add all the
6554 directories in one command.
6557 File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source
6559 9.6 Source and Machine Code
6560 ===========================
6562 You can use the command 'info line' to map source lines to program
6563 addresses (and vice versa), and the command 'disassemble' to display a
6564 range of addresses as machine instructions. You can use the command
6565 'set disassemble-next-line' to set whether to disassemble next source
6566 line when execution stops. When run under GNU Emacs mode, the 'info
6567 line' command causes the arrow to point to the line specified. Also,
6568 'info line' prints addresses in symbolic form as well as hex.
6570 'info line LINESPEC'
6571 Print the starting and ending addresses of the compiled code for
6572 source line LINESPEC. You can specify source lines in any of the
6573 ways documented in *note Specify Location::.
6575 For example, we can use 'info line' to discover the location of the
6576 object code for the first line of function 'm4_changequote':
6578 (gdb) info line m4_changequote
6579 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
6581 We can also inquire (using '*ADDR' as the form for LINESPEC) what source
6582 line covers a particular address:
6583 (gdb) info line *0x63ff
6584 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
6586 After 'info line', the default address for the 'x' command is changed
6587 to the starting address of the line, so that 'x/i' is sufficient to
6588 begin examining the machine code (*note Examining Memory: Memory.).
6589 Also, this address is saved as the value of the convenience variable
6590 '$_' (*note Convenience Variables: Convenience Vars.).
6595 This specialized command dumps a range of memory as machine
6596 instructions. It can also print mixed source+disassembly by
6597 specifying the '/m' modifier and print the raw instructions in hex
6598 as well as in symbolic form by specifying the '/r'. The default
6599 memory range is the function surrounding the program counter of the
6600 selected frame. A single argument to this command is a program
6601 counter value; GDB dumps the function surrounding this value. When
6602 two arguments are given, they should be separated by a comma,
6603 possibly surrounded by whitespace. The arguments specify a range
6604 of addresses to dump, in one of two forms:
6607 the addresses from START (inclusive) to END (exclusive)
6609 the addresses from START (inclusive) to 'START+LENGTH'
6612 When 2 arguments are specified, the name of the function is also
6613 printed (since there could be several functions in the given
6616 The argument(s) can be any expression yielding a numeric value,
6617 such as '0x32c4', '&main+10' or '$pc - 8'.
6619 If the range of memory being disassembled contains current program
6620 counter, the instruction at that location is shown with a '=>'
6623 The following example shows the disassembly of a range of addresses
6624 of HP PA-RISC 2.0 code:
6626 (gdb) disas 0x32c4, 0x32e4
6627 Dump of assembler code from 0x32c4 to 0x32e4:
6628 0x32c4 <main+204>: addil 0,dp
6629 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
6630 0x32cc <main+212>: ldil 0x3000,r31
6631 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
6632 0x32d4 <main+220>: ldo 0(r31),rp
6633 0x32d8 <main+224>: addil -0x800,dp
6634 0x32dc <main+228>: ldo 0x588(r1),r26
6635 0x32e0 <main+232>: ldil 0x3000,r31
6636 End of assembler dump.
6638 Here is an example showing mixed source+assembly for Intel x86, when
6639 the program is stopped just after function prologue:
6642 Dump of assembler code for function main:
6644 0x08048330 <+0>: push %ebp
6645 0x08048331 <+1>: mov %esp,%ebp
6646 0x08048333 <+3>: sub $0x8,%esp
6647 0x08048336 <+6>: and $0xfffffff0,%esp
6648 0x08048339 <+9>: sub $0x10,%esp
6650 6 printf ("Hello.\n");
6651 => 0x0804833c <+12>: movl $0x8048440,(%esp)
6652 0x08048343 <+19>: call 0x8048284 <puts@plt>
6656 0x08048348 <+24>: mov $0x0,%eax
6657 0x0804834d <+29>: leave
6658 0x0804834e <+30>: ret
6660 End of assembler dump.
6662 Here is another example showing raw instructions in hex for AMD
6665 (gdb) disas /r 0x400281,+10
6666 Dump of assembler code from 0x400281 to 0x40028b:
6667 0x0000000000400281: 38 36 cmp %dh,(%rsi)
6668 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
6669 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
6670 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
6671 End of assembler dump.
6673 Addresses cannot be specified as a linespec (*note Specify
6674 Location::). So, for example, if you want to disassemble function 'bar'
6675 in file 'foo.c', you must type 'disassemble 'foo.c'::bar' and not
6676 'disassemble foo.c:bar'.
6678 Some architectures have more than one commonly-used set of
6679 instruction mnemonics or other syntax.
6681 For programs that were dynamically linked and use shared libraries,
6682 instructions that call functions or branch to locations in the shared
6683 libraries might show a seemingly bogus location--it's actually a
6684 location of the relocation table. On some architectures, GDB might be
6685 able to resolve these to actual function names.
6687 'set disassembly-flavor INSTRUCTION-SET'
6688 Select the instruction set to use when disassembling the program
6689 via the 'disassemble' or 'x/i' commands.
6691 Currently this command is only defined for the Intel x86 family.
6692 You can set INSTRUCTION-SET to either 'intel' or 'att'. The
6693 default is 'att', the AT&T flavor used by default by Unix
6694 assemblers for x86-based targets.
6696 'show disassembly-flavor'
6697 Show the current setting of the disassembly flavor.
6699 'set disassemble-next-line'
6700 'show disassemble-next-line'
6701 Control whether or not GDB will disassemble the next source line or
6702 instruction when execution stops. If ON, GDB will display
6703 disassembly of the next source line when execution of the program
6704 being debugged stops. This is _in addition_ to displaying the
6705 source line itself, which GDB always does if possible. If the next
6706 source line cannot be displayed for some reason (e.g., if GDB
6707 cannot find the source file, or there's no line info in the debug
6708 info), GDB will display disassembly of the next _instruction_
6709 instead of showing the next source line. If AUTO, GDB will display
6710 disassembly of next instruction only if the source line cannot be
6711 displayed. This setting causes GDB to display some feedback when
6712 you step through a function with no line info or whose source file
6713 is unavailable. The default is OFF, which means never display the
6714 disassembly of the next line or instruction.
6717 File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top
6722 The usual way to examine data in your program is with the 'print'
6723 command (abbreviated 'p'), or its synonym 'inspect'. It evaluates and
6724 prints the value of an expression of the language your program is
6725 written in (*note Using GDB with Different Languages: Languages.). It
6726 may also print the expression using a Python-based pretty-printer (*note
6731 EXPR is an expression (in the source language). By default the
6732 value of EXPR is printed in a format appropriate to its data type;
6733 you can choose a different format by specifying '/F', where F is a
6734 letter specifying the format; see *note Output Formats: Output
6739 If you omit EXPR, GDB displays the last value again (from the
6740 "value history"; *note Value History: Value History.). This allows
6741 you to conveniently inspect the same value in an alternative
6744 A more low-level way of examining data is with the 'x' command. It
6745 examines data in memory at a specified address and prints it in a
6746 specified format. *Note Examining Memory: Memory.
6748 If you are interested in information about types, or about how the
6749 fields of a struct or a class are declared, use the 'ptype EXP' command
6750 rather than 'print'. *Note Examining the Symbol Table: Symbols.
6752 Another way of examining values of expressions and type information
6753 is through the Python extension command 'explore' (available only if the
6754 GDB build is configured with '--with-python'). It offers an interactive
6755 way to start at the highest level (or, the most abstract level) of the
6756 data type of an expression (or, the data type itself) and explore all
6757 the way down to leaf scalar values/fields embedded in the higher level
6761 ARG is either an expression (in the source language), or a type
6762 visible in the current context of the program being debugged.
6764 The working of the 'explore' command can be illustrated with an
6765 example. If a data type 'struct ComplexStruct' is defined in your C
6774 struct ComplexStruct
6776 struct SimpleStruct *ss_p;
6780 followed by variable declarations as
6782 struct SimpleStruct ss = { 10, 1.11 };
6783 struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } };
6785 then, the value of the variable 'cs' can be explored using the 'explore'
6789 The value of `cs' is a struct/class of type `struct ComplexStruct' with
6790 the following fields:
6792 ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'>
6793 arr = <Enter 1 to explore this field of type `int [10]'>
6795 Enter the field number of choice:
6797 Since the fields of 'cs' are not scalar values, you are being prompted
6798 to chose the field you want to explore. Let's say you choose the field
6799 'ss_p' by entering '0'. Then, since this field is a pointer, you will
6800 be asked if it is pointing to a single value. From the declaration of
6801 'cs' above, it is indeed pointing to a single value, hence you enter
6802 'y'. If you enter 'n', then you will be asked if it were pointing to an
6803 array of values, in which case this field will be explored as if it were
6806 `cs.ss_p' is a pointer to a value of type `struct SimpleStruct'
6807 Continue exploring it as a pointer to a single value [y/n]: y
6808 The value of `*(cs.ss_p)' is a struct/class of type `struct
6809 SimpleStruct' with the following fields:
6811 i = 10 .. (Value of type `int')
6812 d = 1.1100000000000001 .. (Value of type `double')
6814 Press enter to return to parent value:
6816 If the field 'arr' of 'cs' was chosen for exploration by entering '1'
6817 earlier, then since it is as array, you will be prompted to enter the
6818 index of the element in the array that you want to explore.
6820 `cs.arr' is an array of `int'.
6821 Enter the index of the element you want to explore in `cs.arr': 5
6823 `(cs.arr)[5]' is a scalar value of type `int'.
6827 Press enter to return to parent value:
6829 In general, at any stage of exploration, you can go deeper towards
6830 the leaf values by responding to the prompts appropriately, or hit the
6831 return key to return to the enclosing data structure (the higher level
6834 Similar to exploring values, you can use the 'explore' command to
6835 explore types. Instead of specifying a value (which is typically a
6836 variable name or an expression valid in the current context of the
6837 program being debugged), you specify a type name. If you consider the
6838 same example as above, your can explore the type 'struct ComplexStruct'
6839 by passing the argument 'struct ComplexStruct' to the 'explore' command.
6841 (gdb) explore struct ComplexStruct
6843 By responding to the prompts appropriately in the subsequent interactive
6844 session, you can explore the type 'struct ComplexStruct' in a manner
6845 similar to how the value 'cs' was explored in the above example.
6847 The 'explore' command also has two sub-commands, 'explore value' and
6848 'explore type'. The former sub-command is a way to explicitly specify
6849 that value exploration of the argument is being invoked, while the
6850 latter is a way to explicitly specify that type exploration of the
6851 argument is being invoked.
6853 'explore value EXPR'
6854 This sub-command of 'explore' explores the value of the expression
6855 EXPR (if EXPR is an expression valid in the current context of the
6856 program being debugged). The behavior of this command is identical
6857 to that of the behavior of the 'explore' command being passed the
6861 This sub-command of 'explore' explores the type of ARG (if ARG is a
6862 type visible in the current context of program being debugged), or
6863 the type of the value/expression ARG (if ARG is an expression valid
6864 in the current context of the program being debugged). If ARG is a
6865 type, then the behavior of this command is identical to that of the
6866 'explore' command being passed the argument ARG. If ARG is an
6867 expression, then the behavior of this command will be identical to
6868 that of the 'explore' command being passed the type of ARG as the
6873 * Expressions:: Expressions
6874 * Ambiguous Expressions:: Ambiguous Expressions
6875 * Variables:: Program variables
6876 * Arrays:: Artificial arrays
6877 * Output Formats:: Output formats
6878 * Memory:: Examining memory
6879 * Auto Display:: Automatic display
6880 * Print Settings:: Print settings
6881 * Pretty Printing:: Python pretty printing
6882 * Value History:: Value history
6883 * Convenience Vars:: Convenience variables
6884 * Convenience Funs:: Convenience functions
6885 * Registers:: Registers
6886 * Floating Point Hardware:: Floating point hardware
6887 * Vector Unit:: Vector Unit
6888 * OS Information:: Auxiliary data provided by operating system
6889 * Memory Region Attributes:: Memory region attributes
6890 * Dump/Restore Files:: Copy between memory and a file
6891 * Core File Generation:: Cause a program dump its core
6892 * Character Sets:: Debugging programs that use a different
6893 character set than GDB does
6894 * Caching Target Data:: Data caching for targets
6895 * Searching Memory:: Searching memory for a sequence of bytes
6898 File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data
6903 'print' and many other GDB commands accept an expression and compute its
6904 value. Any kind of constant, variable or operator defined by the
6905 programming language you are using is valid in an expression in GDB.
6906 This includes conditional expressions, function calls, casts, and string
6907 constants. It also includes preprocessor macros, if you compiled your
6908 program to include this information; see *note Compilation::.
6910 GDB supports array constants in expressions input by the user. The
6911 syntax is {ELEMENT, ELEMENT...}. For example, you can use the command
6912 'print {1, 2, 3}' to create an array of three integers. If you pass an
6913 array to a function or assign it to a program variable, GDB copies the
6914 array to memory that is 'malloc'ed in the target program.
6916 Because C is so widespread, most of the expressions shown in examples
6917 in this manual are in C. *Note Using GDB with Different Languages:
6918 Languages, for information on how to use expressions in other languages.
6920 In this section, we discuss operators that you can use in GDB
6921 expressions regardless of your programming language.
6923 Casts are supported in all languages, not just in C, because it is so
6924 useful to cast a number into a pointer in order to examine a structure
6925 at that address in memory.
6927 GDB supports these operators, in addition to those common to
6928 programming languages:
6931 '@' is a binary operator for treating parts of memory as arrays.
6932 *Note Artificial Arrays: Arrays, for more information.
6935 '::' allows you to specify a variable in terms of the file or
6936 function where it is defined. *Note Program Variables: Variables.
6939 Refers to an object of type TYPE stored at address ADDR in memory.
6940 The address ADDR may be any expression whose value is an integer or
6941 pointer (but parentheses are required around binary operators, just
6942 as in a cast). This construct is allowed regardless of what kind
6943 of data is normally supposed to reside at ADDR.
6946 File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data
6948 10.2 Ambiguous Expressions
6949 ==========================
6951 Expressions can sometimes contain some ambiguous elements. For
6952 instance, some programming languages (notably Ada, C++ and Objective-C)
6953 permit a single function name to be defined several times, for
6954 application in different contexts. This is called "overloading".
6955 Another example involving Ada is generics. A "generic package" is
6956 similar to C++ templates and is typically instantiated several times,
6957 resulting in the same function name being defined in different contexts.
6959 In some cases and depending on the language, it is possible to adjust
6960 the expression to remove the ambiguity. For instance in C++, you can
6961 specify the signature of the function you want to break on, as in 'break
6962 FUNCTION(TYPES)'. In Ada, using the fully qualified name of your
6963 function often makes the expression unambiguous as well.
6965 When an ambiguity that needs to be resolved is detected, the debugger
6966 has the capability to display a menu of numbered choices for each
6967 possibility, and then waits for the selection with the prompt '>'. The
6968 first option is always '[0] cancel', and typing '0 <RET>' aborts the
6969 current command. If the command in which the expression was used allows
6970 more than one choice to be selected, the next option in the menu is '[1]
6971 all', and typing '1 <RET>' selects all possible choices.
6973 For example, the following session excerpt shows an attempt to set a
6974 breakpoint at the overloaded symbol 'String::after'. We choose three
6975 particular definitions of that function name:
6977 (gdb) b String::after
6980 [2] file:String.cc; line number:867
6981 [3] file:String.cc; line number:860
6982 [4] file:String.cc; line number:875
6983 [5] file:String.cc; line number:853
6984 [6] file:String.cc; line number:846
6985 [7] file:String.cc; line number:735
6987 Breakpoint 1 at 0xb26c: file String.cc, line 867.
6988 Breakpoint 2 at 0xb344: file String.cc, line 875.
6989 Breakpoint 3 at 0xafcc: file String.cc, line 846.
6990 Multiple breakpoints were set.
6991 Use the "delete" command to delete unwanted
6995 'set multiple-symbols MODE'
6997 This option allows you to adjust the debugger behavior when an
6998 expression is ambiguous.
7000 By default, MODE is set to 'all'. If the command with which the
7001 expression is used allows more than one choice, then GDB
7002 automatically selects all possible choices. For instance,
7003 inserting a breakpoint on a function using an ambiguous name
7004 results in a breakpoint inserted on each possible match. However,
7005 if a unique choice must be made, then GDB uses the menu to help you
7006 disambiguate the expression. For instance, printing the address of
7007 an overloaded function will result in the use of the menu.
7009 When MODE is set to 'ask', the debugger always uses the menu when
7010 an ambiguity is detected.
7012 Finally, when MODE is set to 'cancel', the debugger reports an
7013 error due to the ambiguity and the command is aborted.
7015 'show multiple-symbols'
7016 Show the current value of the 'multiple-symbols' setting.
projects / platform / upstream / gdb.git / blob