1 This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
3 INFO-DIR-SECTION Software development
5 * Gdb: (gdb). The GNU debugger.
8 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
9 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
10 2010 2011, 2012 Free Software Foundation, Inc.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being "Free Software" and "Free Software Needs Free
16 Documentation", with the Front-Cover Texts being "A GNU Manual," and
17 with the Back-Cover Texts as in (a) below.
19 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
20 this GNU Manual. Buying copies from GNU Press supports the FSF in
21 developing GNU and promoting software freedom."
23 This file documents the GNU debugger GDB.
25 This is the Tenth Edition, of `Debugging with GDB: the GNU
26 Source-Level Debugger' for GDB (GDB) Version 7.5.1.
28 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
29 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
30 2010 2011, 2012 Free Software Foundation, Inc.
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.3 or
34 any later version published by the Free Software Foundation; with the
35 Invariant Sections being "Free Software" and "Free Software Needs Free
36 Documentation", with the Front-Cover Texts being "A GNU Manual," and
37 with the Back-Cover Texts as in (a) below.
39 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
40 this GNU Manual. Buying copies from GNU Press supports the FSF in
41 developing GNU and promoting software freedom."
44 File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir)
49 This file describes GDB, the GNU symbolic debugger.
51 This is the Tenth Edition, for GDB (GDB) Version 7.5.1.
53 Copyright (C) 1988-2012 Free Software Foundation, Inc.
55 This edition of the GDB manual is dedicated to the memory of Fred
56 Fish. Fred was a long-standing contributor to GDB and to Free software
57 in general. We will miss him.
61 * Summary:: Summary of GDB
62 * Sample Session:: A sample GDB session
64 * Invocation:: Getting in and out of GDB
65 * Commands:: GDB commands
66 * Running:: Running programs under GDB
67 * Stopping:: Stopping and continuing
68 * Reverse Execution:: Running programs backward
69 * Process Record and Replay:: Recording inferior's execution and replaying it
70 * Stack:: Examining the stack
71 * Source:: Examining source files
72 * Data:: Examining data
73 * Optimized Code:: Debugging optimized code
74 * Macros:: Preprocessor Macros
75 * Tracepoints:: Debugging remote targets non-intrusively
76 * Overlays:: Debugging programs that use overlays
78 * Languages:: Using GDB with different languages
80 * Symbols:: Examining the symbol table
81 * Altering:: Altering execution
82 * GDB Files:: GDB files
83 * Targets:: Specifying a debugging target
84 * Remote Debugging:: Debugging remote programs
85 * Configurations:: Configuration-specific information
86 * Controlling GDB:: Controlling GDB
87 * Extending GDB:: Extending GDB
88 * Interpreters:: Command Interpreters
89 * TUI:: GDB Text User Interface
90 * Emacs:: Using GDB under GNU Emacs
91 * GDB/MI:: GDB's Machine Interface.
92 * Annotations:: GDB's annotation interface.
93 * JIT Interface:: Using the JIT debugging interface.
94 * In-Process Agent:: In-Process Agent
96 * GDB Bugs:: Reporting bugs in GDB
99 * Command Line Editing:: Command Line Editing
100 * Using History Interactively:: Using History Interactively
101 * In Memoriam:: In Memoriam
102 * Formatting Documentation:: How to format and print GDB documentation
103 * Installing GDB:: Installing GDB
104 * Maintenance Commands:: Maintenance Commands
105 * Remote Protocol:: GDB Remote Serial Protocol
106 * Agent Expressions:: The GDB Agent Expression Mechanism
107 * Target Descriptions:: How targets can describe themselves to
109 * Operating System Information:: Getting additional information from
111 * Trace File Format:: GDB trace file format
112 * Index Section Format:: .gdb_index section format
113 * Copying:: GNU General Public License says
114 how you can copy and share GDB
115 * GNU Free Documentation License:: The license for this documentation
116 * Concept Index:: Index of GDB concepts
117 * Command and Variable Index:: Index of GDB commands, variables,
118 functions, and Python data types
121 File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top
126 The purpose of a debugger such as GDB is to allow you to see what is
127 going on "inside" another program while it executes--or what another
128 program was doing at the moment it crashed.
130 GDB can do four main kinds of things (plus other things in support of
131 these) to help you catch bugs in the act:
133 * Start your program, specifying anything that might affect its
136 * Make your program stop on specified conditions.
138 * Examine what has happened, when your program has stopped.
140 * Change things in your program, so you can experiment with
141 correcting the effects of one bug and go on to learn about another.
143 You can use GDB to debug programs written in C and C++. For more
144 information, see *Note Supported Languages: Supported Languages. For
145 more information, see *Note C and C++: C.
147 Support for D is partial. For information on D, see *Note D: D.
149 Support for Modula-2 is partial. For information on Modula-2, see
150 *Note Modula-2: Modula-2.
152 Support for OpenCL C is partial. For information on OpenCL C, see
153 *Note OpenCL C: OpenCL C.
155 Debugging Pascal programs which use sets, subranges, file variables,
156 or nested functions does not currently work. GDB does not support
157 entering expressions, printing values, or similar features using Pascal
160 GDB can be used to debug programs written in Fortran, although it
161 may be necessary to refer to some variables with a trailing underscore.
163 GDB can be used to debug programs written in Objective-C, using
164 either the Apple/NeXT or the GNU Objective-C runtime.
168 * Free Software:: Freely redistributable software
169 * Free Documentation:: Free Software Needs Free Documentation
170 * Contributors:: Contributors to GDB
173 File: gdb.info, Node: Free Software, Next: Free Documentation, Up: Summary
178 GDB is "free software", protected by the GNU General Public License
179 (GPL). The GPL gives you the freedom to copy or adapt a licensed
180 program--but every person getting a copy also gets with it the freedom
181 to modify that copy (which means that they must get access to the
182 source code), and the freedom to distribute further copies. Typical
183 software companies use copyrights to limit your freedoms; the Free
184 Software Foundation uses the GPL to preserve these freedoms.
186 Fundamentally, the General Public License is a license which says
187 that you have these freedoms and that you cannot take these freedoms
188 away from anyone else.
191 File: gdb.info, Node: Free Documentation, Next: Contributors, Prev: Free Software, Up: Summary
193 Free Software Needs Free Documentation
194 ======================================
196 The biggest deficiency in the free software community today is not in
197 the software--it is the lack of good free documentation that we can
198 include with the free software. Many of our most important programs do
199 not come with free reference manuals and free introductory texts.
200 Documentation is an essential part of any software package; when an
201 important free software package does not come with a free manual and a
202 free tutorial, that is a major gap. We have many such gaps today.
204 Consider Perl, for instance. The tutorial manuals that people
205 normally use are non-free. How did this come about? Because the
206 authors of those manuals published them with restrictive terms--no
207 copying, no modification, source files not available--which exclude
208 them from the free software world.
210 That wasn't the first time this sort of thing happened, and it was
211 far from the last. Many times we have heard a GNU user eagerly
212 describe a manual that he is writing, his intended contribution to the
213 community, only to learn that he had ruined everything by signing a
214 publication contract to make it non-free.
216 Free documentation, like free software, is a matter of freedom, not
217 price. The problem with the non-free manual is not that publishers
218 charge a price for printed copies--that in itself is fine. (The Free
219 Software Foundation sells printed copies of manuals, too.) The problem
220 is the restrictions on the use of the manual. Free manuals are
221 available in source code form, and give you permission to copy and
222 modify. Non-free manuals do not allow this.
224 The criteria of freedom for a free manual are roughly the same as for
225 free software. Redistribution (including the normal kinds of
226 commercial redistribution) must be permitted, so that the manual can
227 accompany every copy of the program, both on-line and on paper.
229 Permission for modification of the technical content is crucial too.
230 When people modify the software, adding or changing features, if they
231 are conscientious they will change the manual too--so they can provide
232 accurate and clear documentation for the modified program. A manual
233 that leaves you no choice but to write a new manual to document a
234 changed version of the program is not really available to our community.
236 Some kinds of limits on the way modification is handled are
237 acceptable. For example, requirements to preserve the original
238 author's copyright notice, the distribution terms, or the list of
239 authors, are ok. It is also no problem to require modified versions to
240 include notice that they were modified. Even entire sections that may
241 not be deleted or changed are acceptable, as long as they deal with
242 nontechnical topics (like this one). These kinds of restrictions are
243 acceptable because they don't obstruct the community's normal use of
246 However, it must be possible to modify all the _technical_ content
247 of the manual, and then distribute the result in all the usual media,
248 through all the usual channels. Otherwise, the restrictions obstruct
249 the use of the manual, it is not free, and we need another manual to
252 Please spread the word about this issue. Our community continues to
253 lose manuals to proprietary publishing. If we spread the word that
254 free software needs free reference manuals and free tutorials, perhaps
255 the next person who wants to contribute by writing documentation will
256 realize, before it is too late, that only free manuals contribute to
257 the free software community.
259 If you are writing documentation, please insist on publishing it
260 under the GNU Free Documentation License or another free documentation
261 license. Remember that this decision requires your approval--you don't
262 have to let the publisher decide. Some commercial publishers will use
263 a free license if you insist, but they will not propose the option; it
264 is up to you to raise the issue and say firmly that this is what you
265 want. If the publisher you are dealing with refuses, please try other
266 publishers. If you're not sure whether a proposed license is free,
267 write to <licensing@gnu.org>.
269 You can encourage commercial publishers to sell more free, copylefted
270 manuals and tutorials by buying them, and particularly by buying copies
271 from the publishers that paid for their writing or for major
272 improvements. Meanwhile, try to avoid buying non-free documentation at
273 all. Check the distribution terms of a manual before you buy it, and
274 insist that whoever seeks your business must respect your freedom.
275 Check the history of the book, and try to reward the publishers that
276 have paid or pay the authors to work on it.
278 The Free Software Foundation maintains a list of free documentation
279 published by other publishers, at
280 `http://www.fsf.org/doc/other-free-books.html'.
283 File: gdb.info, Node: Contributors, Prev: Free Documentation, Up: Summary
288 Richard Stallman was the original author of GDB, and of many other GNU
289 programs. Many others have contributed to its development. This
290 section attempts to credit major contributors. One of the virtues of
291 free software is that everyone is free to contribute to it; with
292 regret, we cannot actually acknowledge everyone here. The file
293 `ChangeLog' in the GDB distribution approximates a blow-by-blow account.
295 Changes much prior to version 2.0 are lost in the mists of time.
297 _Plea:_ Additions to this section are particularly welcome. If you
298 or your friends (or enemies, to be evenhanded) have been unfairly
299 omitted from this list, we would like to add your names!
301 So that they may not regard their many labors as thankless, we
302 particularly thank those who shepherded GDB through major releases:
303 Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim
304 Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs
305 (release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10,
306 and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5,
307 and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim
308 Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2,
311 Richard Stallman, assisted at various times by Peter TerMaat, Chris
312 Hanson, and Richard Mlynarik, handled releases through 2.8.
314 Michael Tiemann is the author of most of the GNU C++ support in GDB,
315 with significant additional contributions from Per Bothner and Daniel
316 Berlin. James Clark wrote the GNU C++ demangler. Early work on C++
317 was by Peter TerMaat (who also did much general update work leading to
320 GDB uses the BFD subroutine library to examine multiple object-file
321 formats; BFD was a joint project of David V. Henkel-Wallace, Rich
322 Pixley, Steve Chamberlain, and John Gilmore.
324 David Johnson wrote the original COFF support; Pace Willison did the
325 original support for encapsulated COFF.
327 Brent Benson of Harris Computer Systems contributed DWARF 2 support.
329 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
330 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
331 support. Jean-Daniel Fekete contributed Sun 386i support. Chris
332 Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
333 Hasei contributed Sony/News OS 3 support. David Johnson contributed
334 Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
335 Jeff Law contributed HP PA and SOM support. Keith Packard contributed
336 NS32K support. Doug Rabson contributed Acorn Risc Machine support.
337 Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith
338 contributed Convex support (and Fortran debugging). Jonathan Stone
339 contributed Pyramid support. Michael Tiemann contributed SPARC support.
340 Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
341 Pace Willison contributed Intel 386 support. Jay Vosburgh contributed
342 Symmetry support. Marko Mlinar contributed OpenRISC 1000 support.
344 Andreas Schwab contributed M68K GNU/Linux support.
346 Rich Schaefer and Peter Schauer helped with support of SunOS shared
349 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
350 several machine instruction sets.
352 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
353 develop remote debugging. Intel Corporation, Wind River Systems, AMD,
354 and ARM contributed remote debugging modules for the i960, VxWorks,
355 A29K UDI, and RDI targets, respectively.
357 Brian Fox is the author of the readline libraries providing
358 command-line editing and command history.
360 Andrew Beers of SUNY Buffalo wrote the language-switching code, the
361 Modula-2 support, and contributed the Languages chapter of this manual.
363 Fred Fish wrote most of the support for Unix System Vr4. He also
364 enhanced the command-completion support to cover C++ overloaded symbols.
366 Hitachi America (now Renesas America), Ltd. sponsored the support for
367 H8/300, H8/500, and Super-H processors.
369 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx
372 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and
375 Toshiba sponsored the support for the TX39 Mips processor.
377 Matsushita sponsored the support for the MN10200 and MN10300
380 Fujitsu sponsored the support for SPARClite and FR30 processors.
382 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
385 Michael Snyder added support for tracepoints.
387 Stu Grossman wrote gdbserver.
389 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly
390 innumerable bug fixes and cleanups throughout GDB.
392 The following people at the Hewlett-Packard Company contributed
393 support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
394 (narrow mode), HP's implementation of kernel threads, HP's aC++
395 compiler, and the Text User Interface (nee Terminal User Interface):
396 Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
397 Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
398 provided HP-specific information in this manual.
400 DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert
401 Hoehne made significant contributions to the DJGPP port.
403 Cygnus Solutions has sponsored GDB maintenance and much of its
404 development since 1991. Cygnus engineers who have worked on GDB
405 fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
406 Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
407 Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
408 Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
409 Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
410 addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
411 JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
412 Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
413 Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
414 Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
415 Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
416 Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
417 Zuhn have made contributions both large and small.
419 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
420 Cygnus Solutions, implemented the original GDB/MI interface.
422 Jim Blandy added support for preprocessor macros, while working for
425 Andrew Cagney designed GDB's architecture vector. Many people
426 including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek,
427 Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto,
428 Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna
429 Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration
430 of old architectures to this new framework.
432 Andrew Cagney completely re-designed and re-implemented GDB's
433 unwinder framework, this consisting of a fresh new design featuring
434 frame IDs, independent frame sniffers, and the sentinel frame. Mark
435 Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind
436 unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad
437 unwinders. The architecture-specific changes, each involving a
438 complete rewrite of the architecture's frame code, were carried out by
439 Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
440 Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
441 Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
442 Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
445 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
446 Tensilica, Inc. contributed support for Xtensa processors. Others who
447 have worked on the Xtensa port of GDB in the past include Steve Tjiang,
448 John Newlin, and Scott Foehner.
450 Michael Eager and staff of Xilinx, Inc., contributed support for the
451 Xilinx MicroBlaze architecture.
454 File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
456 1 A Sample GDB Session
457 **********************
459 You can use this manual at your leisure to read all about GDB.
460 However, a handful of commands are enough to get started using the
461 debugger. This chapter illustrates those commands.
463 One of the preliminary versions of GNU `m4' (a generic macro
464 processor) exhibits the following bug: sometimes, when we change its
465 quote strings from the default, the commands used to capture one macro
466 definition within another stop working. In the following short `m4'
467 session, we define a macro `foo' which expands to `0000'; we then use
468 the `m4' built-in `defn' to define `bar' as the same thing. However,
469 when we change the open quote string to `<QUOTE>' and the close quote
470 string to `<UNQUOTE>', the same procedure fails to define a new synonym
479 define(bar,defn(`foo'))
483 changequote(<QUOTE>,<UNQUOTE>)
485 define(baz,defn(<QUOTE>foo<UNQUOTE>))
488 m4: End of input: 0: fatal error: EOF in string
490 Let us use GDB to try to see what is going on.
493 GDB is free software and you are welcome to distribute copies
494 of it under certain conditions; type "show copying" to see
496 There is absolutely no warranty for GDB; type "show warranty"
499 GDB 7.5.1, Copyright 1999 Free Software Foundation, Inc...
502 GDB reads only enough symbol data to know where to find the rest when
503 needed; as a result, the first prompt comes up very quickly. We now
504 tell GDB to use a narrower display width than usual, so that examples
509 We need to see how the `m4' built-in `changequote' works. Having
510 looked at the source, we know the relevant subroutine is
511 `m4_changequote', so we set a breakpoint there with the GDB `break'
514 (gdb) break m4_changequote
515 Breakpoint 1 at 0x62f4: file builtin.c, line 879.
517 Using the `run' command, we start `m4' running under GDB control; as
518 long as control does not reach the `m4_changequote' subroutine, the
519 program runs as usual:
522 Starting program: /work/Editorial/gdb/gnu/m4/m4
528 To trigger the breakpoint, we call `changequote'. GDB suspends
529 execution of `m4', displaying information about the context where it
532 changequote(<QUOTE>,<UNQUOTE>)
534 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
536 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
538 Now we use the command `n' (`next') to advance execution to the next
539 line of the current function.
542 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
545 `set_quotes' looks like a promising subroutine. We can go into it by
546 using the command `s' (`step') instead of `next'. `step' goes to the
547 next line to be executed in _any_ subroutine, so it steps into
551 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
553 530 if (lquote != def_lquote)
555 The display that shows the subroutine where `m4' is now suspended (and
556 its arguments) is called a stack frame display. It shows a summary of
557 the stack. We can use the `backtrace' command (which can also be
558 spelled `bt'), to see where we are in the stack as a whole: the
559 `backtrace' command displays a stack frame for each active subroutine.
562 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
564 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
566 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
567 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
569 #4 0x79dc in expand_input () at macro.c:40
570 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
572 We step through a few more lines to see what happens. The first two
573 times, we can use `s'; the next two times we use `n' to avoid falling
574 into the `xstrdup' subroutine.
577 0x3b5c 532 if (rquote != def_rquote)
579 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
580 def_lquote : xstrdup(lq);
582 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
585 538 len_lquote = strlen(rquote);
587 The last line displayed looks a little odd; we can examine the variables
588 `lquote' and `rquote' to see if they are in fact the new left and right
589 quotes we specified. We use the command `p' (`print') to see their
593 $1 = 0x35d40 "<QUOTE>"
595 $2 = 0x35d50 "<UNQUOTE>"
597 `lquote' and `rquote' are indeed the new left and right quotes. To
598 look at some context, we can display ten lines of source surrounding
599 the current line with the `l' (`list') command.
604 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
606 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
609 538 len_lquote = strlen(rquote);
610 539 len_rquote = strlen(lquote);
615 Let us step past the two lines that set `len_lquote' and `len_rquote',
616 and then examine the values of those variables.
619 539 len_rquote = strlen(lquote);
627 That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
628 meant to be the lengths of `lquote' and `rquote' respectively. We can
629 set them to better values using the `p' command, since it can print the
630 value of any expression--and that expression can include subroutine
631 calls and assignments.
633 (gdb) p len_lquote=strlen(lquote)
635 (gdb) p len_rquote=strlen(rquote)
638 Is that enough to fix the problem of using the new quotes with the `m4'
639 built-in `defn'? We can allow `m4' to continue executing with the `c'
640 (`continue') command, and then try the example that caused trouble
646 define(baz,defn(<QUOTE>foo<UNQUOTE>))
651 Success! The new quotes now work just as well as the default ones. The
652 problem seems to have been just the two typos defining the wrong
653 lengths. We allow `m4' exit by giving it an EOF as input:
656 Program exited normally.
658 The message `Program exited normally.' is from GDB; it indicates `m4'
659 has finished executing. We can end our GDB session with the GDB `quit'
665 File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top
667 2 Getting In and Out of GDB
668 ***************************
670 This chapter discusses how to start GDB, and how to get out of it. The
672 * type `gdb' to start GDB.
674 * type `quit' or `Ctrl-d' to exit.
678 * Invoking GDB:: How to start GDB
679 * Quitting GDB:: How to quit GDB
680 * Shell Commands:: How to use shell commands inside GDB
681 * Logging Output:: How to log GDB's output to a file
684 File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation
689 Invoke GDB by running the program `gdb'. Once started, GDB reads
690 commands from the terminal until you tell it to exit.
692 You can also run `gdb' with a variety of arguments and options, to
693 specify more of your debugging environment at the outset.
695 The command-line options described here are designed to cover a
696 variety of situations; in some environments, some of these options may
697 effectively be unavailable.
699 The most usual way to start GDB is with one argument, specifying an
704 You can also start with both an executable program and a core file
709 You can, instead, specify a process ID as a second argument, if you
710 want to debug a running process:
714 would attach GDB to process `1234' (unless you also have a file named
715 `1234'; GDB does check for a core file first).
717 Taking advantage of the second command-line argument requires a
718 fairly complete operating system; when you use GDB as a remote debugger
719 attached to a bare board, there may not be any notion of "process", and
720 there is often no way to get a core dump. GDB will warn you if it is
721 unable to attach or to read core dumps.
723 You can optionally have `gdb' pass any arguments after the
724 executable file to the inferior using `--args'. This option stops
726 gdb --args gcc -O2 -c foo.c
727 This will cause `gdb' to debug `gcc', and to set `gcc''s
728 command-line arguments (*note Arguments::) to `-O2 -c foo.c'.
730 You can run `gdb' without printing the front material, which
731 describes GDB's non-warranty, by specifying `-silent':
735 You can further control how GDB starts up by using command-line
736 options. GDB itself can remind you of the options available.
742 to display all available options and briefly describe their use (`gdb
743 -h' is a shorter equivalent).
745 All options and command line arguments you give are processed in
746 sequential order. The order makes a difference when the `-x' option is
751 * File Options:: Choosing files
752 * Mode Options:: Choosing modes
753 * Startup:: What GDB does during startup
756 File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
761 When GDB starts, it reads any arguments other than options as
762 specifying an executable file and core file (or process ID). This is
763 the same as if the arguments were specified by the `-se' and `-c' (or
764 `-p') options respectively. (GDB reads the first argument that does
765 not have an associated option flag as equivalent to the `-se' option
766 followed by that argument; and the second argument that does not have
767 an associated option flag, if any, as equivalent to the `-c'/`-p'
768 option followed by that argument.) If the second argument begins with
769 a decimal digit, GDB will first attempt to attach to it as a process,
770 and if that fails, attempt to open it as a corefile. If you have a
771 corefile whose name begins with a digit, you can prevent GDB from
772 treating it as a pid by prefixing it with `./', e.g. `./12345'.
774 If GDB has not been configured to included core file support, such
775 as for most embedded targets, then it will complain about a second
776 argument and ignore it.
778 Many options have both long and short forms; both are shown in the
779 following list. GDB also recognizes the long forms if you truncate
780 them, so long as enough of the option is present to be unambiguous.
781 (If you prefer, you can flag option arguments with `--' rather than
782 `-', though we illustrate the more usual convention.)
786 Read symbol table from file FILE.
790 Use file FILE as the executable file to execute when appropriate,
791 and for examining pure data in conjunction with a core dump.
794 Read symbol table from file FILE and use it as the executable file.
798 Use file FILE as a core dump to examine.
802 Connect to process ID NUMBER, as with the `attach' command.
806 Execute commands from file FILE. The contents of this file is
807 evaluated exactly as the `source' command would. *Note Command
808 files: Command Files.
810 `-eval-command COMMAND'
812 Execute a single GDB command.
814 This option may be used multiple times to call multiple commands.
815 It may also be interleaved with `-command' as required.
817 gdb -ex 'target sim' -ex 'load' \
818 -x setbreakpoints -ex 'run' a.out
822 Execute commands from file FILE before loading the inferior (but
823 after loading gdbinit files). *Note Startup::.
825 `-init-eval-command COMMAND'
827 Execute a single GDB command before loading the inferior (but
828 after loading gdbinit files). *Note Startup::.
830 `-directory DIRECTORY'
832 Add DIRECTORY to the path to search for source and script files.
836 Read each symbol file's entire symbol table immediately, rather
837 than the default, which is to read it incrementally as it is
838 needed. This makes startup slower, but makes future operations
843 File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB
848 You can run GDB in various alternative modes--for example, in batch
853 Do not execute commands found in any initialization files.
854 Normally, GDB executes the commands in these files after all the
855 command options and arguments have been processed. *Note Command
856 Files: Command Files.
861 "Quiet". Do not print the introductory and copyright messages.
862 These messages are also suppressed in batch mode.
865 Run in batch mode. Exit with status `0' after processing all the
866 command files specified with `-x' (and all commands from
867 initialization files, if not inhibited with `-n'). Exit with
868 nonzero status if an error occurs in executing the GDB commands in
869 the command files. Batch mode also disables pagination, sets
870 unlimited terminal width and height *note Screen Size::, and acts
871 as if `set confirm off' were in effect (*note Messages/Warnings::).
873 Batch mode may be useful for running GDB as a filter, for example
874 to download and run a program on another computer; in order to
875 make this more useful, the message
877 Program exited normally.
879 (which is ordinarily issued whenever a program running under GDB
880 control terminates) is not issued when running in batch mode.
883 Run in batch mode exactly like `-batch', but totally silently. All
884 GDB output to `stdout' is prevented (`stderr' is unaffected).
885 This is much quieter than `-silent' and would be useless for an
888 This is particularly useful when using targets that give `Loading
889 section' messages, for example.
891 Note that targets that give their output via GDB, as opposed to
892 writing directly to `stdout', will also be made silent.
894 `-return-child-result'
895 The return code from GDB will be the return code from the child
896 process (the process being debugged), with the following
899 * GDB exits abnormally. E.g., due to an incorrect argument or
900 an internal error. In this case the exit code is the same as
901 it would have been without `-return-child-result'.
903 * The user quits with an explicit value. E.g., `quit 1'.
905 * The child process never runs, or is not allowed to terminate,
906 in which case the exit code will be -1.
908 This option is useful in conjunction with `-batch' or
909 `-batch-silent', when GDB is being used as a remote program loader
910 or simulator interface.
914 "No windows". If GDB comes with a graphical user interface (GUI)
915 built in, then this option tells GDB to only use the command-line
916 interface. If no GUI is available, this option has no effect.
920 If GDB includes a GUI, then this option requires it to be used if
924 Run GDB using DIRECTORY as its working directory, instead of the
927 `-data-directory DIRECTORY'
928 Run GDB using DIRECTORY as its data directory. The data directory
929 is where GDB searches for its auxiliary files. *Note Data Files::.
933 GNU Emacs sets this option when it runs GDB as a subprocess. It
934 tells GDB to output the full file name and line number in a
935 standard, recognizable fashion each time a stack frame is
936 displayed (which includes each time your program stops). This
937 recognizable format looks like two `\032' characters, followed by
938 the file name, line number and character position separated by
939 colons, and a newline. The Emacs-to-GDB interface program uses
940 the two `\032' characters as a signal to display the source code
944 The Epoch Emacs-GDB interface sets this option when it runs GDB as
945 a subprocess. It tells GDB to modify its print routines so as to
946 allow Epoch to display values of expressions in a separate window.
949 This option sets the "annotation level" inside GDB. Its effect is
950 identical to using `set annotate LEVEL' (*note Annotations::).
951 The annotation LEVEL controls how much information GDB prints
952 together with its prompt, values of expressions, source lines, and
953 other types of output. Level 0 is the normal, level 1 is for use
954 when GDB is run as a subprocess of GNU Emacs, level 3 is the
955 maximum annotation suitable for programs that control GDB, and
956 level 2 has been deprecated.
958 The annotation mechanism has largely been superseded by GDB/MI
962 Change interpretation of command line so that arguments following
963 the executable file are passed as command line arguments to the
964 inferior. This option stops option processing.
968 Set the line speed (baud rate or bits per second) of any serial
969 interface used by GDB for remote debugging.
972 Set the timeout (in seconds) of any communication used by GDB for
977 Run using DEVICE for your program's standard input and output.
980 Activate the "Text User Interface" when starting. The Text User
981 Interface manages several text windows on the terminal, showing
982 source, assembly, registers and GDB command outputs (*note GDB
983 Text User Interface: TUI.). Do not use this option if you run GDB
984 from Emacs (*note Using GDB under GNU Emacs: Emacs.).
986 `-interpreter INTERP'
987 Use the interpreter INTERP for interface with the controlling
988 program or device. This option is meant to be set by programs
989 which communicate with GDB using it as a back end. *Note Command
990 Interpreters: Interpreters.
992 `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the
993 "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included
994 since GDB version 6.0. The previous GDB/MI interface, included in
995 GDB version 5.3 and selected with `--interpreter=mi1', is
996 deprecated. Earlier GDB/MI interfaces are no longer supported.
999 Open the executable and core files for both reading and writing.
1000 This is equivalent to the `set write on' command inside GDB (*note
1004 This option causes GDB to print statistics about time and memory
1005 usage after it completes each command and returns to the prompt.
1008 This option causes GDB to print its version number and no-warranty
1013 File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB
1015 2.1.3 What GDB Does During Startup
1016 ----------------------------------
1018 Here's the description of what GDB does during session startup:
1020 1. Sets up the command interpreter as specified by the command line
1021 (*note interpreter: Mode Options.).
1023 2. Reads the system-wide "init file" (if `--with-system-gdbinit' was
1024 used when building GDB; *note System-wide configuration and
1025 settings: System-wide configuration.) and executes all the
1026 commands in that file.
1028 3. Reads the init file (if any) in your home directory(1) and
1029 executes all the commands in that file.
1031 4. Executes commands and command files specified by the `-iex' and
1032 `-ix' options in their specified order. Usually you should use the
1033 `-ex' and `-x' options instead, but this way you can apply
1034 settings before GDB init files get executed and before inferior
1037 5. Processes command line options and operands.
1039 6. Reads and executes the commands from init file (if any) in the
1040 current working directory as long as `set auto-load local-gdbinit'
1041 is set to `on' (*note Init File in the Current Directory::). This
1042 is only done if the current directory is different from your home
1043 directory. Thus, you can have more than one init file, one
1044 generic in your home directory, and another, specific to the
1045 program you are debugging, in the directory where you invoke GDB.
1047 7. If the command line specified a program to debug, or a process to
1048 attach to, or a core file, GDB loads any auto-loaded scripts
1049 provided for the program or for its loaded shared libraries.
1050 *Note Auto-loading::.
1052 If you wish to disable the auto-loading during startup, you must
1053 do something like the following:
1055 $ gdb -iex "set auto-load python-scripts off" myprogram
1057 Option `-ex' does not work because the auto-loading is then turned
1060 8. Executes commands and command files specified by the `-ex' and
1061 `-x' options in their specified order. *Note Command Files::, for
1062 more details about GDB command files.
1064 9. Reads the command history recorded in the "history file". *Note
1065 Command History::, for more details about the command history and
1066 the files where GDB records it.
1068 Init files use the same syntax as "command files" (*note Command
1069 Files::) and are processed by GDB in the same way. The init file in
1070 your home directory can set options (such as `set complaints') that
1071 affect subsequent processing of command line options and operands.
1072 Init files are not executed if you use the `-nx' option (*note Choosing
1073 Modes: Mode Options.).
1075 To display the list of init files loaded by gdb at startup, you can
1078 The GDB init files are normally called `.gdbinit'. The DJGPP port
1079 of GDB uses the name `gdb.ini', due to the limitations of file names
1080 imposed by DOS filesystems. The Windows ports of GDB use the standard
1081 name, but if they find a `gdb.ini' file, they warn you about that and
1082 suggest to rename the file to the standard name.
1084 ---------- Footnotes ----------
1086 (1) On DOS/Windows systems, the home directory is the one pointed to
1087 by the `HOME' environment variable.
1090 File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation
1097 To exit GDB, use the `quit' command (abbreviated `q'), or type an
1098 end-of-file character (usually `Ctrl-d'). If you do not supply
1099 EXPRESSION, GDB will terminate normally; otherwise it will
1100 terminate using the result of EXPRESSION as the error code.
1102 An interrupt (often `Ctrl-c') does not exit from GDB, but rather
1103 terminates the action of any GDB command that is in progress and
1104 returns to GDB command level. It is safe to type the interrupt
1105 character at any time because GDB does not allow it to take effect
1106 until a time when it is safe.
1108 If you have been using GDB to control an attached process or device,
1109 you can release it with the `detach' command (*note Debugging an
1110 Already-running Process: Attach.).
1113 File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation
1118 If you need to execute occasional shell commands during your debugging
1119 session, there is no need to leave or suspend GDB; you can just use the
1122 `shell COMMAND-STRING'
1124 Invoke a standard shell to execute COMMAND-STRING. Note that no
1125 space is needed between `!' and COMMAND-STRING. If it exists, the
1126 environment variable `SHELL' determines which shell to run.
1127 Otherwise GDB uses the default shell (`/bin/sh' on Unix systems,
1128 `COMMAND.COM' on MS-DOS, etc.).
1130 The utility `make' is often needed in development environments. You
1131 do not have to use the `shell' command for this purpose in GDB:
1134 Execute the `make' program with the specified arguments. This is
1135 equivalent to `shell make MAKE-ARGS'.
1138 File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation
1143 You may want to save the output of GDB commands to a file. There are
1144 several commands to control GDB's logging.
1152 `set logging file FILE'
1153 Change the name of the current logfile. The default logfile is
1156 `set logging overwrite [on|off]'
1157 By default, GDB will append to the logfile. Set `overwrite' if
1158 you want `set logging on' to overwrite the logfile instead.
1160 `set logging redirect [on|off]'
1161 By default, GDB output will go to both the terminal and the
1162 logfile. Set `redirect' if you want output to go only to the log
1166 Show the current values of the logging settings.
1169 File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
1174 You can abbreviate a GDB command to the first few letters of the command
1175 name, if that abbreviation is unambiguous; and you can repeat certain
1176 GDB commands by typing just <RET>. You can also use the <TAB> key to
1177 get GDB to fill out the rest of a word in a command (or to show you the
1178 alternatives available, if there is more than one possibility).
1182 * Command Syntax:: How to give commands to GDB
1183 * Completion:: Command completion
1184 * Help:: How to ask GDB for help
1187 File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands
1192 A GDB command is a single line of input. There is no limit on how long
1193 it can be. It starts with a command name, which is followed by
1194 arguments whose meaning depends on the command name. For example, the
1195 command `step' accepts an argument which is the number of times to
1196 step, as in `step 5'. You can also use the `step' command with no
1197 arguments. Some commands do not allow any arguments.
1199 GDB command names may always be truncated if that abbreviation is
1200 unambiguous. Other possible command abbreviations are listed in the
1201 documentation for individual commands. In some cases, even ambiguous
1202 abbreviations are allowed; for example, `s' is specially defined as
1203 equivalent to `step' even though there are other commands whose names
1204 start with `s'. You can test abbreviations by using them as arguments
1205 to the `help' command.
1207 A blank line as input to GDB (typing just <RET>) means to repeat the
1208 previous command. Certain commands (for example, `run') will not
1209 repeat this way; these are commands whose unintentional repetition
1210 might cause trouble and which you are unlikely to want to repeat.
1211 User-defined commands can disable this feature; see *Note dont-repeat:
1214 The `list' and `x' commands, when you repeat them with <RET>,
1215 construct new arguments rather than repeating exactly as typed. This
1216 permits easy scanning of source or memory.
1218 GDB can also use <RET> in another way: to partition lengthy output,
1219 in a way similar to the common utility `more' (*note Screen Size:
1220 Screen Size.). Since it is easy to press one <RET> too many in this
1221 situation, GDB disables command repetition after any command that
1222 generates this sort of display.
1224 Any text from a `#' to the end of the line is a comment; it does
1225 nothing. This is useful mainly in command files (*note Command Files:
1228 The `Ctrl-o' binding is useful for repeating a complex sequence of
1229 commands. This command accepts the current line, like <RET>, and then
1230 fetches the next line relative to the current line from the history for
1234 File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
1236 3.2 Command Completion
1237 ======================
1239 GDB can fill in the rest of a word in a command for you, if there is
1240 only one possibility; it can also show you what the valid possibilities
1241 are for the next word in a command, at any time. This works for GDB
1242 commands, GDB subcommands, and the names of symbols in your program.
1244 Press the <TAB> key whenever you want GDB to fill out the rest of a
1245 word. If there is only one possibility, GDB fills in the word, and
1246 waits for you to finish the command (or press <RET> to enter it). For
1247 example, if you type
1249 (gdb) info bre <TAB>
1251 GDB fills in the rest of the word `breakpoints', since that is the only
1252 `info' subcommand beginning with `bre':
1254 (gdb) info breakpoints
1256 You can either press <RET> at this point, to run the `info breakpoints'
1257 command, or backspace and enter something else, if `breakpoints' does
1258 not look like the command you expected. (If you were sure you wanted
1259 `info breakpoints' in the first place, you might as well just type
1260 <RET> immediately after `info bre', to exploit command abbreviations
1261 rather than command completion).
1263 If there is more than one possibility for the next word when you
1264 press <TAB>, GDB sounds a bell. You can either supply more characters
1265 and try again, or just press <TAB> a second time; GDB displays all the
1266 possible completions for that word. For example, you might want to set
1267 a breakpoint on a subroutine whose name begins with `make_', but when
1268 you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again
1269 displays all the function names in your program that begin with those
1270 characters, for example:
1273 GDB sounds bell; press <TAB> again, to see:
1274 make_a_section_from_file make_environ
1275 make_abs_section make_function_type
1276 make_blockvector make_pointer_type
1277 make_cleanup make_reference_type
1278 make_command make_symbol_completion_list
1281 After displaying the available possibilities, GDB copies your partial
1282 input (`b make_' in the example) so you can finish the command.
1284 If you just want to see the list of alternatives in the first place,
1285 you can press `M-?' rather than pressing <TAB> twice. `M-?' means
1286 `<META> ?'. You can type this either by holding down a key designated
1287 as the <META> shift on your keyboard (if there is one) while typing
1288 `?', or as <ESC> followed by `?'.
1290 Sometimes the string you need, while logically a "word", may contain
1291 parentheses or other characters that GDB normally excludes from its
1292 notion of a word. To permit word completion to work in this situation,
1293 you may enclose words in `'' (single quote marks) in GDB commands.
1295 The most likely situation where you might need this is in typing the
1296 name of a C++ function. This is because C++ allows function
1297 overloading (multiple definitions of the same function, distinguished
1298 by argument type). For example, when you want to set a breakpoint you
1299 may need to distinguish whether you mean the version of `name' that
1300 takes an `int' parameter, `name(int)', or the version that takes a
1301 `float' parameter, `name(float)'. To use the word-completion
1302 facilities in this situation, type a single quote `'' at the beginning
1303 of the function name. This alerts GDB that it may need to consider
1304 more information than usual when you press <TAB> or `M-?' to request
1307 (gdb) b 'bubble( M-?
1308 bubble(double,double) bubble(int,int)
1311 In some cases, GDB can tell that completing a name requires using
1312 quotes. When this happens, GDB inserts the quote for you (while
1313 completing as much as it can) if you do not type the quote in the first
1317 GDB alters your input line to the following, and rings a bell:
1320 In general, GDB can tell that a quote is needed (and inserts it) if you
1321 have not yet started typing the argument list when you ask for
1322 completion on an overloaded symbol.
1324 For more information about overloaded functions, see *Note C++
1325 Expressions: C Plus Plus Expressions. You can use the command `set
1326 overload-resolution off' to disable overload resolution; see *Note GDB
1327 Features for C++: Debugging C Plus Plus.
1329 When completing in an expression which looks up a field in a
1330 structure, GDB also tries(1) to limit completions to the field names
1331 available in the type of the left-hand-side:
1333 (gdb) p gdb_stdout.M-?
1334 magic to_fputs to_rewind
1335 to_data to_isatty to_write
1336 to_delete to_put to_write_async_safe
1339 This is because the `gdb_stdout' is a variable of the type `struct
1340 ui_file' that is defined in GDB sources as follows:
1345 ui_file_flush_ftype *to_flush;
1346 ui_file_write_ftype *to_write;
1347 ui_file_write_async_safe_ftype *to_write_async_safe;
1348 ui_file_fputs_ftype *to_fputs;
1349 ui_file_read_ftype *to_read;
1350 ui_file_delete_ftype *to_delete;
1351 ui_file_isatty_ftype *to_isatty;
1352 ui_file_rewind_ftype *to_rewind;
1353 ui_file_put_ftype *to_put;
1357 ---------- Footnotes ----------
1359 (1) The completer can be confused by certain kinds of invalid
1360 expressions. Also, it only examines the static type of the expression,
1361 not the dynamic type.
1364 File: gdb.info, Node: Help, Prev: Completion, Up: Commands
1369 You can always ask GDB itself for information on its commands, using
1374 You can use `help' (abbreviated `h') with no arguments to display
1375 a short list of named classes of commands:
1378 List of classes of commands:
1380 aliases -- Aliases of other commands
1381 breakpoints -- Making program stop at certain points
1382 data -- Examining data
1383 files -- Specifying and examining files
1384 internals -- Maintenance commands
1385 obscure -- Obscure features
1386 running -- Running the program
1387 stack -- Examining the stack
1388 status -- Status inquiries
1389 support -- Support facilities
1390 tracepoints -- Tracing of program execution without
1391 stopping the program
1392 user-defined -- User-defined commands
1394 Type "help" followed by a class name for a list of
1395 commands in that class.
1396 Type "help" followed by command name for full
1398 Command name abbreviations are allowed if unambiguous.
1402 Using one of the general help classes as an argument, you can get a
1403 list of the individual commands in that class. For example, here
1404 is the help display for the class `status':
1411 info -- Generic command for showing things
1412 about the program being debugged
1413 show -- Generic command for showing things
1416 Type "help" followed by command name for full
1418 Command name abbreviations are allowed if unambiguous.
1422 With a command name as `help' argument, GDB displays a short
1423 paragraph on how to use that command.
1426 The `apropos' command searches through all of the GDB commands,
1427 and their documentation, for the regular expression specified in
1428 ARGS. It prints out all matches found. For example:
1434 alias -- Define a new command that is an alias of an existing command
1435 aliases -- Aliases of other commands
1436 d -- Delete some breakpoints or auto-display expressions
1437 del -- Delete some breakpoints or auto-display expressions
1438 delete -- Delete some breakpoints or auto-display expressions
1441 The `complete ARGS' command lists all the possible completions for
1442 the beginning of a command. Use ARGS to specify the beginning of
1443 the command you want completed. For example:
1454 This is intended for use by GNU Emacs.
1456 In addition to `help', you can use the GDB commands `info' and
1457 `show' to inquire about the state of your program, or the state of GDB
1458 itself. Each command supports many topics of inquiry; this manual
1459 introduces each of them in the appropriate context. The listings under
1460 `info' and under `show' in the Command, Variable, and Function Index
1461 point to all the sub-commands. *Note Command and Variable Index::.
1464 This command (abbreviated `i') is for describing the state of your
1465 program. For example, you can show the arguments passed to a
1466 function with `info args', list the registers currently in use
1467 with `info registers', or list the breakpoints you have set with
1468 `info breakpoints'. You can get a complete list of the `info'
1469 sub-commands with `help info'.
1472 You can assign the result of an expression to an environment
1473 variable with `set'. For example, you can set the GDB prompt to a
1474 $-sign with `set prompt $'.
1477 In contrast to `info', `show' is for describing the state of GDB
1478 itself. You can change most of the things you can `show', by
1479 using the related command `set'; for example, you can control what
1480 number system is used for displays with `set radix', or simply
1481 inquire which is currently in use with `show radix'.
1483 To display all the settable parameters and their current values,
1484 you can use `show' with no arguments; you may also use `info set'.
1485 Both commands produce the same display.
1487 Here are three miscellaneous `show' subcommands, all of which are
1488 exceptional in lacking corresponding `set' commands:
1491 Show what version of GDB is running. You should include this
1492 information in GDB bug-reports. If multiple versions of GDB are
1493 in use at your site, you may need to determine which version of
1494 GDB you are running; as GDB evolves, new commands are introduced,
1495 and old ones may wither away. Also, many system vendors ship
1496 variant versions of GDB, and there are variant versions of GDB in
1497 GNU/Linux distributions as well. The version number is the same
1498 as the one announced when you start GDB.
1502 Display information about permission for copying GDB.
1506 Display the GNU "NO WARRANTY" statement, or a warranty, if your
1507 version of GDB comes with one.
1511 File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top
1513 4 Running Programs Under GDB
1514 ****************************
1516 When you run a program under GDB, you must first generate debugging
1517 information when you compile it.
1519 You may start GDB with its arguments, if any, in an environment of
1520 your choice. If you are doing native debugging, you may redirect your
1521 program's input and output, debug an already running process, or kill a
1526 * Compilation:: Compiling for debugging
1527 * Starting:: Starting your program
1528 * Arguments:: Your program's arguments
1529 * Environment:: Your program's environment
1531 * Working Directory:: Your program's working directory
1532 * Input/Output:: Your program's input and output
1533 * Attach:: Debugging an already-running process
1534 * Kill Process:: Killing the child process
1536 * Inferiors and Programs:: Debugging multiple inferiors and programs
1537 * Threads:: Debugging programs with multiple threads
1538 * Forks:: Debugging forks
1539 * Checkpoint/Restart:: Setting a _bookmark_ to return to later
1542 File: gdb.info, Node: Compilation, Next: Starting, Up: Running
1544 4.1 Compiling for Debugging
1545 ===========================
1547 In order to debug a program effectively, you need to generate debugging
1548 information when you compile it. This debugging information is stored
1549 in the object file; it describes the data type of each variable or
1550 function and the correspondence between source line numbers and
1551 addresses in the executable code.
1553 To request debugging information, specify the `-g' option when you
1556 Programs that are to be shipped to your customers are compiled with
1557 optimizations, using the `-O' compiler option. However, some compilers
1558 are unable to handle the `-g' and `-O' options together. Using those
1559 compilers, you cannot generate optimized executables containing
1560 debugging information.
1562 GCC, the GNU C/C++ compiler, supports `-g' with or without `-O',
1563 making it possible to debug optimized code. We recommend that you
1564 _always_ use `-g' whenever you compile a program. You may think your
1565 program is correct, but there is no sense in pushing your luck. For
1566 more information, see *Note Optimized Code::.
1568 Older versions of the GNU C compiler permitted a variant option
1569 `-gg' for debugging information. GDB no longer supports this format;
1570 if your GNU C compiler has this option, do not use it.
1572 GDB knows about preprocessor macros and can show you their expansion
1573 (*note Macros::). Most compilers do not include information about
1574 preprocessor macros in the debugging information if you specify the
1575 `-g' flag alone. Version 3.1 and later of GCC, the GNU C compiler,
1576 provides macro information if you are using the DWARF debugging format,
1577 and specify the option `-g3'.
1579 *Note Options for Debugging Your Program or GCC: (gcc.info)Debugging
1580 Options, for more information on GCC options affecting debug
1583 You will have the best debugging experience if you use the latest
1584 version of the DWARF debugging format that your compiler supports.
1585 DWARF is currently the most expressive and best supported debugging
1589 File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running
1591 4.2 Starting your Program
1592 =========================
1596 Use the `run' command to start your program under GDB. You must
1597 first specify the program name (except on VxWorks) with an
1598 argument to GDB (*note Getting In and Out of GDB: Invocation.), or
1599 by using the `file' or `exec-file' command (*note Commands to
1600 Specify Files: Files.).
1603 If you are running your program in an execution environment that
1604 supports processes, `run' creates an inferior process and makes that
1605 process run your program. In some environments without processes,
1606 `run' jumps to the start of your program. Other targets, like
1607 `remote', are always running. If you get an error message like this
1610 The "remote" target does not support "run".
1611 Try "help target" or "continue".
1613 then use `continue' to run your program. You may need `load' first
1616 The execution of a program is affected by certain information it
1617 receives from its superior. GDB provides ways to specify this
1618 information, which you must do _before_ starting your program. (You
1619 can change it after starting your program, but such changes only affect
1620 your program the next time you start it.) This information may be
1621 divided into four categories:
1624 Specify the arguments to give your program as the arguments of the
1625 `run' command. If a shell is available on your target, the shell
1626 is used to pass the arguments, so that you may use normal
1627 conventions (such as wildcard expansion or variable substitution)
1628 in describing the arguments. In Unix systems, you can control
1629 which shell is used with the `SHELL' environment variable. *Note
1630 Your Program's Arguments: Arguments.
1633 Your program normally inherits its environment from GDB, but you
1634 can use the GDB commands `set environment' and `unset environment'
1635 to change parts of the environment that affect your program.
1636 *Note Your Program's Environment: Environment.
1638 The _working directory._
1639 Your program inherits its working directory from GDB. You can set
1640 the GDB working directory with the `cd' command in GDB. *Note
1641 Your Program's Working Directory: Working Directory.
1643 The _standard input and output._
1644 Your program normally uses the same device for standard input and
1645 standard output as GDB is using. You can redirect input and output
1646 in the `run' command line, or you can use the `tty' command to set
1647 a different device for your program. *Note Your Program's Input
1648 and Output: Input/Output.
1650 _Warning:_ While input and output redirection work, you cannot use
1651 pipes to pass the output of the program you are debugging to
1652 another program; if you attempt this, GDB is likely to wind up
1653 debugging the wrong program.
1655 When you issue the `run' command, your program begins to execute
1656 immediately. *Note Stopping and Continuing: Stopping, for discussion
1657 of how to arrange for your program to stop. Once your program has
1658 stopped, you may call functions in your program, using the `print' or
1659 `call' commands. *Note Examining Data: Data.
1661 If the modification time of your symbol file has changed since the
1662 last time GDB read its symbols, GDB discards its symbol table, and
1663 reads it again. When it does this, GDB tries to retain your current
1667 The name of the main procedure can vary from language to language.
1668 With C or C++, the main procedure name is always `main', but other
1669 languages such as Ada do not require a specific name for their
1670 main procedure. The debugger provides a convenient way to start
1671 the execution of the program and to stop at the beginning of the
1672 main procedure, depending on the language used.
1674 The `start' command does the equivalent of setting a temporary
1675 breakpoint at the beginning of the main procedure and then invoking
1678 Some programs contain an "elaboration" phase where some startup
1679 code is executed before the main procedure is called. This
1680 depends on the languages used to write your program. In C++, for
1681 instance, constructors for static and global objects are executed
1682 before `main' is called. It is therefore possible that the
1683 debugger stops before reaching the main procedure. However, the
1684 temporary breakpoint will remain to halt execution.
1686 Specify the arguments to give to your program as arguments to the
1687 `start' command. These arguments will be given verbatim to the
1688 underlying `run' command. Note that the same arguments will be
1689 reused if no argument is provided during subsequent calls to
1692 It is sometimes necessary to debug the program during elaboration.
1693 In these cases, using the `start' command would stop the
1694 execution of your program too late, as the program would have
1695 already completed the elaboration phase. Under these
1696 circumstances, insert breakpoints in your elaboration code before
1697 running your program.
1699 `set exec-wrapper WRAPPER'
1701 `unset exec-wrapper'
1702 When `exec-wrapper' is set, the specified wrapper is used to
1703 launch programs for debugging. GDB starts your program with a
1704 shell command of the form `exec WRAPPER PROGRAM'. Quoting is
1705 added to PROGRAM and its arguments, but not to WRAPPER, so you
1706 should add quotes if appropriate for your shell. The wrapper runs
1707 until it executes your program, and then GDB takes control.
1709 You can use any program that eventually calls `execve' with its
1710 arguments as a wrapper. Several standard Unix utilities do this,
1711 e.g. `env' and `nohup'. Any Unix shell script ending with `exec
1712 "$@"' will also work.
1714 For example, you can use `env' to pass an environment variable to
1715 the debugged program, without setting the variable in your shell's
1718 (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
1721 This command is available when debugging locally on most targets,
1722 excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.
1724 `set disable-randomization'
1725 `set disable-randomization on'
1726 This option (enabled by default in GDB) will turn off the native
1727 randomization of the virtual address space of the started program.
1728 This option is useful for multiple debugging sessions to make the
1729 execution better reproducible and memory addresses reusable across
1732 This feature is implemented only on certain targets, including
1733 GNU/Linux. On GNU/Linux you can get the same behavior using
1735 (gdb) set exec-wrapper setarch `uname -m` -R
1737 `set disable-randomization off'
1738 Leave the behavior of the started executable unchanged. Some bugs
1739 rear their ugly heads only when the program is loaded at certain
1740 addresses. If your bug disappears when you run the program under
1741 GDB, that might be because GDB by default disables the address
1742 randomization on platforms, such as GNU/Linux, which do that for
1743 stand-alone programs. Use `set disable-randomization off' to try
1744 to reproduce such elusive bugs.
1746 On targets where it is available, virtual address space
1747 randomization protects the programs against certain kinds of
1748 security attacks. In these cases the attacker needs to know the
1749 exact location of a concrete executable code. Randomizing its
1750 location makes it impossible to inject jumps misusing a code at
1751 its expected addresses.
1753 Prelinking shared libraries provides a startup performance
1754 advantage but it makes addresses in these libraries predictable
1755 for privileged processes by having just unprivileged access at the
1756 target system. Reading the shared library binary gives enough
1757 information for assembling the malicious code misusing it. Still
1758 even a prelinked shared library can get loaded at a new random
1759 address just requiring the regular relocation process during the
1760 startup. Shared libraries not already prelinked are always loaded
1761 at a randomly chosen address.
1763 Position independent executables (PIE) contain position
1764 independent code similar to the shared libraries and therefore
1765 such executables get loaded at a randomly chosen address upon
1766 startup. PIE executables always load even already prelinked
1767 shared libraries at a random address. You can build such
1768 executable using `gcc -fPIE -pie'.
1770 Heap (malloc storage), stack and custom mmap areas are always
1771 placed randomly (as long as the randomization is enabled).
1773 `show disable-randomization'
1774 Show the current setting of the explicit disable of the native
1775 randomization of the virtual address space of the started program.
1779 File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running
1781 4.3 Your Program's Arguments
1782 ============================
1784 The arguments to your program can be specified by the arguments of the
1785 `run' command. They are passed to a shell, which expands wildcard
1786 characters and performs redirection of I/O, and thence to your program.
1787 Your `SHELL' environment variable (if it exists) specifies what shell
1788 GDB uses. If you do not define `SHELL', GDB uses the default shell
1789 (`/bin/sh' on Unix).
1791 On non-Unix systems, the program is usually invoked directly by GDB,
1792 which emulates I/O redirection via the appropriate system calls, and
1793 the wildcard characters are expanded by the startup code of the
1794 program, not by the shell.
1796 `run' with no arguments uses the same arguments used by the previous
1797 `run', or those set by the `set args' command.
1800 Specify the arguments to be used the next time your program is
1801 run. If `set args' has no arguments, `run' executes your program
1802 with no arguments. Once you have run your program with arguments,
1803 using `set args' before the next `run' is the only way to run it
1804 again without arguments.
1807 Show the arguments to give your program when it is started.
1810 File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running
1812 4.4 Your Program's Environment
1813 ==============================
1815 The "environment" consists of a set of environment variables and their
1816 values. Environment variables conventionally record such things as
1817 your user name, your home directory, your terminal type, and your search
1818 path for programs to run. Usually you set up environment variables with
1819 the shell and they are inherited by all the other programs you run.
1820 When debugging, it can be useful to try running your program with a
1821 modified environment without having to start GDB over again.
1824 Add DIRECTORY to the front of the `PATH' environment variable (the
1825 search path for executables) that will be passed to your program.
1826 The value of `PATH' used by GDB does not change. You may specify
1827 several directory names, separated by whitespace or by a
1828 system-dependent separator character (`:' on Unix, `;' on MS-DOS
1829 and MS-Windows). If DIRECTORY is already in the path, it is moved
1830 to the front, so it is searched sooner.
1832 You can use the string `$cwd' to refer to whatever is the current
1833 working directory at the time GDB searches the path. If you use
1834 `.' instead, it refers to the directory where you executed the
1835 `path' command. GDB replaces `.' in the DIRECTORY argument (with
1836 the current path) before adding DIRECTORY to the search path.
1839 Display the list of search paths for executables (the `PATH'
1840 environment variable).
1842 `show environment [VARNAME]'
1843 Print the value of environment variable VARNAME to be given to
1844 your program when it starts. If you do not supply VARNAME, print
1845 the names and values of all environment variables to be given to
1846 your program. You can abbreviate `environment' as `env'.
1848 `set environment VARNAME [=VALUE]'
1849 Set environment variable VARNAME to VALUE. The value changes for
1850 your program only, not for GDB itself. VALUE may be any string;
1851 the values of environment variables are just strings, and any
1852 interpretation is supplied by your program itself. The VALUE
1853 parameter is optional; if it is eliminated, the variable is set to
1856 For example, this command:
1860 tells the debugged program, when subsequently run, that its user
1861 is named `foo'. (The spaces around `=' are used for clarity here;
1862 they are not actually required.)
1864 `unset environment VARNAME'
1865 Remove variable VARNAME from the environment to be passed to your
1866 program. This is different from `set env VARNAME ='; `unset
1867 environment' removes the variable from the environment, rather
1868 than assigning it an empty value.
1870 _Warning:_ On Unix systems, GDB runs your program using the shell
1871 indicated by your `SHELL' environment variable if it exists (or
1872 `/bin/sh' if not). If your `SHELL' variable names a shell that runs an
1873 initialization file--such as `.cshrc' for C-shell, or `.bashrc' for
1874 BASH--any variables you set in that file affect your program. You may
1875 wish to move setting of environment variables to files that are only
1876 run when you sign on, such as `.login' or `.profile'.
1879 File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running
1881 4.5 Your Program's Working Directory
1882 ====================================
1884 Each time you start your program with `run', it inherits its working
1885 directory from the current working directory of GDB. The GDB working
1886 directory is initially whatever it inherited from its parent process
1887 (typically the shell), but you can specify a new working directory in
1888 GDB with the `cd' command.
1890 The GDB working directory also serves as a default for the commands
1891 that specify files for GDB to operate on. *Note Commands to Specify
1895 Set the GDB working directory to DIRECTORY.
1898 Print the GDB working directory.
1900 It is generally impossible to find the current working directory of
1901 the process being debugged (since a program can change its directory
1902 during its run). If you work on a system where GDB is configured with
1903 the `/proc' support, you can use the `info proc' command (*note SVR4
1904 Process Information::) to find out the current working directory of the
1908 File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running
1910 4.6 Your Program's Input and Output
1911 ===================================
1913 By default, the program you run under GDB does input and output to the
1914 same terminal that GDB uses. GDB switches the terminal to its own
1915 terminal modes to interact with you, but it records the terminal modes
1916 your program was using and switches back to them when you continue
1917 running your program.
1920 Displays information recorded by GDB about the terminal modes your
1923 You can redirect your program's input and/or output using shell
1924 redirection with the `run' command. For example,
1928 starts your program, diverting its output to the file `outfile'.
1930 Another way to specify where your program should do input and output
1931 is with the `tty' command. This command accepts a file name as
1932 argument, and causes this file to be the default for future `run'
1933 commands. It also resets the controlling terminal for the child
1934 process, for future `run' commands. For example,
1938 directs that processes started with subsequent `run' commands default
1939 to do input and output on the terminal `/dev/ttyb' and have that as
1940 their controlling terminal.
1942 An explicit redirection in `run' overrides the `tty' command's
1943 effect on the input/output device, but not its effect on the controlling
1946 When you use the `tty' command or redirect input in the `run'
1947 command, only the input _for your program_ is affected. The input for
1948 GDB still comes from your terminal. `tty' is an alias for `set
1951 You can use the `show inferior-tty' command to tell GDB to display
1952 the name of the terminal that will be used for future runs of your
1955 `set inferior-tty /dev/ttyb'
1956 Set the tty for the program being debugged to /dev/ttyb.
1959 Show the current tty for the program being debugged.
1962 File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running
1964 4.7 Debugging an Already-running Process
1965 ========================================
1968 This command attaches to a running process--one that was started
1969 outside GDB. (`info files' shows your active targets.) The
1970 command takes as argument a process ID. The usual way to find out
1971 the PROCESS-ID of a Unix process is with the `ps' utility, or with
1972 the `jobs -l' shell command.
1974 `attach' does not repeat if you press <RET> a second time after
1975 executing the command.
1977 To use `attach', your program must be running in an environment
1978 which supports processes; for example, `attach' does not work for
1979 programs on bare-board targets that lack an operating system. You must
1980 also have permission to send the process a signal.
1982 When you use `attach', the debugger finds the program running in the
1983 process first by looking in the current working directory, then (if the
1984 program is not found) by using the source file search path (*note
1985 Specifying Source Directories: Source Path.). You can also use the
1986 `file' command to load the program. *Note Commands to Specify Files:
1989 The first thing GDB does after arranging to debug the specified
1990 process is to stop it. You can examine and modify an attached process
1991 with all the GDB commands that are ordinarily available when you start
1992 processes with `run'. You can insert breakpoints; you can step and
1993 continue; you can modify storage. If you would rather the process
1994 continue running, you may use the `continue' command after attaching
1998 When you have finished debugging the attached process, you can use
1999 the `detach' command to release it from GDB control. Detaching
2000 the process continues its execution. After the `detach' command,
2001 that process and GDB become completely independent once more, and
2002 you are ready to `attach' another process or start one with `run'.
2003 `detach' does not repeat if you press <RET> again after executing
2006 If you exit GDB while you have an attached process, you detach that
2007 process. If you use the `run' command, you kill that process. By
2008 default, GDB asks for confirmation if you try to do either of these
2009 things; you can control whether or not you need to confirm by using the
2010 `set confirm' command (*note Optional Warnings and Messages:
2011 Messages/Warnings.).
2014 File: gdb.info, Node: Kill Process, Next: Inferiors and Programs, Prev: Attach, Up: Running
2016 4.8 Killing the Child Process
2017 =============================
2020 Kill the child process in which your program is running under GDB.
2022 This command is useful if you wish to debug a core dump instead of a
2023 running process. GDB ignores any core dump file while your program is
2026 On some operating systems, a program cannot be executed outside GDB
2027 while you have breakpoints set on it inside GDB. You can use the
2028 `kill' command in this situation to permit running your program outside
2031 The `kill' command is also useful if you wish to recompile and
2032 relink your program, since on many systems it is impossible to modify an
2033 executable file while it is running in a process. In this case, when
2034 you next type `run', GDB notices that the file has changed, and reads
2035 the symbol table again (while trying to preserve your current
2036 breakpoint settings).
2039 File: gdb.info, Node: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running
2041 4.9 Debugging Multiple Inferiors and Programs
2042 =============================================
2044 GDB lets you run and debug multiple programs in a single session. In
2045 addition, GDB on some systems may let you run several programs
2046 simultaneously (otherwise you have to exit from one before starting
2047 another). In the most general case, you can have multiple threads of
2048 execution in each of multiple processes, launched from multiple
2051 GDB represents the state of each program execution with an object
2052 called an "inferior". An inferior typically corresponds to a process,
2053 but is more general and applies also to targets that do not have
2054 processes. Inferiors may be created before a process runs, and may be
2055 retained after a process exits. Inferiors have unique identifiers that
2056 are different from process ids. Usually each inferior will also have
2057 its own distinct address space, although some embedded targets may have
2058 several inferiors running in different parts of a single address space.
2059 Each inferior may in turn have multiple threads running in it.
2061 To find out what inferiors exist at any moment, use `info inferiors':
2064 Print a list of all inferiors currently being managed by GDB.
2066 GDB displays for each inferior (in this order):
2068 1. the inferior number assigned by GDB
2070 2. the target system's inferior identifier
2072 3. the name of the executable the inferior is running.
2075 An asterisk `*' preceding the GDB inferior number indicates the
2080 (gdb) info inferiors
2081 Num Description Executable
2082 2 process 2307 hello
2083 * 1 process 3401 goodbye
2085 To switch focus between inferiors, use the `inferior' command:
2088 Make inferior number INFNO the current inferior. The argument
2089 INFNO is the inferior number assigned by GDB, as shown in the
2090 first field of the `info inferiors' display.
2092 You can get multiple executables into a debugging session via the
2093 `add-inferior' and `clone-inferior' commands. On some systems GDB can
2094 add inferiors to the debug session automatically by following calls to
2095 `fork' and `exec'. To remove inferiors from the debugging session use
2096 the `remove-inferiors' command.
2098 `add-inferior [ -copies N ] [ -exec EXECUTABLE ]'
2099 Adds N inferiors to be run using EXECUTABLE as the executable. N
2100 defaults to 1. If no executable is specified, the inferiors
2101 begins empty, with no program. You can still assign or change the
2102 program assigned to the inferior at any time by using the `file'
2103 command with the executable name as its argument.
2105 `clone-inferior [ -copies N ] [ INFNO ]'
2106 Adds N inferiors ready to execute the same program as inferior
2107 INFNO. N defaults to 1. INFNO defaults to the number of the
2108 current inferior. This is a convenient command when you want to
2109 run another instance of the inferior you are debugging.
2111 (gdb) info inferiors
2112 Num Description Executable
2113 * 1 process 29964 helloworld
2114 (gdb) clone-inferior
2117 (gdb) info inferiors
2118 Num Description Executable
2120 * 1 process 29964 helloworld
2122 You can now simply switch focus to inferior 2 and run it.
2124 `remove-inferiors INFNO...'
2125 Removes the inferior or inferiors INFNO.... It is not possible to
2126 remove an inferior that is running with this command. For those,
2127 use the `kill' or `detach' command first.
2130 To quit debugging one of the running inferiors that is not the
2131 current inferior, you can either detach from it by using the
2132 `detach inferior' command (allowing it to run independently), or kill it
2133 using the `kill inferiors' command:
2135 `detach inferior INFNO...'
2136 Detach from the inferior or inferiors identified by GDB inferior
2137 number(s) INFNO.... Note that the inferior's entry still stays on
2138 the list of inferiors shown by `info inferiors', but its
2139 Description will show `<null>'.
2141 `kill inferiors INFNO...'
2142 Kill the inferior or inferiors identified by GDB inferior
2143 number(s) INFNO.... Note that the inferior's entry still stays on
2144 the list of inferiors shown by `info inferiors', but its
2145 Description will show `<null>'.
2147 After the successful completion of a command such as `detach',
2148 `detach inferiors', `kill' or `kill inferiors', or after a normal
2149 process exit, the inferior is still valid and listed with `info
2150 inferiors', ready to be restarted.
2152 To be notified when inferiors are started or exit under GDB's
2153 control use `set print inferior-events':
2155 `set print inferior-events'
2156 `set print inferior-events on'
2157 `set print inferior-events off'
2158 The `set print inferior-events' command allows you to enable or
2159 disable printing of messages when GDB notices that new inferiors
2160 have started or that inferiors have exited or have been detached.
2161 By default, these messages will not be printed.
2163 `show print inferior-events'
2164 Show whether messages will be printed when GDB detects that
2165 inferiors have started, exited or have been detached.
2167 Many commands will work the same with multiple programs as with a
2168 single program: e.g., `print myglobal' will simply display the value of
2169 `myglobal' in the current inferior.
2171 Occasionaly, when debugging GDB itself, it may be useful to get more
2172 info about the relationship of inferiors, programs, address spaces in a
2173 debug session. You can do that with the `maint info program-spaces'
2176 `maint info program-spaces'
2177 Print a list of all program spaces currently being managed by GDB.
2179 GDB displays for each program space (in this order):
2181 1. the program space number assigned by GDB
2183 2. the name of the executable loaded into the program space,
2184 with e.g., the `file' command.
2187 An asterisk `*' preceding the GDB program space number indicates
2188 the current program space.
2190 In addition, below each program space line, GDB prints extra
2191 information that isn't suitable to display in tabular form. For
2192 example, the list of inferiors bound to the program space.
2194 (gdb) maint info program-spaces
2197 Bound inferiors: ID 1 (process 21561)
2200 Here we can see that no inferior is running the program `hello',
2201 while `process 21561' is running the program `goodbye'. On some
2202 targets, it is possible that multiple inferiors are bound to the
2203 same program space. The most common example is that of debugging
2204 both the parent and child processes of a `vfork' call. For
2207 (gdb) maint info program-spaces
2210 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
2212 Here, both inferior 2 and inferior 1 are running in the same
2213 program space as a result of inferior 1 having executed a `vfork'
2217 File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running
2219 4.10 Debugging Programs with Multiple Threads
2220 =============================================
2222 In some operating systems, such as HP-UX and Solaris, a single program
2223 may have more than one "thread" of execution. The precise semantics of
2224 threads differ from one operating system to another, but in general the
2225 threads of a single program are akin to multiple processes--except that
2226 they share one address space (that is, they can all examine and modify
2227 the same variables). On the other hand, each thread has its own
2228 registers and execution stack, and perhaps private memory.
2230 GDB provides these facilities for debugging multi-thread programs:
2232 * automatic notification of new threads
2234 * `thread THREADNO', a command to switch among threads
2236 * `info threads', a command to inquire about existing threads
2238 * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command
2239 to a list of threads
2241 * thread-specific breakpoints
2243 * `set print thread-events', which controls printing of messages on
2244 thread start and exit.
2246 * `set libthread-db-search-path PATH', which lets the user specify
2247 which `libthread_db' to use if the default choice isn't compatible
2250 _Warning:_ These facilities are not yet available on every GDB
2251 configuration where the operating system supports threads. If
2252 your GDB does not support threads, these commands have no effect.
2253 For example, a system without thread support shows no output from
2254 `info threads', and always rejects the `thread' command, like this:
2258 Thread ID 1 not known. Use the "info threads" command to
2259 see the IDs of currently known threads.
2261 The GDB thread debugging facility allows you to observe all threads
2262 while your program runs--but whenever GDB takes control, one thread in
2263 particular is always the focus of debugging. This thread is called the
2264 "current thread". Debugging commands show program information from the
2265 perspective of the current thread.
2267 Whenever GDB detects a new thread in your program, it displays the
2268 target system's identification for the thread with a message in the
2269 form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies
2270 depending on the particular system. For example, on GNU/Linux, you
2273 [New Thread 0x41e02940 (LWP 25582)]
2275 when GDB notices a new thread. In contrast, on an SGI system, the
2276 SYSTAG is simply something like `process 368', with no further
2279 For debugging purposes, GDB associates its own thread number--always
2280 a single integer--with each thread in your program.
2282 `info threads [ID...]'
2283 Display a summary of all threads currently in your program.
2284 Optional argument ID... is one or more thread ids separated by
2285 spaces, and means to print information only about the specified
2286 thread or threads. GDB displays for each thread (in this order):
2288 1. the thread number assigned by GDB
2290 2. the target system's thread identifier (SYSTAG)
2292 3. the thread's name, if one is known. A thread can either be
2293 named by the user (see `thread name', below), or, in some
2294 cases, by the program itself.
2296 4. the current stack frame summary for that thread
2298 An asterisk `*' to the left of the GDB thread number indicates the
2305 3 process 35 thread 27 0x34e5 in sigpause ()
2306 2 process 35 thread 23 0x34e5 in sigpause ()
2307 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2310 On Solaris, you can display more information about user threads with
2311 a Solaris-specific command:
2313 `maint info sol-threads'
2314 Display info on Solaris user threads.
2317 Make thread number THREADNO the current thread. The command
2318 argument THREADNO is the internal GDB thread number, as shown in
2319 the first field of the `info threads' display. GDB responds by
2320 displaying the system identifier of the thread you selected, and
2321 its current stack frame summary:
2324 [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
2325 #0 some_function (ignore=0x0) at example.c:8
2326 8 printf ("hello\n");
2328 As with the `[New ...]' message, the form of the text after
2329 `Switching to' depends on your system's conventions for identifying
2332 The debugger convenience variable `$_thread' contains the number
2333 of the current thread. You may find this useful in writing
2334 breakpoint conditional expressions, command scripts, and so forth.
2335 See *Note Convenience Variables: Convenience Vars, for general
2336 information on convenience variables.
2338 `thread apply [THREADNO | all] COMMAND'
2339 The `thread apply' command allows you to apply the named COMMAND
2340 to one or more threads. Specify the numbers of the threads that
2341 you want affected with the command argument THREADNO. It can be a
2342 single thread number, one of the numbers shown in the first field
2343 of the `info threads' display; or it could be a range of thread
2344 numbers, as in `2-4'. To apply a command to all threads, type
2345 `thread apply all COMMAND'.
2347 `thread name [NAME]'
2348 This command assigns a name to the current thread. If no argument
2349 is given, any existing user-specified name is removed. The thread
2350 name appears in the `info threads' display.
2352 On some systems, such as GNU/Linux, GDB is able to determine the
2353 name of the thread as given by the OS. On these systems, a name
2354 specified with `thread name' will override the system-give name,
2355 and removing the user-specified name will cause GDB to once again
2356 display the system-specified name.
2358 `thread find [REGEXP]'
2359 Search for and display thread ids whose name or SYSTAG matches the
2360 supplied regular expression.
2362 As well as being the complement to the `thread name' command, this
2363 command also allows you to identify a thread by its target SYSTAG.
2364 For instance, on GNU/Linux, the target SYSTAG is the LWP id.
2366 (GDB) thread find 26688
2367 Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
2370 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
2372 `set print thread-events'
2373 `set print thread-events on'
2374 `set print thread-events off'
2375 The `set print thread-events' command allows you to enable or
2376 disable printing of messages when GDB notices that new threads have
2377 started or that threads have exited. By default, these messages
2378 will be printed if detection of these events is supported by the
2379 target. Note that these messages cannot be disabled on all
2382 `show print thread-events'
2383 Show whether messages will be printed when GDB detects that threads
2384 have started and exited.
2386 *Note Stopping and Starting Multi-thread Programs: Thread Stops, for
2387 more information about how GDB behaves when you stop and start programs
2388 with multiple threads.
2390 *Note Setting Watchpoints: Set Watchpoints, for information about
2391 watchpoints in programs with multiple threads.
2393 `set libthread-db-search-path [PATH]'
2394 If this variable is set, PATH is a colon-separated list of
2395 directories GDB will use to search for `libthread_db'. If you
2396 omit PATH, `libthread-db-search-path' will be reset to its default
2397 value (`$sdir:$pdir' on GNU/Linux and Solaris systems).
2398 Internally, the default value comes from the
2399 `LIBTHREAD_DB_SEARCH_PATH' macro.
2401 On GNU/Linux and Solaris systems, GDB uses a "helper"
2402 `libthread_db' library to obtain information about threads in the
2403 inferior process. GDB will use `libthread-db-search-path' to find
2404 `libthread_db'. GDB also consults first if inferior specific
2405 thread debugging library loading is enabled by `set auto-load
2406 libthread-db' (*note libthread_db.so.1 file::).
2408 A special entry `$sdir' for `libthread-db-search-path' refers to
2409 the default system directories that are normally searched for
2410 loading shared libraries. The `$sdir' entry is the only kind not
2411 needing to be enabled by `set auto-load libthread-db' (*note
2412 libthread_db.so.1 file::).
2414 A special entry `$pdir' for `libthread-db-search-path' refers to
2415 the directory from which `libpthread' was loaded in the inferior
2418 For any `libthread_db' library GDB finds in above directories, GDB
2419 attempts to initialize it with the current inferior process. If
2420 this initialization fails (which could happen because of a version
2421 mismatch between `libthread_db' and `libpthread'), GDB will unload
2422 `libthread_db', and continue with the next directory. If none of
2423 `libthread_db' libraries initialize successfully, GDB will issue a
2424 warning and thread debugging will be disabled.
2426 Setting `libthread-db-search-path' is currently implemented only
2429 `show libthread-db-search-path'
2430 Display current libthread_db search path.
2432 `set debug libthread-db'
2433 `show debug libthread-db'
2434 Turns on or off display of `libthread_db'-related events. Use `1'
2435 to enable, `0' to disable.
2438 File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running
2440 4.11 Debugging Forks
2441 ====================
2443 On most systems, GDB has no special support for debugging programs
2444 which create additional processes using the `fork' function. When a
2445 program forks, GDB will continue to debug the parent process and the
2446 child process will run unimpeded. If you have set a breakpoint in any
2447 code which the child then executes, the child will get a `SIGTRAP'
2448 signal which (unless it catches the signal) will cause it to terminate.
2450 However, if you want to debug the child process there is a workaround
2451 which isn't too painful. Put a call to `sleep' in the code which the
2452 child process executes after the fork. It may be useful to sleep only
2453 if a certain environment variable is set, or a certain file exists, so
2454 that the delay need not occur when you don't want to run GDB on the
2455 child. While the child is sleeping, use the `ps' program to get its
2456 process ID. Then tell GDB (a new invocation of GDB if you are also
2457 debugging the parent process) to attach to the child process (*note
2458 Attach::). From that point on you can debug the child process just
2459 like any other process which you attached to.
2461 On some systems, GDB provides support for debugging programs that
2462 create additional processes using the `fork' or `vfork' functions.
2463 Currently, the only platforms with this feature are HP-UX (11.x and
2464 later only?) and GNU/Linux (kernel version 2.5.60 and later).
2466 By default, when a program forks, GDB will continue to debug the
2467 parent process and the child process will run unimpeded.
2469 If you want to follow the child process instead of the parent
2470 process, use the command `set follow-fork-mode'.
2472 `set follow-fork-mode MODE'
2473 Set the debugger response to a program call of `fork' or `vfork'.
2474 A call to `fork' or `vfork' creates a new process. The MODE
2478 The original process is debugged after a fork. The child
2479 process runs unimpeded. This is the default.
2482 The new process is debugged after a fork. The parent process
2486 `show follow-fork-mode'
2487 Display the current debugger response to a `fork' or `vfork' call.
2489 On Linux, if you want to debug both the parent and child processes,
2490 use the command `set detach-on-fork'.
2492 `set detach-on-fork MODE'
2493 Tells gdb whether to detach one of the processes after a fork, or
2494 retain debugger control over them both.
2497 The child process (or parent process, depending on the value
2498 of `follow-fork-mode') will be detached and allowed to run
2499 independently. This is the default.
2502 Both processes will be held under the control of GDB. One
2503 process (child or parent, depending on the value of
2504 `follow-fork-mode') is debugged as usual, while the other is
2508 `show detach-on-fork'
2509 Show whether detach-on-fork mode is on/off.
2511 If you choose to set `detach-on-fork' mode off, then GDB will retain
2512 control of all forked processes (including nested forks). You can list
2513 the forked processes under the control of GDB by using the
2514 `info inferiors' command, and switch from one fork to another by using
2515 the `inferior' command (*note Debugging Multiple Inferiors and
2516 Programs: Inferiors and Programs.).
2518 To quit debugging one of the forked processes, you can either detach
2519 from it by using the `detach inferiors' command (allowing it to run
2520 independently), or kill it using the `kill inferiors' command. *Note
2521 Debugging Multiple Inferiors and Programs: Inferiors and Programs.
2523 If you ask to debug a child process and a `vfork' is followed by an
2524 `exec', GDB executes the new target up to the first breakpoint in the
2525 new target. If you have a breakpoint set on `main' in your original
2526 program, the breakpoint will also be set on the child process's `main'.
2528 On some systems, when a child process is spawned by `vfork', you
2529 cannot debug the child or parent until an `exec' call completes.
2531 If you issue a `run' command to GDB after an `exec' call executes,
2532 the new target restarts. To restart the parent process, use the `file'
2533 command with the parent executable name as its argument. By default,
2534 after an `exec' call executes, GDB discards the symbols of the previous
2535 executable image. You can change this behaviour with the
2536 `set follow-exec-mode' command.
2538 `set follow-exec-mode MODE'
2539 Set debugger response to a program call of `exec'. An `exec' call
2540 replaces the program image of a process.
2542 `follow-exec-mode' can be:
2545 GDB creates a new inferior and rebinds the process to this
2546 new inferior. The program the process was running before the
2547 `exec' call can be restarted afterwards by restarting the
2552 (gdb) info inferiors
2554 Id Description Executable
2557 process 12020 is executing new program: prog2
2558 Program exited normally.
2559 (gdb) info inferiors
2560 Id Description Executable
2565 GDB keeps the process bound to the same inferior. The new
2566 executable image replaces the previous executable loaded in
2567 the inferior. Restarting the inferior after the `exec' call,
2568 with e.g., the `run' command, restarts the executable the
2569 process was running after the `exec' call. This is the
2574 (gdb) info inferiors
2575 Id Description Executable
2578 process 12020 is executing new program: prog2
2579 Program exited normally.
2580 (gdb) info inferiors
2581 Id Description Executable
2585 You can use the `catch' command to make GDB stop whenever a `fork',
2586 `vfork', or `exec' call is made. *Note Setting Catchpoints: Set
2590 File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running
2592 4.12 Setting a _Bookmark_ to Return to Later
2593 ============================================
2595 On certain operating systems(1), GDB is able to save a "snapshot" of a
2596 program's state, called a "checkpoint", and come back to it later.
2598 Returning to a checkpoint effectively undoes everything that has
2599 happened in the program since the `checkpoint' was saved. This
2600 includes changes in memory, registers, and even (within some limits)
2601 system state. Effectively, it is like going back in time to the moment
2602 when the checkpoint was saved.
2604 Thus, if you're stepping thru a program and you think you're getting
2605 close to the point where things go wrong, you can save a checkpoint.
2606 Then, if you accidentally go too far and miss the critical statement,
2607 instead of having to restart your program from the beginning, you can
2608 just go back to the checkpoint and start again from there.
2610 This can be especially useful if it takes a lot of time or steps to
2611 reach the point where you think the bug occurs.
2613 To use the `checkpoint'/`restart' method of debugging:
2616 Save a snapshot of the debugged program's current execution state.
2617 The `checkpoint' command takes no arguments, but each checkpoint
2618 is assigned a small integer id, similar to a breakpoint id.
2621 List the checkpoints that have been saved in the current debugging
2622 session. For each checkpoint, the following information will be
2631 `Source line, or label'
2633 `restart CHECKPOINT-ID'
2634 Restore the program state that was saved as checkpoint number
2635 CHECKPOINT-ID. All program variables, registers, stack frames
2636 etc. will be returned to the values that they had when the
2637 checkpoint was saved. In essence, gdb will "wind back the clock"
2638 to the point in time when the checkpoint was saved.
2640 Note that breakpoints, GDB variables, command history etc. are
2641 not affected by restoring a checkpoint. In general, a checkpoint
2642 only restores things that reside in the program being debugged,
2643 not in the debugger.
2645 `delete checkpoint CHECKPOINT-ID'
2646 Delete the previously-saved checkpoint identified by CHECKPOINT-ID.
2649 Returning to a previously saved checkpoint will restore the user
2650 state of the program being debugged, plus a significant subset of the
2651 system (OS) state, including file pointers. It won't "un-write" data
2652 from a file, but it will rewind the file pointer to the previous
2653 location, so that the previously written data can be overwritten. For
2654 files opened in read mode, the pointer will also be restored so that the
2655 previously read data can be read again.
2657 Of course, characters that have been sent to a printer (or other
2658 external device) cannot be "snatched back", and characters received
2659 from eg. a serial device can be removed from internal program buffers,
2660 but they cannot be "pushed back" into the serial pipeline, ready to be
2661 received again. Similarly, the actual contents of files that have been
2662 changed cannot be restored (at this time).
2664 However, within those constraints, you actually can "rewind" your
2665 program to a previously saved point in time, and begin debugging it
2666 again -- and you can change the course of events so as to debug a
2667 different execution path this time.
2669 Finally, there is one bit of internal program state that will be
2670 different when you return to a checkpoint -- the program's process id.
2671 Each checkpoint will have a unique process id (or PID), and each will
2672 be different from the program's original PID. If your program has
2673 saved a local copy of its process id, this could potentially pose a
2676 4.12.1 A Non-obvious Benefit of Using Checkpoints
2677 -------------------------------------------------
2679 On some systems such as GNU/Linux, address space randomization is
2680 performed on new processes for security reasons. This makes it
2681 difficult or impossible to set a breakpoint, or watchpoint, on an
2682 absolute address if you have to restart the program, since the absolute
2683 location of a symbol will change from one execution to the next.
2685 A checkpoint, however, is an _identical_ copy of a process.
2686 Therefore if you create a checkpoint at (eg.) the start of main, and
2687 simply return to that checkpoint instead of restarting the process, you
2688 can avoid the effects of address randomization and your symbols will
2689 all stay in the same place.
2691 ---------- Footnotes ----------
2693 (1) Currently, only GNU/Linux.
2696 File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top
2698 5 Stopping and Continuing
2699 *************************
2701 The principal purposes of using a debugger are so that you can stop your
2702 program before it terminates; or so that, if your program runs into
2703 trouble, you can investigate and find out why.
2705 Inside GDB, your program may stop for any of several reasons, such
2706 as a signal, a breakpoint, or reaching a new line after a GDB command
2707 such as `step'. You may then examine and change variables, set new
2708 breakpoints or remove old ones, and then continue execution. Usually,
2709 the messages shown by GDB provide ample explanation of the status of
2710 your program--but you can also explicitly request this information at
2714 Display information about the status of your program: whether it is
2715 running or not, what process it is, and why it stopped.
2719 * Breakpoints:: Breakpoints, watchpoints, and catchpoints
2720 * Continuing and Stepping:: Resuming execution
2721 * Skipping Over Functions and Files::
2722 Skipping over functions and files
2724 * Thread Stops:: Stopping and starting multi-thread programs
2727 File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping
2729 5.1 Breakpoints, Watchpoints, and Catchpoints
2730 =============================================
2732 A "breakpoint" makes your program stop whenever a certain point in the
2733 program is reached. For each breakpoint, you can add conditions to
2734 control in finer detail whether your program stops. You can set
2735 breakpoints with the `break' command and its variants (*note Setting
2736 Breakpoints: Set Breaks.), to specify the place where your program
2737 should stop by line number, function name or exact address in the
2740 On some systems, you can set breakpoints in shared libraries before
2741 the executable is run. There is a minor limitation on HP-UX systems:
2742 you must wait until the executable is run in order to set breakpoints
2743 in shared library routines that are not called directly by the program
2744 (for example, routines that are arguments in a `pthread_create' call).
2746 A "watchpoint" is a special breakpoint that stops your program when
2747 the value of an expression changes. The expression may be a value of a
2748 variable, or it could involve values of one or more variables combined
2749 by operators, such as `a + b'. This is sometimes called "data
2750 breakpoints". You must use a different command to set watchpoints
2751 (*note Setting Watchpoints: Set Watchpoints.), but aside from that, you
2752 can manage a watchpoint like any other breakpoint: you enable, disable,
2753 and delete both breakpoints and watchpoints using the same commands.
2755 You can arrange to have values from your program displayed
2756 automatically whenever GDB stops at a breakpoint. *Note Automatic
2757 Display: Auto Display.
2759 A "catchpoint" is another special breakpoint that stops your program
2760 when a certain kind of event occurs, such as the throwing of a C++
2761 exception or the loading of a library. As with watchpoints, you use a
2762 different command to set a catchpoint (*note Setting Catchpoints: Set
2763 Catchpoints.), but aside from that, you can manage a catchpoint like any
2764 other breakpoint. (To stop when your program receives a signal, use the
2765 `handle' command; see *Note Signals: Signals.)
2767 GDB assigns a number to each breakpoint, watchpoint, or catchpoint
2768 when you create it; these numbers are successive integers starting with
2769 one. In many of the commands for controlling various features of
2770 breakpoints you use the breakpoint number to say which breakpoint you
2771 want to change. Each breakpoint may be "enabled" or "disabled"; if
2772 disabled, it has no effect on your program until you enable it again.
2774 Some GDB commands accept a range of breakpoints on which to operate.
2775 A breakpoint range is either a single breakpoint number, like `5', or
2776 two such numbers, in increasing order, separated by a hyphen, like
2777 `5-7'. When a breakpoint range is given to a command, all breakpoints
2778 in that range are operated on.
2782 * Set Breaks:: Setting breakpoints
2783 * Set Watchpoints:: Setting watchpoints
2784 * Set Catchpoints:: Setting catchpoints
2785 * Delete Breaks:: Deleting breakpoints
2786 * Disabling:: Disabling breakpoints
2787 * Conditions:: Break conditions
2788 * Break Commands:: Breakpoint command lists
2789 * Dynamic Printf:: Dynamic printf
2790 * Save Breakpoints:: How to save breakpoints in a file
2791 * Static Probe Points:: Listing static probe points
2792 * Error in Breakpoints:: ``Cannot insert breakpoints''
2793 * Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
2796 File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints
2798 5.1.1 Setting Breakpoints
2799 -------------------------
2801 Breakpoints are set with the `break' command (abbreviated `b'). The
2802 debugger convenience variable `$bpnum' records the number of the
2803 breakpoint you've set most recently; see *Note Convenience Variables:
2804 Convenience Vars, for a discussion of what you can do with convenience
2808 Set a breakpoint at the given LOCATION, which can specify a
2809 function name, a line number, or an address of an instruction.
2810 (*Note Specify Location::, for a list of all the possible ways to
2811 specify a LOCATION.) The breakpoint will stop your program just
2812 before it executes any of the code in the specified LOCATION.
2814 When using source languages that permit overloading of symbols,
2815 such as C++, a function name may refer to more than one possible
2816 place to break. *Note Ambiguous Expressions: Ambiguous
2817 Expressions, for a discussion of that situation.
2819 It is also possible to insert a breakpoint that will stop the
2820 program only if a specific thread (*note Thread-Specific
2821 Breakpoints::) or a specific task (*note Ada Tasks::) hits that
2825 When called without any arguments, `break' sets a breakpoint at
2826 the next instruction to be executed in the selected stack frame
2827 (*note Examining the Stack: Stack.). In any selected frame but the
2828 innermost, this makes your program stop as soon as control returns
2829 to that frame. This is similar to the effect of a `finish'
2830 command in the frame inside the selected frame--except that
2831 `finish' does not leave an active breakpoint. If you use `break'
2832 without an argument in the innermost frame, GDB stops the next
2833 time it reaches the current location; this may be useful inside
2836 GDB normally ignores breakpoints when it resumes execution, until
2837 at least one instruction has been executed. If it did not do
2838 this, you would be unable to proceed past a breakpoint without
2839 first disabling the breakpoint. This rule applies whether or not
2840 the breakpoint already existed when your program stopped.
2843 Set a breakpoint with condition COND; evaluate the expression COND
2844 each time the breakpoint is reached, and stop only if the value is
2845 nonzero--that is, if COND evaluates as true. `...' stands for one
2846 of the possible arguments described above (or no argument)
2847 specifying where to break. *Note Break Conditions: Conditions,
2848 for more information on breakpoint conditions.
2851 Set a breakpoint enabled only for one stop. ARGS are the same as
2852 for the `break' command, and the breakpoint is set in the same
2853 way, but the breakpoint is automatically deleted after the first
2854 time your program stops there. *Note Disabling Breakpoints:
2858 Set a hardware-assisted breakpoint. ARGS are the same as for the
2859 `break' command and the breakpoint is set in the same way, but the
2860 breakpoint requires hardware support and some target hardware may
2861 not have this support. The main purpose of this is EPROM/ROM code
2862 debugging, so you can set a breakpoint at an instruction without
2863 changing the instruction. This can be used with the new
2864 trap-generation provided by SPARClite DSU and most x86-based
2865 targets. These targets will generate traps when a program
2866 accesses some data or instruction address that is assigned to the
2867 debug registers. However the hardware breakpoint registers can
2868 take a limited number of breakpoints. For example, on the DSU,
2869 only two data breakpoints can be set at a time, and GDB will
2870 reject this command if more than two are used. Delete or disable
2871 unused hardware breakpoints before setting new ones (*note
2872 Disabling Breakpoints: Disabling.). *Note Break Conditions:
2873 Conditions. For remote targets, you can restrict the number of
2874 hardware breakpoints GDB will use, see *Note set remote
2875 hardware-breakpoint-limit::.
2878 Set a hardware-assisted breakpoint enabled only for one stop. ARGS
2879 are the same as for the `hbreak' command and the breakpoint is set
2880 in the same way. However, like the `tbreak' command, the
2881 breakpoint is automatically deleted after the first time your
2882 program stops there. Also, like the `hbreak' command, the
2883 breakpoint requires hardware support and some target hardware may
2884 not have this support. *Note Disabling Breakpoints: Disabling.
2885 See also *Note Break Conditions: Conditions.
2888 Set breakpoints on all functions matching the regular expression
2889 REGEX. This command sets an unconditional breakpoint on all
2890 matches, printing a list of all breakpoints it set. Once these
2891 breakpoints are set, they are treated just like the breakpoints
2892 set with the `break' command. You can delete them, disable them,
2893 or make them conditional the same way as any other breakpoint.
2895 The syntax of the regular expression is the standard one used with
2896 tools like `grep'. Note that this is different from the syntax
2897 used by shells, so for instance `foo*' matches all functions that
2898 include an `fo' followed by zero or more `o's. There is an
2899 implicit `.*' leading and trailing the regular expression you
2900 supply, so to match only functions that begin with `foo', use
2903 When debugging C++ programs, `rbreak' is useful for setting
2904 breakpoints on overloaded functions that are not members of any
2907 The `rbreak' command can be used to set breakpoints in *all* the
2908 functions in a program, like this:
2913 If `rbreak' is called with a filename qualification, it limits the
2914 search for functions matching the given regular expression to the
2915 specified FILE. This can be used, for example, to set breakpoints
2916 on every function in a given file:
2918 (gdb) rbreak file.c:.
2920 The colon separating the filename qualifier from the regex may
2921 optionally be surrounded by spaces.
2923 `info breakpoints [N...]'
2925 Print a table of all breakpoints, watchpoints, and catchpoints set
2926 and not deleted. Optional argument N means print information only
2927 about the specified breakpoint(s) (or watchpoint(s) or
2928 catchpoint(s)). For each breakpoint, following columns are
2931 _Breakpoint Numbers_
2934 Breakpoint, watchpoint, or catchpoint.
2937 Whether the breakpoint is marked to be disabled or deleted
2940 _Enabled or Disabled_
2941 Enabled breakpoints are marked with `y'. `n' marks
2942 breakpoints that are not enabled.
2945 Where the breakpoint is in your program, as a memory address.
2946 For a pending breakpoint whose address is not yet known,
2947 this field will contain `<PENDING>'. Such breakpoint won't
2948 fire until a shared library that has the symbol or line
2949 referred by breakpoint is loaded. See below for details. A
2950 breakpoint with several locations will have `<MULTIPLE>' in
2951 this field--see below for details.
2954 Where the breakpoint is in the source for your program, as a
2955 file and line number. For a pending breakpoint, the original
2956 string passed to the breakpoint command will be listed as it
2957 cannot be resolved until the appropriate shared library is
2958 loaded in the future.
2960 If a breakpoint is conditional, there are two evaluation modes:
2961 "host" and "target". If mode is "host", breakpoint condition
2962 evaluation is done by GDB on the host's side. If it is "target",
2963 then the condition is evaluated by the target. The `info break'
2964 command shows the condition on the line following the affected
2965 breakpoint, together with its condition evaluation mode in between
2968 Breakpoint commands, if any, are listed after that. A pending
2969 breakpoint is allowed to have a condition specified for it. The
2970 condition is not parsed for validity until a shared library is
2971 loaded that allows the pending breakpoint to resolve to a valid
2974 `info break' with a breakpoint number N as argument lists only
2975 that breakpoint. The convenience variable `$_' and the default
2976 examining-address for the `x' command are set to the address of
2977 the last breakpoint listed (*note Examining Memory: Memory.).
2979 `info break' displays a count of the number of times the breakpoint
2980 has been hit. This is especially useful in conjunction with the
2981 `ignore' command. You can ignore a large number of breakpoint
2982 hits, look at the breakpoint info to see how many times the
2983 breakpoint was hit, and then run again, ignoring one less than
2984 that number. This will get you quickly to the last hit of that
2987 For a breakpoints with an enable count (xref) greater than 1,
2988 `info break' also displays that count.
2991 GDB allows you to set any number of breakpoints at the same place in
2992 your program. There is nothing silly or meaningless about this. When
2993 the breakpoints are conditional, this is even useful (*note Break
2994 Conditions: Conditions.).
2996 It is possible that a breakpoint corresponds to several locations in
2997 your program. Examples of this situation are:
2999 * Multiple functions in the program may have the same name.
3001 * For a C++ constructor, the GCC compiler generates several
3002 instances of the function body, used in different cases.
3004 * For a C++ template function, a given line in the function can
3005 correspond to any number of instantiations.
3007 * For an inlined function, a given source line can correspond to
3008 several places where that function is inlined.
3010 In all those cases, GDB will insert a breakpoint at all the relevant
3013 A breakpoint with multiple locations is displayed in the breakpoint
3014 table using several rows--one header row, followed by one row for each
3015 breakpoint location. The header row has `<MULTIPLE>' in the address
3016 column. The rows for individual locations contain the actual addresses
3017 for locations, and show the functions to which those locations belong.
3018 The number column for a location is of the form
3019 BREAKPOINT-NUMBER.LOCATION-NUMBER.
3023 Num Type Disp Enb Address What
3024 1 breakpoint keep y <MULTIPLE>
3026 breakpoint already hit 1 time
3027 1.1 y 0x080486a2 in void foo<int>() at t.cc:8
3028 1.2 y 0x080486ca in void foo<double>() at t.cc:8
3030 Each location can be individually enabled or disabled by passing
3031 BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and
3032 `disable' commands. Note that you cannot delete the individual
3033 locations from the list, you can only delete the entire list of
3034 locations that belong to their parent breakpoint (with the `delete NUM'
3035 command, where NUM is the number of the parent breakpoint, 1 in the
3036 above example). Disabling or enabling the parent breakpoint (*note
3037 Disabling::) affects all of the locations that belong to that
3040 It's quite common to have a breakpoint inside a shared library.
3041 Shared libraries can be loaded and unloaded explicitly, and possibly
3042 repeatedly, as the program is executed. To support this use case, GDB
3043 updates breakpoint locations whenever any shared library is loaded or
3044 unloaded. Typically, you would set a breakpoint in a shared library at
3045 the beginning of your debugging session, when the library is not
3046 loaded, and when the symbols from the library are not available. When
3047 you try to set breakpoint, GDB will ask you if you want to set a so
3048 called "pending breakpoint"--breakpoint whose address is not yet
3051 After the program is run, whenever a new shared library is loaded,
3052 GDB reevaluates all the breakpoints. When a newly loaded shared
3053 library contains the symbol or line referred to by some pending
3054 breakpoint, that breakpoint is resolved and becomes an ordinary
3055 breakpoint. When a library is unloaded, all breakpoints that refer to
3056 its symbols or source lines become pending again.
3058 This logic works for breakpoints with multiple locations, too. For
3059 example, if you have a breakpoint in a C++ template function, and a
3060 newly loaded shared library has an instantiation of that template, a
3061 new location is added to the list of locations for the breakpoint.
3063 Except for having unresolved address, pending breakpoints do not
3064 differ from regular breakpoints. You can set conditions or commands,
3065 enable and disable them and perform other breakpoint operations.
3067 GDB provides some additional commands for controlling what happens
3068 when the `break' command cannot resolve breakpoint address
3069 specification to an address:
3071 `set breakpoint pending auto'
3072 This is the default behavior. When GDB cannot find the breakpoint
3073 location, it queries you whether a pending breakpoint should be
3076 `set breakpoint pending on'
3077 This indicates that an unrecognized breakpoint location should
3078 automatically result in a pending breakpoint being created.
3080 `set breakpoint pending off'
3081 This indicates that pending breakpoints are not to be created. Any
3082 unrecognized breakpoint location results in an error. This
3083 setting does not affect any pending breakpoints previously created.
3085 `show breakpoint pending'
3086 Show the current behavior setting for creating pending breakpoints.
3088 The settings above only affect the `break' command and its variants.
3089 Once breakpoint is set, it will be automatically updated as shared
3090 libraries are loaded and unloaded.
3092 For some targets, GDB can automatically decide if hardware or
3093 software breakpoints should be used, depending on whether the
3094 breakpoint address is read-only or read-write. This applies to
3095 breakpoints set with the `break' command as well as to internal
3096 breakpoints set by commands like `next' and `finish'. For breakpoints
3097 set with `hbreak', GDB will always use hardware breakpoints.
3099 You can control this automatic behaviour with the following
3102 `set breakpoint auto-hw on'
3103 This is the default behavior. When GDB sets a breakpoint, it will
3104 try to use the target memory map to decide if software or hardware
3105 breakpoint must be used.
3107 `set breakpoint auto-hw off'
3108 This indicates GDB should not automatically select breakpoint
3109 type. If the target provides a memory map, GDB will warn when
3110 trying to set software breakpoint at a read-only address.
3112 GDB normally implements breakpoints by replacing the program code at
3113 the breakpoint address with a special instruction, which, when
3114 executed, given control to the debugger. By default, the program code
3115 is so modified only when the program is resumed. As soon as the
3116 program stops, GDB restores the original instructions. This behaviour
3117 guards against leaving breakpoints inserted in the target should gdb
3118 abrubptly disconnect. However, with slow remote targets, inserting and
3119 removing breakpoint can reduce the performance. This behavior can be
3120 controlled with the following commands::
3122 `set breakpoint always-inserted off'
3123 All breakpoints, including newly added by the user, are inserted in
3124 the target only when the target is resumed. All breakpoints are
3125 removed from the target when it stops.
3127 `set breakpoint always-inserted on'
3128 Causes all breakpoints to be inserted in the target at all times.
3129 If the user adds a new breakpoint, or changes an existing
3130 breakpoint, the breakpoints in the target are updated immediately.
3131 A breakpoint is removed from the target only when breakpoint
3134 `set breakpoint always-inserted auto'
3135 This is the default mode. If GDB is controlling the inferior in
3136 non-stop mode (*note Non-Stop Mode::), gdb behaves as if
3137 `breakpoint always-inserted' mode is on. If GDB is controlling
3138 the inferior in all-stop mode, GDB behaves as if `breakpoint
3139 always-inserted' mode is off.
3141 GDB handles conditional breakpoints by evaluating these conditions
3142 when a breakpoint breaks. If the condition is true, then the process
3143 being debugged stops, otherwise the process is resumed.
3145 If the target supports evaluating conditions on its end, GDB may
3146 download the breakpoint, together with its conditions, to it.
3148 This feature can be controlled via the following commands:
3150 `set breakpoint condition-evaluation host'
3151 This option commands GDB to evaluate the breakpoint conditions on
3152 the host's side. Unconditional breakpoints are sent to the target
3153 which in turn receives the triggers and reports them back to GDB
3154 for condition evaluation. This is the standard evaluation mode.
3156 `set breakpoint condition-evaluation target'
3157 This option commands GDB to download breakpoint conditions to the
3158 target at the moment of their insertion. The target is
3159 responsible for evaluating the conditional expression and reporting
3160 breakpoint stop events back to GDB whenever the condition is true.
3161 Due to limitations of target-side evaluation, some conditions
3162 cannot be evaluated there, e.g., conditions that depend on local
3163 data that is only known to the host. Examples include conditional
3164 expressions involving convenience variables, complex types that
3165 cannot be handled by the agent expression parser and expressions
3166 that are too long to be sent over to the target, specially when the
3167 target is a remote system. In these cases, the conditions will be
3170 `set breakpoint condition-evaluation auto'
3171 This is the default mode. If the target supports evaluating
3172 breakpoint conditions on its end, GDB will download breakpoint
3173 conditions to the target (limitations mentioned previously apply).
3174 If the target does not support breakpoint condition evaluation,
3175 then GDB will fallback to evaluating all these conditions on the
3178 GDB itself sometimes sets breakpoints in your program for special
3179 purposes, such as proper handling of `longjmp' (in C programs). These
3180 internal breakpoints are assigned negative numbers, starting with `-1';
3181 `info breakpoints' does not display them. You can see these
3182 breakpoints with the GDB maintenance command `maint info breakpoints'
3183 (*note maint info breakpoints::).
3186 File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints
3188 5.1.2 Setting Watchpoints
3189 -------------------------
3191 You can use a watchpoint to stop execution whenever the value of an
3192 expression changes, without having to predict a particular place where
3193 this may happen. (This is sometimes called a "data breakpoint".) The
3194 expression may be as simple as the value of a single variable, or as
3195 complex as many variables combined by operators. Examples include:
3197 * A reference to the value of a single variable.
3199 * An address cast to an appropriate data type. For example, `*(int
3200 *)0x12345678' will watch a 4-byte region at the specified address
3201 (assuming an `int' occupies 4 bytes).
3203 * An arbitrarily complex expression, such as `a*b + c/d'. The
3204 expression can use any operators valid in the program's native
3205 language (*note Languages::).
3207 You can set a watchpoint on an expression even if the expression can
3208 not be evaluated yet. For instance, you can set a watchpoint on
3209 `*global_ptr' before `global_ptr' is initialized. GDB will stop when
3210 your program sets `global_ptr' and the expression produces a valid
3211 value. If the expression becomes valid in some other way than changing
3212 a variable (e.g. if the memory pointed to by `*global_ptr' becomes
3213 readable as the result of a `malloc' call), GDB may not stop until the
3214 next time the expression changes.
3216 Depending on your system, watchpoints may be implemented in software
3217 or hardware. GDB does software watchpointing by single-stepping your
3218 program and testing the variable's value each time, which is hundreds of
3219 times slower than normal execution. (But this may still be worth it, to
3220 catch errors where you have no clue what part of your program is the
3223 On some systems, such as HP-UX, PowerPC, GNU/Linux and most other
3224 x86-based targets, GDB includes support for hardware watchpoints, which
3225 do not slow down the running of your program.
3227 `watch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]'
3228 Set a watchpoint for an expression. GDB will break when the
3229 expression EXPR is written into by the program and its value
3230 changes. The simplest (and the most popular) use of this command
3231 is to watch the value of a single variable:
3235 If the command includes a `[thread THREADNUM]' argument, GDB
3236 breaks only when the thread identified by THREADNUM changes the
3237 value of EXPR. If any other threads change the value of EXPR, GDB
3238 will not break. Note that watchpoints restricted to a single
3239 thread in this way only work with Hardware Watchpoints.
3241 Ordinarily a watchpoint respects the scope of variables in EXPR
3242 (see below). The `-location' argument tells GDB to instead watch
3243 the memory referred to by EXPR. In this case, GDB will evaluate
3244 EXPR, take the address of the result, and watch the memory at that
3245 address. The type of the result is used to determine the size of
3246 the watched memory. If the expression's result does not have an
3247 address, then GDB will print an error.
3249 The `[mask MASKVALUE]' argument allows creation of masked
3250 watchpoints, if the current architecture supports this feature
3251 (e.g., PowerPC Embedded architecture, see *Note PowerPC
3252 Embedded::.) A "masked watchpoint" specifies a mask in addition
3253 to an address to watch. The mask specifies that some bits of an
3254 address (the bits which are reset in the mask) should be ignored
3255 when matching the address accessed by the inferior against the
3256 watchpoint address. Thus, a masked watchpoint watches many
3257 addresses simultaneously--those addresses whose unmasked bits are
3258 identical to the unmasked bits in the watchpoint address. The
3259 `mask' argument implies `-location'. Examples:
3261 (gdb) watch foo mask 0xffff00ff
3262 (gdb) watch *0xdeadbeef mask 0xffffff00
3264 `rwatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]'
3265 Set a watchpoint that will break when the value of EXPR is read by
3268 `awatch [-l|-location] EXPR [thread THREADNUM] [mask MASKVALUE]'
3269 Set a watchpoint that will break when EXPR is either read from or
3270 written into by the program.
3272 `info watchpoints [N...]'
3273 This command prints a list of watchpoints, using the same format as
3274 `info break' (*note Set Breaks::).
3276 If you watch for a change in a numerically entered address you need
3277 to dereference it, as the address itself is just a constant number
3278 which will never change. GDB refuses to create a watchpoint that
3279 watches a never-changing value:
3281 (gdb) watch 0x600850
3282 Cannot watch constant value 0x600850.
3283 (gdb) watch *(int *) 0x600850
3284 Watchpoint 1: *(int *) 6293584
3286 GDB sets a "hardware watchpoint" if possible. Hardware watchpoints
3287 execute very quickly, and the debugger reports a change in value at the
3288 exact instruction where the change occurs. If GDB cannot set a
3289 hardware watchpoint, it sets a software watchpoint, which executes more
3290 slowly and reports the change in value at the next _statement_, not the
3291 instruction, after the change occurs.
3293 You can force GDB to use only software watchpoints with the `set
3294 can-use-hw-watchpoints 0' command. With this variable set to zero, GDB
3295 will never try to use hardware watchpoints, even if the underlying
3296 system supports them. (Note that hardware-assisted watchpoints that
3297 were set _before_ setting `can-use-hw-watchpoints' to zero will still
3298 use the hardware mechanism of watching expression values.)
3300 `set can-use-hw-watchpoints'
3301 Set whether or not to use hardware watchpoints.
3303 `show can-use-hw-watchpoints'
3304 Show the current mode of using hardware watchpoints.
3306 For remote targets, you can restrict the number of hardware
3307 watchpoints GDB will use, see *Note set remote
3308 hardware-breakpoint-limit::.
3310 When you issue the `watch' command, GDB reports
3312 Hardware watchpoint NUM: EXPR
3314 if it was able to set a hardware watchpoint.
3316 Currently, the `awatch' and `rwatch' commands can only set hardware
3317 watchpoints, because accesses to data that don't change the value of
3318 the watched expression cannot be detected without examining every
3319 instruction as it is being executed, and GDB does not do that
3320 currently. If GDB finds that it is unable to set a hardware breakpoint
3321 with the `awatch' or `rwatch' command, it will print a message like
3324 Expression cannot be implemented with read/access watchpoint.
3326 Sometimes, GDB cannot set a hardware watchpoint because the data
3327 type of the watched expression is wider than what a hardware watchpoint
3328 on the target machine can handle. For example, some systems can only
3329 watch regions that are up to 4 bytes wide; on such systems you cannot
3330 set hardware watchpoints for an expression that yields a
3331 double-precision floating-point number (which is typically 8 bytes
3332 wide). As a work-around, it might be possible to break the large region
3333 into a series of smaller ones and watch them with separate watchpoints.
3335 If you set too many hardware watchpoints, GDB might be unable to
3336 insert all of them when you resume the execution of your program.
3337 Since the precise number of active watchpoints is unknown until such
3338 time as the program is about to be resumed, GDB might not be able to
3339 warn you about this when you set the watchpoints, and the warning will
3340 be printed only when the program is resumed:
3342 Hardware watchpoint NUM: Could not insert watchpoint
3344 If this happens, delete or disable some of the watchpoints.
3346 Watching complex expressions that reference many variables can also
3347 exhaust the resources available for hardware-assisted watchpoints.
3348 That's because GDB needs to watch every variable in the expression with
3349 separately allocated resources.
3351 If you call a function interactively using `print' or `call', any
3352 watchpoints you have set will be inactive until GDB reaches another
3353 kind of breakpoint or the call completes.
3355 GDB automatically deletes watchpoints that watch local (automatic)
3356 variables, or expressions that involve such variables, when they go out
3357 of scope, that is, when the execution leaves the block in which these
3358 variables were defined. In particular, when the program being debugged
3359 terminates, _all_ local variables go out of scope, and so only
3360 watchpoints that watch global variables remain set. If you rerun the
3361 program, you will need to set all such watchpoints again. One way of
3362 doing that would be to set a code breakpoint at the entry to the `main'
3363 function and when it breaks, set all the watchpoints.
3365 In multi-threaded programs, watchpoints will detect changes to the
3366 watched expression from every thread.
3368 _Warning:_ In multi-threaded programs, software watchpoints have
3369 only limited usefulness. If GDB creates a software watchpoint, it
3370 can only watch the value of an expression _in a single thread_.
3371 If you are confident that the expression can only change due to
3372 the current thread's activity (and if you are also confident that
3373 no other thread can become current), then you can use software
3374 watchpoints as usual. However, GDB may not notice when a
3375 non-current thread's activity changes the expression. (Hardware
3376 watchpoints, in contrast, watch an expression in all threads.)
3378 *Note set remote hardware-watchpoint-limit::.
3381 File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints
3383 5.1.3 Setting Catchpoints
3384 -------------------------
3386 You can use "catchpoints" to cause the debugger to stop for certain
3387 kinds of program events, such as C++ exceptions or the loading of a
3388 shared library. Use the `catch' command to set a catchpoint.
3391 Stop when EVENT occurs. EVENT can be any of the following:
3393 The throwing of a C++ exception.
3396 The catching of a C++ exception.
3399 An Ada exception being raised. If an exception name is
3400 specified at the end of the command (eg `catch exception
3401 Program_Error'), the debugger will stop only when this
3402 specific exception is raised. Otherwise, the debugger stops
3403 execution when any Ada exception is raised.
3405 When inserting an exception catchpoint on a user-defined
3406 exception whose name is identical to one of the exceptions
3407 defined by the language, the fully qualified name must be
3408 used as the exception name. Otherwise, GDB will assume that
3409 it should stop on the pre-defined exception rather than the
3410 user-defined one. For instance, assuming an exception called
3411 `Constraint_Error' is defined in package `Pck', then the
3412 command to use to catch such exceptions is `catch exception
3413 Pck.Constraint_Error'.
3415 `exception unhandled'
3416 An exception that was raised but is not handled by the
3420 A failed Ada assertion.
3423 A call to `exec'. This is currently only available for HP-UX
3427 `syscall [NAME | NUMBER] ...'
3428 A call to or return from a system call, a.k.a. "syscall". A
3429 syscall is a mechanism for application programs to request a
3430 service from the operating system (OS) or one of the OS
3431 system services. GDB can catch some or all of the syscalls
3432 issued by the debuggee, and show the related information for
3433 each syscall. If no argument is specified, calls to and
3434 returns from all system calls will be caught.
3436 NAME can be any system call name that is valid for the
3437 underlying OS. Just what syscalls are valid depends on the
3438 OS. On GNU and Unix systems, you can find the full list of
3439 valid syscall names on `/usr/include/asm/unistd.h'.
3441 Normally, GDB knows in advance which syscalls are valid for
3442 each OS, so you can use the GDB command-line completion
3443 facilities (*note command completion: Completion.) to list the
3446 You may also specify the system call numerically. A syscall's
3447 number is the value passed to the OS's syscall dispatcher to
3448 identify the requested service. When you specify the syscall
3449 by its name, GDB uses its database of syscalls to convert the
3450 name into the corresponding numeric code, but using the
3451 number directly may be useful if GDB's database does not have
3452 the complete list of syscalls on your system (e.g., because
3453 GDB lags behind the OS upgrades).
3455 The example below illustrates how this command works if you
3456 don't provide arguments to it:
3459 Catchpoint 1 (syscall)
3461 Starting program: /tmp/catch-syscall
3463 Catchpoint 1 (call to syscall 'close'), \
3464 0xffffe424 in __kernel_vsyscall ()
3468 Catchpoint 1 (returned from syscall 'close'), \
3469 0xffffe424 in __kernel_vsyscall ()
3472 Here is an example of catching a system call by name:
3474 (gdb) catch syscall chroot
3475 Catchpoint 1 (syscall 'chroot' [61])
3477 Starting program: /tmp/catch-syscall
3479 Catchpoint 1 (call to syscall 'chroot'), \
3480 0xffffe424 in __kernel_vsyscall ()
3484 Catchpoint 1 (returned from syscall 'chroot'), \
3485 0xffffe424 in __kernel_vsyscall ()
3488 An example of specifying a system call numerically. In the
3489 case below, the syscall number has a corresponding entry in
3490 the XML file, so GDB finds its name and prints it:
3492 (gdb) catch syscall 252
3493 Catchpoint 1 (syscall(s) 'exit_group')
3495 Starting program: /tmp/catch-syscall
3497 Catchpoint 1 (call to syscall 'exit_group'), \
3498 0xffffe424 in __kernel_vsyscall ()
3502 Program exited normally.
3505 However, there can be situations when there is no
3506 corresponding name in XML file for that syscall number. In
3507 this case, GDB prints a warning message saying that it was
3508 not able to find the syscall name, but the catchpoint will be
3509 set anyway. See the example below:
3511 (gdb) catch syscall 764
3512 warning: The number '764' does not represent a known syscall.
3513 Catchpoint 2 (syscall 764)
3516 If you configure GDB using the `--without-expat' option, it
3517 will not be able to display syscall names. Also, if your
3518 architecture does not have an XML file describing its system
3519 calls, you will not be able to see the syscall names. It is
3520 important to notice that these two features are used for
3521 accessing the syscall name database. In either case, you
3522 will see a warning like this:
3525 warning: Could not open "syscalls/i386-linux.xml"
3526 warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
3527 GDB will not be able to display syscall names.
3528 Catchpoint 1 (syscall)
3531 Of course, the file name will change depending on your
3532 architecture and system.
3534 Still using the example above, you can also try to catch a
3535 syscall by its number. In this case, you would see something
3538 (gdb) catch syscall 252
3539 Catchpoint 1 (syscall(s) 252)
3541 Again, in this case GDB would not be able to display
3545 A call to `fork'. This is currently only available for HP-UX
3549 A call to `vfork'. This is currently only available for HP-UX
3554 The loading or unloading of a shared library. If REGEXP is
3555 given, then the catchpoint will stop only if the regular
3556 expression matches one of the affected libraries.
3560 Set a catchpoint that is enabled only for one stop. The
3561 catchpoint is automatically deleted after the first time the event
3565 Use the `info break' command to list the current catchpoints.
3567 There are currently some limitations to C++ exception handling
3568 (`catch throw' and `catch catch') in GDB:
3570 * If you call a function interactively, GDB normally returns control
3571 to you when the function has finished executing. If the call
3572 raises an exception, however, the call may bypass the mechanism
3573 that returns control to you and cause your program either to abort
3574 or to simply continue running until it hits a breakpoint, catches
3575 a signal that GDB is listening for, or exits. This is the case
3576 even if you set a catchpoint for the exception; catchpoints on
3577 exceptions are disabled within interactive calls.
3579 * You cannot raise an exception interactively.
3581 * You cannot install an exception handler interactively.
3583 Sometimes `catch' is not the best way to debug exception handling:
3584 if you need to know exactly where an exception is raised, it is better
3585 to stop _before_ the exception handler is called, since that way you
3586 can see the stack before any unwinding takes place. If you set a
3587 breakpoint in an exception handler instead, it may not be easy to find
3588 out where the exception was raised.
3590 To stop just before an exception handler is called, you need some
3591 knowledge of the implementation. In the case of GNU C++, exceptions are
3592 raised by calling a library function named `__raise_exception' which
3593 has the following ANSI C interface:
3595 /* ADDR is where the exception identifier is stored.
3596 ID is the exception identifier. */
3597 void __raise_exception (void **addr, void *id);
3599 To make the debugger catch all exceptions before any stack unwinding
3600 takes place, set a breakpoint on `__raise_exception' (*note
3601 Breakpoints; Watchpoints; and Exceptions: Breakpoints.).
3603 With a conditional breakpoint (*note Break Conditions: Conditions.)
3604 that depends on the value of ID, you can stop your program when a
3605 specific exception is raised. You can use multiple conditional
3606 breakpoints to stop your program when any of a number of exceptions are
3610 File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints
3612 5.1.4 Deleting Breakpoints
3613 --------------------------
3615 It is often necessary to eliminate a breakpoint, watchpoint, or
3616 catchpoint once it has done its job and you no longer want your program
3617 to stop there. This is called "deleting" the breakpoint. A breakpoint
3618 that has been deleted no longer exists; it is forgotten.
3620 With the `clear' command you can delete breakpoints according to
3621 where they are in your program. With the `delete' command you can
3622 delete individual breakpoints, watchpoints, or catchpoints by specifying
3623 their breakpoint numbers.
3625 It is not necessary to delete a breakpoint to proceed past it. GDB
3626 automatically ignores breakpoints on the first instruction to be
3627 executed when you continue execution without changing the execution
3631 Delete any breakpoints at the next instruction to be executed in
3632 the selected stack frame (*note Selecting a Frame: Selection.).
3633 When the innermost frame is selected, this is a good way to delete
3634 a breakpoint where your program just stopped.
3637 Delete any breakpoints set at the specified LOCATION. *Note
3638 Specify Location::, for the various forms of LOCATION; the most
3639 useful ones are listed below:
3642 `clear FILENAME:FUNCTION'
3643 Delete any breakpoints set at entry to the named FUNCTION.
3646 `clear FILENAME:LINENUM'
3647 Delete any breakpoints set at or within the code of the
3648 specified LINENUM of the specified FILENAME.
3650 `delete [breakpoints] [RANGE...]'
3651 Delete the breakpoints, watchpoints, or catchpoints of the
3652 breakpoint ranges specified as arguments. If no argument is
3653 specified, delete all breakpoints (GDB asks confirmation, unless
3654 you have `set confirm off'). You can abbreviate this command as
3658 File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints
3660 5.1.5 Disabling Breakpoints
3661 ---------------------------
3663 Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
3664 prefer to "disable" it. This makes the breakpoint inoperative as if it
3665 had been deleted, but remembers the information on the breakpoint so
3666 that you can "enable" it again later.
3668 You disable and enable breakpoints, watchpoints, and catchpoints with
3669 the `enable' and `disable' commands, optionally specifying one or more
3670 breakpoint numbers as arguments. Use `info break' to print a list of
3671 all breakpoints, watchpoints, and catchpoints if you do not know which
3674 Disabling and enabling a breakpoint that has multiple locations
3675 affects all of its locations.
3677 A breakpoint, watchpoint, or catchpoint can have any of several
3678 different states of enablement:
3680 * Enabled. The breakpoint stops your program. A breakpoint set
3681 with the `break' command starts out in this state.
3683 * Disabled. The breakpoint has no effect on your program.
3685 * Enabled once. The breakpoint stops your program, but then becomes
3688 * Enabled for a count. The breakpoint stops your program for the
3689 next N times, then becomes disabled.
3691 * Enabled for deletion. The breakpoint stops your program, but
3692 immediately after it does so it is deleted permanently. A
3693 breakpoint set with the `tbreak' command starts out in this state.
3695 You can use the following commands to enable or disable breakpoints,
3696 watchpoints, and catchpoints:
3698 `disable [breakpoints] [RANGE...]'
3699 Disable the specified breakpoints--or all breakpoints, if none are
3700 listed. A disabled breakpoint has no effect but is not forgotten.
3701 All options such as ignore-counts, conditions and commands are
3702 remembered in case the breakpoint is enabled again later. You may
3703 abbreviate `disable' as `dis'.
3705 `enable [breakpoints] [RANGE...]'
3706 Enable the specified breakpoints (or all defined breakpoints).
3707 They become effective once again in stopping your program.
3709 `enable [breakpoints] once RANGE...'
3710 Enable the specified breakpoints temporarily. GDB disables any of
3711 these breakpoints immediately after stopping your program.
3713 `enable [breakpoints] count COUNT RANGE...'
3714 Enable the specified breakpoints temporarily. GDB records COUNT
3715 with each of the specified breakpoints, and decrements a
3716 breakpoint's count when it is hit. When any count reaches 0, GDB
3717 disables that breakpoint. If a breakpoint has an ignore count
3718 (*note Break Conditions: Conditions.), that will be decremented to
3719 0 before COUNT is affected.
3721 `enable [breakpoints] delete RANGE...'
3722 Enable the specified breakpoints to work once, then die. GDB
3723 deletes any of these breakpoints as soon as your program stops
3724 there. Breakpoints set by the `tbreak' command start out in this
3727 Except for a breakpoint set with `tbreak' (*note Setting
3728 Breakpoints: Set Breaks.), breakpoints that you set are initially
3729 enabled; subsequently, they become disabled or enabled only when you
3730 use one of the commands above. (The command `until' can set and delete
3731 a breakpoint of its own, but it does not change the state of your other
3732 breakpoints; see *Note Continuing and Stepping: Continuing and
3736 File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints
3738 5.1.6 Break Conditions
3739 ----------------------
3741 The simplest sort of breakpoint breaks every time your program reaches a
3742 specified place. You can also specify a "condition" for a breakpoint.
3743 A condition is just a Boolean expression in your programming language
3744 (*note Expressions: Expressions.). A breakpoint with a condition
3745 evaluates the expression each time your program reaches it, and your
3746 program stops only if the condition is _true_.
3748 This is the converse of using assertions for program validation; in
3749 that situation, you want to stop when the assertion is violated--that
3750 is, when the condition is false. In C, if you want to test an
3751 assertion expressed by the condition ASSERT, you should set the
3752 condition `! ASSERT' on the appropriate breakpoint.
3754 Conditions are also accepted for watchpoints; you may not need them,
3755 since a watchpoint is inspecting the value of an expression anyhow--but
3756 it might be simpler, say, to just set a watchpoint on a variable name,
3757 and specify a condition that tests whether the new value is an
3760 Break conditions can have side effects, and may even call functions
3761 in your program. This can be useful, for example, to activate functions
3762 that log program progress, or to use your own print functions to format
3763 special data structures. The effects are completely predictable unless
3764 there is another enabled breakpoint at the same address. (In that
3765 case, GDB might see the other breakpoint first and stop your program
3766 without checking the condition of this one.) Note that breakpoint
3767 commands are usually more convenient and flexible than break conditions
3768 for the purpose of performing side effects when a breakpoint is reached
3769 (*note Breakpoint Command Lists: Break Commands.).
3771 Breakpoint conditions can also be evaluated on the target's side if
3772 the target supports it. Instead of evaluating the conditions locally,
3773 GDB encodes the expression into an agent expression (*note Agent
3774 Expressions::) suitable for execution on the target, independently of
3775 GDB. Global variables become raw memory locations, locals become stack
3776 accesses, and so forth.
3778 In this case, GDB will only be notified of a breakpoint trigger when
3779 its condition evaluates to true. This mechanism may provide faster
3780 response times depending on the performance characteristics of the
3781 target since it does not need to keep GDB informed about every
3782 breakpoint trigger, even those with false conditions.
3784 Break conditions can be specified when a breakpoint is set, by using
3785 `if' in the arguments to the `break' command. *Note Setting
3786 Breakpoints: Set Breaks. They can also be changed at any time with the
3787 `condition' command.
3789 You can also use the `if' keyword with the `watch' command. The
3790 `catch' command does not recognize the `if' keyword; `condition' is the
3791 only way to impose a further condition on a catchpoint.
3793 `condition BNUM EXPRESSION'
3794 Specify EXPRESSION as the break condition for breakpoint,
3795 watchpoint, or catchpoint number BNUM. After you set a condition,
3796 breakpoint BNUM stops your program only if the value of EXPRESSION
3797 is true (nonzero, in C). When you use `condition', GDB checks
3798 EXPRESSION immediately for syntactic correctness, and to determine
3799 whether symbols in it have referents in the context of your
3800 breakpoint. If EXPRESSION uses symbols not referenced in the
3801 context of the breakpoint, GDB prints an error message:
3803 No symbol "foo" in current context.
3805 GDB does not actually evaluate EXPRESSION at the time the
3806 `condition' command (or a command that sets a breakpoint with a
3807 condition, like `break if ...') is given, however. *Note
3808 Expressions: Expressions.
3811 Remove the condition from breakpoint number BNUM. It becomes an
3812 ordinary unconditional breakpoint.
3814 A special case of a breakpoint condition is to stop only when the
3815 breakpoint has been reached a certain number of times. This is so
3816 useful that there is a special way to do it, using the "ignore count"
3817 of the breakpoint. Every breakpoint has an ignore count, which is an
3818 integer. Most of the time, the ignore count is zero, and therefore has
3819 no effect. But if your program reaches a breakpoint whose ignore count
3820 is positive, then instead of stopping, it just decrements the ignore
3821 count by one and continues. As a result, if the ignore count value is
3822 N, the breakpoint does not stop the next N times your program reaches
3826 Set the ignore count of breakpoint number BNUM to COUNT. The next
3827 COUNT times the breakpoint is reached, your program's execution
3828 does not stop; other than to decrement the ignore count, GDB takes
3831 To make the breakpoint stop the next time it is reached, specify a
3834 When you use `continue' to resume execution of your program from a
3835 breakpoint, you can specify an ignore count directly as an
3836 argument to `continue', rather than using `ignore'. *Note
3837 Continuing and Stepping: Continuing and Stepping.
3839 If a breakpoint has a positive ignore count and a condition, the
3840 condition is not checked. Once the ignore count reaches zero, GDB
3841 resumes checking the condition.
3843 You could achieve the effect of the ignore count with a condition
3844 such as `$foo-- <= 0' using a debugger convenience variable that
3845 is decremented each time. *Note Convenience Variables:
3848 Ignore counts apply to breakpoints, watchpoints, and catchpoints.
3851 File: gdb.info, Node: Break Commands, Next: Dynamic Printf, Prev: Conditions, Up: Breakpoints
3853 5.1.7 Breakpoint Command Lists
3854 ------------------------------
3856 You can give any breakpoint (or watchpoint or catchpoint) a series of
3857 commands to execute when your program stops due to that breakpoint. For
3858 example, you might want to print the values of certain expressions, or
3859 enable other breakpoints.
3861 `commands [RANGE...]'
3862 `... COMMAND-LIST ...'
3864 Specify a list of commands for the given breakpoints. The commands
3865 themselves appear on the following lines. Type a line containing
3866 just `end' to terminate the commands.
3868 To remove all commands from a breakpoint, type `commands' and
3869 follow it immediately with `end'; that is, give no commands.
3871 With no argument, `commands' refers to the last breakpoint,
3872 watchpoint, or catchpoint set (not to the breakpoint most recently
3873 encountered). If the most recent breakpoints were set with a
3874 single command, then the `commands' will apply to all the
3875 breakpoints set by that command. This applies to breakpoints set
3876 by `rbreak', and also applies when a single `break' command
3877 creates multiple breakpoints (*note Ambiguous Expressions:
3878 Ambiguous Expressions.).
3880 Pressing <RET> as a means of repeating the last GDB command is
3881 disabled within a COMMAND-LIST.
3883 You can use breakpoint commands to start your program up again.
3884 Simply use the `continue' command, or `step', or any other command that
3887 Any other commands in the command list, after a command that resumes
3888 execution, are ignored. This is because any time you resume execution
3889 (even with a simple `next' or `step'), you may encounter another
3890 breakpoint--which could have its own command list, leading to
3891 ambiguities about which list to execute.
3893 If the first command you specify in a command list is `silent', the
3894 usual message about stopping at a breakpoint is not printed. This may
3895 be desirable for breakpoints that are to print a specific message and
3896 then continue. If none of the remaining commands print anything, you
3897 see no sign that the breakpoint was reached. `silent' is meaningful
3898 only at the beginning of a breakpoint command list.
3900 The commands `echo', `output', and `printf' allow you to print
3901 precisely controlled output, and are often useful in silent
3902 breakpoints. *Note Commands for Controlled Output: Output.
3904 For example, here is how you could use breakpoint commands to print
3905 the value of `x' at entry to `foo' whenever `x' is positive.
3910 printf "x is %d\n",x
3914 One application for breakpoint commands is to compensate for one bug
3915 so you can test for another. Put a breakpoint just after the erroneous
3916 line of code, give it a condition to detect the case in which something
3917 erroneous has been done, and give it commands to assign correct values
3918 to any variables that need them. End with the `continue' command so
3919 that your program does not stop, and start with the `silent' command so
3920 that no output is produced. Here is an example:
3930 File: gdb.info, Node: Dynamic Printf, Next: Save Breakpoints, Prev: Break Commands, Up: Breakpoints
3932 5.1.8 Dynamic Printf
3933 --------------------
3935 The dynamic printf command `dprintf' combines a breakpoint with
3936 formatted printing of your program's data to give you the effect of
3937 inserting `printf' calls into your program on-the-fly, without having
3940 In its most basic form, the output goes to the GDB console. However,
3941 you can set the variable `dprintf-style' for alternate handling. For
3942 instance, you can ask to format the output by calling your program's
3943 `printf' function. This has the advantage that the characters go to
3944 the program's output device, so they can recorded in redirects to files
3947 If you are doing remote debugging with a stub or agent, you can also
3948 ask to have the printf handled by the remote agent. In addition to
3949 ensuring that the output goes to the remote program's device along with
3950 any other output the program might produce, you can also ask that the
3951 dprintf remain active even after disconnecting from the remote target.
3952 Using the stub/agent is also more efficient, as it can do everything
3953 without needing to communicate with GDB.
3955 `dprintf LOCATION,TEMPLATE,EXPRESSION[,EXPRESSION...]'
3956 Whenever execution reaches LOCATION, print the values of one or
3957 more EXPRESSIONS under the control of the string TEMPLATE. To
3958 print several values, separate them with commas.
3960 `set dprintf-style STYLE'
3961 Set the dprintf output to be handled in one of several different
3962 styles enumerated below. A change of style affects all existing
3963 dynamic printfs immediately. (If you need individual control over
3964 the print commands, simply define normal breakpoints with
3965 explicitly-supplied command lists.)
3968 Handle the output using the GDB `printf' command.
3971 Handle the output by calling a function in your program (normally
3975 Have the remote debugging agent (such as `gdbserver') handle the
3976 output itself. This style is only available for agents that
3977 support running commands on the target.
3979 `set dprintf-function FUNCTION'
3980 Set the function to call if the dprintf style is `call'. By
3981 default its value is `printf'. You may set it to any expression.
3982 that GDB can evaluate to a function, as per the `call' command.
3984 `set dprintf-channel CHANNEL'
3985 Set a "channel" for dprintf. If set to a non-empty value, GDB
3986 will evaluate it as an expression and pass the result as a first
3987 argument to the `dprintf-function', in the manner of `fprintf' and
3988 similar functions. Otherwise, the dprintf format string will be
3989 the first argument, in the manner of `printf'.
3991 As an example, if you wanted `dprintf' output to go to a logfile
3992 that is a standard I/O stream assigned to the variable `mylog',
3993 you could do the following:
3995 (gdb) set dprintf-style call
3996 (gdb) set dprintf-function fprintf
3997 (gdb) set dprintf-channel mylog
3998 (gdb) dprintf 25,"at line 25, glob=%d\n",glob
3999 Dprintf 1 at 0x123456: file main.c, line 25.
4001 1 dprintf keep y 0x00123456 in main at main.c:25
4002 call (void) fprintf (mylog,"at line 25, glob=%d\n",glob)
4006 Note that the `info break' displays the dynamic printf commands as
4007 normal breakpoint commands; you can thus easily see the effect of
4008 the variable settings.
4010 `set disconnected-dprintf on'
4011 `set disconnected-dprintf off'
4012 Choose whether `dprintf' commands should continue to run if GDB
4013 has disconnected from the target. This only applies if the
4014 `dprintf-style' is `agent'.
4016 `show disconnected-dprintf off'
4017 Show the current choice for disconnected `dprintf'.
4020 GDB does not check the validity of function and channel, relying on
4021 you to supply values that are meaningful for the contexts in which they
4022 are being used. For instance, the function and channel may be the
4023 values of local variables, but if that is the case, then all enabled
4024 dynamic prints must be at locations within the scope of those locals.
4025 If evaluation fails, GDB will report an error.
4028 File: gdb.info, Node: Save Breakpoints, Next: Static Probe Points, Prev: Dynamic Printf, Up: Breakpoints
4030 5.1.9 How to save breakpoints to a file
4031 ---------------------------------------
4033 To save breakpoint definitions to a file use the `save breakpoints'
4036 `save breakpoints [FILENAME]'
4037 This command saves all current breakpoint definitions together with
4038 their commands and ignore counts, into a file `FILENAME' suitable
4039 for use in a later debugging session. This includes all types of
4040 breakpoints (breakpoints, watchpoints, catchpoints, tracepoints).
4041 To read the saved breakpoint definitions, use the `source' command
4042 (*note Command Files::). Note that watchpoints with expressions
4043 involving local variables may fail to be recreated because it may
4044 not be possible to access the context where the watchpoint is
4045 valid anymore. Because the saved breakpoint definitions are
4046 simply a sequence of GDB commands that recreate the breakpoints,
4047 you can edit the file in your favorite editing program, and remove
4048 the breakpoint definitions you're not interested in, or that can
4049 no longer be recreated.
4052 File: gdb.info, Node: Static Probe Points, Next: Error in Breakpoints, Prev: Save Breakpoints, Up: Breakpoints
4054 5.1.10 Static Probe Points
4055 --------------------------
4057 GDB supports "SDT" probes in the code. SDT stands for Statically
4058 Defined Tracing, and the probes are designed to have a tiny runtime
4059 code and data footprint, and no dynamic relocations. They are usable
4060 from assembly, C and C++ languages. See
4061 `http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation' for
4062 a good reference on how the SDT probes are implemented.
4064 Currently, `SystemTap' (`http://sourceware.org/systemtap/') SDT
4065 probes are supported on ELF-compatible systems. See
4066 `http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps' for
4067 more information on how to add `SystemTap' SDT probes in your
4070 Some probes have an associated semaphore variable; for instance, this
4071 happens automatically if you defined your probe using a DTrace-style
4072 `.d' file. If your probe has a semaphore, GDB will automatically
4073 enable it when you specify a breakpoint using the `-probe-stap'
4074 notation. But, if you put a breakpoint at a probe's location by some
4075 other method (e.g., `break file:line'), then GDB will not automatically
4078 You can examine the available static static probes using `info
4079 probes', with optional arguments:
4081 `info probes stap [PROVIDER [NAME [OBJFILE]]]'
4082 If given, PROVIDER is a regular expression used to match against
4083 provider names when selecting which probes to list. If omitted,
4084 probes by all probes from all providers are listed.
4086 If given, NAME is a regular expression to match against probe names
4087 when selecting which probes to list. If omitted, probe names are
4088 not considered when deciding whether to display them.
4090 If given, OBJFILE is a regular expression used to select which
4091 object files (executable or shared libraries) to examine. If not
4092 given, all object files are considered.
4095 List the available static probes, from all types.
4097 A probe may specify up to twelve arguments. These are available at
4098 the point at which the probe is defined--that is, when the current PC is
4099 at the probe's location. The arguments are available using the
4100 convenience variables (*note Convenience Vars::)
4101 `$_probe_arg0'...`$_probe_arg11'. Each probe argument is an integer of
4102 the appropriate size; types are not preserved. The convenience
4103 variable `$_probe_argc' holds the number of arguments at the current
4106 These variables are always available, but attempts to access them at
4107 any location other than a probe point will cause GDB to give an error
4111 File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Static Probe Points, Up: Breakpoints
4113 5.1.11 "Cannot insert breakpoints"
4114 ----------------------------------
4116 If you request too many active hardware-assisted breakpoints and
4117 watchpoints, you will see this error message:
4119 Stopped; cannot insert breakpoints.
4120 You may have requested too many hardware breakpoints and watchpoints.
4122 This message is printed when you attempt to resume the program, since
4123 only then GDB knows exactly how many hardware breakpoints and
4124 watchpoints it needs to insert.
4126 When this message is printed, you need to disable or remove some of
4127 the hardware-assisted breakpoints and watchpoints, and then continue.
4130 File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints
4132 5.1.12 "Breakpoint address adjusted..."
4133 ---------------------------------------
4135 Some processor architectures place constraints on the addresses at
4136 which breakpoints may be placed. For architectures thus constrained,
4137 GDB will attempt to adjust the breakpoint's address to comply with the
4138 constraints dictated by the architecture.
4140 One example of such an architecture is the Fujitsu FR-V. The FR-V is
4141 a VLIW architecture in which a number of RISC-like instructions may be
4142 bundled together for parallel execution. The FR-V architecture
4143 constrains the location of a breakpoint instruction within such a
4144 bundle to the instruction with the lowest address. GDB honors this
4145 constraint by adjusting a breakpoint's address to the first in the
4148 It is not uncommon for optimized code to have bundles which contain
4149 instructions from different source statements, thus it may happen that
4150 a breakpoint's address will be adjusted from one source statement to
4151 another. Since this adjustment may significantly alter GDB's
4152 breakpoint related behavior from what the user expects, a warning is
4153 printed when the breakpoint is first set and also when the breakpoint
4156 A warning like the one below is printed when setting a breakpoint
4157 that's been subject to address adjustment:
4159 warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
4161 Such warnings are printed both for user settable and GDB's internal
4162 breakpoints. If you see one of these warnings, you should verify that
4163 a breakpoint set at the adjusted address will have the desired affect.
4164 If not, the breakpoint in question may be removed and other breakpoints
4165 may be set which will have the desired behavior. E.g., it may be
4166 sufficient to place the breakpoint at a later instruction. A
4167 conditional breakpoint may also be useful in some cases to prevent the
4168 breakpoint from triggering too often.
4170 GDB will also issue a warning when stopping at one of these adjusted
4173 warning: Breakpoint 1 address previously adjusted from 0x00010414
4176 When this warning is encountered, it may be too late to take remedial
4177 action except in cases where the breakpoint is hit earlier or more
4178 frequently than expected.
4181 File: gdb.info, Node: Continuing and Stepping, Next: Skipping Over Functions and Files, Prev: Breakpoints, Up: Stopping
4183 5.2 Continuing and Stepping
4184 ===========================
4186 "Continuing" means resuming program execution until your program
4187 completes normally. In contrast, "stepping" means executing just one
4188 more "step" of your program, where "step" may mean either one line of
4189 source code, or one machine instruction (depending on what particular
4190 command you use). Either when continuing or when stepping, your
4191 program may stop even sooner, due to a breakpoint or a signal. (If it
4192 stops due to a signal, you may want to use `handle', or use `signal 0'
4193 to resume execution. *Note Signals: Signals.)
4195 `continue [IGNORE-COUNT]'
4198 Resume program execution, at the address where your program last
4199 stopped; any breakpoints set at that address are bypassed. The
4200 optional argument IGNORE-COUNT allows you to specify a further
4201 number of times to ignore a breakpoint at this location; its
4202 effect is like that of `ignore' (*note Break Conditions:
4205 The argument IGNORE-COUNT is meaningful only when your program
4206 stopped due to a breakpoint. At other times, the argument to
4207 `continue' is ignored.
4209 The synonyms `c' and `fg' (for "foreground", as the debugged
4210 program is deemed to be the foreground program) are provided
4211 purely for convenience, and have exactly the same behavior as
4214 To resume execution at a different place, you can use `return'
4215 (*note Returning from a Function: Returning.) to go back to the calling
4216 function; or `jump' (*note Continuing at a Different Address: Jumping.)
4217 to go to an arbitrary location in your program.
4219 A typical technique for using stepping is to set a breakpoint (*note
4220 Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the
4221 beginning of the function or the section of your program where a problem
4222 is believed to lie, run your program until it stops at that breakpoint,
4223 and then step through the suspect area, examining the variables that are
4224 interesting, until you see the problem happen.
4227 Continue running your program until control reaches a different
4228 source line, then stop it and return control to GDB. This command
4231 _Warning:_ If you use the `step' command while control is
4232 within a function that was compiled without debugging
4233 information, execution proceeds until control reaches a
4234 function that does have debugging information. Likewise, it
4235 will not step into a function which is compiled without
4236 debugging information. To step through functions without
4237 debugging information, use the `stepi' command, described
4240 The `step' command only stops at the first instruction of a source
4241 line. This prevents the multiple stops that could otherwise occur
4242 in `switch' statements, `for' loops, etc. `step' continues to
4243 stop if a function that has debugging information is called within
4244 the line. In other words, `step' _steps inside_ any functions
4245 called within the line.
4247 Also, the `step' command only enters a function if there is line
4248 number information for the function. Otherwise it acts like the
4249 `next' command. This avoids problems when using `cc -gl' on MIPS
4250 machines. Previously, `step' entered subroutines if there was any
4251 debugging information about the routine.
4254 Continue running as in `step', but do so COUNT times. If a
4255 breakpoint is reached, or a signal not related to stepping occurs
4256 before COUNT steps, stepping stops right away.
4259 Continue to the next source line in the current (innermost) stack
4260 frame. This is similar to `step', but function calls that appear
4261 within the line of code are executed without stopping. Execution
4262 stops when control reaches a different line of code at the
4263 original stack level that was executing when you gave the `next'
4264 command. This command is abbreviated `n'.
4266 An argument COUNT is a repeat count, as for `step'.
4268 The `next' command only stops at the first instruction of a source
4269 line. This prevents multiple stops that could otherwise occur in
4270 `switch' statements, `for' loops, etc.
4274 The `set step-mode on' command causes the `step' command to stop
4275 at the first instruction of a function which contains no debug line
4276 information rather than stepping over it.
4278 This is useful in cases where you may be interested in inspecting
4279 the machine instructions of a function which has no symbolic info
4280 and do not want GDB to automatically skip over this function.
4283 Causes the `step' command to step over any functions which
4284 contains no debug information. This is the default.
4287 Show whether GDB will stop in or step over functions without
4288 source line debug information.
4291 Continue running until just after function in the selected stack
4292 frame returns. Print the returned value (if any). This command
4293 can be abbreviated as `fin'.
4295 Contrast this with the `return' command (*note Returning from a
4296 Function: Returning.).
4300 Continue running until a source line past the current line, in the
4301 current stack frame, is reached. This command is used to avoid
4302 single stepping through a loop more than once. It is like the
4303 `next' command, except that when `until' encounters a jump, it
4304 automatically continues execution until the program counter is
4305 greater than the address of the jump.
4307 This means that when you reach the end of a loop after single
4308 stepping though it, `until' makes your program continue execution
4309 until it exits the loop. In contrast, a `next' command at the end
4310 of a loop simply steps back to the beginning of the loop, which
4311 forces you to step through the next iteration.
4313 `until' always stops your program if it attempts to exit the
4314 current stack frame.
4316 `until' may produce somewhat counterintuitive results if the order
4317 of machine code does not match the order of the source lines. For
4318 example, in the following excerpt from a debugging session, the `f'
4319 (`frame') command shows that execution is stopped at line `206';
4320 yet when we use `until', we get to line `195':
4323 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206
4326 195 for ( ; argc > 0; NEXTARG) {
4328 This happened because, for execution efficiency, the compiler had
4329 generated code for the loop closure test at the end, rather than
4330 the start, of the loop--even though the test in a C `for'-loop is
4331 written before the body of the loop. The `until' command appeared
4332 to step back to the beginning of the loop when it advanced to this
4333 expression; however, it has not really gone to an earlier
4334 statement--not in terms of the actual machine code.
4336 `until' with no argument works by means of single instruction
4337 stepping, and hence is slower than `until' with an argument.
4341 Continue running your program until either the specified location
4342 is reached, or the current stack frame returns. LOCATION is any of
4343 the forms described in *Note Specify Location::. This form of the
4344 command uses temporary breakpoints, and hence is quicker than
4345 `until' without an argument. The specified location is actually
4346 reached only if it is in the current frame. This implies that
4347 `until' can be used to skip over recursive function invocations.
4348 For instance in the code below, if the current location is line
4349 `96', issuing `until 99' will execute the program up to line `99'
4350 in the same invocation of factorial, i.e., after the inner
4351 invocations have returned.
4353 94 int factorial (int value)
4356 97 value *= factorial (value - 1);
4362 Continue running the program up to the given LOCATION. An
4363 argument is required, which should be of one of the forms
4364 described in *Note Specify Location::. Execution will also stop
4365 upon exit from the current stack frame. This command is similar
4366 to `until', but `advance' will not skip over recursive function
4367 calls, and the target location doesn't have to be in the same
4368 frame as the current one.
4373 Execute one machine instruction, then stop and return to the
4376 It is often useful to do `display/i $pc' when stepping by machine
4377 instructions. This makes GDB automatically display the next
4378 instruction to be executed, each time your program stops. *Note
4379 Automatic Display: Auto Display.
4381 An argument is a repeat count, as in `step'.
4386 Execute one machine instruction, but if it is a function call,
4387 proceed until the function returns.
4389 An argument is a repeat count, as in `next'.
4392 File: gdb.info, Node: Skipping Over Functions and Files, Next: Signals, Prev: Continuing and Stepping, Up: Stopping
4394 5.3 Skipping Over Functions and Files
4395 =====================================
4397 The program you are debugging may contain some functions which are
4398 uninteresting to debug. The `skip' comand lets you tell GDB to skip a
4399 function or all functions in a file when stepping.
4401 For example, consider the following C function:
4409 Suppose you wish to step into the functions `foo' and `bar', but you
4410 are not interested in stepping through `boring'. If you run `step' at
4411 line 103, you'll enter `boring()', but if you run `next', you'll step
4412 over both `foo' and `boring'!
4414 One solution is to `step' into `boring' and use the `finish' command
4415 to immediately exit it. But this can become tedious if `boring' is
4416 called from many places.
4418 A more flexible solution is to execute `skip boring'. This instructs
4419 GDB never to step into `boring'. Now when you execute `step' at line
4420 103, you'll step over `boring' and directly into `foo'.
4422 You can also instruct GDB to skip all functions in a file, with, for
4423 example, `skip file boring.c'.
4426 `skip function [LINESPEC]'
4427 After running this command, the function named by LINESPEC or the
4428 function containing the line named by LINESPEC will be skipped
4429 over when stepping. *Note Specify Location::.
4431 If you do not specify LINESPEC, the function you're currently
4432 debugging will be skipped.
4434 (If you have a function called `file' that you want to skip, use
4435 `skip function file'.)
4437 `skip file [FILENAME]'
4438 After running this command, any function whose source lives in
4439 FILENAME will be skipped over when stepping.
4441 If you do not specify FILENAME, functions whose source lives in
4442 the file you're currently debugging will be skipped.
4444 Skips can be listed, deleted, disabled, and enabled, much like
4445 breakpoints. These are the commands for managing your list of skips:
4448 Print details about the specified skip(s). If RANGE is not
4449 specified, print a table with details about all functions and
4450 files marked for skipping. `info skip' prints the following
4451 information about each skip:
4454 A number identifying this skip.
4457 The type of this skip, either `function' or `file'.
4459 _Enabled or Disabled_
4460 Enabled skips are marked with `y'. Disabled skips are marked
4464 For function skips, this column indicates the address in
4465 memory of the function being skipped. If you've set a
4466 function skip on a function which has not yet been loaded,
4467 this field will contain `<PENDING>'. Once a shared library
4468 which has the function is loaded, `info skip' will show the
4469 function's address here.
4472 For file skips, this field contains the filename being
4473 skipped. For functions skips, this field contains the
4474 function name and its line number in the file where it is
4477 `skip delete [RANGE]'
4478 Delete the specified skip(s). If RANGE is not specified, delete
4481 `skip enable [RANGE]'
4482 Enable the specified skip(s). If RANGE is not specified, enable
4485 `skip disable [RANGE]'
4486 Disable the specified skip(s). If RANGE is not specified, disable
4491 File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Skipping Over Functions and Files, Up: Stopping
4496 A signal is an asynchronous event that can happen in a program. The
4497 operating system defines the possible kinds of signals, and gives each
4498 kind a name and a number. For example, in Unix `SIGINT' is the signal
4499 a program gets when you type an interrupt character (often `Ctrl-c');
4500 `SIGSEGV' is the signal a program gets from referencing a place in
4501 memory far away from all the areas in use; `SIGALRM' occurs when the
4502 alarm clock timer goes off (which happens only if your program has
4503 requested an alarm).
4505 Some signals, including `SIGALRM', are a normal part of the
4506 functioning of your program. Others, such as `SIGSEGV', indicate
4507 errors; these signals are "fatal" (they kill your program immediately)
4508 if the program has not specified in advance some other way to handle
4509 the signal. `SIGINT' does not indicate an error in your program, but
4510 it is normally fatal so it can carry out the purpose of the interrupt:
4511 to kill the program.
4513 GDB has the ability to detect any occurrence of a signal in your
4514 program. You can tell GDB in advance what to do for each kind of
4517 Normally, GDB is set up to let the non-erroneous signals like
4518 `SIGALRM' be silently passed to your program (so as not to interfere
4519 with their role in the program's functioning) but to stop your program
4520 immediately whenever an error signal happens. You can change these
4521 settings with the `handle' command.
4525 Print a table of all the kinds of signals and how GDB has been
4526 told to handle each one. You can use this to see the signal
4527 numbers of all the defined types of signals.
4530 Similar, but print information only about the specified signal
4533 `info handle' is an alias for `info signals'.
4535 `handle SIGNAL [KEYWORDS...]'
4536 Change the way GDB handles signal SIGNAL. SIGNAL can be the
4537 number of a signal or its name (with or without the `SIG' at the
4538 beginning); a list of signal numbers of the form `LOW-HIGH'; or
4539 the word `all', meaning all the known signals. Optional arguments
4540 KEYWORDS, described below, say what change to make.
4542 The keywords allowed by the `handle' command can be abbreviated.
4543 Their full names are:
4546 GDB should not stop your program when this signal happens. It may
4547 still print a message telling you that the signal has come in.
4550 GDB should stop your program when this signal happens. This
4551 implies the `print' keyword as well.
4554 GDB should print a message when this signal happens.
4557 GDB should not mention the occurrence of the signal at all. This
4558 implies the `nostop' keyword as well.
4562 GDB should allow your program to see this signal; your program can
4563 handle the signal, or else it may terminate if the signal is fatal
4564 and not handled. `pass' and `noignore' are synonyms.
4568 GDB should not allow your program to see this signal. `nopass'
4569 and `ignore' are synonyms.
4571 When a signal stops your program, the signal is not visible to the
4572 program until you continue. Your program sees the signal then, if
4573 `pass' is in effect for the signal in question _at that time_. In
4574 other words, after GDB reports a signal, you can use the `handle'
4575 command with `pass' or `nopass' to control whether your program sees
4576 that signal when you continue.
4578 The default is set to `nostop', `noprint', `pass' for non-erroneous
4579 signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop',
4580 `print', `pass' for the erroneous signals.
4582 You can also use the `signal' command to prevent your program from
4583 seeing a signal, or cause it to see a signal it normally would not see,
4584 or to give it any signal at any time. For example, if your program
4585 stopped due to some sort of memory reference error, you might store
4586 correct values into the erroneous variables and continue, hoping to see
4587 more execution; but your program would probably terminate immediately as
4588 a result of the fatal signal once it saw the signal. To prevent this,
4589 you can continue with `signal 0'. *Note Giving your Program a Signal:
4592 On some targets, GDB can inspect extra signal information associated
4593 with the intercepted signal, before it is actually delivered to the
4594 program being debugged. This information is exported by the
4595 convenience variable `$_siginfo', and consists of data that is passed
4596 by the kernel to the signal handler at the time of the receipt of a
4597 signal. The data type of the information itself is target dependent.
4598 You can see the data type using the `ptype $_siginfo' command. On Unix
4599 systems, it typically corresponds to the standard `siginfo_t' type, as
4600 defined in the `signal.h' system header.
4602 Here's an example, on a GNU/Linux system, printing the stray
4603 referenced address that raised a segmentation fault.
4606 Program received signal SIGSEGV, Segmentation fault.
4607 0x0000000000400766 in main ()
4609 (gdb) ptype $_siginfo
4617 struct {...} _timer;
4619 struct {...} _sigchld;
4620 struct {...} _sigfault;
4621 struct {...} _sigpoll;
4624 (gdb) ptype $_siginfo._sifields._sigfault
4628 (gdb) p $_siginfo._sifields._sigfault.si_addr
4629 $1 = (void *) 0x7ffff7ff7000
4631 Depending on target support, `$_siginfo' may also be writable.
4634 File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping
4636 5.5 Stopping and Starting Multi-thread Programs
4637 ===============================================
4639 GDB supports debugging programs with multiple threads (*note Debugging
4640 Programs with Multiple Threads: Threads.). There are two modes of
4641 controlling execution of your program within the debugger. In the
4642 default mode, referred to as "all-stop mode", when any thread in your
4643 program stops (for example, at a breakpoint or while being stepped),
4644 all other threads in the program are also stopped by GDB. On some
4645 targets, GDB also supports "non-stop mode", in which other threads can
4646 continue to run freely while you examine the stopped thread in the
4651 * All-Stop Mode:: All threads stop when GDB takes control
4652 * Non-Stop Mode:: Other threads continue to execute
4653 * Background Execution:: Running your program asynchronously
4654 * Thread-Specific Breakpoints:: Controlling breakpoints
4655 * Interrupted System Calls:: GDB may interfere with system calls
4656 * Observer Mode:: GDB does not alter program behavior
4659 File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops
4664 In all-stop mode, whenever your program stops under GDB for any reason,
4665 _all_ threads of execution stop, not just the current thread. This
4666 allows you to examine the overall state of the program, including
4667 switching between threads, without worrying that things may change
4670 Conversely, whenever you restart the program, _all_ threads start
4671 executing. _This is true even when single-stepping_ with commands like
4674 In particular, GDB cannot single-step all threads in lockstep.
4675 Since thread scheduling is up to your debugging target's operating
4676 system (not controlled by GDB), other threads may execute more than one
4677 statement while the current thread completes a single step. Moreover,
4678 in general other threads stop in the middle of a statement, rather than
4679 at a clean statement boundary, when the program stops.
4681 You might even find your program stopped in another thread after
4682 continuing or even single-stepping. This happens whenever some other
4683 thread runs into a breakpoint, a signal, or an exception before the
4684 first thread completes whatever you requested.
4686 Whenever GDB stops your program, due to a breakpoint or a signal, it
4687 automatically selects the thread where that breakpoint or signal
4688 happened. GDB alerts you to the context switch with a message such as
4689 `[Switching to Thread N]' to identify the thread.
4691 On some OSes, you can modify GDB's default behavior by locking the
4692 OS scheduler to allow only a single thread to run.
4694 `set scheduler-locking MODE'
4695 Set the scheduler locking mode. If it is `off', then there is no
4696 locking and any thread may run at any time. If `on', then only the
4697 current thread may run when the inferior is resumed. The `step'
4698 mode optimizes for single-stepping; it prevents other threads from
4699 preempting the current thread while you are stepping, so that the
4700 focus of debugging does not change unexpectedly. Other threads
4701 only rarely (or never) get a chance to run when you step. They
4702 are more likely to run when you `next' over a function call, and
4703 they are completely free to run when you use commands like
4704 `continue', `until', or `finish'. However, unless another thread
4705 hits a breakpoint during its timeslice, GDB does not change the
4706 current thread away from the thread that you are debugging.
4708 `show scheduler-locking'
4709 Display the current scheduler locking mode.
4711 By default, when you issue one of the execution commands such as
4712 `continue', `next' or `step', GDB allows only threads of the current
4713 inferior to run. For example, if GDB is attached to two inferiors,
4714 each with two threads, the `continue' command resumes only the two
4715 threads of the current inferior. This is useful, for example, when you
4716 debug a program that forks and you want to hold the parent stopped (so
4717 that, for instance, it doesn't run to exit), while you debug the child.
4718 In other situations, you may not be interested in inspecting the
4719 current state of any of the processes GDB is attached to, and you may
4720 want to resume them all until some breakpoint is hit. In the latter
4721 case, you can instruct GDB to allow all threads of all the inferiors to
4722 run with the `set schedule-multiple' command.
4724 `set schedule-multiple'
4725 Set the mode for allowing threads of multiple processes to be
4726 resumed when an execution command is issued. When `on', all
4727 threads of all processes are allowed to run. When `off', only the
4728 threads of the current process are resumed. The default is `off'.
4729 The `scheduler-locking' mode takes precedence when set to `on',
4730 or while you are stepping and set to `step'.
4732 `show schedule-multiple'
4733 Display the current mode for resuming the execution of threads of
4737 File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops
4742 For some multi-threaded targets, GDB supports an optional mode of
4743 operation in which you can examine stopped program threads in the
4744 debugger while other threads continue to execute freely. This
4745 minimizes intrusion when debugging live systems, such as programs where
4746 some threads have real-time constraints or must continue to respond to
4747 external events. This is referred to as "non-stop" mode.
4749 In non-stop mode, when a thread stops to report a debugging event,
4750 _only_ that thread is stopped; GDB does not stop other threads as well,
4751 in contrast to the all-stop mode behavior. Additionally, execution
4752 commands such as `continue' and `step' apply by default only to the
4753 current thread in non-stop mode, rather than all threads as in all-stop
4754 mode. This allows you to control threads explicitly in ways that are
4755 not possible in all-stop mode -- for example, stepping one thread while
4756 allowing others to run freely, stepping one thread while holding all
4757 others stopped, or stepping several threads independently and
4760 To enter non-stop mode, use this sequence of commands before you run
4761 or attach to your program:
4763 # Enable the async interface.
4766 # If using the CLI, pagination breaks non-stop.
4769 # Finally, turn it on!
4772 You can use these commands to manipulate the non-stop mode setting:
4775 Enable selection of non-stop mode.
4778 Disable selection of non-stop mode.
4781 Show the current non-stop enablement setting.
4783 Note these commands only reflect whether non-stop mode is enabled,
4784 not whether the currently-executing program is being run in non-stop
4785 mode. In particular, the `set non-stop' preference is only consulted
4786 when GDB starts or connects to the target program, and it is generally
4787 not possible to switch modes once debugging has started. Furthermore,
4788 since not all targets support non-stop mode, even when you have enabled
4789 non-stop mode, GDB may still fall back to all-stop operation by default.
4791 In non-stop mode, all execution commands apply only to the current
4792 thread by default. That is, `continue' only continues one thread. To
4793 continue all threads, issue `continue -a' or `c -a'.
4795 You can use GDB's background execution commands (*note Background
4796 Execution::) to run some threads in the background while you continue
4797 to examine or step others from GDB. The MI execution commands (*note
4798 GDB/MI Program Execution::) are always executed asynchronously in
4801 Suspending execution is done with the `interrupt' command when
4802 running in the background, or `Ctrl-c' during foreground execution. In
4803 all-stop mode, this stops the whole process; but in non-stop mode the
4804 interrupt applies only to the current thread. To stop the whole
4805 program, use `interrupt -a'.
4807 Other execution commands do not currently support the `-a' option.
4809 In non-stop mode, when a thread stops, GDB doesn't automatically make
4810 that thread current, as it does in all-stop mode. This is because the
4811 thread stop notifications are asynchronous with respect to GDB's
4812 command interpreter, and it would be confusing if GDB unexpectedly
4813 changed to a different thread just as you entered a command to operate
4814 on the previously current thread.
4817 File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops
4819 5.5.3 Background Execution
4820 --------------------------
4822 GDB's execution commands have two variants: the normal foreground
4823 (synchronous) behavior, and a background (asynchronous) behavior. In
4824 foreground execution, GDB waits for the program to report that some
4825 thread has stopped before prompting for another command. In background
4826 execution, GDB immediately gives a command prompt so that you can issue
4827 other commands while your program runs.
4829 You need to explicitly enable asynchronous mode before you can use
4830 background execution commands. You can use these commands to
4831 manipulate the asynchronous mode setting:
4833 `set target-async on'
4834 Enable asynchronous mode.
4836 `set target-async off'
4837 Disable asynchronous mode.
4840 Show the current target-async setting.
4842 If the target doesn't support async mode, GDB issues an error
4843 message if you attempt to use the background execution commands.
4845 To specify background execution, add a `&' to the command. For
4846 example, the background form of the `continue' command is `continue&',
4847 or just `c&'. The execution commands that accept background execution
4851 *Note Starting your Program: Starting.
4854 *Note Debugging an Already-running Process: Attach.
4857 *Note step: Continuing and Stepping.
4860 *Note stepi: Continuing and Stepping.
4863 *Note next: Continuing and Stepping.
4866 *Note nexti: Continuing and Stepping.
4869 *Note continue: Continuing and Stepping.
4872 *Note finish: Continuing and Stepping.
4875 *Note until: Continuing and Stepping.
4878 Background execution is especially useful in conjunction with
4879 non-stop mode for debugging programs with multiple threads; see *Note
4880 Non-Stop Mode::. However, you can also use these commands in the
4881 normal all-stop mode with the restriction that you cannot issue another
4882 execution command until the previous one finishes. Examples of
4883 commands that are valid in all-stop mode while the program is running
4884 include `help' and `info break'.
4886 You can interrupt your program while it is running in the background
4887 by using the `interrupt' command.
4891 Suspend execution of the running program. In all-stop mode,
4892 `interrupt' stops the whole process, but in non-stop mode, it stops
4893 only the current thread. To stop the whole program in non-stop
4894 mode, use `interrupt -a'.
4897 File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops
4899 5.5.4 Thread-Specific Breakpoints
4900 ---------------------------------
4902 When your program has multiple threads (*note Debugging Programs with
4903 Multiple Threads: Threads.), you can choose whether to set breakpoints
4904 on all threads, or on a particular thread.
4906 `break LINESPEC thread THREADNO'
4907 `break LINESPEC thread THREADNO if ...'
4908 LINESPEC specifies source lines; there are several ways of writing
4909 them (*note Specify Location::), but the effect is always to
4910 specify some source line.
4912 Use the qualifier `thread THREADNO' with a breakpoint command to
4913 specify that you only want GDB to stop the program when a
4914 particular thread reaches this breakpoint. THREADNO is one of the
4915 numeric thread identifiers assigned by GDB, shown in the first
4916 column of the `info threads' display.
4918 If you do not specify `thread THREADNO' when you set a breakpoint,
4919 the breakpoint applies to _all_ threads of your program.
4921 You can use the `thread' qualifier on conditional breakpoints as
4922 well; in this case, place `thread THREADNO' before or after the
4923 breakpoint condition, like this:
4925 (gdb) break frik.c:13 thread 28 if bartab > lim
4929 File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops
4931 5.5.5 Interrupted System Calls
4932 ------------------------------
4934 There is an unfortunate side effect when using GDB to debug
4935 multi-threaded programs. If one thread stops for a breakpoint, or for
4936 some other reason, and another thread is blocked in a system call, then
4937 the system call may return prematurely. This is a consequence of the
4938 interaction between multiple threads and the signals that GDB uses to
4939 implement breakpoints and other events that stop execution.
4941 To handle this problem, your program should check the return value of
4942 each system call and react appropriately. This is good programming
4945 For example, do not write code like this:
4949 The call to `sleep' will return early if a different thread stops at
4950 a breakpoint or for some other reason.
4952 Instead, write this:
4956 unslept = sleep (unslept);
4958 A system call is allowed to return early, so the system is still
4959 conforming to its specification. But GDB does cause your
4960 multi-threaded program to behave differently than it would without GDB.
4962 Also, GDB uses internal breakpoints in the thread library to monitor
4963 certain events such as thread creation and thread destruction. When
4964 such an event happens, a system call in another thread may return
4965 prematurely, even though your program does not appear to stop.
4968 File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops
4973 If you want to build on non-stop mode and observe program behavior
4974 without any chance of disruption by GDB, you can set variables to
4975 disable all of the debugger's attempts to modify state, whether by
4976 writing memory, inserting breakpoints, etc. These operate at a low
4977 level, intercepting operations from all commands.
4979 When all of these are set to `off', then GDB is said to be "observer
4980 mode". As a convenience, the variable `observer' can be set to disable
4981 these, plus enable non-stop mode.
4983 Note that GDB will not prevent you from making nonsensical
4984 combinations of these settings. For instance, if you have enabled
4985 `may-insert-breakpoints' but disabled `may-write-memory', then
4986 breakpoints that work by writing trap instructions into the code stream
4987 will still not be able to be placed.
4991 When set to `on', this disables all the permission variables below
4992 (except for `insert-fast-tracepoints'), plus enables non-stop
4993 debugging. Setting this to `off' switches back to normal
4994 debugging, though remaining in non-stop mode.
4997 Show whether observer mode is on or off.
4999 `set may-write-registers on'
5000 `set may-write-registers off'
5001 This controls whether GDB will attempt to alter the values of
5002 registers, such as with assignment expressions in `print', or the
5003 `jump' command. It defaults to `on'.
5005 `show may-write-registers'
5006 Show the current permission to write registers.
5008 `set may-write-memory on'
5009 `set may-write-memory off'
5010 This controls whether GDB will attempt to alter the contents of
5011 memory, such as with assignment expressions in `print'. It
5014 `show may-write-memory'
5015 Show the current permission to write memory.
5017 `set may-insert-breakpoints on'
5018 `set may-insert-breakpoints off'
5019 This controls whether GDB will attempt to insert breakpoints.
5020 This affects all breakpoints, including internal breakpoints
5021 defined by GDB. It defaults to `on'.
5023 `show may-insert-breakpoints'
5024 Show the current permission to insert breakpoints.
5026 `set may-insert-tracepoints on'
5027 `set may-insert-tracepoints off'
5028 This controls whether GDB will attempt to insert (regular)
5029 tracepoints at the beginning of a tracing experiment. It affects
5030 only non-fast tracepoints, fast tracepoints being under the
5031 control of `may-insert-fast-tracepoints'. It defaults to `on'.
5033 `show may-insert-tracepoints'
5034 Show the current permission to insert tracepoints.
5036 `set may-insert-fast-tracepoints on'
5037 `set may-insert-fast-tracepoints off'
5038 This controls whether GDB will attempt to insert fast tracepoints
5039 at the beginning of a tracing experiment. It affects only fast
5040 tracepoints, regular (non-fast) tracepoints being under the
5041 control of `may-insert-tracepoints'. It defaults to `on'.
5043 `show may-insert-fast-tracepoints'
5044 Show the current permission to insert fast tracepoints.
5046 `set may-interrupt on'
5047 `set may-interrupt off'
5048 This controls whether GDB will attempt to interrupt or stop
5049 program execution. When this variable is `off', the `interrupt'
5050 command will have no effect, nor will `Ctrl-c'. It defaults to
5053 `show may-interrupt'
5054 Show the current permission to interrupt or stop the program.
5058 File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top
5060 6 Running programs backward
5061 ***************************
5063 When you are debugging a program, it is not unusual to realize that you
5064 have gone too far, and some event of interest has already happened. If
5065 the target environment supports it, GDB can allow you to "rewind" the
5066 program by running it backward.
5068 A target environment that supports reverse execution should be able
5069 to "undo" the changes in machine state that have taken place as the
5070 program was executing normally. Variables, registers etc. should
5071 revert to their previous values. Obviously this requires a great deal
5072 of sophistication on the part of the target environment; not all target
5073 environments can support reverse execution.
5075 When a program is executed in reverse, the instructions that have
5076 most recently been executed are "un-executed", in reverse order. The
5077 program counter runs backward, following the previous thread of
5078 execution in reverse. As each instruction is "un-executed", the values
5079 of memory and/or registers that were changed by that instruction are
5080 reverted to their previous states. After executing a piece of source
5081 code in reverse, all side effects of that code should be "undone", and
5082 all variables should be returned to their prior values(1).
5084 If you are debugging in a target environment that supports reverse
5085 execution, GDB provides the following commands.
5087 `reverse-continue [IGNORE-COUNT]'
5089 Beginning at the point where your program last stopped, start
5090 executing in reverse. Reverse execution will stop for breakpoints
5091 and synchronous exceptions (signals), just like normal execution.
5092 Behavior of asynchronous signals depends on the target environment.
5094 `reverse-step [COUNT]'
5095 Run the program backward until control reaches the start of a
5096 different source line; then stop it, and return control to GDB.
5098 Like the `step' command, `reverse-step' will only stop at the
5099 beginning of a source line. It "un-executes" the previously
5100 executed source line. If the previous source line included calls
5101 to debuggable functions, `reverse-step' will step (backward) into
5102 the called function, stopping at the beginning of the _last_
5103 statement in the called function (typically a return statement).
5105 Also, as with the `step' command, if non-debuggable functions are
5106 called, `reverse-step' will run thru them backward without
5109 `reverse-stepi [COUNT]'
5110 Reverse-execute one machine instruction. Note that the instruction
5111 to be reverse-executed is _not_ the one pointed to by the program
5112 counter, but the instruction executed prior to that one. For
5113 instance, if the last instruction was a jump, `reverse-stepi' will
5114 take you back from the destination of the jump to the jump
5117 `reverse-next [COUNT]'
5118 Run backward to the beginning of the previous line executed in the
5119 current (innermost) stack frame. If the line contains function
5120 calls, they will be "un-executed" without stopping. Starting from
5121 the first line of a function, `reverse-next' will take you back to
5122 the caller of that function, _before_ the function was called,
5123 just as the normal `next' command would take you from the last
5124 line of a function back to its return to its caller (2).
5126 `reverse-nexti [COUNT]'
5127 Like `nexti', `reverse-nexti' executes a single instruction in
5128 reverse, except that called functions are "un-executed" atomically.
5129 That is, if the previously executed instruction was a return from
5130 another function, `reverse-nexti' will continue to execute in
5131 reverse until the call to that function (from the current stack
5135 Just as the `finish' command takes you to the point where the
5136 current function returns, `reverse-finish' takes you to the point
5137 where it was called. Instead of ending up at the end of the
5138 current function invocation, you end up at the beginning.
5140 `set exec-direction'
5141 Set the direction of target execution.
5143 `set exec-direction reverse'
5144 GDB will perform all execution commands in reverse, until the
5145 exec-direction mode is changed to "forward". Affected commands
5146 include `step, stepi, next, nexti, continue, and finish'. The
5147 `return' command cannot be used in reverse mode.
5149 `set exec-direction forward'
5150 GDB will perform all execution commands in the normal fashion.
5151 This is the default.
5153 ---------- Footnotes ----------
5155 (1) Note that some side effects are easier to undo than others. For
5156 instance, memory and registers are relatively easy, but device I/O is
5157 hard. Some targets may be able undo things like device I/O, and some
5160 The contract between GDB and the reverse executing target requires
5161 only that the target do something reasonable when GDB tells it to
5162 execute backwards, and then report the results back to GDB. Whatever
5163 the target reports back to GDB, GDB will report back to the user. GDB
5164 assumes that the memory and registers that the target reports are in a
5165 consistant state, but GDB accepts whatever it is given.
5167 (2) Unless the code is too heavily optimized.
5170 File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top
5172 7 Recording Inferior's Execution and Replaying It
5173 *************************************************
5175 On some platforms, GDB provides a special "process record and replay"
5176 target that can record a log of the process execution, and replay it
5177 later with both forward and reverse execution commands.
5179 When this target is in use, if the execution log includes the record
5180 for the next instruction, GDB will debug in "replay mode". In the
5181 replay mode, the inferior does not really execute code instructions.
5182 Instead, all the events that normally happen during code execution are
5183 taken from the execution log. While code is not really executed in
5184 replay mode, the values of registers (including the program counter
5185 register) and the memory of the inferior are still changed as they
5186 normally would. Their contents are taken from the execution log.
5188 If the record for the next instruction is not in the execution log,
5189 GDB will debug in "record mode". In this mode, the inferior executes
5190 normally, and GDB records the execution log for future replay.
5192 The process record and replay target supports reverse execution
5193 (*note Reverse Execution::), even if the platform on which the inferior
5194 runs does not. However, the reverse execution is limited in this case
5195 by the range of the instructions recorded in the execution log. In
5196 other words, reverse execution on platforms that don't support it
5197 directly can only be done in the replay mode.
5199 When debugging in the reverse direction, GDB will work in replay
5200 mode as long as the execution log includes the record for the previous
5201 instruction; otherwise, it will work in record mode, if the platform
5202 supports reverse execution, or stop if not.
5204 For architecture environments that support process record and replay,
5205 GDB provides the following commands:
5208 This command starts the process record and replay target. The
5209 process record and replay target can only debug a process that is
5210 already running. Therefore, you need first to start the process
5211 with the `run' or `start' commands, and then start the recording
5212 with the `target record' command.
5214 Both `record' and `rec' are aliases of `target record'.
5216 Displaced stepping (*note displaced stepping: Maintenance
5217 Commands.) will be automatically disabled when process record and
5218 replay target is started. That's because the process record and
5219 replay target doesn't support displaced stepping.
5221 If the inferior is in the non-stop mode (*note Non-Stop Mode::) or
5222 in the asynchronous execution mode (*note Background Execution::),
5223 the process record and replay target cannot be started because it
5224 doesn't support these two modes.
5227 Stop the process record and replay target. When process record and
5228 replay target stops, the entire execution log will be deleted and
5229 the inferior will either be terminated, or will remain in its
5232 When you stop the process record and replay target in record mode
5233 (at the end of the execution log), the inferior will be stopped at
5234 the next instruction that would have been recorded. In other
5235 words, if you record for a while and then stop recording, the
5236 inferior process will be left in the same state as if the
5237 recording never happened.
5239 On the other hand, if the process record and replay target is
5240 stopped while in replay mode (that is, not at the end of the
5241 execution log, but at some earlier point), the inferior process
5242 will become "live" at that earlier state, and it will then be
5243 possible to continue the usual "live" debugging of the process
5246 When the inferior process exits, or GDB detaches from it, process
5247 record and replay target will automatically stop itself.
5249 `record save FILENAME'
5250 Save the execution log to a file `FILENAME'. Default filename is
5251 `gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the
5254 `record restore FILENAME'
5255 Restore the execution log from a file `FILENAME'. File must have
5256 been created with `record save'.
5258 `set record insn-number-max LIMIT'
5259 Set the limit of instructions to be recorded. Default value is
5262 If LIMIT is a positive number, then GDB will start deleting
5263 instructions from the log once the number of the record
5264 instructions becomes greater than LIMIT. For every new recorded
5265 instruction, GDB will delete the earliest recorded instruction to
5266 keep the number of recorded instructions at the limit. (Since
5267 deleting recorded instructions loses information, GDB lets you
5268 control what happens when the limit is reached, by means of the
5269 `stop-at-limit' option, described below.)
5271 If LIMIT is zero, GDB will never delete recorded instructions from
5272 the execution log. The number of recorded instructions is
5273 unlimited in this case.
5275 `show record insn-number-max'
5276 Show the limit of instructions to be recorded.
5278 `set record stop-at-limit'
5279 Control the behavior when the number of recorded instructions
5280 reaches the limit. If ON (the default), GDB will stop when the
5281 limit is reached for the first time and ask you whether you want
5282 to stop the inferior or continue running it and recording the
5283 execution log. If you decide to continue recording, each new
5284 recorded instruction will cause the oldest one to be deleted.
5286 If this option is OFF, GDB will automatically delete the oldest
5287 record to make room for each new one, without asking.
5289 `show record stop-at-limit'
5290 Show the current setting of `stop-at-limit'.
5292 `set record memory-query'
5293 Control the behavior when GDB is unable to record memory changes
5294 caused by an instruction. If ON, GDB will query whether to stop
5295 the inferior in that case.
5297 If this option is OFF (the default), GDB will automatically ignore
5298 the effect of such instructions on memory. Later, when GDB
5299 replays this execution log, it will mark the log of this
5300 instruction as not accessible, and it will not affect the replay
5303 `show record memory-query'
5304 Show the current setting of `memory-query'.
5307 Show various statistics about the state of process record and its
5308 in-memory execution log buffer, including:
5310 * Whether in record mode or replay mode.
5312 * Lowest recorded instruction number (counting from when the
5313 current execution log started recording instructions).
5315 * Highest recorded instruction number.
5317 * Current instruction about to be replayed (if in replay mode).
5319 * Number of instructions contained in the execution log.
5321 * Maximum number of instructions that may be contained in the
5325 When record target runs in replay mode ("in the past"), delete the
5326 subsequent execution log and begin to record a new execution log
5327 starting from the current address. This means you will abandon
5328 the previously recorded "future" and begin recording a new
5332 File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top
5334 8 Examining the Stack
5335 *********************
5337 When your program has stopped, the first thing you need to know is
5338 where it stopped and how it got there.
5340 Each time your program performs a function call, information about
5341 the call is generated. That information includes the location of the
5342 call in your program, the arguments of the call, and the local
5343 variables of the function being called. The information is saved in a
5344 block of data called a "stack frame". The stack frames are allocated
5345 in a region of memory called the "call stack".
5347 When your program stops, the GDB commands for examining the stack
5348 allow you to see all of this information.
5350 One of the stack frames is "selected" by GDB and many GDB commands
5351 refer implicitly to the selected frame. In particular, whenever you
5352 ask GDB for the value of a variable in your program, the value is found
5353 in the selected frame. There are special GDB commands to select
5354 whichever frame you are interested in. *Note Selecting a Frame:
5357 When your program stops, GDB automatically selects the currently
5358 executing frame and describes it briefly, similar to the `frame'
5359 command (*note Information about a Frame: Frame Info.).
5363 * Frames:: Stack frames
5364 * Backtrace:: Backtraces
5365 * Selection:: Selecting a frame
5366 * Frame Info:: Information on a frame
5369 File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack
5374 The call stack is divided up into contiguous pieces called "stack
5375 frames", or "frames" for short; each frame is the data associated with
5376 one call to one function. The frame contains the arguments given to
5377 the function, the function's local variables, and the address at which
5378 the function is executing.
5380 When your program is started, the stack has only one frame, that of
5381 the function `main'. This is called the "initial" frame or the
5382 "outermost" frame. Each time a function is called, a new frame is
5383 made. Each time a function returns, the frame for that function
5384 invocation is eliminated. If a function is recursive, there can be
5385 many frames for the same function. The frame for the function in which
5386 execution is actually occurring is called the "innermost" frame. This
5387 is the most recently created of all the stack frames that still exist.
5389 Inside your program, stack frames are identified by their addresses.
5390 A stack frame consists of many bytes, each of which has its own
5391 address; each kind of computer has a convention for choosing one byte
5392 whose address serves as the address of the frame. Usually this address
5393 is kept in a register called the "frame pointer register" (*note $fp:
5394 Registers.) while execution is going on in that frame.
5396 GDB assigns numbers to all existing stack frames, starting with zero
5397 for the innermost frame, one for the frame that called it, and so on
5398 upward. These numbers do not really exist in your program; they are
5399 assigned by GDB to give you a way of designating stack frames in GDB
5402 Some compilers provide a way to compile functions so that they
5403 operate without stack frames. (For example, the GCC option
5404 `-fomit-frame-pointer'
5405 generates functions without a frame.) This is occasionally done
5406 with heavily used library functions to save the frame setup time. GDB
5407 has limited facilities for dealing with these function invocations. If
5408 the innermost function invocation has no stack frame, GDB nevertheless
5409 regards it as though it had a separate frame, which is numbered zero as
5410 usual, allowing correct tracing of the function call chain. However,
5411 GDB has no provision for frameless functions elsewhere in the stack.
5414 The `frame' command allows you to move from one stack frame to
5415 another, and to print the stack frame you select. ARGS may be
5416 either the address of the frame or the stack frame number.
5417 Without an argument, `frame' prints the current stack frame.
5420 The `select-frame' command allows you to move from one stack frame
5421 to another without printing the frame. This is the silent version
5425 File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack
5430 A backtrace is a summary of how your program got where it is. It shows
5431 one line per frame, for many frames, starting with the currently
5432 executing frame (frame zero), followed by its caller (frame one), and
5437 Print a backtrace of the entire stack: one line per frame for all
5438 frames in the stack.
5440 You can stop the backtrace at any time by typing the system
5441 interrupt character, normally `Ctrl-c'.
5445 Similar, but print only the innermost N frames.
5449 Similar, but print only the outermost N frames.
5455 Print the values of the local variables also. N specifies the
5456 number of frames to print, as described above.
5458 The names `where' and `info stack' (abbreviated `info s') are
5459 additional aliases for `backtrace'.
5461 In a multi-threaded program, GDB by default shows the backtrace only
5462 for the current thread. To display the backtrace for several or all of
5463 the threads, use the command `thread apply' (*note thread apply:
5464 Threads.). For example, if you type `thread apply all backtrace', GDB
5465 will display the backtrace for all the threads; this is handy when you
5466 debug a core dump of a multi-threaded program.
5468 Each line in the backtrace shows the frame number and the function
5469 name. The program counter value is also shown--unless you use `set
5470 print address off'. The backtrace also shows the source file name and
5471 line number, as well as the arguments to the function. The program
5472 counter value is omitted if it is at the beginning of the code for that
5475 Here is an example of a backtrace. It was made with the command `bt
5476 3', so it shows the innermost three frames.
5478 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
5480 #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
5481 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
5483 (More stack frames follow...)
5485 The display for frame zero does not begin with a program counter value,
5486 indicating that your program has stopped at the beginning of the code
5487 for line `993' of `builtin.c'.
5489 The value of parameter `data' in frame 1 has been replaced by `...'.
5490 By default, GDB prints the value of a parameter only if it is a scalar
5491 (integer, pointer, enumeration, etc). See command `set print
5492 frame-arguments' in *Note Print Settings:: for more details on how to
5493 configure the way function parameter values are printed.
5495 If your program was compiled with optimizations, some compilers will
5496 optimize away arguments passed to functions if those arguments are
5497 never used after the call. Such optimizations generate code that
5498 passes arguments through registers, but doesn't store those arguments
5499 in the stack frame. GDB has no way of displaying such arguments in
5500 stack frames other than the innermost one. Here's what such a
5501 backtrace might look like:
5503 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
5505 #1 0x6e38 in expand_macro (sym=<optimized out>) at macro.c:242
5506 #2 0x6840 in expand_token (obs=0x0, t=<optimized out>, td=0xf7fffb08)
5508 (More stack frames follow...)
5510 The values of arguments that were not saved in their stack frames are
5511 shown as `<optimized out>'.
5513 If you need to display the values of such optimized-out arguments,
5514 either deduce that from other variables whose values depend on the one
5515 you are interested in, or recompile without optimizations.
5517 Most programs have a standard user entry point--a place where system
5518 libraries and startup code transition into user code. For C this is
5519 `main'(1). When GDB finds the entry function in a backtrace it will
5520 terminate the backtrace, to avoid tracing into highly system-specific
5521 (and generally uninteresting) code.
5523 If you need to examine the startup code, or limit the number of
5524 levels in a backtrace, you can change this behavior:
5526 `set backtrace past-main'
5527 `set backtrace past-main on'
5528 Backtraces will continue past the user entry point.
5530 `set backtrace past-main off'
5531 Backtraces will stop when they encounter the user entry point.
5532 This is the default.
5534 `show backtrace past-main'
5535 Display the current user entry point backtrace policy.
5537 `set backtrace past-entry'
5538 `set backtrace past-entry on'
5539 Backtraces will continue past the internal entry point of an
5540 application. This entry point is encoded by the linker when the
5541 application is built, and is likely before the user entry point
5542 `main' (or equivalent) is called.
5544 `set backtrace past-entry off'
5545 Backtraces will stop when they encounter the internal entry point
5546 of an application. This is the default.
5548 `show backtrace past-entry'
5549 Display the current internal entry point backtrace policy.
5551 `set backtrace limit N'
5552 `set backtrace limit 0'
5553 Limit the backtrace to N levels. A value of zero means unlimited.
5555 `show backtrace limit'
5556 Display the current limit on backtrace levels.
5558 ---------- Footnotes ----------
5560 (1) Note that embedded programs (the so-called "free-standing"
5561 environment) are not required to have a `main' function as the entry
5562 point. They could even have multiple entry points.
5565 File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack
5567 8.3 Selecting a Frame
5568 =====================
5570 Most commands for examining the stack and other data in your program
5571 work on whichever stack frame is selected at the moment. Here are the
5572 commands for selecting a stack frame; all of them finish by printing a
5573 brief description of the stack frame just selected.
5577 Select frame number N. Recall that frame zero is the innermost
5578 (currently executing) frame, frame one is the frame that called the
5579 innermost one, and so on. The highest-numbered frame is the one
5584 Select the frame at address ADDR. This is useful mainly if the
5585 chaining of stack frames has been damaged by a bug, making it
5586 impossible for GDB to assign numbers properly to all frames. In
5587 addition, this can be useful when your program has multiple stacks
5588 and switches between them.
5590 On the SPARC architecture, `frame' needs two addresses to select
5591 an arbitrary frame: a frame pointer and a stack pointer.
5593 On the MIPS and Alpha architecture, it needs two addresses: a stack
5594 pointer and a program counter.
5596 On the 29k architecture, it needs three addresses: a register stack
5597 pointer, a program counter, and a memory stack pointer.
5600 Move N frames up the stack. For positive numbers N, this advances
5601 toward the outermost frame, to higher frame numbers, to frames
5602 that have existed longer. N defaults to one.
5605 Move N frames down the stack. For positive numbers N, this
5606 advances toward the innermost frame, to lower frame numbers, to
5607 frames that were created more recently. N defaults to one. You
5608 may abbreviate `down' as `do'.
5610 All of these commands end by printing two lines of output describing
5611 the frame. The first line shows the frame number, the function name,
5612 the arguments, and the source file and line number of execution in that
5613 frame. The second line shows the text of that source line.
5618 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
5620 10 read_input_file (argv[i]);
5622 After such a printout, the `list' command with no arguments prints
5623 ten lines centered on the point of execution in the frame. You can
5624 also edit the program at the point of execution with your favorite
5625 editing program by typing `edit'. *Note Printing Source Lines: List,
5630 These two commands are variants of `up' and `down', respectively;
5631 they differ in that they do their work silently, without causing
5632 display of the new frame. They are intended primarily for use in
5633 GDB command scripts, where the output might be unnecessary and
5637 File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack
5639 8.4 Information About a Frame
5640 =============================
5642 There are several other commands to print information about the selected
5647 When used without any argument, this command does not change which
5648 frame is selected, but prints a brief description of the currently
5649 selected stack frame. It can be abbreviated `f'. With an
5650 argument, this command is used to select a stack frame. *Note
5651 Selecting a Frame: Selection.
5655 This command prints a verbose description of the selected stack
5658 * the address of the frame
5660 * the address of the next frame down (called by this frame)
5662 * the address of the next frame up (caller of this frame)
5664 * the language in which the source code corresponding to this
5667 * the address of the frame's arguments
5669 * the address of the frame's local variables
5671 * the program counter saved in it (the address of execution in
5674 * which registers were saved in the frame
5676 The verbose description is useful when something has gone wrong
5677 that has made the stack format fail to fit the usual conventions.
5681 Print a verbose description of the frame at address ADDR, without
5682 selecting that frame. The selected frame remains unchanged by this
5683 command. This requires the same kind of address (more than one
5684 for some architectures) that you specify in the `frame' command.
5685 *Note Selecting a Frame: Selection.
5688 Print the arguments of the selected frame, each on a separate line.
5691 Print the local variables of the selected frame, each on a separate
5692 line. These are all variables (declared either static or
5693 automatic) accessible at the point of execution of the selected
5698 File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top
5700 9 Examining Source Files
5701 ************************
5703 GDB can print parts of your program's source, since the debugging
5704 information recorded in the program tells GDB what source files were
5705 used to build it. When your program stops, GDB spontaneously prints
5706 the line where it stopped. Likewise, when you select a stack frame
5707 (*note Selecting a Frame: Selection.), GDB prints the line where
5708 execution in that frame has stopped. You can print other portions of
5709 source files by explicit command.
5711 If you use GDB through its GNU Emacs interface, you may prefer to
5712 use Emacs facilities to view source; see *Note Using GDB under GNU
5717 * List:: Printing source lines
5718 * Specify Location:: How to specify code locations
5719 * Edit:: Editing source files
5720 * Search:: Searching source files
5721 * Source Path:: Specifying source directories
5722 * Machine Code:: Source and machine code
5725 File: gdb.info, Node: List, Next: Specify Location, Up: Source
5727 9.1 Printing Source Lines
5728 =========================
5730 To print lines from a source file, use the `list' command (abbreviated
5731 `l'). By default, ten lines are printed. There are several ways to
5732 specify what part of the file you want to print; see *Note Specify
5733 Location::, for the full list.
5735 Here are the forms of the `list' command most commonly used:
5738 Print lines centered around line number LINENUM in the current
5742 Print lines centered around the beginning of function FUNCTION.
5745 Print more lines. If the last lines printed were printed with a
5746 `list' command, this prints lines following the last lines
5747 printed; however, if the last line printed was a solitary line
5748 printed as part of displaying a stack frame (*note Examining the
5749 Stack: Stack.), this prints lines centered around that line.
5752 Print lines just before the lines last printed.
5754 By default, GDB prints ten source lines with any of these forms of
5755 the `list' command. You can change this using `set listsize':
5757 `set listsize COUNT'
5758 Make the `list' command display COUNT source lines (unless the
5759 `list' argument explicitly specifies some other number).
5762 Display the number of lines that `list' prints.
5764 Repeating a `list' command with <RET> discards the argument, so it
5765 is equivalent to typing just `list'. This is more useful than listing
5766 the same lines again. An exception is made for an argument of `-';
5767 that argument is preserved in repetition so that each repetition moves
5768 up in the source file.
5770 In general, the `list' command expects you to supply zero, one or two
5771 "linespecs". Linespecs specify source lines; there are several ways of
5772 writing them (*note Specify Location::), but the effect is always to
5773 specify some source line.
5775 Here is a complete description of the possible arguments for `list':
5778 Print lines centered around the line specified by LINESPEC.
5781 Print lines from FIRST to LAST. Both arguments are linespecs.
5782 When a `list' command has two linespecs, and the source file of
5783 the second linespec is omitted, this refers to the same source
5784 file as the first linespec.
5787 Print lines ending with LAST.
5790 Print lines starting with FIRST.
5793 Print lines just after the lines last printed.
5796 Print lines just before the lines last printed.
5799 As described in the preceding table.
5802 File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source
5804 9.2 Specifying a Location
5805 =========================
5807 Several GDB commands accept arguments that specify a location of your
5808 program's code. Since GDB is a source-level debugger, a location
5809 usually specifies some line in the source code; for that reason,
5810 locations are also known as "linespecs".
5812 Here are all the different ways of specifying a code location that
5816 Specifies the line number LINENUM of the current source file.
5820 Specifies the line OFFSET lines before or after the "current
5821 line". For the `list' command, the current line is the last one
5822 printed; for the breakpoint commands, this is the line at which
5823 execution stopped in the currently selected "stack frame" (*note
5824 Frames: Frames, for a description of stack frames.) When used as
5825 the second of the two linespecs in a `list' command, this
5826 specifies the line OFFSET lines up or down from the first linespec.
5829 Specifies the line LINENUM in the source file FILENAME. If
5830 FILENAME is a relative file name, then it will match any source
5831 file name with the same trailing components. For example, if
5832 FILENAME is `gcc/expr.c', then it will match source file name of
5833 `/build/trunk/gcc/expr.c', but not `/build/trunk/libcpp/expr.c' or
5834 `/build/trunk/gcc/x-expr.c'.
5837 Specifies the line that begins the body of the function FUNCTION.
5838 For example, in C, this is the line with the open brace.
5841 Specifies the line where LABEL appears in FUNCTION.
5844 Specifies the line that begins the body of the function FUNCTION
5845 in the file FILENAME. You only need the file name with a function
5846 name to avoid ambiguity when there are identically named functions
5847 in different source files.
5850 Specifies the line at which the label named LABEL appears. GDB
5851 searches for the label in the function corresponding to the
5852 currently selected stack frame. If there is no current selected
5853 stack frame (for instance, if the inferior is not running), then
5854 GDB will not search for a label.
5857 Specifies the program address ADDRESS. For line-oriented
5858 commands, such as `list' and `edit', this specifies a source line
5859 that contains ADDRESS. For `break' and other breakpoint oriented
5860 commands, this can be used to set breakpoints in parts of your
5861 program which do not have debugging information or source files.
5863 Here ADDRESS may be any expression valid in the current working
5864 language (*note working language: Languages.) that specifies a code
5865 address. In addition, as a convenience, GDB extends the semantics
5866 of expressions used in locations to cover the situations that
5867 frequently happen during debugging. Here are the various forms of
5871 Any expression valid in the current working language.
5874 An address of a function or procedure derived from its name.
5875 In C, C++, Java, Objective-C, Fortran, minimal, and assembly,
5876 this is simply the function's name FUNCTION (and actually a
5877 special case of a valid expression). In Pascal and Modula-2,
5878 this is `&FUNCTION'. In Ada, this is `FUNCTION'Address'
5879 (although the Pascal form also works).
5881 This form specifies the address of the function's first
5882 instruction, before the stack frame and arguments have been
5885 `'FILENAME'::FUNCADDR'
5886 Like FUNCADDR above, but also specifies the name of the source
5887 file explicitly. This is useful if the name of the function
5888 does not specify the function unambiguously, e.g., if there
5889 are several functions with identical names in different
5892 `-pstap|-probe-stap [OBJFILE:[PROVIDER:]]NAME'
5893 The GNU/Linux tool `SystemTap' provides a way for applications to
5894 embed static probes. *Note Static Probe Points::, for more
5895 information on finding and using static probes. This form of
5896 linespec specifies the location of such a static probe.
5898 If OBJFILE is given, only probes coming from that shared library
5899 or executable matching OBJFILE as a regular expression are
5900 considered. If PROVIDER is given, then only probes from that
5901 provider are considered. If several probes match the spec, GDB
5902 will insert a breakpoint at each one of those probes.
5906 File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source
5908 9.3 Editing Source Files
5909 ========================
5911 To edit the lines in a source file, use the `edit' command. The
5912 editing program of your choice is invoked with the current line set to
5913 the active line in the program. Alternatively, there are several ways
5914 to specify what part of the file you want to print if you want to see
5915 other parts of the program:
5918 Edit the source file specified by `location'. Editing starts at
5919 that LOCATION, e.g., at the specified source line of the specified
5920 file. *Note Specify Location::, for all the possible forms of the
5921 LOCATION argument; here are the forms of the `edit' command most
5925 Edit the current source file with NUMBER as the active line
5929 Edit the file containing FUNCTION at the beginning of its
5933 9.3.1 Choosing your Editor
5934 --------------------------
5936 You can customize GDB to use any editor you want (1). By default, it
5937 is `/bin/ex', but you can change this by setting the environment
5938 variable `EDITOR' before using GDB. For example, to configure GDB to
5939 use the `vi' editor, you could use these commands with the `sh' shell:
5943 or in the `csh' shell,
5944 setenv EDITOR /usr/bin/vi
5947 ---------- Footnotes ----------
5949 (1) The only restriction is that your editor (say `ex'), recognizes
5950 the following command-line syntax:
5952 The optional numeric value +NUMBER specifies the number of the line
5953 in the file where to start editing.
5956 File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source
5958 9.4 Searching Source Files
5959 ==========================
5961 There are two commands for searching through the current source file
5962 for a regular expression.
5964 `forward-search REGEXP'
5966 The command `forward-search REGEXP' checks each line, starting
5967 with the one following the last line listed, for a match for
5968 REGEXP. It lists the line that is found. You can use the synonym
5969 `search REGEXP' or abbreviate the command name as `fo'.
5971 `reverse-search REGEXP'
5972 The command `reverse-search REGEXP' checks each line, starting
5973 with the one before the last line listed and going backward, for a
5974 match for REGEXP. It lists the line that is found. You can
5975 abbreviate this command as `rev'.
5978 File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source
5980 9.5 Specifying Source Directories
5981 =================================
5983 Executable programs sometimes do not record the directories of the
5984 source files from which they were compiled, just the names. Even when
5985 they do, the directories could be moved between the compilation and
5986 your debugging session. GDB has a list of directories to search for
5987 source files; this is called the "source path". Each time GDB wants a
5988 source file, it tries all the directories in the list, in the order
5989 they are present in the list, until it finds a file with the desired
5992 For example, suppose an executable references the file
5993 `/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The
5994 file is first looked up literally; if this fails,
5995 `/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails,
5996 `/mnt/cross/foo.c' is opened; if this fails, an error message is
5997 printed. GDB does not look up the parts of the source file name, such
5998 as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of
5999 the source path are not searched: if the source path is `/mnt/cross',
6000 and the binary refers to `foo.c', GDB would not find it under
6001 `/mnt/cross/usr/src/foo-1.0/lib'.
6003 Plain file names, relative file names with leading directories, file
6004 names containing dots, etc. are all treated as described above; for
6005 instance, if the source path is `/mnt/cross', and the source file is
6006 recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then
6007 `/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'.
6009 Note that the executable search path is _not_ used to locate the
6012 Whenever you reset or rearrange the source path, GDB clears out any
6013 information it has cached about where source files are found and where
6014 each line is in the file.
6016 When you start GDB, its source path includes only `cdir' and `cwd',
6017 in that order. To add other directories, use the `directory' command.
6019 The search path is used to find both program source files and GDB
6020 script files (read using the `-command' option and `source' command).
6022 In addition to the source path, GDB provides a set of commands that
6023 manage a list of source path substitution rules. A "substitution rule"
6024 specifies how to rewrite source directories stored in the program's
6025 debug information in case the sources were moved to a different
6026 directory between compilation and debugging. A rule is made of two
6027 strings, the first specifying what needs to be rewritten in the path,
6028 and the second specifying how it should be rewritten. In *Note set
6029 substitute-path::, we name these two parts FROM and TO respectively.
6030 GDB does a simple string replacement of FROM with TO at the start of
6031 the directory part of the source file name, and uses that result
6032 instead of the original file name to look up the sources.
6034 Using the previous example, suppose the `foo-1.0' tree has been
6035 moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace
6036 `/usr/src' in all source path names with `/mnt/cross'. The first
6037 lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the
6038 original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source
6039 path substitution rule, use the `set substitute-path' command (*note
6040 set substitute-path::).
6042 To avoid unexpected substitution results, a rule is applied only if
6043 the FROM part of the directory name ends at a directory separator. For
6044 instance, a rule substituting `/usr/source' into `/mnt/cross' will be
6045 applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'.
6046 And because the substitution is applied only at the beginning of the
6047 directory name, this rule will not be applied to
6048 `/root/usr/source/baz.c' either.
6050 In many cases, you can achieve the same result using the `directory'
6051 command. However, `set substitute-path' can be more efficient in the
6052 case where the sources are organized in a complex tree with multiple
6053 subdirectories. With the `directory' command, you need to add each
6054 subdirectory of your project. If you moved the entire tree while
6055 preserving its internal organization, then `set substitute-path' allows
6056 you to direct the debugger to all the sources with one single command.
6058 `set substitute-path' is also more than just a shortcut command.
6059 The source path is only used if the file at the original location no
6060 longer exists. On the other hand, `set substitute-path' modifies the
6061 debugger behavior to look at the rewritten location instead. So, if
6062 for any reason a source file that is not relevant to your executable is
6063 located at the original location, a substitution rule is the only
6064 method available to point GDB at the new location.
6066 You can configure a default source path substitution rule by
6067 configuring GDB with the `--with-relocated-sources=DIR' option. The DIR
6068 should be the name of a directory under GDB's configured prefix (set
6069 with `--prefix' or `--exec-prefix'), and directory names in debug
6070 information under DIR will be adjusted automatically if the installed
6071 GDB is moved to a new location. This is useful if GDB, libraries or
6072 executables with debug information and corresponding source code are
6073 being moved together.
6075 `directory DIRNAME ...'
6078 Add directory DIRNAME to the front of the source path. Several
6079 directory names may be given to this command, separated by `:'
6080 (`;' on MS-DOS and MS-Windows, where `:' usually appears as part
6081 of absolute file names) or whitespace. You may specify a
6082 directory that is already in the source path; this moves it
6083 forward, so GDB searches it sooner.
6085 You can use the string `$cdir' to refer to the compilation
6086 directory (if one is recorded), and `$cwd' to refer to the current
6087 working directory. `$cwd' is not the same as `.'--the former
6088 tracks the current working directory as it changes during your GDB
6089 session, while the latter is immediately expanded to the current
6090 directory at the time you add an entry to the source path.
6093 Reset the source path to its default value (`$cdir:$cwd' on Unix
6094 systems). This requires confirmation.
6096 `set directories PATH-LIST'
6097 Set the source path to PATH-LIST. `$cdir:$cwd' are added if
6101 Print the source path: show which directories it contains.
6103 `set substitute-path FROM TO'
6104 Define a source path substitution rule, and add it at the end of
6105 the current list of existing substitution rules. If a rule with
6106 the same FROM was already defined, then the old rule is also
6109 For example, if the file `/foo/bar/baz.c' was moved to
6110 `/mnt/cross/baz.c', then the command
6112 (gdb) set substitute-path /usr/src /mnt/cross
6114 will tell GDB to replace `/usr/src' with `/mnt/cross', which will
6115 allow GDB to find the file `baz.c' even though it was moved.
6117 In the case when more than one substitution rule have been defined,
6118 the rules are evaluated one by one in the order where they have
6119 been defined. The first one matching, if any, is selected to
6120 perform the substitution.
6122 For instance, if we had entered the following commands:
6124 (gdb) set substitute-path /usr/src/include /mnt/include
6125 (gdb) set substitute-path /usr/src /mnt/src
6127 GDB would then rewrite `/usr/src/include/defs.h' into
6128 `/mnt/include/defs.h' by using the first rule. However, it would
6129 use the second rule to rewrite `/usr/src/lib/foo.c' into
6130 `/mnt/src/lib/foo.c'.
6132 `unset substitute-path [path]'
6133 If a path is specified, search the current list of substitution
6134 rules for a rule that would rewrite that path. Delete that rule
6135 if found. A warning is emitted by the debugger if no rule could
6138 If no path is specified, then all substitution rules are deleted.
6140 `show substitute-path [path]'
6141 If a path is specified, then print the source path substitution
6142 rule which would rewrite that path, if any.
6144 If no path is specified, then print all existing source path
6148 If your source path is cluttered with directories that are no longer
6149 of interest, GDB may sometimes cause confusion by finding the wrong
6150 versions of source. You can correct the situation as follows:
6152 1. Use `directory' with no argument to reset the source path to its
6155 2. Use `directory' with suitable arguments to reinstall the
6156 directories you want in the source path. You can add all the
6157 directories in one command.
6160 File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source
6162 9.6 Source and Machine Code
6163 ===========================
6165 You can use the command `info line' to map source lines to program
6166 addresses (and vice versa), and the command `disassemble' to display a
6167 range of addresses as machine instructions. You can use the command
6168 `set disassemble-next-line' to set whether to disassemble next source
6169 line when execution stops. When run under GNU Emacs mode, the `info
6170 line' command causes the arrow to point to the line specified. Also,
6171 `info line' prints addresses in symbolic form as well as hex.
6173 `info line LINESPEC'
6174 Print the starting and ending addresses of the compiled code for
6175 source line LINESPEC. You can specify source lines in any of the
6176 ways documented in *Note Specify Location::.
6178 For example, we can use `info line' to discover the location of the
6179 object code for the first line of function `m4_changequote':
6181 (gdb) info line m4_changequote
6182 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
6184 We can also inquire (using `*ADDR' as the form for LINESPEC) what
6185 source line covers a particular address:
6186 (gdb) info line *0x63ff
6187 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
6189 After `info line', the default address for the `x' command is
6190 changed to the starting address of the line, so that `x/i' is
6191 sufficient to begin examining the machine code (*note Examining Memory:
6192 Memory.). Also, this address is saved as the value of the convenience
6193 variable `$_' (*note Convenience Variables: Convenience Vars.).
6198 This specialized command dumps a range of memory as machine
6199 instructions. It can also print mixed source+disassembly by
6200 specifying the `/m' modifier and print the raw instructions in hex
6201 as well as in symbolic form by specifying the `/r'. The default
6202 memory range is the function surrounding the program counter of
6203 the selected frame. A single argument to this command is a
6204 program counter value; GDB dumps the function surrounding this
6205 value. When two arguments are given, they should be separated by
6206 a comma, possibly surrounded by whitespace. The arguments specify
6207 a range of addresses to dump, in one of two forms:
6210 the addresses from START (inclusive) to END (exclusive)
6213 the addresses from START (inclusive) to `START+LENGTH'
6216 When 2 arguments are specified, the name of the function is also
6217 printed (since there could be several functions in the given
6220 The argument(s) can be any expression yielding a numeric value,
6221 such as `0x32c4', `&main+10' or `$pc - 8'.
6223 If the range of memory being disassembled contains current program
6224 counter, the instruction at that location is shown with a `=>'
6227 The following example shows the disassembly of a range of addresses
6228 of HP PA-RISC 2.0 code:
6230 (gdb) disas 0x32c4, 0x32e4
6231 Dump of assembler code from 0x32c4 to 0x32e4:
6232 0x32c4 <main+204>: addil 0,dp
6233 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
6234 0x32cc <main+212>: ldil 0x3000,r31
6235 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
6236 0x32d4 <main+220>: ldo 0(r31),rp
6237 0x32d8 <main+224>: addil -0x800,dp
6238 0x32dc <main+228>: ldo 0x588(r1),r26
6239 0x32e0 <main+232>: ldil 0x3000,r31
6240 End of assembler dump.
6242 Here is an example showing mixed source+assembly for Intel x86, when
6243 the program is stopped just after function prologue:
6246 Dump of assembler code for function main:
6248 0x08048330 <+0>: push %ebp
6249 0x08048331 <+1>: mov %esp,%ebp
6250 0x08048333 <+3>: sub $0x8,%esp
6251 0x08048336 <+6>: and $0xfffffff0,%esp
6252 0x08048339 <+9>: sub $0x10,%esp
6254 6 printf ("Hello.\n");
6255 => 0x0804833c <+12>: movl $0x8048440,(%esp)
6256 0x08048343 <+19>: call 0x8048284 <puts@plt>
6260 0x08048348 <+24>: mov $0x0,%eax
6261 0x0804834d <+29>: leave
6262 0x0804834e <+30>: ret
6264 End of assembler dump.
6266 Here is another example showing raw instructions in hex for AMD
6269 (gdb) disas /r 0x400281,+10
6270 Dump of assembler code from 0x400281 to 0x40028b:
6271 0x0000000000400281: 38 36 cmp %dh,(%rsi)
6272 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
6273 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
6274 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
6275 End of assembler dump.
6277 Some architectures have more than one commonly-used set of
6278 instruction mnemonics or other syntax.
6280 For programs that were dynamically linked and use shared libraries,
6281 instructions that call functions or branch to locations in the shared
6282 libraries might show a seemingly bogus location--it's actually a
6283 location of the relocation table. On some architectures, GDB might be
6284 able to resolve these to actual function names.
6286 `set disassembly-flavor INSTRUCTION-SET'
6287 Select the instruction set to use when disassembling the program
6288 via the `disassemble' or `x/i' commands.
6290 Currently this command is only defined for the Intel x86 family.
6291 You can set INSTRUCTION-SET to either `intel' or `att'. The
6292 default is `att', the AT&T flavor used by default by Unix
6293 assemblers for x86-based targets.
6295 `show disassembly-flavor'
6296 Show the current setting of the disassembly flavor.
6298 `set disassemble-next-line'
6299 `show disassemble-next-line'
6300 Control whether or not GDB will disassemble the next source line
6301 or instruction when execution stops. If ON, GDB will display
6302 disassembly of the next source line when execution of the program
6303 being debugged stops. This is _in addition_ to displaying the
6304 source line itself, which GDB always does if possible. If the
6305 next source line cannot be displayed for some reason (e.g., if GDB
6306 cannot find the source file, or there's no line info in the debug
6307 info), GDB will display disassembly of the next _instruction_
6308 instead of showing the next source line. If AUTO, GDB will
6309 display disassembly of next instruction only if the source line
6310 cannot be displayed. This setting causes GDB to display some
6311 feedback when you step through a function with no line info or
6312 whose source file is unavailable. The default is OFF, which means
6313 never display the disassembly of the next line or instruction.
6316 File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top
6321 The usual way to examine data in your program is with the `print'
6322 command (abbreviated `p'), or its synonym `inspect'. It evaluates and
6323 prints the value of an expression of the language your program is
6324 written in (*note Using GDB with Different Languages: Languages.). It
6325 may also print the expression using a Python-based pretty-printer
6326 (*note Pretty Printing::).
6330 EXPR is an expression (in the source language). By default the
6331 value of EXPR is printed in a format appropriate to its data type;
6332 you can choose a different format by specifying `/F', where F is a
6333 letter specifying the format; see *Note Output Formats: Output
6338 If you omit EXPR, GDB displays the last value again (from the
6339 "value history"; *note Value History: Value History.). This
6340 allows you to conveniently inspect the same value in an
6343 A more low-level way of examining data is with the `x' command. It
6344 examines data in memory at a specified address and prints it in a
6345 specified format. *Note Examining Memory: Memory.
6347 If you are interested in information about types, or about how the
6348 fields of a struct or a class are declared, use the `ptype EXP' command
6349 rather than `print'. *Note Examining the Symbol Table: Symbols.
6351 Another way of examining values of expressions and type information
6352 is through the Python extension command `explore' (available only if
6353 the GDB build is configured with `--with-python'). It offers an
6354 interactive way to start at the highest level (or, the most abstract
6355 level) of the data type of an expression (or, the data type itself) and
6356 explore all the way down to leaf scalar values/fields embedded in the
6357 higher level data types.
6360 ARG is either an expression (in the source language), or a type
6361 visible in the current context of the program being debugged.
6363 The working of the `explore' command can be illustrated with an
6364 example. If a data type `struct ComplexStruct' is defined in your C
6373 struct ComplexStruct
6375 struct SimpleStruct *ss_p;
6379 followed by variable declarations as
6381 struct SimpleStruct ss = { 10, 1.11 };
6382 struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } };
6384 then, the value of the variable `cs' can be explored using the
6385 `explore' command as follows.
6388 The value of `cs' is a struct/class of type `struct ComplexStruct' with
6389 the following fields:
6391 ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'>
6392 arr = <Enter 1 to explore this field of type `int [10]'>
6394 Enter the field number of choice:
6396 Since the fields of `cs' are not scalar values, you are being prompted
6397 to chose the field you want to explore. Let's say you choose the field
6398 `ss_p' by entering `0'. Then, since this field is a pointer, you will
6399 be asked if it is pointing to a single value. From the declaration of
6400 `cs' above, it is indeed pointing to a single value, hence you enter
6401 `y'. If you enter `n', then you will be asked if it were pointing to
6402 an array of values, in which case this field will be explored as if it
6405 `cs.ss_p' is a pointer to a value of type `struct SimpleStruct'
6406 Continue exploring it as a pointer to a single value [y/n]: y
6407 The value of `*(cs.ss_p)' is a struct/class of type `struct
6408 SimpleStruct' with the following fields:
6410 i = 10 .. (Value of type `int')
6411 d = 1.1100000000000001 .. (Value of type `double')
6413 Press enter to return to parent value:
6415 If the field `arr' of `cs' was chosen for exploration by entering `1'
6416 earlier, then since it is as array, you will be prompted to enter the
6417 index of the element in the array that you want to explore.
6419 `cs.arr' is an array of `int'.
6420 Enter the index of the element you want to explore in `cs.arr': 5
6422 `(cs.arr)[5]' is a scalar value of type `int'.
6426 Press enter to return to parent value:
6428 In general, at any stage of exploration, you can go deeper towards
6429 the leaf values by responding to the prompts appropriately, or hit the
6430 return key to return to the enclosing data structure (the higher level
6433 Similar to exploring values, you can use the `explore' command to
6434 explore types. Instead of specifying a value (which is typically a
6435 variable name or an expression valid in the current context of the
6436 program being debugged), you specify a type name. If you consider the
6437 same example as above, your can explore the type `struct ComplexStruct'
6438 by passing the argument `struct ComplexStruct' to the `explore' command.
6440 (gdb) explore struct ComplexStruct
6442 By responding to the prompts appropriately in the subsequent interactive
6443 session, you can explore the type `struct ComplexStruct' in a manner
6444 similar to how the value `cs' was explored in the above example.
6446 The `explore' command also has two sub-commands, `explore value' and
6447 `explore type'. The former sub-command is a way to explicitly specify
6448 that value exploration of the argument is being invoked, while the
6449 latter is a way to explicitly specify that type exploration of the
6450 argument is being invoked.
6452 `explore value EXPR'
6453 This sub-command of `explore' explores the value of the expression
6454 EXPR (if EXPR is an expression valid in the current context of the
6455 program being debugged). The behavior of this command is
6456 identical to that of the behavior of the `explore' command being
6457 passed the argument EXPR.
6460 This sub-command of `explore' explores the type of ARG (if ARG is
6461 a type visible in the current context of program being debugged),
6462 or the type of the value/expression ARG (if ARG is an expression
6463 valid in the current context of the program being debugged). If
6464 ARG is a type, then the behavior of this command is identical to
6465 that of the `explore' command being passed the argument ARG. If
6466 ARG is an expression, then the behavior of this command will be
6467 identical to that of the `explore' command being passed the type
6468 of ARG as the argument.
6472 * Expressions:: Expressions
6473 * Ambiguous Expressions:: Ambiguous Expressions
6474 * Variables:: Program variables
6475 * Arrays:: Artificial arrays
6476 * Output Formats:: Output formats
6477 * Memory:: Examining memory
6478 * Auto Display:: Automatic display
6479 * Print Settings:: Print settings
6480 * Pretty Printing:: Python pretty printing
6481 * Value History:: Value history
6482 * Convenience Vars:: Convenience variables
6483 * Registers:: Registers
6484 * Floating Point Hardware:: Floating point hardware
6485 * Vector Unit:: Vector Unit
6486 * OS Information:: Auxiliary data provided by operating system
6487 * Memory Region Attributes:: Memory region attributes
6488 * Dump/Restore Files:: Copy between memory and a file
6489 * Core File Generation:: Cause a program dump its core
6490 * Character Sets:: Debugging programs that use a different
6491 character set than GDB does
6492 * Caching Remote Data:: Data caching for remote targets
6493 * Searching Memory:: Searching memory for a sequence of bytes
6496 File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data
6501 `print' and many other GDB commands accept an expression and compute
6502 its value. Any kind of constant, variable or operator defined by the
6503 programming language you are using is valid in an expression in GDB.
6504 This includes conditional expressions, function calls, casts, and
6505 string constants. It also includes preprocessor macros, if you
6506 compiled your program to include this information; see *Note
6509 GDB supports array constants in expressions input by the user. The
6510 syntax is {ELEMENT, ELEMENT...}. For example, you can use the command
6511 `print {1, 2, 3}' to create an array of three integers. If you pass an
6512 array to a function or assign it to a program variable, GDB copies the
6513 array to memory that is `malloc'ed in the target program.
6515 Because C is so widespread, most of the expressions shown in
6516 examples in this manual are in C. *Note Using GDB with Different
6517 Languages: Languages, for information on how to use expressions in other
6520 In this section, we discuss operators that you can use in GDB
6521 expressions regardless of your programming language.
6523 Casts are supported in all languages, not just in C, because it is so
6524 useful to cast a number into a pointer in order to examine a structure
6525 at that address in memory.
6527 GDB supports these operators, in addition to those common to
6528 programming languages:
6531 `@' is a binary operator for treating parts of memory as arrays.
6532 *Note Artificial Arrays: Arrays, for more information.
6535 `::' allows you to specify a variable in terms of the file or
6536 function where it is defined. *Note Program Variables: Variables.
6539 Refers to an object of type TYPE stored at address ADDR in memory.
6540 ADDR may be any expression whose value is an integer or pointer
6541 (but parentheses are required around binary operators, just as in
6542 a cast). This construct is allowed regardless of what kind of
6543 data is normally supposed to reside at ADDR.
6546 File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data
6548 10.2 Ambiguous Expressions
6549 ==========================
6551 Expressions can sometimes contain some ambiguous elements. For
6552 instance, some programming languages (notably Ada, C++ and Objective-C)
6553 permit a single function name to be defined several times, for
6554 application in different contexts. This is called "overloading".
6555 Another example involving Ada is generics. A "generic package" is
6556 similar to C++ templates and is typically instantiated several times,
6557 resulting in the same function name being defined in different contexts.
6559 In some cases and depending on the language, it is possible to adjust
6560 the expression to remove the ambiguity. For instance in C++, you can
6561 specify the signature of the function you want to break on, as in
6562 `break FUNCTION(TYPES)'. In Ada, using the fully qualified name of
6563 your function often makes the expression unambiguous as well.
6565 When an ambiguity that needs to be resolved is detected, the debugger
6566 has the capability to display a menu of numbered choices for each
6567 possibility, and then waits for the selection with the prompt `>'. The
6568 first option is always `[0] cancel', and typing `0 <RET>' aborts the
6569 current command. If the command in which the expression was used
6570 allows more than one choice to be selected, the next option in the menu
6571 is `[1] all', and typing `1 <RET>' selects all possible choices.
6573 For example, the following session excerpt shows an attempt to set a
6574 breakpoint at the overloaded symbol `String::after'. We choose three
6575 particular definitions of that function name:
6577 (gdb) b String::after
6580 [2] file:String.cc; line number:867
6581 [3] file:String.cc; line number:860
6582 [4] file:String.cc; line number:875
6583 [5] file:String.cc; line number:853
6584 [6] file:String.cc; line number:846
6585 [7] file:String.cc; line number:735
6587 Breakpoint 1 at 0xb26c: file String.cc, line 867.
6588 Breakpoint 2 at 0xb344: file String.cc, line 875.
6589 Breakpoint 3 at 0xafcc: file String.cc, line 846.
6590 Multiple breakpoints were set.
6591 Use the "delete" command to delete unwanted
6595 `set multiple-symbols MODE'
6596 This option allows you to adjust the debugger behavior when an
6597 expression is ambiguous.
6599 By default, MODE is set to `all'. If the command with which the
6600 expression is used allows more than one choice, then GDB
6601 automatically selects all possible choices. For instance,
6602 inserting a breakpoint on a function using an ambiguous name
6603 results in a breakpoint inserted on each possible match. However,
6604 if a unique choice must be made, then GDB uses the menu to help
6605 you disambiguate the expression. For instance, printing the
6606 address of an overloaded function will result in the use of the
6609 When MODE is set to `ask', the debugger always uses the menu when
6610 an ambiguity is detected.
6612 Finally, when MODE is set to `cancel', the debugger reports an
6613 error due to the ambiguity and the command is aborted.
6615 `show multiple-symbols'
6616 Show the current value of the `multiple-symbols' setting.
6619 File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data
6621 10.3 Program Variables
6622 ======================
6624 The most common kind of expression to use is the name of a variable in
6627 Variables in expressions are understood in the selected stack frame
6628 (*note Selecting a Frame: Selection.); they must be either:
6630 * global (or file-static)
6634 * visible according to the scope rules of the programming language
6635 from the point of execution in that frame
6637 This means that in the function
6649 you can examine and use the variable `a' whenever your program is
6650 executing within the function `foo', but you can only use or examine
6651 the variable `b' while your program is executing inside the block where
6654 There is an exception: you can refer to a variable or function whose
6655 scope is a single source file even if the current execution point is not
6656 in this file. But it is possible to have more than one such variable or
6657 function with the same name (in different source files). If that
6658 happens, referring to that name has unpredictable effects. If you wish,
6659 you can specify a static variable in a particular function or file by
6660 using the colon-colon (`::') notation:
6665 Here FILE or FUNCTION is the name of the context for the static
6666 VARIABLE. In the case of file names, you can use quotes to make sure
6667 GDB parses the file name as a single word--for example, to print a
6668 global value of `x' defined in `f2.c':
6672 The `::' notation is normally used for referring to static
6673 variables, since you typically disambiguate uses of local variables in
6674 functions by selecting the appropriate frame and using the simple name
6675 of the variable. However, you may also use this notation to refer to
6676 local variables in frames enclosing the selected frame:
6684 process (a); /* Stop here */
6693 For example, if there is a breakpoint at the commented line, here is
6694 what you might see when the program stops after executing the call
6702 #2 0x080483d0 in foo (a=5) at foobar.c:12
6708 These uses of `::' are very rarely in conflict with the very similar
6709 use of the same notation in C++. GDB also supports use of the C++
6710 scope resolution operator in GDB expressions.
6712 _Warning:_ Occasionally, a local variable may appear to have the
6713 wrong value at certain points in a function--just after entry to a
6714 new scope, and just before exit.
6715 You may see this problem when you are stepping by machine
6716 instructions. This is because, on most machines, it takes more than
6717 one instruction to set up a stack frame (including local variable
6718 definitions); if you are stepping by machine instructions, variables
6719 may appear to have the wrong values until the stack frame is completely
6720 built. On exit, it usually also takes more than one machine
6721 instruction to destroy a stack frame; after you begin stepping through
6722 that group of instructions, local variable definitions may be gone.
6724 This may also happen when the compiler does significant
6725 optimizations. To be sure of always seeing accurate values, turn off
6726 all optimization when compiling.
6728 Another possible effect of compiler optimizations is to optimize
6729 unused variables out of existence, or assign variables to registers (as
6730 opposed to memory addresses). Depending on the support for such cases
6731 offered by the debug info format used by the compiler, GDB might not be
6732 able to display values for such local variables. If that happens, GDB
6733 will print a message like this:
6735 No symbol "foo" in current context.
6737 To solve such problems, either recompile without optimizations, or
6738 use a different debug info format, if the compiler supports several such
6739 formats. *Note Compilation::, for more information on choosing compiler
6740 options. *Note C and C++: C, for more information about debug info
6741 formats that are best suited to C++ programs.
6743 If you ask to print an object whose contents are unknown to GDB,
6744 e.g., because its data type is not completely specified by the debug
6745 information, GDB will say `<incomplete type>'. *Note incomplete type:
6746 Symbols, for more about this.
6748 If you append `@entry' string to a function parameter name you get
6749 its value at the time the function got called. If the value is not
6750 available an error message is printed. Entry values are available only
6751 with some compilers. Entry values are normally also printed at the
6752 function parameter list according to *Note set print entry-values::.
6754 Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29
6763 Strings are identified as arrays of `char' values without specified
6764 signedness. Arrays of either `signed char' or `unsigned char' get
6765 printed as arrays of 1 byte sized integers. `-fsigned-char' or
6766 `-funsigned-char' GCC options have no effect as GDB defines literal
6767 string type `"char"' as `char' without a sign. For program code
6770 signed char var1[] = "A";
6772 You get during debugging
6776 $2 = {65 'A', 0 '\0'}
6779 File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data
6781 10.4 Artificial Arrays
6782 ======================
6784 It is often useful to print out several successive objects of the same
6785 type in memory; a section of an array, or an array of dynamically
6786 determined size for which only a pointer exists in the program.
6788 You can do this by referring to a contiguous span of memory as an
6789 "artificial array", using the binary operator `@'. The left operand of
6790 `@' should be the first element of the desired array and be an
6791 individual object. The right operand should be the desired length of
6792 the array. The result is an array value whose elements are all of the
6793 type of the left argument. The first element is actually the left
6794 argument; the second element comes from bytes of memory immediately
6795 following those that hold the first element, and so on. Here is an
6796 example. If a program says
6798 int *array = (int *) malloc (len * sizeof (int));
6800 you can print the contents of `array' with
6804 The left operand of `@' must reside in memory. Array values made
6805 with `@' in this way behave just like other arrays in terms of
6806 subscripting, and are coerced to pointers when used in expressions.
6807 Artificial arrays most often appear in expressions via the value history
6808 (*note Value History: Value History.), after printing one out.
6810 Another way to create an artificial array is to use a cast. This
6811 re-interprets a value as if it were an array. The value need not be in
6813 (gdb) p/x (short[2])0x12345678
6814 $1 = {0x1234, 0x5678}
6816 As a convenience, if you leave the array length out (as in
6817 `(TYPE[])VALUE') GDB calculates the size to fill the value (as
6818 `sizeof(VALUE)/sizeof(TYPE)':
6819 (gdb) p/x (short[])0x12345678
6820 $2 = {0x1234, 0x5678}
6822 Sometimes the artificial array mechanism is not quite enough; in
6823 moderately complex data structures, the elements of interest may not
6824 actually be adjacent--for example, if you are interested in the values
6825 of pointers in an array. One useful work-around in this situation is
6826 to use a convenience variable (*note Convenience Variables: Convenience
6827 Vars.) as a counter in an expression that prints the first interesting
6828 value, and then repeat that expression via <RET>. For instance,
6829 suppose you have an array `dtab' of pointers to structures, and you are
6830 interested in the values of a field `fv' in each structure. Here is an
6831 example of what you might type:
6840 File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data
6845 By default, GDB prints a value according to its data type. Sometimes
6846 this is not what you want. For example, you might want to print a
6847 number in hex, or a pointer in decimal. Or you might want to view data
6848 in memory at a certain address as a character string or as an
6849 instruction. To do these things, specify an "output format" when you
6852 The simplest use of output formats is to say how to print a value
6853 already computed. This is done by starting the arguments of the
6854 `print' command with a slash and a format letter. The format letters
6858 Regard the bits of the value as an integer, and print the integer
6862 Print as integer in signed decimal.
6865 Print as integer in unsigned decimal.
6868 Print as integer in octal.
6871 Print as integer in binary. The letter `t' stands for "two". (1)
6874 Print as an address, both absolute in hexadecimal and as an offset
6875 from the nearest preceding symbol. You can use this format used
6876 to discover where (in what function) an unknown address is located:
6879 $3 = 0x54320 <_initialize_vx+396>
6881 The command `info symbol 0x54320' yields similar results. *Note
6882 info symbol: Symbols.
6885 Regard as an integer and print it as a character constant. This
6886 prints both the numerical value and its character representation.
6887 The character representation is replaced with the octal escape
6888 `\nnn' for characters outside the 7-bit ASCII range.
6890 Without this format, GDB displays `char', `unsigned char', and
6891 `signed char' data as character constants. Single-byte members of
6892 vectors are displayed as integer data.
6895 Regard the bits of the value as a floating point number and print
6896 using typical floating point syntax.
6899 Regard as a string, if possible. With this format, pointers to
6900 single-byte data are displayed as null-terminated strings and
6901 arrays of single-byte data are displayed as fixed-length strings.
6902 Other values are displayed in their natural types.
6904 Without this format, GDB displays pointers to and arrays of
6905 `char', `unsigned char', and `signed char' as strings.
6906 Single-byte members of a vector are displayed as an integer array.
6909 Print using the `raw' formatting. By default, GDB will use a
6910 Python-based pretty-printer, if one is available (*note Pretty
6911 Printing::). This typically results in a higher-level display of
6912 the value's contents. The `r' format bypasses any Python
6913 pretty-printer which might exist.
6915 For example, to print the program counter in hex (*note
6920 Note that no space is required before the slash; this is because command
6921 names in GDB cannot contain a slash.
6923 To reprint the last value in the value history with a different
6924 format, you can use the `print' command with just a format and no
6925 expression. For example, `p/x' reprints the last value in hex.
6927 ---------- Footnotes ----------
6929 (1) `b' cannot be used because these format letters are also used
6930 with the `x' command, where `b' stands for "byte"; see *Note Examining
6934 File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data
6936 10.6 Examining Memory
6937 =====================
6939 You can use the command `x' (for "examine") to examine memory in any of
6940 several formats, independently of your program's data types.
6945 Use the `x' command to examine memory.
6947 N, F, and U are all optional parameters that specify how much memory
6948 to display and how to format it; ADDR is an expression giving the
6949 address where you want to start displaying memory. If you use defaults
6950 for NFU, you need not type the slash `/'. Several commands set
6951 convenient defaults for ADDR.
6954 The repeat count is a decimal integer; the default is 1. It
6955 specifies how much memory (counting by units U) to display.
6957 F, the display format
6958 The display format is one of the formats used by `print' (`x',
6959 `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for
6960 machine instructions). The default is `x' (hexadecimal)
6961 initially. The default changes each time you use either `x' or
6965 The unit size is any of
6971 Halfwords (two bytes).
6974 Words (four bytes). This is the initial default.
6977 Giant words (eight bytes).
6979 Each time you specify a unit size with `x', that size becomes the
6980 default unit the next time you use `x'. For the `i' format, the
6981 unit size is ignored and is normally not written. For the `s'
6982 format, the unit size defaults to `b', unless it is explicitly
6983 given. Use `x /hs' to display 16-bit char strings and `x /ws' to
6984 display 32-bit strings. The next use of `x /s' will again display
6985 8-bit strings. Note that the results depend on the programming
6986 language of the current compilation unit. If the language is C,
6987 the `s' modifier will use the UTF-16 encoding while `w' will use
6988 UTF-32. The encoding is set by the programming language and cannot
6991 ADDR, starting display address
6992 ADDR is the address where you want GDB to begin displaying memory.
6993 The expression need not have a pointer value (though it may); it
6994 is always interpreted as an integer address of a byte of memory.
6995 *Note Expressions: Expressions, for more information on
6996 expressions. The default for ADDR is usually just after the last
6997 address examined--but several other commands also set the default
6998 address: `info breakpoints' (to the address of the last breakpoint
6999 listed), `info line' (to the starting address of a line), and
7000 `print' (if you use it to display a value from memory).
7002 For example, `x/3uh 0x54320' is a request to display three halfwords
7003 (`h') of memory, formatted as unsigned decimal integers (`u'), starting
7004 at address `0x54320'. `x/4xw $sp' prints the four words (`w') of
7005 memory above the stack pointer (here, `$sp'; *note Registers:
7006 Registers.) in hexadecimal (`x').
7008 Since the letters indicating unit sizes are all distinct from the
7009 letters specifying output formats, you do not have to remember whether
7010 unit size or format comes first; either order works. The output
7011 specifications `4xw' and `4wx' mean exactly the same thing. (However,
7012 the count N must come first; `wx4' does not work.)
7014 Even though the unit size U is ignored for the formats `s' and `i',
7015 you might still want to use a count N; for example, `3i' specifies that
7016 you want to see three machine instructions, including any operands.
7017 For convenience, especially when used with the `display' command, the
7018 `i' format also prints branch delay slot instructions, if any, beyond
7019 the count specified, which immediately follow the last instruction that
7020 is within the count. The command `disassemble' gives an alternative
7021 way of inspecting machine instructions; see *Note Source and Machine
7024 All the defaults for the arguments to `x' are designed to make it
7025 easy to continue scanning memory with minimal specifications each time
7026 you use `x'. For example, after you have inspected three machine
7027 instructions with `x/3i ADDR', you can inspect the next seven with just
7028 `x/7'. If you use <RET> to repeat the `x' command, the repeat count N
7029 is used again; the other arguments default as for successive uses of
7032 When examining machine instructions, the instruction at current
7033 program counter is shown with a `=>' marker. For example:
7036 0x804837f <main+11>: mov %esp,%ebp
7037 0x8048381 <main+13>: push %ecx
7038 0x8048382 <main+14>: sub $0x4,%esp
7039 => 0x8048385 <main+17>: movl $0x8048460,(%esp)
7040 0x804838c <main+24>: call 0x80482d4 <puts@plt>
7042 The addresses and contents printed by the `x' command are not saved
7043 in the value history because there is often too much of them and they
7044 would get in the way. Instead, GDB makes these values available for
7045 subsequent use in expressions as values of the convenience variables
7046 `$_' and `$__'. After an `x' command, the last address examined is
7047 available for use in expressions in the convenience variable `$_'. The
7048 contents of that address, as examined, are available in the convenience
7051 If the `x' command has a repeat count, the address and contents saved
7052 are from the last memory unit printed; this is not the same as the last
7053 address printed if several units were printed on the last line of
7056 When you are debugging a program running on a remote target machine
7057 (*note Remote Debugging::), you may wish to verify the program's image
7058 in the remote machine's memory against the executable file you
7059 downloaded to the target. The `compare-sections' command is provided
7060 for such situations.
7062 `compare-sections [SECTION-NAME]'
7063 Compare the data of a loadable section SECTION-NAME in the
7064 executable file of the program being debugged with the same
7065 section in the remote machine's memory, and report any mismatches.
7066 With no arguments, compares all loadable sections. This command's
7067 availability depends on the target's support for the `"qCRC"'
projects / platform / upstream / gdb.git / blob