| This is gdb.info, produced by makeinfo version 4.8 from |
| ../.././gdb/doc/gdb.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Ninth Edition, of `Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB Version 6.8. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, |
| 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) |
| |
| Debugging with GDB |
| ****************** |
| |
| This file describes GDB, the GNU symbolic debugger. |
| |
| This is the Ninth Edition, for GDB Version 6.8. |
| |
| Copyright (C) 1988-2006 Free Software Foundation, Inc. |
| |
| This edition of the GDB manual is dedicated to the memory of Fred |
| Fish. Fred was a long-standing contributor to GDB and to Free software |
| in general. We will miss him. |
| |
| * Menu: |
| |
| * Summary:: Summary of GDB |
| * Sample Session:: A sample GDB session |
| |
| * Invocation:: Getting in and out of GDB |
| * Commands:: GDB commands |
| * Running:: Running programs under GDB |
| * Stopping:: Stopping and continuing |
| * Stack:: Examining the stack |
| * Source:: Examining source files |
| * Data:: Examining data |
| * Macros:: Preprocessor Macros |
| * Tracepoints:: Debugging remote targets non-intrusively |
| * Overlays:: Debugging programs that use overlays |
| |
| * Languages:: Using GDB with different languages |
| |
| * Symbols:: Examining the symbol table |
| * Altering:: Altering execution |
| * GDB Files:: GDB files |
| * Targets:: Specifying a debugging target |
| * Remote Debugging:: Debugging remote programs |
| * Configurations:: Configuration-specific information |
| * Controlling GDB:: Controlling GDB |
| * Sequences:: Canned sequences of commands |
| * Interpreters:: Command Interpreters |
| * TUI:: GDB Text User Interface |
| * Emacs:: Using GDB under GNU Emacs |
| * GDB/MI:: GDB's Machine Interface. |
| * Annotations:: GDB's annotation interface. |
| |
| * GDB Bugs:: Reporting bugs in GDB |
| |
| * Command Line Editing:: Command Line Editing |
| * Using History Interactively:: Using History Interactively |
| * Formatting Documentation:: How to format and print GDB documentation |
| * Installing GDB:: Installing GDB |
| * Maintenance Commands:: Maintenance Commands |
| * Remote Protocol:: GDB Remote Serial Protocol |
| * Agent Expressions:: The GDB Agent Expression Mechanism |
| * Target Descriptions:: How targets can describe themselves to |
| GDB |
| * Copying:: GNU General Public License says |
| how you can copy and share GDB |
| * GNU Free Documentation License:: The license for this documentation |
| * Index:: Index |
| |
| |
| File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top |
| |
| Summary of GDB |
| ************** |
| |
| The purpose of a debugger such as GDB is to allow you to see what is |
| going on "inside" another program while it executes--or what another |
| program was doing at the moment it crashed. |
| |
| GDB can do four main kinds of things (plus other things in support of |
| these) to help you catch bugs in the act: |
| |
| * Start your program, specifying anything that might affect its |
| behavior. |
| |
| * Make your program stop on specified conditions. |
| |
| * Examine what has happened, when your program has stopped. |
| |
| * Change things in your program, so you can experiment with |
| correcting the effects of one bug and go on to learn about another. |
| |
| You can use GDB to debug programs written in C and C++. For more |
| information, see *Note Supported Languages: Supported Languages. For |
| more information, see *Note C and C++: C. |
| |
| Support for Modula-2 is partial. For information on Modula-2, see |
| *Note Modula-2: Modula-2. |
| |
| Debugging Pascal programs which use sets, subranges, file variables, |
| or nested functions does not currently work. GDB does not support |
| entering expressions, printing values, or similar features using Pascal |
| syntax. |
| |
| GDB can be used to debug programs written in Fortran, although it |
| may be necessary to refer to some variables with a trailing underscore. |
| |
| GDB can be used to debug programs written in Objective-C, using |
| either the Apple/NeXT or the GNU Objective-C runtime. |
| |
| * Menu: |
| |
| * Free Software:: Freely redistributable software |
| * Contributors:: Contributors to GDB |
| |
| |
| File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary |
| |
| Free Software |
| ============= |
| |
| GDB is "free software", protected by the GNU General Public License |
| (GPL). The GPL gives you the freedom to copy or adapt a licensed |
| program--but every person getting a copy also gets with it the freedom |
| to modify that copy (which means that they must get access to the |
| source code), and the freedom to distribute further copies. Typical |
| software companies use copyrights to limit your freedoms; the Free |
| Software Foundation uses the GPL to preserve these freedoms. |
| |
| Fundamentally, the General Public License is a license which says |
| that you have these freedoms and that you cannot take these freedoms |
| away from anyone else. |
| |
| Free Software Needs Free Documentation |
| ====================================== |
| |
| The biggest deficiency in the free software community today is not in |
| the software--it is the lack of good free documentation that we can |
| include with the free software. Many of our most important programs do |
| not come with free reference manuals and free introductory texts. |
| Documentation is an essential part of any software package; when an |
| important free software package does not come with a free manual and a |
| free tutorial, that is a major gap. We have many such gaps today. |
| |
| Consider Perl, for instance. The tutorial manuals that people |
| normally use are non-free. How did this come about? Because the |
| authors of those manuals published them with restrictive terms--no |
| copying, no modification, source files not available--which exclude |
| them from the free software world. |
| |
| That wasn't the first time this sort of thing happened, and it was |
| far from the last. Many times we have heard a GNU user eagerly |
| describe a manual that he is writing, his intended contribution to the |
| community, only to learn that he had ruined everything by signing a |
| publication contract to make it non-free. |
| |
| Free documentation, like free software, is a matter of freedom, not |
| price. The problem with the non-free manual is not that publishers |
| charge a price for printed copies--that in itself is fine. (The Free |
| Software Foundation sells printed copies of manuals, too.) The problem |
| is the restrictions on the use of the manual. Free manuals are |
| available in source code form, and give you permission to copy and |
| modify. Non-free manuals do not allow this. |
| |
| The criteria of freedom for a free manual are roughly the same as for |
| free software. Redistribution (including the normal kinds of |
| commercial redistribution) must be permitted, so that the manual can |
| accompany every copy of the program, both on-line and on paper. |
| |
| Permission for modification of the technical content is crucial too. |
| When people modify the software, adding or changing features, if they |
| are conscientious they will change the manual too--so they can provide |
| accurate and clear documentation for the modified program. A manual |
| that leaves you no choice but to write a new manual to document a |
| changed version of the program is not really available to our community. |
| |
| Some kinds of limits on the way modification is handled are |
| acceptable. For example, requirements to preserve the original |
| author's copyright notice, the distribution terms, or the list of |
| authors, are ok. It is also no problem to require modified versions to |
| include notice that they were modified. Even entire sections that may |
| not be deleted or changed are acceptable, as long as they deal with |
| nontechnical topics (like this one). These kinds of restrictions are |
| acceptable because they don't obstruct the community's normal use of |
| the manual. |
| |
| However, it must be possible to modify all the _technical_ content |
| of the manual, and then distribute the result in all the usual media, |
| through all the usual channels. Otherwise, the restrictions obstruct |
| the use of the manual, it is not free, and we need another manual to |
| replace it. |
| |
| Please spread the word about this issue. Our community continues to |
| lose manuals to proprietary publishing. If we spread the word that |
| free software needs free reference manuals and free tutorials, perhaps |
| the next person who wants to contribute by writing documentation will |
| realize, before it is too late, that only free manuals contribute to |
| the free software community. |
| |
| If you are writing documentation, please insist on publishing it |
| under the GNU Free Documentation License or another free documentation |
| license. Remember that this decision requires your approval--you don't |
| have to let the publisher decide. Some commercial publishers will use |
| a free license if you insist, but they will not propose the option; it |
| is up to you to raise the issue and say firmly that this is what you |
| want. If the publisher you are dealing with refuses, please try other |
| publishers. If you're not sure whether a proposed license is free, |
| write to <licensing@gnu.org>. |
| |
| You can encourage commercial publishers to sell more free, copylefted |
| manuals and tutorials by buying them, and particularly by buying copies |
| from the publishers that paid for their writing or for major |
| improvements. Meanwhile, try to avoid buying non-free documentation at |
| all. Check the distribution terms of a manual before you buy it, and |
| insist that whoever seeks your business must respect your freedom. |
| Check the history of the book, and try to reward the publishers that |
| have paid or pay the authors to work on it. |
| |
| The Free Software Foundation maintains a list of free documentation |
| published by other publishers, at |
| `http://www.fsf.org/doc/other-free-books.html'. |
| |
| |
| File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary |
| |
| Contributors to GDB |
| =================== |
| |
| Richard Stallman was the original author of GDB, and of many other GNU |
| programs. Many others have contributed to its development. This |
| section attempts to credit major contributors. One of the virtues of |
| free software is that everyone is free to contribute to it; with |
| regret, we cannot actually acknowledge everyone here. The file |
| `ChangeLog' in the GDB distribution approximates a blow-by-blow account. |
| |
| Changes much prior to version 2.0 are lost in the mists of time. |
| |
| _Plea:_ Additions to this section are particularly welcome. If you |
| or your friends (or enemies, to be evenhanded) have been unfairly |
| omitted from this list, we would like to add your names! |
| |
| So that they may not regard their many labors as thankless, we |
| particularly thank those who shepherded GDB through major releases: |
| Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim |
| Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs |
| (release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, |
| and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, |
| and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim |
| Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, |
| 3.1, and 3.0). |
| |
| Richard Stallman, assisted at various times by Peter TerMaat, Chris |
| Hanson, and Richard Mlynarik, handled releases through 2.8. |
| |
| Michael Tiemann is the author of most of the GNU C++ support in GDB, |
| with significant additional contributions from Per Bothner and Daniel |
| Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ |
| was by Peter TerMaat (who also did much general update work leading to |
| release 3.0). |
| |
| GDB uses the BFD subroutine library to examine multiple object-file |
| formats; BFD was a joint project of David V. Henkel-Wallace, Rich |
| Pixley, Steve Chamberlain, and John Gilmore. |
| |
| David Johnson wrote the original COFF support; Pace Willison did the |
| original support for encapsulated COFF. |
| |
| Brent Benson of Harris Computer Systems contributed DWARF 2 support. |
| |
| Adam de Boor and Bradley Davis contributed the ISI Optimum V support. |
| Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS |
| support. Jean-Daniel Fekete contributed Sun 386i support. Chris |
| Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki |
| Hasei contributed Sony/News OS 3 support. David Johnson contributed |
| Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. |
| Jeff Law contributed HP PA and SOM support. Keith Packard contributed |
| NS32K support. Doug Rabson contributed Acorn Risc Machine support. |
| Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith |
| contributed Convex support (and Fortran debugging). Jonathan Stone |
| contributed Pyramid support. Michael Tiemann contributed SPARC support. |
| Tim Tucker contributed support for the Gould NP1 and Gould Powernode. |
| Pace Willison contributed Intel 386 support. Jay Vosburgh contributed |
| Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. |
| |
| Andreas Schwab contributed M68K GNU/Linux support. |
| |
| Rich Schaefer and Peter Schauer helped with support of SunOS shared |
| libraries. |
| |
| Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about |
| several machine instruction sets. |
| |
| Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped |
| develop remote debugging. Intel Corporation, Wind River Systems, AMD, |
| and ARM contributed remote debugging modules for the i960, VxWorks, |
| A29K UDI, and RDI targets, respectively. |
| |
| Brian Fox is the author of the readline libraries providing |
| command-line editing and command history. |
| |
| Andrew Beers of SUNY Buffalo wrote the language-switching code, the |
| Modula-2 support, and contributed the Languages chapter of this manual. |
| |
| Fred Fish wrote most of the support for Unix System Vr4. He also |
| enhanced the command-completion support to cover C++ overloaded symbols. |
| |
| Hitachi America (now Renesas America), Ltd. sponsored the support for |
| H8/300, H8/500, and Super-H processors. |
| |
| NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx |
| processors. |
| |
| Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and |
| M32R/D processors. |
| |
| Toshiba sponsored the support for the TX39 Mips processor. |
| |
| Matsushita sponsored the support for the MN10200 and MN10300 |
| processors. |
| |
| Fujitsu sponsored the support for SPARClite and FR30 processors. |
| |
| Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware |
| watchpoints. |
| |
| Michael Snyder added support for tracepoints. |
| |
| Stu Grossman wrote gdbserver. |
| |
| Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly |
| innumerable bug fixes and cleanups throughout GDB. |
| |
| The following people at the Hewlett-Packard Company contributed |
| support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 |
| (narrow mode), HP's implementation of kernel threads, HP's aC++ |
| compiler, and the Text User Interface (nee Terminal User Interface): |
| Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, |
| Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase |
| provided HP-specific information in this manual. |
| |
| DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert |
| Hoehne made significant contributions to the DJGPP port. |
| |
| Cygnus Solutions has sponsored GDB maintenance and much of its |
| development since 1991. Cygnus engineers who have worked on GDB |
| fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin |
| Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim |
| Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, |
| Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek |
| Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In |
| addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, |
| JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug |
| Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff |
| Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, |
| Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin |
| Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela |
| Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David |
| Zuhn have made contributions both large and small. |
| |
| Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for |
| Cygnus Solutions, implemented the original GDB/MI interface. |
| |
| Jim Blandy added support for preprocessor macros, while working for |
| Red Hat. |
| |
| Andrew Cagney designed GDB's architecture vector. Many people |
| including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, |
| Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, |
| Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna |
| Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration |
| of old architectures to this new framework. |
| |
| Andrew Cagney completely re-designed and re-implemented GDB's |
| unwinder framework, this consisting of a fresh new design featuring |
| frame IDs, independent frame sniffers, and the sentinel frame. Mark |
| Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind |
| unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad |
| unwinders. The architecture-specific changes, each involving a |
| complete rewrite of the architecture's frame code, were carried out by |
| Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane |
| Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel |
| Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei |
| Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich |
| Weigand. |
| |
| Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from |
| Tensilica, Inc. contributed support for Xtensa processors. Others who |
| have worked on the Xtensa port of GDB in the past include Steve Tjiang, |
| John Newlin, and Scott Foehner. |
| |
| |
| File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top |
| |
| 1 A Sample GDB Session |
| ********************** |
| |
| You can use this manual at your leisure to read all about GDB. |
| However, a handful of commands are enough to get started using the |
| debugger. This chapter illustrates those commands. |
| |
| One of the preliminary versions of GNU `m4' (a generic macro |
| processor) exhibits the following bug: sometimes, when we change its |
| quote strings from the default, the commands used to capture one macro |
| definition within another stop working. In the following short `m4' |
| session, we define a macro `foo' which expands to `0000'; we then use |
| the `m4' built-in `defn' to define `bar' as the same thing. However, |
| when we change the open quote string to `<QUOTE>' and the close quote |
| string to `<UNQUOTE>', the same procedure fails to define a new synonym |
| `baz': |
| |
| $ cd gnu/m4 |
| $ ./m4 |
| define(foo,0000) |
| |
| foo |
| 0000 |
| define(bar,defn(`foo')) |
| |
| bar |
| 0000 |
| changequote(<QUOTE>,<UNQUOTE>) |
| |
| define(baz,defn(<QUOTE>foo<UNQUOTE>)) |
| baz |
| Ctrl-d |
| m4: End of input: 0: fatal error: EOF in string |
| |
| Let us use GDB to try to see what is going on. |
| |
| $ gdb m4 |
| GDB is free software and you are welcome to distribute copies |
| of it under certain conditions; type "show copying" to see |
| the conditions. |
| There is absolutely no warranty for GDB; type "show warranty" |
| for details. |
| |
| GDB 6.8, Copyright 1999 Free Software Foundation, Inc... |
| (gdb) |
| |
| GDB reads only enough symbol data to know where to find the rest when |
| needed; as a result, the first prompt comes up very quickly. We now |
| tell GDB to use a narrower display width than usual, so that examples |
| fit in this manual. |
| |
| (gdb) set width 70 |
| |
| We need to see how the `m4' built-in `changequote' works. Having |
| looked at the source, we know the relevant subroutine is |
| `m4_changequote', so we set a breakpoint there with the GDB `break' |
| command. |
| |
| (gdb) break m4_changequote |
| Breakpoint 1 at 0x62f4: file builtin.c, line 879. |
| |
| Using the `run' command, we start `m4' running under GDB control; as |
| long as control does not reach the `m4_changequote' subroutine, the |
| program runs as usual: |
| |
| (gdb) run |
| Starting program: /work/Editorial/gdb/gnu/m4/m4 |
| define(foo,0000) |
| |
| foo |
| 0000 |
| |
| To trigger the breakpoint, we call `changequote'. GDB suspends |
| execution of `m4', displaying information about the context where it |
| stops. |
| |
| changequote(<QUOTE>,<UNQUOTE>) |
| |
| Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) |
| at builtin.c:879 |
| 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) |
| |
| Now we use the command `n' (`next') to advance execution to the next |
| line of the current function. |
| |
| (gdb) n |
| 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ |
| : nil, |
| |
| `set_quotes' looks like a promising subroutine. We can go into it by |
| using the command `s' (`step') instead of `next'. `step' goes to the |
| next line to be executed in _any_ subroutine, so it steps into |
| `set_quotes'. |
| |
| (gdb) s |
| set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") |
| at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| The display that shows the subroutine where `m4' is now suspended (and |
| its arguments) is called a stack frame display. It shows a summary of |
| the stack. We can use the `backtrace' command (which can also be |
| spelled `bt'), to see where we are in the stack as a whole: the |
| `backtrace' command displays a stack frame for each active subroutine. |
| |
| (gdb) bt |
| #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") |
| at input.c:530 |
| #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) |
| at builtin.c:882 |
| #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 |
| #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) |
| at macro.c:71 |
| #4 0x79dc in expand_input () at macro.c:40 |
| #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 |
| |
| We step through a few more lines to see what happens. The first two |
| times, we can use `s'; the next two times we use `n' to avoid falling |
| into the `xstrdup' subroutine. |
| |
| (gdb) s |
| 0x3b5c 532 if (rquote != def_rquote) |
| (gdb) s |
| 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ |
| def_lquote : xstrdup(lq); |
| (gdb) n |
| 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ |
| : xstrdup(rq); |
| (gdb) n |
| 538 len_lquote = strlen(rquote); |
| |
| The last line displayed looks a little odd; we can examine the variables |
| `lquote' and `rquote' to see if they are in fact the new left and right |
| quotes we specified. We use the command `p' (`print') to see their |
| values. |
| |
| (gdb) p lquote |
| $1 = 0x35d40 "<QUOTE>" |
| (gdb) p rquote |
| $2 = 0x35d50 "<UNQUOTE>" |
| |
| `lquote' and `rquote' are indeed the new left and right quotes. To |
| look at some context, we can display ten lines of source surrounding |
| the current line with the `l' (`list') command. |
| |
| (gdb) l |
| 533 xfree(rquote); |
| 534 |
| 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ |
| : xstrdup (lq); |
| 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ |
| : xstrdup (rq); |
| 537 |
| 538 len_lquote = strlen(rquote); |
| 539 len_rquote = strlen(lquote); |
| 540 } |
| 541 |
| 542 void |
| |
| Let us step past the two lines that set `len_lquote' and `len_rquote', |
| and then examine the values of those variables. |
| |
| (gdb) n |
| 539 len_rquote = strlen(lquote); |
| (gdb) n |
| 540 } |
| (gdb) p len_lquote |
| $3 = 9 |
| (gdb) p len_rquote |
| $4 = 7 |
| |
| That certainly looks wrong, assuming `len_lquote' and `len_rquote' are |
| meant to be the lengths of `lquote' and `rquote' respectively. We can |
| set them to better values using the `p' command, since it can print the |
| value of any expression--and that expression can include subroutine |
| calls and assignments. |
| |
| (gdb) p len_lquote=strlen(lquote) |
| $5 = 7 |
| (gdb) p len_rquote=strlen(rquote) |
| $6 = 9 |
| |
| Is that enough to fix the problem of using the new quotes with the `m4' |
| built-in `defn'? We can allow `m4' to continue executing with the `c' |
| (`continue') command, and then try the example that caused trouble |
| initially: |
| |
| (gdb) c |
| Continuing. |
| |
| define(baz,defn(<QUOTE>foo<UNQUOTE>)) |
| |
| baz |
| 0000 |
| |
| Success! The new quotes now work just as well as the default ones. The |
| problem seems to have been just the two typos defining the wrong |
| lengths. We allow `m4' exit by giving it an EOF as input: |
| |
| Ctrl-d |
| Program exited normally. |
| |
| The message `Program exited normally.' is from GDB; it indicates `m4' |
| has finished executing. We can end our GDB session with the GDB `quit' |
| command. |
| |
| (gdb) quit |
| |
| |
| File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top |
| |
| 2 Getting In and Out of GDB |
| *************************** |
| |
| This chapter discusses how to start GDB, and how to get out of it. The |
| essentials are: |
| * type `gdb' to start GDB. |
| |
| * type `quit' or `Ctrl-d' to exit. |
| |
| * Menu: |
| |
| * Invoking GDB:: How to start GDB |
| * Quitting GDB:: How to quit GDB |
| * Shell Commands:: How to use shell commands inside GDB |
| * Logging Output:: How to log GDB's output to a file |
| |
| |
| File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation |
| |
| 2.1 Invoking GDB |
| ================ |
| |
| Invoke GDB by running the program `gdb'. Once started, GDB reads |
| commands from the terminal until you tell it to exit. |
| |
| You can also run `gdb' with a variety of arguments and options, to |
| specify more of your debugging environment at the outset. |
| |
| The command-line options described here are designed to cover a |
| variety of situations; in some environments, some of these options may |
| effectively be unavailable. |
| |
| The most usual way to start GDB is with one argument, specifying an |
| executable program: |
| |
| gdb PROGRAM |
| |
| You can also start with both an executable program and a core file |
| specified: |
| |
| gdb PROGRAM CORE |
| |
| You can, instead, specify a process ID as a second argument, if you |
| want to debug a running process: |
| |
| gdb PROGRAM 1234 |
| |
| would attach GDB to process `1234' (unless you also have a file named |
| `1234'; GDB does check for a core file first). |
| |
| Taking advantage of the second command-line argument requires a |
| fairly complete operating system; when you use GDB as a remote debugger |
| attached to a bare board, there may not be any notion of "process", and |
| there is often no way to get a core dump. GDB will warn you if it is |
| unable to attach or to read core dumps. |
| |
| You can optionally have `gdb' pass any arguments after the |
| executable file to the inferior using `--args'. This option stops |
| option processing. |
| gdb --args gcc -O2 -c foo.c |
| This will cause `gdb' to debug `gcc', and to set `gcc''s |
| command-line arguments (*note Arguments::) to `-O2 -c foo.c'. |
| |
| You can run `gdb' without printing the front material, which |
| describes GDB's non-warranty, by specifying `-silent': |
| |
| gdb -silent |
| |
| You can further control how GDB starts up by using command-line |
| options. GDB itself can remind you of the options available. |
| |
| Type |
| |
| gdb -help |
| |
| to display all available options and briefly describe their use (`gdb |
| -h' is a shorter equivalent). |
| |
| All options and command line arguments you give are processed in |
| sequential order. The order makes a difference when the `-x' option is |
| used. |
| |
| * Menu: |
| |
| * File Options:: Choosing files |
| * Mode Options:: Choosing modes |
| * Startup:: What GDB does during startup |
| |
| |
| File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB |
| |
| 2.1.1 Choosing Files |
| -------------------- |
| |
| When GDB starts, it reads any arguments other than options as |
| specifying an executable file and core file (or process ID). This is |
| the same as if the arguments were specified by the `-se' and `-c' (or |
| `-p') options respectively. (GDB reads the first argument that does |
| not have an associated option flag as equivalent to the `-se' option |
| followed by that argument; and the second argument that does not have |
| an associated option flag, if any, as equivalent to the `-c'/`-p' |
| option followed by that argument.) If the second argument begins with |
| a decimal digit, GDB will first attempt to attach to it as a process, |
| and if that fails, attempt to open it as a corefile. If you have a |
| corefile whose name begins with a digit, you can prevent GDB from |
| treating it as a pid by prefixing it with `./', e.g. `./12345'. |
| |
| If GDB has not been configured to included core file support, such |
| as for most embedded targets, then it will complain about a second |
| argument and ignore it. |
| |
| Many options have both long and short forms; both are shown in the |
| following list. GDB also recognizes the long forms if you truncate |
| them, so long as enough of the option is present to be unambiguous. |
| (If you prefer, you can flag option arguments with `--' rather than |
| `-', though we illustrate the more usual convention.) |
| |
| `-symbols FILE' |
| `-s FILE' |
| Read symbol table from file FILE. |
| |
| `-exec FILE' |
| `-e FILE' |
| Use file FILE as the executable file to execute when appropriate, |
| and for examining pure data in conjunction with a core dump. |
| |
| `-se FILE' |
| Read symbol table from file FILE and use it as the executable file. |
| |
| `-core FILE' |
| `-c FILE' |
| Use file FILE as a core dump to examine. |
| |
| `-pid NUMBER' |
| `-p NUMBER' |
| Connect to process ID NUMBER, as with the `attach' command. |
| |
| `-command FILE' |
| `-x FILE' |
| Execute GDB commands from file FILE. *Note Command files: Command |
| Files. |
| |
| `-eval-command COMMAND' |
| `-ex COMMAND' |
| Execute a single GDB command. |
| |
| This option may be used multiple times to call multiple commands. |
| It may also be interleaved with `-command' as required. |
| |
| gdb -ex 'target sim' -ex 'load' \ |
| -x setbreakpoints -ex 'run' a.out |
| |
| `-directory DIRECTORY' |
| `-d DIRECTORY' |
| Add DIRECTORY to the path to search for source and script files. |
| |
| `-r' |
| `-readnow' |
| Read each symbol file's entire symbol table immediately, rather |
| than the default, which is to read it incrementally as it is |
| needed. This makes startup slower, but makes future operations |
| faster. |
| |
| |
| |
| File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB |
| |
| 2.1.2 Choosing Modes |
| -------------------- |
| |
| You can run GDB in various alternative modes--for example, in batch |
| mode or quiet mode. |
| |
| `-nx' |
| `-n' |
| Do not execute commands found in any initialization files. |
| Normally, GDB executes the commands in these files after all the |
| command options and arguments have been processed. *Note Command |
| Files: Command Files. |
| |
| `-quiet' |
| `-silent' |
| `-q' |
| "Quiet". Do not print the introductory and copyright messages. |
| These messages are also suppressed in batch mode. |
| |
| `-batch' |
| Run in batch mode. Exit with status `0' after processing all the |
| command files specified with `-x' (and all commands from |
| initialization files, if not inhibited with `-n'). Exit with |
| nonzero status if an error occurs in executing the GDB commands in |
| the command files. |
| |
| Batch mode may be useful for running GDB as a filter, for example |
| to download and run a program on another computer; in order to |
| make this more useful, the message |
| |
| Program exited normally. |
| |
| (which is ordinarily issued whenever a program running under GDB |
| control terminates) is not issued when running in batch mode. |
| |
| `-batch-silent' |
| Run in batch mode exactly like `-batch', but totally silently. All |
| GDB output to `stdout' is prevented (`stderr' is unaffected). |
| This is much quieter than `-silent' and would be useless for an |
| interactive session. |
| |
| This is particularly useful when using targets that give `Loading |
| section' messages, for example. |
| |
| Note that targets that give their output via GDB, as opposed to |
| writing directly to `stdout', will also be made silent. |
| |
| `-return-child-result' |
| The return code from GDB will be the return code from the child |
| process (the process being debugged), with the following |
| exceptions: |
| |
| * GDB exits abnormally. E.g., due to an incorrect argument or |
| an internal error. In this case the exit code is the same as |
| it would have been without `-return-child-result'. |
| |
| * The user quits with an explicit value. E.g., `quit 1'. |
| |
| * The child process never runs, or is not allowed to terminate, |
| in which case the exit code will be -1. |
| |
| This option is useful in conjunction with `-batch' or |
| `-batch-silent', when GDB is being used as a remote program loader |
| or simulator interface. |
| |
| `-nowindows' |
| `-nw' |
| "No windows". If GDB comes with a graphical user interface (GUI) |
| built in, then this option tells GDB to only use the command-line |
| interface. If no GUI is available, this option has no effect. |
| |
| `-windows' |
| `-w' |
| If GDB includes a GUI, then this option requires it to be used if |
| possible. |
| |
| `-cd DIRECTORY' |
| Run GDB using DIRECTORY as its working directory, instead of the |
| current directory. |
| |
| `-fullname' |
| `-f' |
| GNU Emacs sets this option when it runs GDB as a subprocess. It |
| tells GDB to output the full file name and line number in a |
| standard, recognizable fashion each time a stack frame is |
| displayed (which includes each time your program stops). This |
| recognizable format looks like two `\032' characters, followed by |
| the file name, line number and character position separated by |
| colons, and a newline. The Emacs-to-GDB interface program uses |
| the two `\032' characters as a signal to display the source code |
| for the frame. |
| |
| `-epoch' |
| The Epoch Emacs-GDB interface sets this option when it runs GDB as |
| a subprocess. It tells GDB to modify its print routines so as to |
| allow Epoch to display values of expressions in a separate window. |
| |
| `-annotate LEVEL' |
| This option sets the "annotation level" inside GDB. Its effect is |
| identical to using `set annotate LEVEL' (*note Annotations::). |
| The annotation LEVEL controls how much information GDB prints |
| together with its prompt, values of expressions, source lines, and |
| other types of output. Level 0 is the normal, level 1 is for use |
| when GDB is run as a subprocess of GNU Emacs, level 3 is the |
| maximum annotation suitable for programs that control GDB, and |
| level 2 has been deprecated. |
| |
| The annotation mechanism has largely been superseded by GDB/MI |
| (*note GDB/MI::). |
| |
| `--args' |
| Change interpretation of command line so that arguments following |
| the executable file are passed as command line arguments to the |
| inferior. This option stops option processing. |
| |
| `-baud BPS' |
| `-b BPS' |
| Set the line speed (baud rate or bits per second) of any serial |
| interface used by GDB for remote debugging. |
| |
| `-l TIMEOUT' |
| Set the timeout (in seconds) of any communication used by GDB for |
| remote debugging. |
| |
| `-tty DEVICE' |
| `-t DEVICE' |
| Run using DEVICE for your program's standard input and output. |
| |
| `-tui' |
| Activate the "Text User Interface" when starting. The Text User |
| Interface manages several text windows on the terminal, showing |
| source, assembly, registers and GDB command outputs (*note GDB |
| Text User Interface: TUI.). Alternatively, the Text User |
| Interface can be enabled by invoking the program `gdbtui'. Do not |
| use this option if you run GDB from Emacs (*note Using GDB under |
| GNU Emacs: Emacs.). |
| |
| `-interpreter INTERP' |
| Use the interpreter INTERP for interface with the controlling |
| program or device. This option is meant to be set by programs |
| which communicate with GDB using it as a back end. *Note Command |
| Interpreters: Interpreters. |
| |
| `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the |
| "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included |
| since GDB version 6.0. The previous GDB/MI interface, included in |
| GDB version 5.3 and selected with `--interpreter=mi1', is |
| deprecated. Earlier GDB/MI interfaces are no longer supported. |
| |
| `-write' |
| Open the executable and core files for both reading and writing. |
| This is equivalent to the `set write on' command inside GDB (*note |
| Patching::). |
| |
| `-statistics' |
| This option causes GDB to print statistics about time and memory |
| usage after it completes each command and returns to the prompt. |
| |
| `-version' |
| This option causes GDB to print its version number and no-warranty |
| blurb, and exit. |
| |
| |
| |
| File: gdb.info, Node: Startup, Prev: Mode Options, Up: Invoking GDB |
| |
| 2.1.3 What GDB Does During Startup |
| ---------------------------------- |
| |
| Here's the description of what GDB does during session startup: |
| |
| 1. Sets up the command interpreter as specified by the command line |
| (*note interpreter: Mode Options.). |
| |
| 2. Reads the "init file" (if any) in your home directory(1) and |
| executes all the commands in that file. |
| |
| 3. Processes command line options and operands. |
| |
| 4. Reads and executes the commands from init file (if any) in the |
| current working directory. This is only done if the current |
| directory is different from your home directory. Thus, you can |
| have more than one init file, one generic in your home directory, |
| and another, specific to the program you are debugging, in the |
| directory where you invoke GDB. |
| |
| 5. Reads command files specified by the `-x' option. *Note Command |
| Files::, for more details about GDB command files. |
| |
| 6. Reads the command history recorded in the "history file". *Note |
| Command History::, for more details about the command history and |
| the files where GDB records it. |
| |
| Init files use the same syntax as "command files" (*note Command |
| Files::) and are processed by GDB in the same way. The init file in |
| your home directory can set options (such as `set complaints') that |
| affect subsequent processing of command line options and operands. |
| Init files are not executed if you use the `-nx' option (*note Choosing |
| Modes: Mode Options.). |
| |
| The GDB init files are normally called `.gdbinit'. The DJGPP port |
| of GDB uses the name `gdb.ini', due to the limitations of file names |
| imposed by DOS filesystems. The Windows ports of GDB use the standard |
| name, but if they find a `gdb.ini' file, they warn you about that and |
| suggest to rename the file to the standard name. |
| |
| ---------- Footnotes ---------- |
| |
| (1) On DOS/Windows systems, the home directory is the one pointed to |
| by the `HOME' environment variable. |
| |
| |
| File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation |
| |
| 2.2 Quitting GDB |
| ================ |
| |
| `quit [EXPRESSION]' |
| `q' |
| To exit GDB, use the `quit' command (abbreviated `q'), or type an |
| end-of-file character (usually `Ctrl-d'). If you do not supply |
| EXPRESSION, GDB will terminate normally; otherwise it will |
| terminate using the result of EXPRESSION as the error code. |
| |
| An interrupt (often `Ctrl-c') does not exit from GDB, but rather |
| terminates the action of any GDB command that is in progress and |
| returns to GDB command level. It is safe to type the interrupt |
| character at any time because GDB does not allow it to take effect |
| until a time when it is safe. |
| |
| If you have been using GDB to control an attached process or device, |
| you can release it with the `detach' command (*note Debugging an |
| Already-running Process: Attach.). |
| |
| |
| File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation |
| |
| 2.3 Shell Commands |
| ================== |
| |
| If you need to execute occasional shell commands during your debugging |
| session, there is no need to leave or suspend GDB; you can just use the |
| `shell' command. |
| |
| `shell COMMAND STRING' |
| Invoke a standard shell to execute COMMAND STRING. If it exists, |
| the environment variable `SHELL' determines which shell to run. |
| Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, |
| `COMMAND.COM' on MS-DOS, etc.). |
| |
| The utility `make' is often needed in development environments. You |
| do not have to use the `shell' command for this purpose in GDB: |
| |
| `make MAKE-ARGS' |
| Execute the `make' program with the specified arguments. This is |
| equivalent to `shell make MAKE-ARGS'. |
| |
| |
| File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation |
| |
| 2.4 Logging Output |
| ================== |
| |
| You may want to save the output of GDB commands to a file. There are |
| several commands to control GDB's logging. |
| |
| `set logging on' |
| Enable logging. |
| |
| `set logging off' |
| Disable logging. |
| |
| `set logging file FILE' |
| Change the name of the current logfile. The default logfile is |
| `gdb.txt'. |
| |
| `set logging overwrite [on|off]' |
| By default, GDB will append to the logfile. Set `overwrite' if |
| you want `set logging on' to overwrite the logfile instead. |
| |
| `set logging redirect [on|off]' |
| By default, GDB output will go to both the terminal and the |
| logfile. Set `redirect' if you want output to go only to the log |
| file. |
| |
| `show logging' |
| Show the current values of the logging settings. |
| |
| |
| File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top |
| |
| 3 GDB Commands |
| ************** |
| |
| You can abbreviate a GDB command to the first few letters of the command |
| name, if that abbreviation is unambiguous; and you can repeat certain |
| GDB commands by typing just <RET>. You can also use the <TAB> key to |
| get GDB to fill out the rest of a word in a command (or to show you the |
| alternatives available, if there is more than one possibility). |
| |
| * Menu: |
| |
| * Command Syntax:: How to give commands to GDB |
| * Completion:: Command completion |
| * Help:: How to ask GDB for help |
| |
| |
| File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands |
| |
| 3.1 Command Syntax |
| ================== |
| |
| A GDB command is a single line of input. There is no limit on how long |
| it can be. It starts with a command name, which is followed by |
| arguments whose meaning depends on the command name. For example, the |
| command `step' accepts an argument which is the number of times to |
| step, as in `step 5'. You can also use the `step' command with no |
| arguments. Some commands do not allow any arguments. |
| |
| GDB command names may always be truncated if that abbreviation is |
| unambiguous. Other possible command abbreviations are listed in the |
| documentation for individual commands. In some cases, even ambiguous |
| abbreviations are allowed; for example, `s' is specially defined as |
| equivalent to `step' even though there are other commands whose names |
| start with `s'. You can test abbreviations by using them as arguments |
| to the `help' command. |
| |
| A blank line as input to GDB (typing just <RET>) means to repeat the |
| previous command. Certain commands (for example, `run') will not |
| repeat this way; these are commands whose unintentional repetition |
| might cause trouble and which you are unlikely to want to repeat. |
| User-defined commands can disable this feature; see *Note dont-repeat: |
| Define. |
| |
| The `list' and `x' commands, when you repeat them with <RET>, |
| construct new arguments rather than repeating exactly as typed. This |
| permits easy scanning of source or memory. |
| |
| GDB can also use <RET> in another way: to partition lengthy output, |
| in a way similar to the common utility `more' (*note Screen Size: |
| Screen Size.). Since it is easy to press one <RET> too many in this |
| situation, GDB disables command repetition after any command that |
| generates this sort of display. |
| |
| Any text from a `#' to the end of the line is a comment; it does |
| nothing. This is useful mainly in command files (*note Command Files: |
| Command Files.). |
| |
| The `Ctrl-o' binding is useful for repeating a complex sequence of |
| commands. This command accepts the current line, like <RET>, and then |
| fetches the next line relative to the current line from the history for |
| editing. |
| |
| |
| File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands |
| |
| 3.2 Command Completion |
| ====================== |
| |
| GDB can fill in the rest of a word in a command for you, if there is |
| only one possibility; it can also show you what the valid possibilities |
| are for the next word in a command, at any time. This works for GDB |
| commands, GDB subcommands, and the names of symbols in your program. |
| |
| Press the <TAB> key whenever you want GDB to fill out the rest of a |
| word. If there is only one possibility, GDB fills in the word, and |
| waits for you to finish the command (or press <RET> to enter it). For |
| example, if you type |
| |
| (gdb) info bre <TAB> |
| |
| GDB fills in the rest of the word `breakpoints', since that is the only |
| `info' subcommand beginning with `bre': |
| |
| (gdb) info breakpoints |
| |
| You can either press <RET> at this point, to run the `info breakpoints' |
| command, or backspace and enter something else, if `breakpoints' does |
| not look like the command you expected. (If you were sure you wanted |
| `info breakpoints' in the first place, you might as well just type |
| <RET> immediately after `info bre', to exploit command abbreviations |
| rather than command completion). |
| |
| If there is more than one possibility for the next word when you |
| press <TAB>, GDB sounds a bell. You can either supply more characters |
| and try again, or just press <TAB> a second time; GDB displays all the |
| possible completions for that word. For example, you might want to set |
| a breakpoint on a subroutine whose name begins with `make_', but when |
| you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again |
| displays all the function names in your program that begin with those |
| characters, for example: |
| |
| (gdb) b make_ <TAB> |
| GDB sounds bell; press <TAB> again, to see: |
| make_a_section_from_file make_environ |
| make_abs_section make_function_type |
| make_blockvector make_pointer_type |
| make_cleanup make_reference_type |
| make_command make_symbol_completion_list |
| (gdb) b make_ |
| |
| After displaying the available possibilities, GDB copies your partial |
| input (`b make_' in the example) so you can finish the command. |
| |
| If you just want to see the list of alternatives in the first place, |
| you can press `M-?' rather than pressing <TAB> twice. `M-?' means |
| `<META> ?'. You can type this either by holding down a key designated |
| as the <META> shift on your keyboard (if there is one) while typing |
| `?', or as <ESC> followed by `?'. |
| |
| Sometimes the string you need, while logically a "word", may contain |
| parentheses or other characters that GDB normally excludes from its |
| notion of a word. To permit word completion to work in this situation, |
| you may enclose words in `'' (single quote marks) in GDB commands. |
| |
| The most likely situation where you might need this is in typing the |
| name of a C++ function. This is because C++ allows function |
| overloading (multiple definitions of the same function, distinguished |
| by argument type). For example, when you want to set a breakpoint you |
| may need to distinguish whether you mean the version of `name' that |
| takes an `int' parameter, `name(int)', or the version that takes a |
| `float' parameter, `name(float)'. To use the word-completion |
| facilities in this situation, type a single quote `'' at the beginning |
| of the function name. This alerts GDB that it may need to consider |
| more information than usual when you press <TAB> or `M-?' to request |
| word completion: |
| |
| (gdb) b 'bubble( M-? |
| bubble(double,double) bubble(int,int) |
| (gdb) b 'bubble( |
| |
| In some cases, GDB can tell that completing a name requires using |
| quotes. When this happens, GDB inserts the quote for you (while |
| completing as much as it can) if you do not type the quote in the first |
| place: |
| |
| (gdb) b bub <TAB> |
| GDB alters your input line to the following, and rings a bell: |
| (gdb) b 'bubble( |
| |
| In general, GDB can tell that a quote is needed (and inserts it) if you |
| have not yet started typing the argument list when you ask for |
| completion on an overloaded symbol. |
| |
| For more information about overloaded functions, see *Note C++ |
| Expressions: C Plus Plus Expressions. You can use the command `set |
| overload-resolution off' to disable overload resolution; see *Note GDB |
| Features for C++: Debugging C Plus Plus. |
| |
| |
| File: gdb.info, Node: Help, Prev: Completion, Up: Commands |
| |
| 3.3 Getting Help |
| ================ |
| |
| You can always ask GDB itself for information on its commands, using |
| the command `help'. |
| |
| `help' |
| `h' |
| You can use `help' (abbreviated `h') with no arguments to display |
| a short list of named classes of commands: |
| |
| (gdb) help |
| List of classes of commands: |
| |
| aliases -- Aliases of other commands |
| breakpoints -- Making program stop at certain points |
| data -- Examining data |
| files -- Specifying and examining files |
| internals -- Maintenance commands |
| obscure -- Obscure features |
| running -- Running the program |
| stack -- Examining the stack |
| status -- Status inquiries |
| support -- Support facilities |
| tracepoints -- Tracing of program execution without |
| stopping the program |
| user-defined -- User-defined commands |
| |
| Type "help" followed by a class name for a list of |
| commands in that class. |
| Type "help" followed by command name for full |
| documentation. |
| Command name abbreviations are allowed if unambiguous. |
| (gdb) |
| |
| `help CLASS' |
| Using one of the general help classes as an argument, you can get a |
| list of the individual commands in that class. For example, here |
| is the help display for the class `status': |
| |
| (gdb) help status |
| Status inquiries. |
| |
| List of commands: |
| |
| info -- Generic command for showing things |
| about the program being debugged |
| show -- Generic command for showing things |
| about the debugger |
| |
| Type "help" followed by command name for full |
| documentation. |
| Command name abbreviations are allowed if unambiguous. |
| (gdb) |
| |
| `help COMMAND' |
| With a command name as `help' argument, GDB displays a short |
| paragraph on how to use that command. |
| |
| `apropos ARGS' |
| The `apropos' command searches through all of the GDB commands, |
| and their documentation, for the regular expression specified in |
| ARGS. It prints out all matches found. For example: |
| |
| apropos reload |
| |
| results in: |
| |
| set symbol-reloading -- Set dynamic symbol table reloading |
| multiple times in one run |
| show symbol-reloading -- Show dynamic symbol table reloading |
| multiple times in one run |
| |
| `complete ARGS' |
| The `complete ARGS' command lists all the possible completions for |
| the beginning of a command. Use ARGS to specify the beginning of |
| the command you want completed. For example: |
| |
| complete i |
| |
| results in: |
| |
| if |
| ignore |
| info |
| inspect |
| |
| This is intended for use by GNU Emacs. |
| |
| In addition to `help', you can use the GDB commands `info' and |
| `show' to inquire about the state of your program, or the state of GDB |
| itself. Each command supports many topics of inquiry; this manual |
| introduces each of them in the appropriate context. The listings under |
| `info' and under `show' in the Index point to all the sub-commands. |
| *Note Index::. |
| |
| `info' |
| This command (abbreviated `i') is for describing the state of your |
| program. For example, you can show the arguments passed to a |
| function with `info args', list the registers currently in use |
| with `info registers', or list the breakpoints you have set with |
| `info breakpoints'. You can get a complete list of the `info' |
| sub-commands with `help info'. |
| |
| `set' |
| You can assign the result of an expression to an environment |
| variable with `set'. For example, you can set the GDB prompt to a |
| $-sign with `set prompt $'. |
| |
| `show' |
| In contrast to `info', `show' is for describing the state of GDB |
| itself. You can change most of the things you can `show', by |
| using the related command `set'; for example, you can control what |
| number system is used for displays with `set radix', or simply |
| inquire which is currently in use with `show radix'. |
| |
| To display all the settable parameters and their current values, |
| you can use `show' with no arguments; you may also use `info set'. |
| Both commands produce the same display. |
| |
| Here are three miscellaneous `show' subcommands, all of which are |
| exceptional in lacking corresponding `set' commands: |
| |
| `show version' |
| Show what version of GDB is running. You should include this |
| information in GDB bug-reports. If multiple versions of GDB are |
| in use at your site, you may need to determine which version of |
| GDB you are running; as GDB evolves, new commands are introduced, |
| and old ones may wither away. Also, many system vendors ship |
| variant versions of GDB, and there are variant versions of GDB in |
| GNU/Linux distributions as well. The version number is the same |
| as the one announced when you start GDB. |
| |
| `show copying' |
| `info copying' |
| Display information about permission for copying GDB. |
| |
| `show warranty' |
| `info warranty' |
| Display the GNU "NO WARRANTY" statement, or a warranty, if your |
| version of GDB comes with one. |
| |
| |
| |
| File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top |
| |
| 4 Running Programs Under GDB |
| **************************** |
| |
| When you run a program under GDB, you must first generate debugging |
| information when you compile it. |
| |
| You may start GDB with its arguments, if any, in an environment of |
| your choice. If you are doing native debugging, you may redirect your |
| program's input and output, debug an already running process, or kill a |
| child process. |
| |
| * Menu: |
| |
| * Compilation:: Compiling for debugging |
| * Starting:: Starting your program |
| * Arguments:: Your program's arguments |
| * Environment:: Your program's environment |
| |
| * Working Directory:: Your program's working directory |
| * Input/Output:: Your program's input and output |
| * Attach:: Debugging an already-running process |
| * Kill Process:: Killing the child process |
| |
| * Threads:: Debugging programs with multiple threads |
| * Processes:: Debugging programs with multiple processes |
| * Checkpoint/Restart:: Setting a _bookmark_ to return to later |
| |
| |
| File: gdb.info, Node: Compilation, Next: Starting, Up: Running |
| |
| 4.1 Compiling for Debugging |
| =========================== |
| |
| In order to debug a program effectively, you need to generate debugging |
| information when you compile it. This debugging information is stored |
| in the object file; it describes the data type of each variable or |
| function and the correspondence between source line numbers and |
| addresses in the executable code. |
| |
| To request debugging information, specify the `-g' option when you |
| run the compiler. |
| |
| Programs that are to be shipped to your customers are compiled with |
| optimizations, using the `-O' compiler option. However, many compilers |
| are unable to handle the `-g' and `-O' options together. Using those |
| compilers, you cannot generate optimized executables containing |
| debugging information. |
| |
| GCC, the GNU C/C++ compiler, supports `-g' with or without `-O', |
| making it possible to debug optimized code. We recommend that you |
| _always_ use `-g' whenever you compile a program. You may think your |
| program is correct, but there is no sense in pushing your luck. |
| |
| When you debug a program compiled with `-g -O', remember that the |
| optimizer is rearranging your code; the debugger shows you what is |
| really there. Do not be too surprised when the execution path does not |
| exactly match your source file! An extreme example: if you define a |
| variable, but never use it, GDB never sees that variable--because the |
| compiler optimizes it out of existence. |
| |
| Some things do not work as well with `-g -O' as with just `-g', |
| particularly on machines with instruction scheduling. If in doubt, |
| recompile with `-g' alone, and if this fixes the problem, please report |
| it to us as a bug (including a test case!). *Note Variables::, for |
| more information about debugging optimized code. |
| |
| Older versions of the GNU C compiler permitted a variant option |
| `-gg' for debugging information. GDB no longer supports this format; |
| if your GNU C compiler has this option, do not use it. |
| |
| GDB knows about preprocessor macros and can show you their expansion |
| (*note Macros::). Most compilers do not include information about |
| preprocessor macros in the debugging information if you specify the |
| `-g' flag alone, because this information is rather large. Version 3.1 |
| and later of GCC, the GNU C compiler, provides macro information if you |
| specify the options `-gdwarf-2' and `-g3'; the former option requests |
| debugging information in the Dwarf 2 format, and the latter requests |
| "extra information". In the future, we hope to find more compact ways |
| to represent macro information, so that it can be included with `-g' |
| alone. |
| |
| |
| File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running |
| |
| 4.2 Starting your Program |
| ========================= |
| |
| `run' |
| `r' |
| Use the `run' command to start your program under GDB. You must |
| first specify the program name (except on VxWorks) with an |
| argument to GDB (*note Getting In and Out of GDB: Invocation.), or |
| by using the `file' or `exec-file' command (*note Commands to |
| Specify Files: Files.). |
| |
| |
| If you are running your program in an execution environment that |
| supports processes, `run' creates an inferior process and makes that |
| process run your program. (In environments without processes, `run' |
| jumps to the start of your program.) |
| |
| The execution of a program is affected by certain information it |
| receives from its superior. GDB provides ways to specify this |
| information, which you must do _before_ starting your program. (You |
| can change it after starting your program, but such changes only affect |
| your program the next time you start it.) This information may be |
| divided into four categories: |
| |
| The _arguments._ |
| Specify the arguments to give your program as the arguments of the |
| `run' command. If a shell is available on your target, the shell |
| is used to pass the arguments, so that you may use normal |
| conventions (such as wildcard expansion or variable substitution) |
| in describing the arguments. In Unix systems, you can control |
| which shell is used with the `SHELL' environment variable. *Note |
| Your Program's Arguments: Arguments. |
| |
| The _environment._ |
| Your program normally inherits its environment from GDB, but you |
| can use the GDB commands `set environment' and `unset environment' |
| to change parts of the environment that affect your program. |
| *Note Your Program's Environment: Environment. |
| |
| The _working directory._ |
| Your program inherits its working directory from GDB. You can set |
| the GDB working directory with the `cd' command in GDB. *Note |
| Your Program's Working Directory: Working Directory. |
| |
| The _standard input and output._ |
| Your program normally uses the same device for standard input and |
| standard output as GDB is using. You can redirect input and output |
| in the `run' command line, or you can use the `tty' command to set |
| a different device for your program. *Note Your Program's Input |
| and Output: Input/Output. |
| |
| _Warning:_ While input and output redirection work, you cannot use |
| pipes to pass the output of the program you are debugging to |
| another program; if you attempt this, GDB is likely to wind up |
| debugging the wrong program. |
| |
| When you issue the `run' command, your program begins to execute |
| immediately. *Note Stopping and Continuing: Stopping, for discussion |
| of how to arrange for your program to stop. Once your program has |
| stopped, you may call functions in your program, using the `print' or |
| `call' commands. *Note Examining Data: Data. |
| |
| If the modification time of your symbol file has changed since the |
| last time GDB read its symbols, GDB discards its symbol table, and |
| reads it again. When it does this, GDB tries to retain your current |
| breakpoints. |
| |
| `start' |
| The name of the main procedure can vary from language to language. |
| With C or C++, the main procedure name is always `main', but other |
| languages such as Ada do not require a specific name for their |
| main procedure. The debugger provides a convenient way to start |
| the execution of the program and to stop at the beginning of the |
| main procedure, depending on the language used. |
| |
| The `start' command does the equivalent of setting a temporary |
| breakpoint at the beginning of the main procedure and then invoking |
| the `run' command. |
| |
| Some programs contain an "elaboration" phase where some startup |
| code is executed before the main procedure is called. This |
| depends on the languages used to write your program. In C++, for |
| instance, constructors for static and global objects are executed |
| before `main' is called. It is therefore possible that the |
| debugger stops before reaching the main procedure. However, the |
| temporary breakpoint will remain to halt execution. |
| |
| Specify the arguments to give to your program as arguments to the |
| `start' command. These arguments will be given verbatim to the |
| underlying `run' command. Note that the same arguments will be |
| reused if no argument is provided during subsequent calls to |
| `start' or `run'. |
| |
| It is sometimes necessary to debug the program during elaboration. |
| In these cases, using the `start' command would stop the |
| execution of your program too late, as the program would have |
| already completed the elaboration phase. Under these |
| circumstances, insert breakpoints in your elaboration code before |
| running your program. |
| |
| |
| File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running |
| |
| 4.3 Your Program's Arguments |
| ============================ |
| |
| The arguments to your program can be specified by the arguments of the |
| `run' command. They are passed to a shell, which expands wildcard |
| characters and performs redirection of I/O, and thence to your program. |
| Your `SHELL' environment variable (if it exists) specifies what shell |
| GDB uses. If you do not define `SHELL', GDB uses the default shell |
| (`/bin/sh' on Unix). |
| |
| On non-Unix systems, the program is usually invoked directly by GDB, |
| which emulates I/O redirection via the appropriate system calls, and |
| the wildcard characters are expanded by the startup code of the |
| program, not by the shell. |
| |
| `run' with no arguments uses the same arguments used by the previous |
| `run', or those set by the `set args' command. |
| |
| `set args' |
| Specify the arguments to be used the next time your program is |
| run. If `set args' has no arguments, `run' executes your program |
| with no arguments. Once you have run your program with arguments, |
| using `set args' before the next `run' is the only way to run it |
| again without arguments. |
| |
| `show args' |
| Show the arguments to give your program when it is started. |
| |
| |
| File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running |
| |
| 4.4 Your Program's Environment |
| ============================== |
| |
| The "environment" consists of a set of environment variables and their |
| values. Environment variables conventionally record such things as |
| your user name, your home directory, your terminal type, and your search |
| path for programs to run. Usually you set up environment variables with |
| the shell and they are inherited by all the other programs you run. |
| When debugging, it can be useful to try running your program with a |
| modified environment without having to start GDB over again. |
| |
| `path DIRECTORY' |
| Add DIRECTORY to the front of the `PATH' environment variable (the |
| search path for executables) that will be passed to your program. |
| The value of `PATH' used by GDB does not change. You may specify |
| several directory names, separated by whitespace or by a |
| system-dependent separator character (`:' on Unix, `;' on MS-DOS |
| and MS-Windows). If DIRECTORY is already in the path, it is moved |
| to the front, so it is searched sooner. |
| |
| You can use the string `$cwd' to refer to whatever is the current |
| working directory at the time GDB searches the path. If you use |
| `.' instead, it refers to the directory where you executed the |
| `path' command. GDB replaces `.' in the DIRECTORY argument (with |
| the current path) before adding DIRECTORY to the search path. |
| |
| `show paths' |
| Display the list of search paths for executables (the `PATH' |
| environment variable). |
| |
| `show environment [VARNAME]' |
| Print the value of environment variable VARNAME to be given to |
| your program when it starts. If you do not supply VARNAME, print |
| the names and values of all environment variables to be given to |
| your program. You can abbreviate `environment' as `env'. |
| |
| `set environment VARNAME [=VALUE]' |
| Set environment variable VARNAME to VALUE. The value changes for |
| your program only, not for GDB itself. VALUE may be any string; |
| the values of environment variables are just strings, and any |
| interpretation is supplied by your program itself. The VALUE |
| parameter is optional; if it is eliminated, the variable is set to |
| a null value. |
| |
| For example, this command: |
| |
| set env USER = foo |
| |
| tells the debugged program, when subsequently run, that its user |
| is named `foo'. (The spaces around `=' are used for clarity here; |
| they are not actually required.) |
| |
| `unset environment VARNAME' |
| Remove variable VARNAME from the environment to be passed to your |
| program. This is different from `set env VARNAME ='; `unset |
| environment' removes the variable from the environment, rather |
| than assigning it an empty value. |
| |
| _Warning:_ On Unix systems, GDB runs your program using the shell |
| indicated by your `SHELL' environment variable if it exists (or |
| `/bin/sh' if not). If your `SHELL' variable names a shell that runs an |
| initialization file--such as `.cshrc' for C-shell, or `.bashrc' for |
| BASH--any variables you set in that file affect your program. You may |
| wish to move setting of environment variables to files that are only |
| run when you sign on, such as `.login' or `.profile'. |
| |
| |
| File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running |
| |
| 4.5 Your Program's Working Directory |
| ==================================== |
| |
| Each time you start your program with `run', it inherits its working |
| directory from the current working directory of GDB. The GDB working |
| directory is initially whatever it inherited from its parent process |
| (typically the shell), but you can specify a new working directory in |
| GDB with the `cd' command. |
| |
| The GDB working directory also serves as a default for the commands |
| that specify files for GDB to operate on. *Note Commands to Specify |
| Files: Files. |
| |
| `cd DIRECTORY' |
| Set the GDB working directory to DIRECTORY. |
| |
| `pwd' |
| Print the GDB working directory. |
| |
| It is generally impossible to find the current working directory of |
| the process being debugged (since a program can change its directory |
| during its run). If you work on a system where GDB is configured with |
| the `/proc' support, you can use the `info proc' command (*note SVR4 |
| Process Information::) to find out the current working directory of the |
| debuggee. |
| |
| |
| File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running |
| |
| 4.6 Your Program's Input and Output |
| =================================== |
| |
| By default, the program you run under GDB does input and output to the |
| same terminal that GDB uses. GDB switches the terminal to its own |
| terminal modes to interact with you, but it records the terminal modes |
| your program was using and switches back to them when you continue |
| running your program. |
| |
| `info terminal' |
| Displays information recorded by GDB about the terminal modes your |
| program is using. |
| |
| You can redirect your program's input and/or output using shell |
| redirection with the `run' command. For example, |
| |
| run > outfile |
| |
| starts your program, diverting its output to the file `outfile'. |
| |
| Another way to specify where your program should do input and output |
| is with the `tty' command. This command accepts a file name as |
| argument, and causes this file to be the default for future `run' |
| commands. It also resets the controlling terminal for the child |
| process, for future `run' commands. For example, |
| |
| tty /dev/ttyb |
| |
| directs that processes started with subsequent `run' commands default |
| to do input and output on the terminal `/dev/ttyb' and have that as |
| their controlling terminal. |
| |
| An explicit redirection in `run' overrides the `tty' command's |
| effect on the input/output device, but not its effect on the controlling |
| terminal. |
| |
| When you use the `tty' command or redirect input in the `run' |
| command, only the input _for your program_ is affected. The input for |
| GDB still comes from your terminal. `tty' is an alias for `set |
| inferior-tty'. |
| |
| You can use the `show inferior-tty' command to tell GDB to display |
| the name of the terminal that will be used for future runs of your |
| program. |
| |
| `set inferior-tty /dev/ttyb' |
| Set the tty for the program being debugged to /dev/ttyb. |
| |
| `show inferior-tty' |
| Show the current tty for the program being debugged. |
| |
| |
| File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running |
| |
| 4.7 Debugging an Already-running Process |
| ======================================== |
| |
| `attach PROCESS-ID' |
| This command attaches to a running process--one that was started |
| outside GDB. (`info files' shows your active targets.) The |
| command takes as argument a process ID. The usual way to find out |
| the PROCESS-ID of a Unix process is with the `ps' utility, or with |
| the `jobs -l' shell command. |
| |
| `attach' does not repeat if you press <RET> a second time after |
| executing the command. |
| |
| To use `attach', your program must be running in an environment |
| which supports processes; for example, `attach' does not work for |
| programs on bare-board targets that lack an operating system. You must |
| also have permission to send the process a signal. |
| |
| When you use `attach', the debugger finds the program running in the |
| process first by looking in the current working directory, then (if the |
| program is not found) by using the source file search path (*note |
| Specifying Source Directories: Source Path.). You can also use the |
| `file' command to load the program. *Note Commands to Specify Files: |
| Files. |
| |
| The first thing GDB does after arranging to debug the specified |
| process is to stop it. You can examine and modify an attached process |
| with all the GDB commands that are ordinarily available when you start |
| processes with `run'. You can insert breakpoints; you can step and |
| continue; you can modify storage. If you would rather the process |
| continue running, you may use the `continue' command after attaching |
| GDB to the process. |
| |
| `detach' |
| When you have finished debugging the attached process, you can use |
| the `detach' command to release it from GDB control. Detaching |
| the process continues its execution. After the `detach' command, |
| that process and GDB become completely independent once more, and |
| you are ready to `attach' another process or start one with `run'. |
| `detach' does not repeat if you press <RET> again after executing |
| the command. |
| |
| If you exit GDB while you have an attached process, you detach that |
| process. If you use the `run' command, you kill that process. By |
| default, GDB asks for confirmation if you try to do either of these |
| things; you can control whether or not you need to confirm by using the |
| `set confirm' command (*note Optional Warnings and Messages: |
| Messages/Warnings.). |
| |
| |
| File: gdb.info, Node: Kill Process, Next: Threads, Prev: Attach, Up: Running |
| |
| 4.8 Killing the Child Process |
| ============================= |
| |
| `kill' |
| Kill the child process in which your program is running under GDB. |
| |
| This command is useful if you wish to debug a core dump instead of a |
| running process. GDB ignores any core dump file while your program is |
| running. |
| |
| On some operating systems, a program cannot be executed outside GDB |
| while you have breakpoints set on it inside GDB. You can use the |
| `kill' command in this situation to permit running your program outside |
| the debugger. |
| |
| The `kill' command is also useful if you wish to recompile and |
| relink your program, since on many systems it is impossible to modify an |
| executable file while it is running in a process. In this case, when |
| you next type `run', GDB notices that the file has changed, and reads |
| the symbol table again (while trying to preserve your current |
| breakpoint settings). |
| |
| |
| File: gdb.info, Node: Threads, Next: Processes, Prev: Kill Process, Up: Running |
| |
| 4.9 Debugging Programs with Multiple Threads |
| ============================================ |
| |
| In some operating systems, such as HP-UX and Solaris, a single program |
| may have more than one "thread" of execution. The precise semantics of |
| threads differ from one operating system to another, but in general the |
| threads of a single program are akin to multiple processes--except that |
| they share one address space (that is, they can all examine and modify |
| the same variables). On the other hand, each thread has its own |
| registers and execution stack, and perhaps private memory. |
| |
| GDB provides these facilities for debugging multi-thread programs: |
| |
| * automatic notification of new threads |
| |
| * `thread THREADNO', a command to switch among threads |
| |
| * `info threads', a command to inquire about existing threads |
| |
| * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command |
| to a list of threads |
| |
| * thread-specific breakpoints |
| |
| * `set print thread-events', which controls printing of messages on |
| thread start and exit. |
| |
| _Warning:_ These facilities are not yet available on every GDB |
| configuration where the operating system supports threads. If |
| your GDB does not support threads, these commands have no effect. |
| For example, a system without thread support shows no output from |
| `info threads', and always rejects the `thread' command, like this: |
| |
| (gdb) info threads |
| (gdb) thread 1 |
| Thread ID 1 not known. Use the "info threads" command to |
| see the IDs of currently known threads. |
| |
| The GDB thread debugging facility allows you to observe all threads |
| while your program runs--but whenever GDB takes control, one thread in |
| particular is always the focus of debugging. This thread is called the |
| "current thread". Debugging commands show program information from the |
| perspective of the current thread. |
| |
| Whenever GDB detects a new thread in your program, it displays the |
| target system's identification for the thread with a message in the |
| form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies |
| depending on the particular system. For example, on GNU/Linux, you |
| might see |
| |
| [New Thread 46912507313328 (LWP 25582)] |
| |
| when GDB notices a new thread. In contrast, on an SGI system, the |
| SYSTAG is simply something like `process 368', with no further |
| qualifier. |
| |
| For debugging purposes, GDB associates its own thread number--always |
| a single integer--with each thread in your program. |
| |
| `info threads' |
| Display a summary of all threads currently in your program. GDB |
| displays for each thread (in this order): |
| |
| 1. the thread number assigned by GDB |
| |
| 2. the target system's thread identifier (SYSTAG) |
| |
| 3. the current stack frame summary for that thread |
| |
| An asterisk `*' to the left of the GDB thread number indicates the |
| current thread. |
| |
| For example, |
| |
| (gdb) info threads |
| 3 process 35 thread 27 0x34e5 in sigpause () |
| 2 process 35 thread 23 0x34e5 in sigpause () |
| * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) |
| at threadtest.c:68 |
| |
| On HP-UX systems: |
| |
| For debugging purposes, GDB associates its own thread number--a |
| small integer assigned in thread-creation order--with each thread in |
| your program. |
| |
| Whenever GDB detects a new thread in your program, it displays both |
| GDB's thread number and the target system's identification for the |
| thread with a message in the form `[New SYSTAG]'. SYSTAG is a thread |
| identifier whose form varies depending on the particular system. For |
| example, on HP-UX, you see |
| |
| [New thread 2 (system thread 26594)] |
| |
| when GDB notices a new thread. |
| |
| `info threads' |
| Display a summary of all threads currently in your program. GDB |
| displays for each thread (in this order): |
| |
| 1. the thread number assigned by GDB |
| |
| 2. the target system's thread identifier (SYSTAG) |
| |
| 3. the current stack frame summary for that thread |
| |
| An asterisk `*' to the left of the GDB thread number indicates the |
| current thread. |
| |
| For example, |
| |
| (gdb) info threads |
| * 3 system thread 26607 worker (wptr=0x7b09c318 "@") \ |
| |
| at quicksort.c:137 |
| 2 system thread 26606 0x7b0030d8 in __ksleep () \ |
| |
| from /usr/lib/libc.2 |
| 1 system thread 27905 0x7b003498 in _brk () \ |
| |
| from /usr/lib/libc.2 |
| |
| On Solaris, you can display more information about user threads with |
| a Solaris-specific command: |
| |
| `maint info sol-threads' |
| Display info on Solaris user threads. |
| |
| `thread THREADNO' |
| Make thread number THREADNO the current thread. The command |
| argument THREADNO is the internal GDB thread number, as shown in |
| the first field of the `info threads' display. GDB responds by |
| displaying the system identifier of the thread you selected, and |
| its current stack frame summary: |
| |
| (gdb) thread 2 |
| [Switching to process 35 thread 23] |
| 0x34e5 in sigpause () |
| |
| As with the `[New ...]' message, the form of the text after |
| `Switching to' depends on your system's conventions for identifying |
| threads. |
| |
| `thread apply [THREADNO] [ALL] COMMAND' |
| The `thread apply' command allows you to apply the named COMMAND |
| to one or more threads. Specify the numbers of the threads that |
| you want affected with the command argument THREADNO. It can be a |
| single thread number, one of the numbers shown in the first field |
| of the `info threads' display; or it could be a range of thread |
| numbers, as in `2-4'. To apply a command to all threads, type |
| `thread apply all COMMAND'. |
| |
| `set print thread-events' |
| `set print thread-events on' |
| `set print thread-events off' |
| The `set print thread-events' command allows you to enable or |
| disable printing of messages when GDB notices that new threads have |
| started or that threads have exited. By default, these messages |
| will be printed if detection of these events is supported by the |
| target. Note that these messages cannot be disabled on all |
| targets. |
| |
| `show print thread-events' |
| Show whether messages will be printed when GDB detects that threads |
| have started and exited. |
| |
| Whenever GDB stops your program, due to a breakpoint or a signal, it |
| automatically selects the thread where that breakpoint or signal |
| happened. GDB alerts you to the context switch with a message of the |
| form `[Switching to SYSTAG]' to identify the thread. |
| |
| *Note Stopping and Starting Multi-thread Programs: Thread Stops, for |
| more information about how GDB behaves when you stop and start programs |
| with multiple threads. |
| |
| *Note Setting Watchpoints: Set Watchpoints, for information about |
| watchpoints in programs with multiple threads. |
| |
| |
| File: gdb.info, Node: Processes, Next: Checkpoint/Restart, Prev: Threads, Up: Running |
| |
| 4.10 Debugging Programs with Multiple Processes |
| =============================================== |
| |
| On most systems, GDB has no special support for debugging programs |
| which create additional processes using the `fork' function. When a |
| program forks, GDB will continue to debug the parent process and the |
| child process will run unimpeded. If you have set a breakpoint in any |
| code which the child then executes, the child will get a `SIGTRAP' |
| signal which (unless it catches the signal) will cause it to terminate. |
| |
| However, if you want to debug the child process there is a workaround |
| which isn't too painful. Put a call to `sleep' in the code which the |
| child process executes after the fork. It may be useful to sleep only |
| if a certain environment variable is set, or a certain file exists, so |
| that the delay need not occur when you don't want to run GDB on the |
| child. While the child is sleeping, use the `ps' program to get its |
| process ID. Then tell GDB (a new invocation of GDB if you are also |
| debugging the parent process) to attach to the child process (*note |
| Attach::). From that point on you can debug the child process just |
| like any other process which you attached to. |
| |
| On some systems, GDB provides support for debugging programs that |
| create additional processes using the `fork' or `vfork' functions. |
| Currently, the only platforms with this feature are HP-UX (11.x and |
| later only?) and GNU/Linux (kernel version 2.5.60 and later). |
| |
| By default, when a program forks, GDB will continue to debug the |
| parent process and the child process will run unimpeded. |
| |
| If you want to follow the child process instead of the parent |
| process, use the command `set follow-fork-mode'. |
| |
| `set follow-fork-mode MODE' |
| Set the debugger response to a program call of `fork' or `vfork'. |
| A call to `fork' or `vfork' creates a new process. The MODE |
| argument can be: |
| |
| `parent' |
| The original process is debugged after a fork. The child |
| process runs unimpeded. This is the default. |
| |
| `child' |
| The new process is debugged after a fork. The parent process |
| runs unimpeded. |
| |
| |
| `show follow-fork-mode' |
| Display the current debugger response to a `fork' or `vfork' call. |
| |
| On Linux, if you want to debug both the parent and child processes, |
| use the command `set detach-on-fork'. |
| |
| `set detach-on-fork MODE' |
| Tells gdb whether to detach one of the processes after a fork, or |
| retain debugger control over them both. |
| |
| `on' |
| The child process (or parent process, depending on the value |
| of `follow-fork-mode') will be detached and allowed to run |
| independently. This is the default. |
| |
| `off' |
| Both processes will be held under the control of GDB. One |
| process (child or parent, depending on the value of |
| `follow-fork-mode') is debugged as usual, while the other is |
| held suspended. |
| |
| |
| `show detach-on-fork' |
| Show whether detach-on-fork mode is on/off. |
| |
| If you choose to set `detach-on-fork' mode off, then GDB will retain |
| control of all forked processes (including nested forks). You can list |
| the forked processes under the control of GDB by using the `info forks' |
| command, and switch from one fork to another by using the `fork' |
| command. |
| |
| `info forks' |
| Print a list of all forked processes under the control of GDB. |
| The listing will include a fork id, a process id, and the current |
| position (program counter) of the process. |
| |
| `fork FORK-ID' |
| Make fork number FORK-ID the current process. The argument |
| FORK-ID is the internal fork number assigned by GDB, as shown in |
| the first field of the `info forks' display. |
| |
| `process PROCESS-ID' |
| Make process number PROCESS-ID the current process. The argument |
| PROCESS-ID must be one that is listed in the output of `info |
| forks'. |
| |
| |
| To quit debugging one of the forked processes, you can either detach |
| from it by using the `detach fork' command (allowing it to run |
| independently), or delete (and kill) it using the `delete fork' command. |
| |
| `detach fork FORK-ID' |
| Detach from the process identified by GDB fork number FORK-ID, and |
| remove it from the fork list. The process will be allowed to run |
| independently. |
| |
| `delete fork FORK-ID' |
| Kill the process identified by GDB fork number FORK-ID, and remove |
| it from the fork list. |
| |
| |
| If you ask to debug a child process and a `vfork' is followed by an |
| `exec', GDB executes the new target up to the first breakpoint in the |
| new target. If you have a breakpoint set on `main' in your original |
| program, the breakpoint will also be set on the child process's `main'. |
| |
| When a child process is spawned by `vfork', you cannot debug the |
| child or parent until an `exec' call completes. |
| |
| If you issue a `run' command to GDB after an `exec' call executes, |
| the new target restarts. To restart the parent process, use the `file' |
| command with the parent executable name as its argument. |
| |
| You can use the `catch' command to make GDB stop whenever a `fork', |
| `vfork', or `exec' call is made. *Note Setting Catchpoints: Set |
| Catchpoints. |
| |
| |
| File: gdb.info, Node: Checkpoint/Restart, Prev: Processes, Up: Running |
| |
| 4.11 Setting a _Bookmark_ to Return to Later |
| ============================================ |
| |
| On certain operating systems(1), GDB is able to save a "snapshot" of a |
| program's state, called a "checkpoint", and come back to it later. |
| |
| Returning to a checkpoint effectively undoes everything that has |
| happened in the program since the `checkpoint' was saved. This |
| includes changes in memory, registers, and even (within some limits) |
| system state. Effectively, it is like going back in time to the moment |
| when the checkpoint was saved. |
| |
| Thus, if you're stepping thru a program and you think you're getting |
| close to the point where things go wrong, you can save a checkpoint. |
| Then, if you accidentally go too far and miss the critical statement, |
| instead of having to restart your program from the beginning, you can |
| just go back to the checkpoint and start again from there. |
| |
| This can be especially useful if it takes a lot of time or steps to |
| reach the point where you think the bug occurs. |
| |
| To use the `checkpoint'/`restart' method of debugging: |
| |
| `checkpoint' |
| Save a snapshot of the debugged program's current execution state. |
| The `checkpoint' command takes no arguments, but each checkpoint |
| is assigned a small integer id, similar to a breakpoint id. |
| |
| `info checkpoints' |
| List the checkpoints that have been saved in the current debugging |
| session. For each checkpoint, the following information will be |
| listed: |
| |
| `Checkpoint ID' |
| |
| `Process ID' |
| |
| `Code Address' |
| |
| `Source line, or label' |
| |
| `restart CHECKPOINT-ID' |
| Restore the program state that was saved as checkpoint number |
| CHECKPOINT-ID. All program variables, registers, stack frames |
| etc. will be returned to the values that they had when the |
| checkpoint was saved. In essence, gdb will "wind back the clock" |
| to the point in time when the checkpoint was saved. |
| |
| Note that breakpoints, GDB variables, command history etc. are |
| not affected by restoring a checkpoint. In general, a checkpoint |
| only restores things that reside in the program being debugged, |
| not in the debugger. |
| |
| `delete checkpoint CHECKPOINT-ID' |
| Delete the previously-saved checkpoint identified by CHECKPOINT-ID. |
| |
| |
| Returning to a previously saved checkpoint will restore the user |
| state of the program being debugged, plus a significant subset of the |
| system (OS) state, including file pointers. It won't "un-write" data |
| from a file, but it will rewind the file pointer to the previous |
| location, so that the previously written data can be overwritten. For |
| files opened in read mode, the pointer will also be restored so that the |
| previously read data can be read again. |
| |
| Of course, characters that have been sent to a printer (or other |
| external device) cannot be "snatched back", and characters received |
| from eg. a serial device can be removed from internal program buffers, |
| but they cannot be "pushed back" into the serial pipeline, ready to be |
| received again. Similarly, the actual contents of files that have been |
| changed cannot be restored (at this time). |
| |
| However, within those constraints, you actually can "rewind" your |
| program to a previously saved point in time, and begin debugging it |
| again -- and you can change the course of events so as to debug a |
| different execution path this time. |
| |
| Finally, there is one bit of internal program state that will be |
| different when you return to a checkpoint -- the program's process id. |
| Each checkpoint will have a unique process id (or PID), and each will |
| be different from the program's original PID. If your program has |
| saved a local copy of its process id, this could potentially pose a |
| problem. |
| |
| 4.11.1 A Non-obvious Benefit of Using Checkpoints |
| ------------------------------------------------- |
| |
| On some systems such as GNU/Linux, address space randomization is |
| performed on new processes for security reasons. This makes it |
| difficult or impossible to set a breakpoint, or watchpoint, on an |
| absolute address if you have to restart the program, since the absolute |
| location of a symbol will change from one execution to the next. |
| |
| A checkpoint, however, is an _identical_ copy of a process. |
| Therefore if you create a checkpoint at (eg.) the start of main, and |
| simply return to that checkpoint instead of restarting the process, you |
| can avoid the effects of address randomization and your symbols will |
| all stay in the same place. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Currently, only GNU/Linux. |
| |
| |
| File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top |
| |
| 5 Stopping and Continuing |
| ************************* |
| |
| The principal purposes of using a debugger are so that you can stop your |
| program before it terminates; or so that, if your program runs into |
| trouble, you can investigate and find out why. |
| |
| Inside GDB, your program may stop for any of several reasons, such |
| as a signal, a breakpoint, or reaching a new line after a GDB command |
| such as `step'. You may then examine and change variables, set new |
| breakpoints or remove old ones, and then continue execution. Usually, |
| the messages shown by GDB provide ample explanation of the status of |
| your program--but you can also explicitly request this information at |
| any time. |
| |
| `info program' |
| Display information about the status of your program: whether it is |
| running or not, what process it is, and why it stopped. |
| |
| * Menu: |
| |
| * Breakpoints:: Breakpoints, watchpoints, and catchpoints |
| * Continuing and Stepping:: Resuming execution |
| * Signals:: Signals |
| * Thread Stops:: Stopping and starting multi-thread programs |
| |
| |
| File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping |
| |
| 5.1 Breakpoints, Watchpoints, and Catchpoints |
| ============================================= |
| |
| A "breakpoint" makes your program stop whenever a certain point in the |
| program is reached. For each breakpoint, you can add conditions to |
| control in finer detail whether your program stops. You can set |
| breakpoints with the `break' command and its variants (*note Setting |
| Breakpoints: Set Breaks.), to specify the place where your program |
| should stop by line number, function name or exact address in the |
| program. |
| |
| On some systems, you can set breakpoints in shared libraries before |
| the executable is run. There is a minor limitation on HP-UX systems: |
| you must wait until the executable is run in order to set breakpoints |
| in shared library routines that are not called directly by the program |
| (for example, routines that are arguments in a `pthread_create' call). |
| |
| A "watchpoint" is a special breakpoint that stops your program when |
| the value of an expression changes. The expression may be a value of a |
| variable, or it could involve values of one or more variables combined |
| by operators, such as `a + b'. This is sometimes called "data |
| breakpoints". You must use a different command to set watchpoints |
| (*note Setting Watchpoints: Set Watchpoints.), but aside from that, you |
| can manage a watchpoint like any other breakpoint: you enable, disable, |
| and delete both breakpoints and watchpoints using the same commands. |
| |
| You can arrange to have values from your program displayed |
| automatically whenever GDB stops at a breakpoint. *Note Automatic |
| Display: Auto Display. |
| |
| A "catchpoint" is another special breakpoint that stops your program |
| when a certain kind of event occurs, such as the throwing of a C++ |
| exception or the loading of a library. As with watchpoints, you use a |
| different command to set a catchpoint (*note Setting Catchpoints: Set |
| Catchpoints.), but aside from that, you can manage a catchpoint like any |
| other breakpoint. (To stop when your program receives a signal, use the |
| `handle' command; see *Note Signals: Signals.) |
| |
| GDB assigns a number to each breakpoint, watchpoint, or catchpoint |
| when you create it; these numbers are successive integers starting with |
| one. In many of the commands for controlling various features of |
| breakpoints you use the breakpoint number to say which breakpoint you |
| want to change. Each breakpoint may be "enabled" or "disabled"; if |
| disabled, it has no effect on your program until you enable it again. |
| |
| Some GDB commands accept a range of breakpoints on which to operate. |
| A breakpoint range is either a single breakpoint number, like `5', or |
| two such numbers, in increasing order, separated by a hyphen, like |
| `5-7'. When a breakpoint range is given to a command, all breakpoints |
| in that range are operated on. |
| |
| * Menu: |
| |
| * Set Breaks:: Setting breakpoints |
| * Set Watchpoints:: Setting watchpoints |
| * Set Catchpoints:: Setting catchpoints |
| * Delete Breaks:: Deleting breakpoints |
| * Disabling:: Disabling breakpoints |
| * Conditions:: Break conditions |
| * Break Commands:: Breakpoint command lists |
| * Breakpoint Menus:: Breakpoint menus |
| * Error in Breakpoints:: ``Cannot insert breakpoints'' |
| * Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' |
| |
| |
| File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints |
| |
| 5.1.1 Setting Breakpoints |
| ------------------------- |
| |
| Breakpoints are set with the `break' command (abbreviated `b'). The |
| debugger convenience variable `$bpnum' records the number of the |
| breakpoint you've set most recently; see *Note Convenience Variables: |
| Convenience Vars, for a discussion of what you can do with convenience |
| variables. |
| |
| `break LOCATION' |
| Set a breakpoint at the given LOCATION, which can specify a |
| function name, a line number, or an address of an instruction. |
| (*Note Specify Location::, for a list of all the possible ways to |
| specify a LOCATION.) The breakpoint will stop your program just |
| before it executes any of the code in the specified LOCATION. |
| |
| When using source languages that permit overloading of symbols, |
| such as C++, a function name may refer to more than one possible |
| place to break. *Note Breakpoint Menus: Breakpoint Menus, for a |
| discussion of that situation. |
| |
| `break' |
| When called without any arguments, `break' sets a breakpoint at |
| the next instruction to be executed in the selected stack frame |
| (*note Examining the Stack: Stack.). In any selected frame but the |
| innermost, this makes your program stop as soon as control returns |
| to that frame. This is similar to the effect of a `finish' |
| command in the frame inside the selected frame--except that |
| `finish' does not leave an active breakpoint. If you use `break' |
| without an argument in the innermost frame, GDB stops the next |
| time it reaches the current location; this may be useful inside |
| loops. |
| |
| GDB normally ignores breakpoints when it resumes execution, until |
| at least one instruction has been executed. If it did not do |
| this, you would be unable to proceed past a breakpoint without |
| first disabling the breakpoint. This rule applies whether or not |
| the breakpoint already existed when your program stopped. |
| |
| `break ... if COND' |
| Set a breakpoint with condition COND; evaluate the expression COND |
| each time the breakpoint is reached, and stop only if the value is |
| nonzero--that is, if COND evaluates as true. `...' stands for one |
| of the possible arguments described above (or no argument) |
| specifying where to break. *Note Break Conditions: Conditions, |
| for more information on breakpoint conditions. |
| |
| `tbreak ARGS' |
| Set a breakpoint enabled only for one stop. ARGS are the same as |
| for the `break' command, and the breakpoint is set in the same |
| way, but the breakpoint is automatically deleted after the first |
| time your program stops there. *Note Disabling Breakpoints: |
| Disabling. |
| |
| `hbreak ARGS' |
| Set a hardware-assisted breakpoint. ARGS are the same as for the |
| `break' command and the breakpoint is set in the same way, but the |
| breakpoint requires hardware support and some target hardware may |
| not have this support. The main purpose of this is EPROM/ROM code |
| debugging, so you can set a breakpoint at an instruction without |
| changing the instruction. This can be used with the new |
| trap-generation provided by SPARClite DSU and most x86-based |
| targets. These targets will generate traps when a program |
| accesses some data or instruction address that is assigned to the |
| debug registers. However the hardware breakpoint registers can |
| take a limited number of breakpoints. For example, on the DSU, |
| only two data breakpoints can be set at a time, and GDB will |
| reject this command if more than two are used. Delete or disable |
| unused hardware breakpoints before setting new ones (*note |
| Disabling Breakpoints: Disabling.). *Note Break Conditions: |
| Conditions. For remote targets, you can restrict the number of |
| hardware breakpoints GDB will use, see *Note set remote |
| hardware-breakpoint-limit::. |
| |
| `thbreak ARGS' |
| Set a hardware-assisted breakpoint enabled only for one stop. ARGS |
| are the same as for the `hbreak' command and the breakpoint is set |
| in the same way. However, like the `tbreak' command, the |
| breakpoint is automatically deleted after the first time your |
| program stops there. Also, like the `hbreak' command, the |
| breakpoint requires hardware support and some target hardware may |
| not have this support. *Note Disabling Breakpoints: Disabling. |
| See also *Note Break Conditions: Conditions. |
| |
| `rbreak REGEX' |
| Set breakpoints on all functions matching the regular expression |
| REGEX. This command sets an unconditional breakpoint on all |
| matches, printing a list of all breakpoints it set. Once these |
| breakpoints are set, they are treated just like the breakpoints |
| set with the `break' command. You can delete them, disable them, |
| or make them conditional the same way as any other breakpoint. |
| |
| The syntax of the regular expression is the standard one used with |
| tools like `grep'. Note that this is different from the syntax |
| used by shells, so for instance `foo*' matches all functions that |
| include an `fo' followed by zero or more `o's. There is an |
| implicit `.*' leading and trailing the regular expression you |
| supply, so to match only functions that begin with `foo', use |
| `^foo'. |
| |
| When debugging C++ programs, `rbreak' is useful for setting |
| breakpoints on overloaded functions that are not members of any |
| special classes. |
| |
| The `rbreak' command can be used to set breakpoints in *all* the |
| functions in a program, like this: |
| |
| (gdb) rbreak . |
| |
| `info breakpoints [N]' |
| `info break [N]' |
| `info watchpoints [N]' |
| Print a table of all breakpoints, watchpoints, and catchpoints set |
| and not deleted. Optional argument N means print information only |
| about the specified breakpoint (or watchpoint or catchpoint). For |
| each breakpoint, following columns are printed: |
| |
| _Breakpoint Numbers_ |
| |
| _Type_ |
| Breakpoint, watchpoint, or catchpoint. |
| |
| _Disposition_ |
| Whether the breakpoint is marked to be disabled or deleted |
| when hit. |
| |
| _Enabled or Disabled_ |
| Enabled breakpoints are marked with `y'. `n' marks |
| breakpoints that are not enabled. |
| |
| _Address_ |
| Where the breakpoint is in your program, as a memory address. |
| For a pending breakpoint whose address is not yet known, |
| this field will contain `<PENDING>'. Such breakpoint won't |
| fire until a shared library that has the symbol or line |
| referred by breakpoint is loaded. See below for details. A |
| breakpoint with several locations will have `<MULTIPLE>' in |
| this field--see below for details. |
| |
| _What_ |
| Where the breakpoint is in the source for your program, as a |
| file and line number. For a pending breakpoint, the original |
| string passed to the breakpoint command will be listed as it |
| cannot be resolved until the appropriate shared library is |
| loaded in the future. |
| |
| If a breakpoint is conditional, `info break' shows the condition on |
| the line following the affected breakpoint; breakpoint commands, |
| if any, are listed after that. A pending breakpoint is allowed to |
| have a condition specified for it. The condition is not parsed |
| for validity until a shared library is loaded that allows the |
| pending breakpoint to resolve to a valid location. |
| |
| `info break' with a breakpoint number N as argument lists only |
| that breakpoint. The convenience variable `$_' and the default |
| examining-address for the `x' command are set to the address of |
| the last breakpoint listed (*note Examining Memory: Memory.). |
| |
| `info break' displays a count of the number of times the breakpoint |
| has been hit. This is especially useful in conjunction with the |
| `ignore' command. You can ignore a large number of breakpoint |
| hits, look at the breakpoint info to see how many times the |
| breakpoint was hit, and then run again, ignoring one less than |
| that number. This will get you quickly to the last hit of that |
| breakpoint. |
| |
| GDB allows you to set any number of breakpoints at the same place in |
| your program. There is nothing silly or meaningless about this. When |
| the breakpoints are conditional, this is even useful (*note Break |
| Conditions: Conditions.). |
| |
| It is possible that a breakpoint corresponds to several locations in |
| your program. Examples of this situation are: |
| |
| * For a C++ constructor, the GCC compiler generates several |
| instances of the function body, used in different cases. |
| |
| * For a C++ template function, a given line in the function can |
| correspond to any number of instantiations. |
| |
| * For an inlined function, a given source line can correspond to |
| several places where that function is inlined. |
| |
| |
| In all those cases, GDB will insert a breakpoint at all the relevant |
| locations. |
| |
| A breakpoint with multiple locations is displayed in the breakpoint |
| table using several rows--one header row, followed by one row for each |
| breakpoint location. The header row has `<MULTIPLE>' in the address |
| column. The rows for individual locations contain the actual addresses |
| for locations, and show the functions to which those locations belong. |
| The number column for a location is of the form |
| BREAKPOINT-NUMBER.LOCATION-NUMBER. |
| |
| For example: |
| |
| Num Type Disp Enb Address What |
| 1 breakpoint keep y <MULTIPLE> |
| stop only if i==1 |
| breakpoint already hit 1 time |
| 1.1 y 0x080486a2 in void foo<int>() at t.cc:8 |
| 1.2 y 0x080486ca in void foo<double>() at t.cc:8 |
| |
| Each location can be individually enabled or disabled by passing |
| BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and |
| `disable' commands. Note that you cannot delete the individual |
| locations from the list, you can only delete the entire list of |
| locations that belong to their parent breakpoint (with the `delete NUM' |
| command, where NUM is the number of the parent breakpoint, 1 in the |
| above example). Disabling or enabling the parent breakpoint (*note |
| Disabling::) affects all of the locations that belong to that |
| breakpoint. |
| |
| It's quite common to have a breakpoint inside a shared library. |
| Shared libraries can be loaded and unloaded explicitly, and possibly |
| repeatedly, as the program is executed. To support this use case, GDB |
| updates breakpoint locations whenever any shared library is loaded or |
| unloaded. Typically, you would set a breakpoint in a shared library at |
| the beginning of your debugging session, when the library is not |
| loaded, and when the symbols from the library are not available. When |
| you try to set breakpoint, GDB will ask you if you want to set a so |
| called "pending breakpoint"--breakpoint whose address is not yet |
| resolved. |
| |
| After the program is run, whenever a new shared library is loaded, |
| GDB reevaluates all the breakpoints. When a newly loaded shared |
| library contains the symbol or line referred to by some pending |
| breakpoint, that breakpoint is resolved and becomes an ordinary |
| breakpoint. When a library is unloaded, all breakpoints that refer to |
| its symbols or source lines become pending again. |
| |
| This logic works for breakpoints with multiple locations, too. For |
| example, if you have a breakpoint in a C++ template function, and a |
| newly loaded shared library has an instantiation of that template, a |
| new location is added to the list of locations for the breakpoint. |
| |
| Except for having unresolved address, pending breakpoints do not |
| differ from regular breakpoints. You can set conditions or commands, |
| enable and disable them and perform other breakpoint operations. |
| |
| GDB provides some additional commands for controlling what happens |
| when the `break' command cannot resolve breakpoint address |
| specification to an address: |
| |
| `set breakpoint pending auto' |
| This is the default behavior. When GDB cannot find the breakpoint |
| location, it queries you whether a pending breakpoint should be |
| created. |
| |
| `set breakpoint pending on' |
| This indicates that an unrecognized breakpoint location should |
| automatically result in a pending breakpoint being created. |
| |
| `set breakpoint pending off' |
| This indicates that pending breakpoints are not to be created. Any |
| unrecognized breakpoint location results in an error. This |
| setting does not affect any pending breakpoints previously created. |
| |
| `show breakpoint pending' |
| Show the current behavior setting for creating pending breakpoints. |
| |
| The settings above only affect the `break' command and its variants. |
| Once breakpoint is set, it will be automatically updated as shared |
| libraries are loaded and unloaded. |
| |
| For some targets, GDB can automatically decide if hardware or |
| software breakpoints should be used, depending on whether the |
| breakpoint address is read-only or read-write. This applies to |
| breakpoints set with the `break' command as well as to internal |
| breakpoints set by commands like `next' and `finish'. For breakpoints |
| set with `hbreak', GDB will always use hardware breakpoints. |
| |
| You can control this automatic behaviour with the following |
| commands:: |
| |
| `set breakpoint auto-hw on' |
| This is the default behavior. When GDB sets a breakpoint, it will |
| try to use the target memory map to decide if software or hardware |
| breakpoint must be used. |
| |
| `set breakpoint auto-hw off' |
| This indicates GDB should not automatically select breakpoint |
| type. If the target provides a memory map, GDB will warn when |
| trying to set software breakpoint at a read-only address. |
| |
| GDB itself sometimes sets breakpoints in your program for special |
| purposes, such as proper handling of `longjmp' (in C programs). These |
| internal breakpoints are assigned negative numbers, starting with `-1'; |
| `info breakpoints' does not display them. You can see these |
| breakpoints with the GDB maintenance command `maint info breakpoints' |
| (*note maint info breakpoints::). |
| |
| |
| File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints |
| |
| 5.1.2 Setting Watchpoints |
| ------------------------- |
| |
| You can use a watchpoint to stop execution whenever the value of an |
| expression changes, without having to predict a particular place where |
| this may happen. (This is sometimes called a "data breakpoint".) The |
| expression may be as simple as the value of a single variable, or as |
| complex as many variables combined by operators. Examples include: |
| |
| * A reference to the value of a single variable. |
| |
| * An address cast to an appropriate data type. For example, `*(int |
| *)0x12345678' will watch a 4-byte region at the specified address |
| (assuming an `int' occupies 4 bytes). |
| |
| * An arbitrarily complex expression, such as `a*b + c/d'. The |
| expression can use any operators valid in the program's native |
| language (*note Languages::). |
| |
| Depending on your system, watchpoints may be implemented in software |
| or hardware. GDB does software watchpointing by single-stepping your |
| program and testing the variable's value each time, which is hundreds of |
| times slower than normal execution. (But this may still be worth it, to |
| catch errors where you have no clue what part of your program is the |
| culprit.) |
| |
| On some systems, such as HP-UX, PowerPC, GNU/Linux and most other |
| x86-based targets, GDB includes support for hardware watchpoints, which |
| do not slow down the running of your program. |
| |
| `watch EXPR [thread THREADNUM]' |
| Set a watchpoint for an expression. GDB will break when the |
| expression EXPR is written into by the program and its value |
| changes. The simplest (and the most popular) use of this command |
| is to watch the value of a single variable: |
| |
| (gdb) watch foo |
| |
| If the command includes a `[thread THREADNUM]' clause, GDB breaks |
| only when the thread identified by THREADNUM changes the value of |
| EXPR. If any other threads change the value of EXPR, GDB will not |
| break. Note that watchpoints restricted to a single thread in |
| this way only work with Hardware Watchpoints. |
| |
| `rwatch EXPR [thread THREADNUM]' |
| Set a watchpoint that will break when the value of EXPR is read by |
| the program. |
| |
| `awatch EXPR [thread THREADNUM]' |
| Set a watchpoint that will break when EXPR is either read from or |
| written into by the program. |
| |
| `info watchpoints' |
| This command prints a list of watchpoints, breakpoints, and |
| catchpoints; it is the same as `info break' (*note Set Breaks::). |
| |
| GDB sets a "hardware watchpoint" if possible. Hardware watchpoints |
| execute very quickly, and the debugger reports a change in value at the |
| exact instruction where the change occurs. If GDB cannot set a |
| hardware watchpoint, it sets a software watchpoint, which executes more |
| slowly and reports the change in value at the next _statement_, not the |
| instruction, after the change occurs. |
| |
| You can force GDB to use only software watchpoints with the `set |
| can-use-hw-watchpoints 0' command. With this variable set to zero, GDB |
| will never try to use hardware watchpoints, even if the underlying |
| system supports them. (Note that hardware-assisted watchpoints that |
| were set _before_ setting `can-use-hw-watchpoints' to zero will still |
| use the hardware mechanism of watching expression values.) |
| |
| `set can-use-hw-watchpoints' |
| Set whether or not to use hardware watchpoints. |
| |
| `show can-use-hw-watchpoints' |
| Show the current mode of using hardware watchpoints. |
| |
| For remote targets, you can restrict the number of hardware |
| watchpoints GDB will use, see *Note set remote |
| hardware-breakpoint-limit::. |
| |
| When you issue the `watch' command, GDB reports |
| |
| Hardware watchpoint NUM: EXPR |
| |
| if it was able to set a hardware watchpoint. |
| |
| Currently, the `awatch' and `rwatch' commands can only set hardware |
| watchpoints, because accesses to data that don't change the value of |
| the watched expression cannot be detected without examining every |
| instruction as it is being executed, and GDB does not do that |
| currently. If GDB finds that it is unable to set a hardware breakpoint |
| with the `awatch' or `rwatch' command, it will print a message like |
| this: |
| |
| Expression cannot be implemented with read/access watchpoint. |
| |
| Sometimes, GDB cannot set a hardware watchpoint because the data |
| type of the watched expression is wider than what a hardware watchpoint |
| on the target machine can handle. For example, some systems can only |
| watch regions that are up to 4 bytes wide; on such systems you cannot |
| set hardware watchpoints for an expression that yields a |
| double-precision floating-point number (which is typically 8 bytes |
| wide). As a work-around, it might be possible to break the large region |
| into a series of smaller ones and watch them with separate watchpoints. |
| |
| If you set too many hardware watchpoints, GDB might be unable to |
| insert all of them when you resume the execution of your program. |
| Since the precise number of active watchpoints is unknown until such |
| time as the program is about to be resumed, GDB might not be able to |
| warn you about this when you set the watchpoints, and the warning will |
| be printed only when the program is resumed: |
| |
| Hardware watchpoint NUM: Could not insert watchpoint |
| |
| If this happens, delete or disable some of the watchpoints. |
| |
| Watching complex expressions that reference many variables can also |
| exhaust the resources available for hardware-assisted watchpoints. |
| That's because GDB needs to watch every variable in the expression with |
| separately allocated resources. |
| |
| The SPARClite DSU will generate traps when a program accesses some |
| data or instruction address that is assigned to the debug registers. |
| For the data addresses, DSU facilitates the `watch' command. However |
| the hardware breakpoint registers can only take two data watchpoints, |
| and both watchpoints must be the same kind. For example, you can set |
| two watchpoints with `watch' commands, two with `rwatch' commands, *or* |
| two with `awatch' commands, but you cannot set one watchpoint with one |
| command and the other with a different command. GDB will reject the |
| command if you try to mix watchpoints. Delete or disable unused |
| watchpoint commands before setting new ones. |
| |
| If you call a function interactively using `print' or `call', any |
| watchpoints you have set will be inactive until GDB reaches another |
| kind of breakpoint or the call completes. |
| |
| GDB automatically deletes watchpoints that watch local (automatic) |
| variables, or expressions that involve such variables, when they go out |
| of scope, that is, when the execution leaves the block in which these |
| variables were defined. In particular, when the program being debugged |
| terminates, _all_ local variables go out of scope, and so only |
| watchpoints that watch global variables remain set. If you rerun the |
| program, you will need to set all such watchpoints again. One way of |
| doing that would be to set a code breakpoint at the entry to the `main' |
| function and when it breaks, set all the watchpoints. |
| |
| In multi-threaded programs, watchpoints will detect changes to the |
| watched expression from every thread. |
| |
| _Warning:_ In multi-threaded programs, software watchpoints have |
| only limited usefulness. If GDB creates a software watchpoint, it |
| can only watch the value of an expression _in a single thread_. |
| If you are confident that the expression can only change due to |
| the current thread's activity (and if you are also confident that |
| no other thread can become current), then you can use software |
| watchpoints as usual. However, GDB may not notice when a |
| non-current thread's activity changes the expression. (Hardware |
| watchpoints, in contrast, watch an expression in all threads.) |
| |
| *Note set remote hardware-watchpoint-limit::. |
| |
| |
| File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints |
| |
| 5.1.3 Setting Catchpoints |
| ------------------------- |
| |
| You can use "catchpoints" to cause the debugger to stop for certain |
| kinds of program events, such as C++ exceptions or the loading of a |
| shared library. Use the `catch' command to set a catchpoint. |
| |
| `catch EVENT' |
| Stop when EVENT occurs. EVENT can be any of the following: |
| `throw' |
| The throwing of a C++ exception. |
| |
| `catch' |
| The catching of a C++ exception. |
| |
| `exception' |
| An Ada exception being raised. If an exception name is |
| specified at the end of the command (eg `catch exception |
| Program_Error'), the debugger will stop only when this |
| specific exception is raised. Otherwise, the debugger stops |
| execution when any Ada exception is raised. |
| |
| `exception unhandled' |
| An exception that was raised but is not handled by the |
| program. |
| |
| `assert' |
| A failed Ada assertion. |
| |
| `exec' |
| A call to `exec'. This is currently only available for HP-UX |
| and GNU/Linux. |
| |
| `fork' |
| A call to `fork'. This is currently only available for HP-UX |
| and GNU/Linux. |
| |
| `vfork' |
| A call to `vfork'. This is currently only available for HP-UX |
| and GNU/Linux. |
| |
| `load' |
| `load LIBNAME' |
| The dynamic loading of any shared library, or the loading of |
| the library LIBNAME. This is currently only available for |
| HP-UX. |
| |
| `unload' |
| `unload LIBNAME' |
| The unloading of any dynamically loaded shared library, or |
| the unloading of the library LIBNAME. This is currently only |
| available for HP-UX. |
| |
| `tcatch EVENT' |
| Set a catchpoint that is enabled only for one stop. The |
| catchpoint is automatically deleted after the first time the event |
| is caught. |
| |
| |
| Use the `info break' command to list the current catchpoints. |
| |
| There are currently some limitations to C++ exception handling |
| (`catch throw' and `catch catch') in GDB: |
| |
| * If you call a function interactively, GDB normally returns control |
| to you when the function has finished executing. If the call |
| raises an exception, however, the call may bypass the mechanism |
| that returns control to you and cause your program either to abort |
| or to simply continue running until it hits a breakpoint, catches |
| a signal that GDB is listening for, or exits. This is the case |
| even if you set a catchpoint for the exception; catchpoints on |
| exceptions are disabled within interactive calls. |
| |
| * You cannot raise an exception interactively. |
| |
| * You cannot install an exception handler interactively. |
| |
| Sometimes `catch' is not the best way to debug exception handling: |
| if you need to know exactly where an exception is raised, it is better |
| to stop _before_ the exception handler is called, since that way you |
| can see the stack before any unwinding takes place. If you set a |
| breakpoint in an exception handler instead, it may not be easy to find |
| out where the exception was raised. |
| |
| To stop just before an exception handler is called, you need some |
| knowledge of the implementation. In the case of GNU C++, exceptions are |
| raised by calling a library function named `__raise_exception' which |
| has the following ANSI C interface: |
| |
| /* ADDR is where the exception identifier is stored. |
| ID is the exception identifier. */ |
| void __raise_exception (void **addr, void *id); |
| |
| To make the debugger catch all exceptions before any stack unwinding |
| takes place, set a breakpoint on `__raise_exception' (*note |
| Breakpoints; Watchpoints; and Exceptions: Breakpoints.). |
| |
| With a conditional breakpoint (*note Break Conditions: Conditions.) |
| that depends on the value of ID, you can stop your program when a |
| specific exception is raised. You can use multiple conditional |
| breakpoints to stop your program when any of a number of exceptions are |
| raised. |
| |
| |
| File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints |
| |
| 5.1.4 Deleting Breakpoints |
| -------------------------- |
| |
| It is often necessary to eliminate a breakpoint, watchpoint, or |
| catchpoint once it has done its job and you no longer want your program |
| to stop there. This is called "deleting" the breakpoint. A breakpoint |
| that has been deleted no longer exists; it is forgotten. |
| |
| With the `clear' command you can delete breakpoints according to |
| where they are in your program. With the `delete' command you can |
| delete individual breakpoints, watchpoints, or catchpoints by specifying |
| their breakpoint numbers. |
| |
| It is not necessary to delete a breakpoint to proceed past it. GDB |
| automatically ignores breakpoints on the first instruction to be |
| executed when you continue execution without changing the execution |
| address. |
| |
| `clear' |
| Delete any breakpoints at the next instruction to be executed in |
| the selected stack frame (*note Selecting a Frame: Selection.). |
| When the innermost frame is selected, this is a good way to delete |
| a breakpoint where your program just stopped. |
| |
| `clear LOCATION' |
| Delete any breakpoints set at the specified LOCATION. *Note |
| Specify Location::, for the various forms of LOCATION; the most |
| useful ones are listed below: |
| |
| `clear FUNCTION' |
| `clear FILENAME:FUNCTION' |
| Delete any breakpoints set at entry to the named FUNCTION. |
| |
| `clear LINENUM' |
| `clear FILENAME:LINENUM' |
| Delete any breakpoints set at or within the code of the |
| specified LINENUM of the specified FILENAME. |
| |
| `delete [breakpoints] [RANGE...]' |
| Delete the breakpoints, watchpoints, or catchpoints of the |
| breakpoint ranges specified as arguments. If no argument is |
| specified, delete all breakpoints (GDB asks confirmation, unless |
| you have `set confirm off'). You can abbreviate this command as |
| `d'. |
| |
| |
| File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints |
| |
| 5.1.5 Disabling Breakpoints |
| --------------------------- |
| |
| Rather than deleting a breakpoint, watchpoint, or catchpoint, you might |
| prefer to "disable" it. This makes the breakpoint inoperative as if it |
| had been deleted, but remembers the information on the breakpoint so |
| that you can "enable" it again later. |
| |
| You disable and enable breakpoints, watchpoints, and catchpoints with |
| the `enable' and `disable' commands, optionally specifying one or more |
| breakpoint numbers as arguments. Use `info break' or `info watch' to |
| print a list of breakpoints, watchpoints, and catchpoints if you do not |
| know which numbers to use. |
| |
| Disabling and enabling a breakpoint that has multiple locations |
| affects all of its locations. |
| |
| A breakpoint, watchpoint, or catchpoint can have any of four |
| different states of enablement: |
| |
| * Enabled. The breakpoint stops your program. A breakpoint set |
| with the `break' command starts out in this state. |
| |
| * Disabled. The breakpoint has no effect on your program. |
| |
| * Enabled once. The breakpoint stops your program, but then becomes |
| disabled. |
| |
| * Enabled for deletion. The breakpoint stops your program, but |
| immediately after it does so it is deleted permanently. A |
| breakpoint set with the `tbreak' command starts out in this state. |
| |
| You can use the following commands to enable or disable breakpoints, |
| watchpoints, and catchpoints: |
| |
| `disable [breakpoints] [RANGE...]' |
| Disable the specified breakpoints--or all breakpoints, if none are |
| listed. A disabled breakpoint has no effect but is not forgotten. |
| All options such as ignore-counts, conditions and commands are |
| remembered in case the breakpoint is enabled again later. You may |
| abbreviate `disable' as `dis'. |
| |
| `enable [breakpoints] [RANGE...]' |
| Enable the specified breakpoints (or all defined breakpoints). |
| They become effective once again in stopping your program. |
| |
| `enable [breakpoints] once RANGE...' |
| Enable the specified breakpoints temporarily. GDB disables any of |
| these breakpoints immediately after stopping your program. |
| |
| `enable [breakpoints] delete RANGE...' |
| Enable the specified breakpoints to work once, then die. GDB |
| deletes any of these breakpoints as soon as your program stops |
| there. Breakpoints set by the `tbreak' command start out in this |
| state. |
| |
| Except for a breakpoint set with `tbreak' (*note Setting |
| Breakpoints: Set Breaks.), breakpoints that you set are initially |
| enabled; subsequently, they become disabled or enabled only when you |
| use one of the commands above. (The command `until' can set and delete |
| a breakpoint of its own, but it does not change the state of your other |
| breakpoints; see *Note Continuing and Stepping: Continuing and |
| Stepping.) |
| |
| |
| File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints |
| |
| 5.1.6 Break Conditions |
| ---------------------- |
| |
| The simplest sort of breakpoint breaks every time your program reaches a |
| specified place. You can also specify a "condition" for a breakpoint. |
| A condition is just a Boolean expression in your programming language |
| (*note Expressions: Expressions.). A breakpoint with a condition |
| evaluates the expression each time your program reaches it, and your |
| program stops only if the condition is _true_. |
| |
| This is the converse of using assertions for program validation; in |
| that situation, you want to stop when the assertion is violated--that |
| is, when the condition is false. In C, if you want to test an |
| assertion expressed by the condition ASSERT, you should set the |
| condition `! ASSERT' on the appropriate breakpoint. |
| |
| Conditions are also accepted for watchpoints; you may not need them, |
| since a watchpoint is inspecting the value of an expression anyhow--but |
| it might be simpler, say, to just set a watchpoint on a variable name, |
| and specify a condition that tests whether the new value is an |
| interesting one. |
| |
| Break conditions can have side effects, and may even call functions |
| in your program. This can be useful, for example, to activate functions |
| that log program progress, or to use your own print functions to format |
| special data structures. The effects are completely predictable unless |
| there is another enabled breakpoint at the same address. (In that |
| case, GDB might see the other breakpoint first and stop your program |
| without checking the condition of this one.) Note that breakpoint |
| commands are usually more convenient and flexible than break conditions |
| for the purpose of performing side effects when a breakpoint is reached |
| (*note Breakpoint Command Lists: Break Commands.). |
| |
| Break conditions can be specified when a breakpoint is set, by using |
| `if' in the arguments to the `break' command. *Note Setting |
| Breakpoints: Set Breaks. They can also be changed at any time with the |
| `condition' command. |
| |
| You can also use the `if' keyword with the `watch' command. The |
| `catch' command does not recognize the `if' keyword; `condition' is the |
| only way to impose a further condition on a catchpoint. |
| |
| `condition BNUM EXPRESSION' |
| Specify EXPRESSION as the break condition for breakpoint, |
| watchpoint, or catchpoint number BNUM. After you set a condition, |
| breakpoint BNUM stops your program only if the value of EXPRESSION |
| is true (nonzero, in C). When you use `condition', GDB checks |
| EXPRESSION immediately for syntactic correctness, and to determine |
| whether symbols in it have referents in the context of your |
| breakpoint. If EXPRESSION uses symbols not referenced in the |
| context of the breakpoint, GDB prints an error message: |
| |
| No symbol "foo" in current context. |
| |
| GDB does not actually evaluate EXPRESSION at the time the |
| `condition' command (or a command that sets a breakpoint with a |
| condition, like `break if ...') is given, however. *Note |
| Expressions: Expressions. |
| |
| `condition BNUM' |
| Remove the condition from breakpoint number BNUM. It becomes an |
| ordinary unconditional breakpoint. |
| |
| A special case of a breakpoint condition is to stop only when the |
| breakpoint has been reached a certain number of times. This is so |
| useful that there is a special way to do it, using the "ignore count" |
| of the breakpoint. Every breakpoint has an ignore count, which is an |
| integer. Most of the time, the ignore count is zero, and therefore has |
| no effect. But if your program reaches a breakpoint whose ignore count |
| is positive, then instead of stopping, it just decrements the ignore |
| count by one and continues. As a result, if the ignore count value is |
| N, the breakpoint does not stop the next N times your program reaches |
| it. |
| |
| `ignore BNUM COUNT' |
| Set the ignore count of breakpoint number BNUM to COUNT. The next |
| COUNT times the breakpoint is reached, your program's execution |
| does not stop; other than to decrement the ignore count, GDB takes |
| no action. |
| |
| To make the breakpoint stop the next time it is reached, specify a |
| count of zero. |
| |
| When you use `continue' to resume execution of your program from a |
| breakpoint, you can specify an ignore count directly as an |
| argument to `continue', rather than using `ignore'. *Note |
| Continuing and Stepping: Continuing and Stepping. |
| |
| If a breakpoint has a positive ignore count and a condition, the |
| condition is not checked. Once the ignore count reaches zero, GDB |
| resumes checking the condition. |
| |
| You could achieve the effect of the ignore count with a condition |
| such as `$foo-- <= 0' using a debugger convenience variable that |
| is decremented each time. *Note Convenience Variables: |
| Convenience Vars. |
| |
| Ignore counts apply to breakpoints, watchpoints, and catchpoints. |
| |
| |
| File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints |
| |
| 5.1.7 Breakpoint Command Lists |
| ------------------------------ |
| |
| You can give any breakpoint (or watchpoint or catchpoint) a series of |
| commands to execute when your program stops due to that breakpoint. For |
| example, you might want to print the values of certain expressions, or |
| enable other breakpoints. |
| |
| `commands [BNUM]' |
| `... COMMAND-LIST ...' |
| `end' |
| Specify a list of commands for breakpoint number BNUM. The |
| commands themselves appear on the following lines. Type a line |
| containing just `end' to terminate the commands. |
| |
| To remove all commands from a breakpoint, type `commands' and |
| follow it immediately with `end'; that is, give no commands. |
| |
| With no BNUM argument, `commands' refers to the last breakpoint, |
| watchpoint, or catchpoint set (not to the breakpoint most recently |
| encountered). |
| |
| Pressing <RET> as a means of repeating the last GDB command is |
| disabled within a COMMAND-LIST. |
| |
| You can use breakpoint commands to start your program up again. |
| Simply use the `continue' command, or `step', or any other command that |
| resumes execution. |
| |
| Any other commands in the command list, after a command that resumes |
| execution, are ignored. This is because any time you resume execution |
| (even with a simple `next' or `step'), you may encounter another |
| breakpoint--which could have its own command list, leading to |
| ambiguities about which list to execute. |
| |
| If the first command you specify in a command list is `silent', the |
| usual message about stopping at a breakpoint is not printed. This may |
| be desirable for breakpoints that are to print a specific message and |
| then continue. If none of the remaining commands print anything, you |
| see no sign that the breakpoint was reached. `silent' is meaningful |
| only at the beginning of a breakpoint command list. |
| |
| The commands `echo', `output', and `printf' allow you to print |
| precisely controlled output, and are often useful in silent |
| breakpoints. *Note Commands for Controlled Output: Output. |
| |
| For example, here is how you could use breakpoint commands to print |
| the value of `x' at entry to `foo' whenever `x' is positive. |
| |
| break foo if x>0 |
| commands |
| silent |
| printf "x is %d\n",x |
| cont |
| end |
| |
| One application for breakpoint commands is to compensate for one bug |
| so you can test for another. Put a breakpoint just after the erroneous |
| line of code, give it a condition to detect the case in which something |
| erroneous has been done, and give it commands to assign correct values |
| to any variables that need them. End with the `continue' command so |
| that your program does not stop, and start with the `silent' command so |
| that no output is produced. Here is an example: |
| |
| break 403 |
| commands |
| silent |
| set x = y + 4 |
| cont |
| end |
| |
| |
| File: gdb.info, Node: Breakpoint Menus, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints |
| |
| 5.1.8 Breakpoint Menus |
| ---------------------- |
| |
| Some programming languages (notably C++ and Objective-C) permit a |
| single function name to be defined several times, for application in |
| different contexts. This is called "overloading". When a function |
| name is overloaded, `break FUNCTION' is not enough to tell GDB where |
| you want a breakpoint. You can use explicit signature of the function, |
| as in `break FUNCTION(TYPES)', to specify which particular version of |
| the function you want. Otherwise, GDB offers you a menu of numbered |
| choices for different possible breakpoints, and waits for your |
| selection with the prompt `>'. The first two options are always `[0] |
| cancel' and `[1] all'. Typing `1' sets a breakpoint at each definition |
| of FUNCTION, and typing `0' aborts the `break' command without setting |
| any new breakpoints. |
| |
| For example, the following session excerpt shows an attempt to set a |
| breakpoint at the overloaded symbol `String::after'. We choose three |
| particular definitions of that function name: |
| |
| (gdb) b String::after |
| [0] cancel |
| [1] all |
| [2] file:String.cc; line number:867 |
| [3] file:String.cc; line number:860 |
| [4] file:String.cc; line number:875 |
| [5] file:String.cc; line number:853 |
| [6] file:String.cc; line number:846 |
| [7] file:String.cc; line number:735 |
| > 2 4 6 |
| Breakpoint 1 at 0xb26c: file String.cc, line 867. |
| Breakpoint 2 at 0xb344: file String.cc, line 875. |
| Breakpoint 3 at 0xafcc: file String.cc, line 846. |
| Multiple breakpoints were set. |
| Use the "delete" command to delete unwanted |
| breakpoints. |
| (gdb) |
| |
| |
| File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Breakpoint Menus, Up: Breakpoints |
| |
| 5.1.9 "Cannot insert breakpoints" |
| --------------------------------- |
| |
| Under some operating systems, breakpoints cannot be used in a program if |
| any other process is running that program. In this situation, |
| attempting to run or continue a program with a breakpoint causes GDB to |
| print an error message: |
| |
| Cannot insert breakpoints. |
| The same program may be running in another process. |
| |
| When this happens, you have three ways to proceed: |
| |
| 1. Remove or disable the breakpoints, then continue. |
| |
| 2. Suspend GDB, and copy the file containing your program to a new |
| name. Resume GDB and use the `exec-file' command to specify that |
| GDB should run your program under that name. Then start your |
| program again. |
| |
| 3. Relink your program so that the text segment is nonsharable, using |
| the linker option `-N'. The operating system limitation may not |
| apply to nonsharable executables. |
| |
| A similar message can be printed if you request too many active |
| hardware-assisted breakpoints and watchpoints: |
| |
| Stopped; cannot insert breakpoints. |
| You may have requested too many hardware breakpoints and watchpoints. |
| |
| This message is printed when you attempt to resume the program, since |
| only then GDB knows exactly how many hardware breakpoints and |
| watchpoints it needs to insert. |
| |
| When this message is printed, you need to disable or remove some of |
| the hardware-assisted breakpoints and watchpoints, and then continue. |
| |
| |
| File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints |
| |
| 5.1.10 "Breakpoint address adjusted..." |
| --------------------------------------- |
| |
| Some processor architectures place constraints on the addresses at |
| which breakpoints may be placed. For architectures thus constrained, |
| GDB will attempt to adjust the breakpoint's address to comply with the |
| constraints dictated by the architecture. |
| |
| One example of such an architecture is the Fujitsu FR-V. The FR-V is |
| a VLIW architecture in which a number of RISC-like instructions may be |
| bundled together for parallel execution. The FR-V architecture |
| constrains the location of a breakpoint instruction within such a |
| bundle to the instruction with the lowest address. GDB honors this |
| constraint by adjusting a breakpoint's address to the first in the |
| bundle. |
| |
| It is not uncommon for optimized code to have bundles which contain |
| instructions from different source statements, thus it may happen that |
| a breakpoint's address will be adjusted from one source statement to |
| another. Since this adjustment may significantly alter GDB's |
| breakpoint related behavior from what the user expects, a warning is |
| printed when the breakpoint is first set and also when the breakpoint |
| is hit. |
| |
| A warning like the one below is printed when setting a breakpoint |
| that's been subject to address adjustment: |
| |
| warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. |
| |
| Such warnings are printed both for user settable and GDB's internal |
| breakpoints. If you see one of these warnings, you should verify that |
| a breakpoint set at the adjusted address will have the desired affect. |
| If not, the breakpoint in question may be removed and other breakpoints |
| may be set which will have the desired behavior. E.g., it may be |
| sufficient to place the breakpoint at a later instruction. A |
| conditional breakpoint may also be useful in some cases to prevent the |
| breakpoint from triggering too often. |
| |
| GDB will also issue a warning when stopping at one of these adjusted |
| breakpoints: |
| |
| warning: Breakpoint 1 address previously adjusted from 0x00010414 |
| to 0x00010410. |
| |
| When this warning is encountered, it may be too late to take remedial |
| action except in cases where the breakpoint is hit earlier or more |
| frequently than expected. |
| |
| |
| File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping |
| |
| 5.2 Continuing and Stepping |
| =========================== |
| |
| "Continuing" means resuming program execution until your program |
| completes normally. In contrast, "stepping" means executing just one |
| more "step" of your program, where "step" may mean either one line of |
| source code, or one machine instruction (depending on what particular |
| command you use). Either when continuing or when stepping, your |
| program may stop even sooner, due to a breakpoint or a signal. (If it |
| stops due to a signal, you may want to use `handle', or use `signal 0' |
| to resume execution. *Note Signals: Signals.) |
| |
| `continue [IGNORE-COUNT]' |
| `c [IGNORE-COUNT]' |
| `fg [IGNORE-COUNT]' |
| Resume program execution, at the address where your program last |
| stopped; any breakpoints set at that address are bypassed. The |
| optional argument IGNORE-COUNT allows you to specify a further |
| number of times to ignore a breakpoint at this location; its |
| effect is like that of `ignore' (*note Break Conditions: |
| Conditions.). |
| |
| The argument IGNORE-COUNT is meaningful only when your program |
| stopped due to a breakpoint. At other times, the argument to |
| `continue' is ignored. |
| |
| The synonyms `c' and `fg' (for "foreground", as the debugged |
| program is deemed to be the foreground program) are provided |
| purely for convenience, and have exactly the same behavior as |
| `continue'. |
| |
| To resume execution at a different place, you can use `return' |
| (*note Returning from a Function: Returning.) to go back to the calling |
| function; or `jump' (*note Continuing at a Different Address: Jumping.) |
| to go to an arbitrary location in your program. |
| |
| A typical technique for using stepping is to set a breakpoint (*note |
| Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the |
| beginning of the function or the section of your program where a problem |
| is believed to lie, run your program until it stops at that breakpoint, |
| and then step through the suspect area, examining the variables that are |
| interesting, until you see the problem happen. |
| |
| `step' |
| Continue running your program until control reaches a different |
| source line, then stop it and return control to GDB. This command |
| is abbreviated `s'. |
| |
| _Warning:_ If you use the `step' command while control is |
| within a function that was compiled without debugging |
| information, execution proceeds until control reaches a |
| function that does have debugging information. Likewise, it |
| will not step into a function which is compiled without |
| debugging information. To step through functions without |
| debugging information, use the `stepi' command, described |
| below. |
| |
| The `step' command only stops at the first instruction of a source |
| line. This prevents the multiple stops that could otherwise occur |
| in `switch' statements, `for' loops, etc. `step' continues to |
| stop if a function that has debugging information is called within |
| the line. In other words, `step' _steps inside_ any functions |
| called within the line. |
| |
| Also, the `step' command only enters a function if there is line |
| number information for the function. Otherwise it acts like the |
| `next' command. This avoids problems when using `cc -gl' on MIPS |
| machines. Previously, `step' entered subroutines if there was any |
| debugging information about the routine. |
| |
| `step COUNT' |
| Continue running as in `step', but do so COUNT times. If a |
| breakpoint is reached, or a signal not related to stepping occurs |
| before COUNT steps, stepping stops right away. |
| |
| `next [COUNT]' |
| Continue to the next source line in the current (innermost) stack |
| frame. This is similar to `step', but function calls that appear |
| within the line of code are executed without stopping. Execution |
| stops when control reaches a different line of code at the |
| original stack level that was executing when you gave the `next' |
| command. This command is abbreviated `n'. |
| |
| An argument COUNT is a repeat count, as for `step'. |
| |
| The `next' command only stops at the first instruction of a source |
| line. This prevents multiple stops that could otherwise occur in |
| `switch' statements, `for' loops, etc. |
| |
| `set step-mode' |
| `set step-mode on' |
| The `set step-mode on' command causes the `step' command to stop |
| at the first instruction of a function which contains no debug line |
| information rather than stepping over it. |
| |
| This is useful in cases where you may be interested in inspecting |
| the machine instructions of a function which has no symbolic info |
| and do not want GDB to automatically skip over this function. |
| |
| `set step-mode off' |
| Causes the `step' command to step over any functions which |
| contains no debug information. This is the default. |
| |
| `show step-mode' |
| Show whether GDB will stop in or step over functions without |
| source line debug information. |
| |
| `finish' |
| Continue running until just after function in the selected stack |
| frame returns. Print the returned value (if any). |
| |
| Contrast this with the `return' command (*note Returning from a |
| Function: Returning.). |
| |
| `until' |
| `u' |
| Continue running until a source line past the current line, in the |
| current stack frame, is reached. This command is used to avoid |
| single stepping through a loop more than once. It is like the |
| `next' command, except that when `until' encounters a jump, it |
| automatically continues execution until the program counter is |
| greater than the address of the jump. |
| |
| This means that when you reach the end of a loop after single |
| stepping though it, `until' makes your program continue execution |
| until it exits the loop. In contrast, a `next' command at the end |
| of a loop simply steps back to the beginning of the loop, which |
| forces you to step through the next iteration. |
| |
| `until' always stops your program if it attempts to exit the |
| current stack frame. |
| |
| `until' may produce somewhat counterintuitive results if the order |
| of machine code does not match the order of the source lines. For |
| example, in the following excerpt from a debugging session, the `f' |
| (`frame') command shows that execution is stopped at line `206'; |
| yet when we use `until', we get to line `195': |
| |
| (gdb) f |
| #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 |
| 206 expand_input(); |
| (gdb) until |
| 195 for ( ; argc > 0; NEXTARG) { |
| |
| This happened because, for execution efficiency, the compiler had |
| generated code for the loop closure test at the end, rather than |
| the start, of the loop--even though the test in a C `for'-loop is |
| written before the body of the loop. The `until' command appeared |
| to step back to the beginning of the loop when it advanced to this |
| expression; however, it has not really gone to an earlier |
| statement--not in terms of the actual machine code. |
| |
| `until' with no argument works by means of single instruction |
| stepping, and hence is slower than `until' with an argument. |
| |
| `until LOCATION' |
| `u LOCATION' |
| Continue running your program until either the specified location |
| is reached, or the current stack frame returns. LOCATION is any of |
| the forms described in *Note Specify Location::. This form of the |
| command uses temporary breakpoints, and hence is quicker than |
| `until' without an argument. The specified location is actually |
| reached only if it is in the current frame. This implies that |
| `until' can be used to skip over recursive function invocations. |
| For instance in the code below, if the current location is line |
| `96', issuing `until 99' will execute the program up to line `99' |
| in the same invocation of factorial, i.e., after the inner |
| invocations have returned. |
| |
| 94 int factorial (int value) |
| 95 { |
| 96 if (value > 1) { |
| 97 value *= factorial (value - 1); |
| 98 } |
| 99 return (value); |
| 100 } |
| |
| `advance LOCATION' |
| Continue running the program up to the given LOCATION. An |
| argument is required, which should be of one of the forms |
| described in *Note Specify Location::. Execution will also stop |
| upon exit from the current stack frame. This command is similar |
| to `until', but `advance' will not skip over recursive function |
| calls, and the target location doesn't have to be in the same |
| frame as the current one. |
| |
| `stepi' |
| `stepi ARG' |
| `si' |
| Execute one machine instruction, then stop and return to the |
| debugger. |
| |
| It is often useful to do `display/i $pc' when stepping by machine |
| instructions. This makes GDB automatically display the next |
| instruction to be executed, each time your program stops. *Note |
| Automatic Display: Auto Display. |
| |
| An argument is a repeat count, as in `step'. |
| |
| `nexti' |
| `nexti ARG' |
| `ni' |
| Execute one machine instruction, but if it is a function call, |
| proceed until the function returns. |
| |
| An argument is a repeat count, as in `next'. |
| |
| |
| File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping |
| |
| 5.3 Signals |
| =========== |
| |
| A signal is an asynchronous event that can happen in a program. The |
| operating system defines the possible kinds of signals, and gives each |
| kind a name and a number. For example, in Unix `SIGINT' is the signal |
| a program gets when you type an interrupt character (often `Ctrl-c'); |
| `SIGSEGV' is the signal a program gets from referencing a place in |
| memory far away from all the areas in use; `SIGALRM' occurs when the |
| alarm clock timer goes off (which happens only if your program has |
| requested an alarm). |
| |
| Some signals, including `SIGALRM', are a normal part of the |
| functioning of your program. Others, such as `SIGSEGV', indicate |
| errors; these signals are "fatal" (they kill your program immediately) |
| if the program has not specified in advance some other way to handle |
| the signal. `SIGINT' does not indicate an error in your program, but |
| it is normally fatal so it can carry out the purpose of the interrupt: |
| to kill the program. |
| |
| GDB has the ability to detect any occurrence of a signal in your |
| program. You can tell GDB in advance what to do for each kind of |
| signal. |
| |
| Normally, GDB is set up to let the non-erroneous signals like |
| `SIGALRM' be silently passed to your program (so as not to interfere |
| with their role in the program's functioning) but to stop your program |
| immediately whenever an error signal happens. You can change these |
| settings with the `handle' command. |
| |
| `info signals' |
| `info handle' |
| Print a table of all the kinds of signals and how GDB has been |
| told to handle each one. You can use this to see the signal |
| numbers of all the defined types of signals. |
| |
| `info signals SIG' |
| Similar, but print information only about the specified signal |
| number. |
| |
| `info handle' is an alias for `info signals'. |
| |
| `handle SIGNAL [KEYWORDS...]' |
| Change the way GDB handles signal SIGNAL. SIGNAL can be the |
| number of a signal or its name (with or without the `SIG' at the |
| beginning); a list of signal numbers of the form `LOW-HIGH'; or |
| the word `all', meaning all the known signals. Optional arguments |
| KEYWORDS, described below, say what change to make. |
| |
| The keywords allowed by the `handle' command can be abbreviated. |
| Their full names are: |
| |
| `nostop' |
| GDB should not stop your program when this signal happens. It may |
| still print a message telling you that the signal has come in. |
| |
| `stop' |
| GDB should stop your program when this signal happens. This |
| implies the `print' keyword as well. |
| |
| `print' |
| GDB should print a message when this signal happens. |
| |
| `noprint' |
| GDB should not mention the occurrence of the signal at all. This |
| implies the `nostop' keyword as well. |
| |
| `pass' |
| `noignore' |
| GDB should allow your program to see this signal; your program can |
| handle the signal, or else it may terminate if the signal is fatal |
| and not handled. `pass' and `noignore' are synonyms. |
| |
| `nopass' |
| `ignore' |
| GDB should not allow your program to see this signal. `nopass' |
| and `ignore' are synonyms. |
| |
| When a signal stops your program, the signal is not visible to the |
| program until you continue. Your program sees the signal then, if |
| `pass' is in effect for the signal in question _at that time_. In |
| other words, after GDB reports a signal, you can use the `handle' |
| command with `pass' or `nopass' to control whether your program sees |
| that signal when you continue. |
| |
| The default is set to `nostop', `noprint', `pass' for non-erroneous |
| signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop', |
| `print', `pass' for the erroneous signals. |
| |
| You can also use the `signal' command to prevent your program from |
| seeing a signal, or cause it to see a signal it normally would not see, |
| or to give it any signal at any time. For example, if your program |
| stopped due to some sort of memory reference error, you might store |
| correct values into the erroneous variables and continue, hoping to see |
| more execution; but your program would probably terminate immediately as |
| a result of the fatal signal once it saw the signal. To prevent this, |
| you can continue with `signal 0'. *Note Giving your Program a Signal: |
| Signaling. |
| |
| |
| File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping |
| |
| 5.4 Stopping and Starting Multi-thread Programs |
| =============================================== |
| |
| When your program has multiple threads (*note Debugging Programs with |
| Multiple Threads: Threads.), you can choose whether to set breakpoints |
| on all threads, or on a particular thread. |
| |
| `break LINESPEC thread THREADNO' |
| `break LINESPEC thread THREADNO if ...' |
| LINESPEC specifies source lines; there are several ways of writing |
| them (*note Specify Location::), but the effect is always to |
| specify some source line. |
| |
| Use the qualifier `thread THREADNO' with a breakpoint command to |
| specify that you only want GDB to stop the program when a |
| particular thread reaches this breakpoint. THREADNO is one of the |
| numeric thread identifiers assigned by GDB, shown in the first |
| column of the `info threads' display. |
| |
| If you do not specify `thread THREADNO' when you set a breakpoint, |
| the breakpoint applies to _all_ threads of your program. |
| |
| You can use the `thread' qualifier on conditional breakpoints as |
| well; in this case, place `thread THREADNO' before the breakpoint |
| condition, like this: |
| |
| (gdb) break frik.c:13 thread 28 if bartab > lim |
| |
| |
| Whenever your program stops under GDB for any reason, _all_ threads |
| of execution stop, not just the current thread. This allows you to |
| examine the overall state of the program, including switching between |
| threads, without worrying that things may change underfoot. |
| |
| There is an unfortunate side effect. If one thread stops for a |
| breakpoint, or for some other reason, and another thread is blocked in a |
| system call, then the system call may return prematurely. This is a |
| consequence of the interaction between multiple threads and the signals |
| that GDB uses to implement breakpoints and other events that stop |
| execution. |
| |
| To handle this problem, your program should check the return value of |
| each system call and react appropriately. This is good programming |
| style anyways. |
| |
| For example, do not write code like this: |
| |
| sleep (10); |
| |
| The call to `sleep' will return early if a different thread stops at |
| a breakpoint or for some other reason. |
| |
| Instead, write this: |
| |
| int unslept = 10; |
| while (unslept > 0) |
| unslept = sleep (unslept); |
| |
| A system call is allowed to return early, so the system is still |
| conforming to its specification. But GDB does cause your |
| multi-threaded program to behave differently than it would without GDB. |
| |
| Also, GDB uses internal breakpoints in the thread library to monitor |
| certain events such as thread creation and thread destruction. When |
| such an event happens, a system call in another thread may return |
| prematurely, even though your program does not appear to stop. |
| |
| Conversely, whenever you restart the program, _all_ threads start |
| executing. _This is true even when single-stepping_ with commands like |
| `step' or `next'. |
| |
| In particular, GDB cannot single-step all threads in lockstep. |
| Since thread scheduling is up to your debugging target's operating |
| system (not controlled by GDB), other threads may execute more than one |
| statement while the current thread completes a single step. Moreover, |
| in general other threads stop in the middle of a statement, rather than |
| at a clean statement boundary, when the program stops. |
| |
| You might even find your program stopped in another thread after |
| continuing or even single-stepping. This happens whenever some other |
| thread runs into a breakpoint, a signal, or an exception before the |
| first thread completes whatever you requested. |
| |
| On some OSes, you can lock the OS scheduler and thus allow only a |
| single thread to run. |
| |
| `set scheduler-locking MODE' |
| Set the scheduler locking mode. If it is `off', then there is no |
| locking and any thread may run at any time. If `on', then only the |
| current thread may run when the inferior is resumed. The `step' |
| mode optimizes for single-stepping. It stops other threads from |
| "seizing the prompt" by preempting the current thread while you are |
| stepping. Other threads will only rarely (or never) get a chance |
| to run when you step. They are more likely to run when you `next' |
| over a function call, and they are completely free to run when you |
| use commands like `continue', `until', or `finish'. However, |
| unless another thread hits a breakpoint during its timeslice, they |
| will never steal the GDB prompt away from the thread that you are |
| debugging. |
| |
| `show scheduler-locking' |
| Display the current scheduler locking mode. |
| |
| |
| File: gdb.info, Node: Stack, Next: Source, Prev: Stopping, Up: Top |
| |
| 6 Examining the Stack |
| ********************* |
| |
| When your program has stopped, the first thing you need to know is |
| where it stopped and how it got there. |
| |
| Each time your program performs a function call, information about |
| the call is generated. That information includes the location of the |
| call in your program, the arguments of the call, and the local |
| variables of the function being called. The information is saved in a |
| block of data called a "stack frame". The stack frames are allocated |
| in a region of memory called the "call stack". |
| |
| When your program stops, the GDB commands for examining the stack |
| allow you to see all of this information. |
| |
| One of the stack frames is "selected" by GDB and many GDB commands |
| refer implicitly to the selected frame. In particular, whenever you |
| ask GDB for the value of a variable in your program, the value is found |
| in the selected frame. There are special GDB commands to select |
| whichever frame you are interested in. *Note Selecting a Frame: |
| Selection. |
| |
| When your program stops, GDB automatically selects the currently |
| executing frame and describes it briefly, similar to the `frame' |
| command (*note Information about a Frame: Frame Info.). |
| |
| * Menu: |
| |
| * Frames:: Stack frames |
| * Backtrace:: Backtraces |
| * Selection:: Selecting a frame |
| * Frame Info:: Information on a frame |
| |
| |
| File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack |
| |
| 6.1 Stack Frames |
| ================ |
| |
| The call stack is divided up into contiguous pieces called "stack |
| frames", or "frames" for short; each frame is the data associated with |
| one call to one function. The frame contains the arguments given to |
| the function, the function's local variables, and the address at which |
| the function is executing. |
| |
| When your program is started, the stack has only one frame, that of |
| the function `main'. This is called the "initial" frame or the |
| "outermost" frame. Each time a function is called, a new frame is |
| made. Each time a function returns, the frame for that function |
| invocation is eliminated. If a function is recursive, there can be |
| many frames for the same function. The frame for the function in which |
| execution is actually occurring is called the "innermost" frame. This |
| is the most recently created of all the stack frames that still exist. |
| |
| Inside your program, stack frames are identified by their addresses. |
| A stack frame consists of many bytes, each of which has its own |
| address; each kind of computer has a convention for choosing one byte |
| whose address serves as the address of the frame. Usually this address |
| is kept in a register called the "frame pointer register" (*note $fp: |
| Registers.) while execution is going on in that frame. |
| |
| GDB assigns numbers to all existing stack frames, starting with zero |
| for the innermost frame, one for the frame that called it, and so on |
| upward. These numbers do not really exist in your program; they are |
| assigned by GDB to give you a way of designating stack frames in GDB |
| commands. |
| |
| Some compilers provide a way to compile functions so that they |
| operate without stack frames. (For example, the GCC option |
| `-fomit-frame-pointer' |
| generates functions without a frame.) This is occasionally done |
| with heavily used library functions to save the frame setup time. GDB |
| has limited facilities for dealing with these function invocations. If |
| the innermost function invocation has no stack frame, GDB nevertheless |
| regards it as though it had a separate frame, which is numbered zero as |
| usual, allowing correct tracing of the function call chain. However, |
| GDB has no provision for frameless functions elsewhere in the stack. |
| |
| `frame ARGS' |
| The `frame' command allows you to move from one stack frame to |
| another, and to print the stack frame you select. ARGS may be |
| either the address of the frame or the stack frame number. |
| Without an argument, `frame' prints the current stack frame. |
| |
| `select-frame' |
| The `select-frame' command allows you to move from one stack frame |
| to another without printing the frame. This is the silent version |
| of `frame'. |
| |
| |
| File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack |
| |
| 6.2 Backtraces |
| ============== |
| |
| A backtrace is a summary of how your program got where it is. It shows |
| one line per frame, for many frames, starting with the currently |
| executing frame (frame zero), followed by its caller (frame one), and |
| on up the stack. |
| |
| `backtrace' |
| `bt' |
| Print a backtrace of the entire stack: one line per frame for all |
| frames in the stack. |
| |
| You can stop the backtrace at any time by typing the system |
| interrupt character, normally `Ctrl-c'. |
| |
| `backtrace N' |
| `bt N' |
| Similar, but print only the innermost N frames. |
| |
| `backtrace -N' |
| `bt -N' |
| Similar, but print only the outermost N frames. |
| |
| `backtrace full' |
| `bt full' |
| `bt full N' |
| `bt full -N' |
| Print the values of the local variables also. N specifies the |
| number of frames to print, as described above. |
| |
| The names `where' and `info stack' (abbreviated `info s') are |
| additional aliases for `backtrace'. |
| |
| In a multi-threaded program, GDB by default shows the backtrace only |
| for the current thread. To display the backtrace for several or all of |
| the threads, use the command `thread apply' (*note thread apply: |
| Threads.). For example, if you type `thread apply all backtrace', GDB |
| will display the backtrace for all the threads; this is handy when you |
| debug a core dump of a multi-threaded program. |
| |
| Each line in the backtrace shows the frame number and the function |
| name. The program counter value is also shown--unless you use `set |
| print address off'. The backtrace also shows the source file name and |
| line number, as well as the arguments to the function. The program |
| counter value is omitted if it is at the beginning of the code for that |
| line number. |
| |
| Here is an example of a backtrace. It was made with the command `bt |
| 3', so it shows the innermost three frames. |
| |
| #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) |
| at builtin.c:993 |
| #1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 |
| #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) |
| at macro.c:71 |
| (More stack frames follow...) |
| |
| The display for frame zero does not begin with a program counter value, |
| indicating that your program has stopped at the beginning of the code |
| for line `993' of `builtin.c'. |
| |
| If your program was compiled with optimizations, some compilers will |
| optimize away arguments passed to functions if those arguments are |
| never used after the call. Such optimizations generate code that |
| passes arguments through registers, but doesn't store those arguments |
| in the stack frame. GDB has no way of displaying such arguments in |
| stack frames other than the innermost one. Here's what such a |
| backtrace might look like: |
| |
| #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) |
| at builtin.c:993 |
| #1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242 |
| #2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08) |
| at macro.c:71 |
| (More stack frames follow...) |
| |
| The values of arguments that were not saved in their stack frames are |
| shown as `<value optimized out>'. |
| |
| If you need to display the values of such optimized-out arguments, |
| either deduce that from other variables whose values depend on the one |
| you are interested in, or recompile without optimizations. |
| |
| Most programs have a standard user entry point--a place where system |
| libraries and startup code transition into user code. For C this is |
| `main'(1). When GDB finds the entry function in a backtrace it will |
| terminate the backtrace, to avoid tracing into highly system-specific |
| (and generally uninteresting) code. |
| |
| If you need to examine the startup code, or limit the number of |
| levels in a backtrace, you can change this behavior: |
| |
| `set backtrace past-main' |
| `set backtrace past-main on' |
| Backtraces will continue past the user entry point. |
| |
| `set backtrace past-main off' |
| Backtraces will stop when they encounter the user entry point. |
| This is the default. |
| |
| `show backtrace past-main' |
| Display the current user entry point backtrace policy. |
| |
| `set backtrace past-entry' |
| `set backtrace past-entry on' |
| Backtraces will continue past the internal entry point of an |
| application. This entry point is encoded by the linker when the |
| application is built, and is likely before the user entry point |
| `main' (or equivalent) is called. |
| |
| `set backtrace past-entry off' |
| Backtraces will stop when they encounter the internal entry point |
| of an application. This is the default. |
| |
| `show backtrace past-entry' |
| Display the current internal entry point backtrace policy. |
| |
| `set backtrace limit N' |
| `set backtrace limit 0' |
| Limit the backtrace to N levels. A value of zero means unlimited. |
| |
| `show backtrace limit' |
| Display the current limit on backtrace levels. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Note that embedded programs (the so-called "free-standing" |
| environment) are not required to have a `main' function as the entry |
| point. They could even have multiple entry points. |
| |
| |
| File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack |
| |
| 6.3 Selecting a Frame |
| ===================== |
| |
| Most commands for examining the stack and other data in your program |
| work on whichever stack frame is selected at the moment. Here are the |
| commands for selecting a stack frame; all of them finish by printing a |
| brief description of the stack frame just selected. |
| |
| `frame N' |
| `f N' |
| Select frame number N. Recall that frame zero is the innermost |
| (currently executing) frame, frame one is the frame that called the |
| innermost one, and so on. The highest-numbered frame is the one |
| for `main'. |
| |
| `frame ADDR' |
| `f ADDR' |
| Select the frame at address ADDR. This is useful mainly if the |
| chaining of stack frames has been damaged by a bug, making it |
| impossible for GDB to assign numbers properly to all frames. In |
| addition, this can be useful when your program has multiple stacks |
| and switches between them. |
| |
| On the SPARC architecture, `frame' needs two addresses to select |
| an arbitrary frame: a frame pointer and a stack pointer. |
| |
| On the MIPS and Alpha architecture, it needs two addresses: a stack |
| pointer and a program counter. |
| |
| On the 29k architecture, it needs three addresses: a register stack |
| pointer, a program counter, and a memory stack pointer. |
| |
| `up N' |
| Move N frames up the stack. For positive numbers N, this advances |
| toward the outermost frame, to higher frame numbers, to frames |
| that have existed longer. N defaults to one. |
| |
| `down N' |
| Move N frames down the stack. For positive numbers N, this |
| advances toward the innermost frame, to lower frame numbers, to |
| frames that were created more recently. N defaults to one. You |
| may abbreviate `down' as `do'. |
| |
| All of these commands end by printing two lines of output describing |
| the frame. The first line shows the frame number, the function name, |
| the arguments, and the source file and line number of execution in that |
| frame. The second line shows the text of that source line. |
| |
| For example: |
| |
| (gdb) up |
| #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) |
| at env.c:10 |
| 10 read_input_file (argv[i]); |
| |
| After such a printout, the `list' command with no arguments prints |
| ten lines centered on the point of execution in the frame. You can |
| also edit the program at the point of execution with your favorite |
| editing program by typing `edit'. *Note Printing Source Lines: List, |
| for details. |
| |
| `up-silently N' |
| `down-silently N' |
| These two commands are variants of `up' and `down', respectively; |
| they differ in that they do their work silently, without causing |
| display of the new frame. They are intended primarily for use in |
| GDB command scripts, where the output might be unnecessary and |
| distracting. |
| |
| |
| File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack |
| |
| 6.4 Information About a Frame |
| ============================= |
| |
| There are several other commands to print information about the selected |
| stack frame. |
| |
| `frame' |
| `f' |
| When used without any argument, this command does not change which |
| frame is selected, but prints a brief description of the currently |
| selected stack frame. It can be abbreviated `f'. With an |
| argument, this command is used to select a stack frame. *Note |
| Selecting a Frame: Selection. |
| |
| `info frame' |
| `info f' |
| This command prints a verbose description of the selected stack |
| frame, including: |
| |
| * the address of the frame |
| |
| * the address of the next frame down (called by this frame) |
| |
| * the address of the next frame up (caller of this frame) |
| |
| * the language in which the source code corresponding to this |
| frame is written |
| |
| * the address of the frame's arguments |
| |
| * the address of the frame's local variables |
| |
| * the program counter saved in it (the address of execution in |
| the caller frame) |
| |
| * which registers were saved in the frame |
| |
| The verbose description is useful when something has gone wrong |
| that has made the stack format fail to fit the usual conventions. |
| |
| `info frame ADDR' |
| `info f ADDR' |
| Print a verbose description of the frame at address ADDR, without |
| selecting that frame. The selected frame remains unchanged by this |
| command. This requires the same kind of address (more than one |
| for some architectures) that you specify in the `frame' command. |
| *Note Selecting a Frame: Selection. |
| |
| `info args' |
| Print the arguments of the selected frame, each on a separate line. |
| |
| `info locals' |
| Print the local variables of the selected frame, each on a separate |
| line. These are all variables (declared either static or |
| automatic) accessible at the point of execution of the selected |
| frame. |
| |
| `info catch' |
| Print a list of all the exception handlers that are active in the |
| current stack frame at the current point of execution. To see |
| other exception handlers, visit the associated frame (using the |
| `up', `down', or `frame' commands); then type `info catch'. *Note |
| Setting Catchpoints: Set Catchpoints. |
| |
| |
| |
| File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top |
| |
| 7 Examining Source Files |
| ************************ |
| |
| GDB can print parts of your program's source, since the debugging |
| information recorded in the program tells GDB what source files were |
| used to build it. When your program stops, GDB spontaneously prints |
| the line where it stopped. Likewise, when you select a stack frame |
| (*note Selecting a Frame: Selection.), GDB prints the line where |
| execution in that frame has stopped. You can print other portions of |
| source files by explicit command. |
| |
| If you use GDB through its GNU Emacs interface, you may prefer to |
| use Emacs facilities to view source; see *Note Using GDB under GNU |
| Emacs: Emacs. |
| |
| * Menu: |
| |
| * List:: Printing source lines |
| * Specify Location:: How to specify code locations |
| * Edit:: Editing source files |
| * Search:: Searching source files |
| * Source Path:: Specifying source directories |
| * Machine Code:: Source and machine code |
| |
| |
| File: gdb.info, Node: List, Next: Specify Location, Up: Source |
| |
| 7.1 Printing Source Lines |
| ========================= |
| |
| To print lines from a source file, use the `list' command (abbreviated |
| `l'). By default, ten lines are printed. There are several ways to |
| specify what part of the file you want to print; see *Note Specify |
| Location::, for the full list. |
| |
| Here are the forms of the `list' command most commonly used: |
| |
| `list LINENUM' |
| Print lines centered around line number LINENUM in the current |
| source file. |
| |
| `list FUNCTION' |
| Print lines centered around the beginning of function FUNCTION. |
| |
| `list' |
| Print more lines. If the last lines printed were printed with a |
| `list' command, this prints lines following the last lines |
| printed; however, if the last line printed was a solitary line |
| printed as part of displaying a stack frame (*note Examining the |
| Stack: Stack.), this prints lines centered around that line. |
| |
| `list -' |
| Print lines just before the lines last printed. |
| |
| By default, GDB prints ten source lines with any of these forms of |
| the `list' command. You can change this using `set listsize': |
| |
| `set listsize COUNT' |
| Make the `list' command display COUNT source lines (unless the |
| `list' argument explicitly specifies some other number). |
| |
| `show listsize' |
| Display the number of lines that `list' prints. |
| |
| Repeating a `list' command with <RET> discards the argument, so it |
| is equivalent to typing just `list'. This is more useful than listing |
| the same lines again. An exception is made for an argument of `-'; |
| that argument is preserved in repetition so that each repetition moves |
| up in the source file. |
| |
| In general, the `list' command expects you to supply zero, one or two |
| "linespecs". Linespecs specify source lines; there are several ways of |
| writing them (*note Specify Location::), but the effect is always to |
| specify some source line. |
| |
| Here is a complete description of the possible arguments for `list': |
| |
| `list LINESPEC' |
| Print lines centered around the line specified by LINESPEC. |
| |
| `list FIRST,LAST' |
| Print lines from FIRST to LAST. Both arguments are linespecs. |
| When a `list' command has two linespecs, and the source file of |
| the second linespec is omitted, this refers to the same source |
| file as the first linespec. |
| |
| `list ,LAST' |
| Print lines ending with LAST. |
| |
| `list FIRST,' |
| Print lines starting with FIRST. |
| |
| `list +' |
| Print lines just after the lines last printed. |
| |
| `list -' |
| Print lines just before the lines last printed. |
| |
| `list' |
| As described in the preceding table. |
| |
| |
| File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source |
| |
| 7.2 Specifying a Location |
| ========================= |
| |
| Several GDB commands accept arguments that specify a location of your |
| program's code. Since GDB is a source-level debugger, a location |
| usually specifies some line in the source code; for that reason, |
| locations are also known as "linespecs". |
| |
| Here are all the different ways of specifying a code location that |
| GDB understands: |
| |
| `LINENUM' |
| Specifies the line number LINENUM of the current source file. |
| |
| `-OFFSET' |
| `+OFFSET' |
| Specifies the line OFFSET lines before or after the "current |
| line". For the `list' command, the current line is the last one |
| printed; for the breakpoint commands, this is the line at which |
| execution stopped in the currently selected "stack frame" (*note |
| Frames: Frames, for a description of stack frames.) When used as |
| the second of the two linespecs in a `list' command, this |
| specifies the line OFFSET lines up or down from the first linespec. |
| |
| `FILENAME:LINENUM' |
| Specifies the line LINENUM in the source file FILENAME. |
| |
| `FUNCTION' |
| Specifies the line that begins the body of the function FUNCTION. |
| For example, in C, this is the line with the open brace. |
| |
| `FILENAME:FUNCTION' |
| Specifies the line that begins the body of the function FUNCTION |
| in the file FILENAME. You only need the file name with a function |
| name to avoid ambiguity when there are identically named functions |
| in different source files. |
| |
| `*ADDRESS' |
| Specifies the program address ADDRESS. For line-oriented |
| commands, such as `list' and `edit', this specifies a source line |
| that contains ADDRESS. For `break' and other breakpoint oriented |
| commands, this can be used to set breakpoints in parts of your |
| program which do not have debugging information or source files. |
| |
| Here ADDRESS may be any expression valid in the current working |
| language (*note working language: Languages.) that specifies a code |
| address. In addition, as a convenience, GDB extends the semantics |
| of expressions used in locations to cover the situations that |
| frequently happen during debugging. Here are the various forms of |
| ADDRESS: |
| |
| `EXPRESSION' |
| Any expression valid in the current working language. |
| |
| `FUNCADDR' |
| An address of a function or procedure derived from its name. |
| In C, C++, Java, Objective-C, Fortran, minimal, and assembly, |
| this is simply the function's name FUNCTION (and actually a |
| special case of a valid expression). In Pascal and Modula-2, |
| this is `&FUNCTION'. In Ada, this is `FUNCTION'Address' |
| (although the Pascal form also works). |
| |
| This form specifies the address of the function's first |
| instruction, before the stack frame and arguments have been |
| set up. |
| |
| `'FILENAME'::FUNCADDR' |
| Like FUNCADDR above, but also specifies the name of the source |
| file explicitly. This is useful if the name of the function |
| does not specify the function unambiguously, e.g., if there |
| are several functions with identical names in different |
| source files. |
| |
| |
| |
| File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source |
| |
| 7.3 Editing Source Files |
| ======================== |
| |
| To edit the lines in a source file, use the `edit' command. The |
| editing program of your choice is invoked with the current line set to |
| the active line in the program. Alternatively, there are several ways |
| to specify what part of the file you want to print if you want to see |
| other parts of the program: |
| |
| `edit LOCATION' |
| Edit the source file specified by `location'. Editing starts at |
| that LOCATION, e.g., at the specified source line of the specified |
| file. *Note Specify Location::, for all the possible forms of the |
| LOCATION argument; here are the forms of the `edit' command most |
| commonly used: |
| |
| `edit NUMBER' |
| Edit the current source file with NUMBER as the active line |
| number. |
| |
| `edit FUNCTION' |
| Edit the file containing FUNCTION at the beginning of its |
| definition. |
| |
| |
| 7.3.1 Choosing your Editor |
| -------------------------- |
| |
| You can customize GDB to use any editor you want (1). By default, it |
| is `/bin/ex', but you can change this by setting the environment |
| variable `EDITOR' before using GDB. For example, to configure GDB to |
| use the `vi' editor, you could use these commands with the `sh' shell: |
| EDITOR=/usr/bin/vi |
| export EDITOR |
| gdb ... |
| or in the `csh' shell, |
| setenv EDITOR /usr/bin/vi |
| gdb ... |
| |
| ---------- Footnotes ---------- |
| |
| (1) The only restriction is that your editor (say `ex'), recognizes |
| the following command-line syntax: |
| ex +NUMBER file |
| The optional numeric value +NUMBER specifies the number of the line |
| in the file where to start editing. |
| |
| |
| File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source |
| |
| 7.4 Searching Source Files |
| ========================== |
| |
| There are two commands for searching through the current source file |
| for a regular expression. |
| |
| `forward-search REGEXP' |
| `search REGEXP' |
| The command `forward-search REGEXP' checks each line, starting |
| with the one following the last line listed, for a match for |
| REGEXP. It lists the line that is found. You can use the synonym |
| `search REGEXP' or abbreviate the command name as `fo'. |
| |
| `reverse-search REGEXP' |
| The command `reverse-search REGEXP' checks each line, starting |
| with the one before the last line listed and going backward, for a |
| match for REGEXP. It lists the line that is found. You can |
| abbreviate this command as `rev'. |
| |
| |
| File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source |
| |
| 7.5 Specifying Source Directories |
| ================================= |
| |
| Executable programs sometimes do not record the directories of the |
| source files from which they were compiled, just the names. Even when |
| they do, the directories could be moved between the compilation and |
| your debugging session. GDB has a list of directories to search for |
| source files; this is called the "source path". Each time GDB wants a |
| source file, it tries all the directories in the list, in the order |
| they are present in the list, until it finds a file with the desired |
| name. |
| |
| For example, suppose an executable references the file |
| `/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The |
| file is first looked up literally; if this fails, |
| `/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, |
| `/mnt/cross/foo.c' is opened; if this fails, an error message is |
| printed. GDB does not look up the parts of the source file name, such |
| as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of |
| the source path are not searched: if the source path is `/mnt/cross', |
| and the binary refers to `foo.c', GDB would not find it under |
| `/mnt/cross/usr/src/foo-1.0/lib'. |
| |
| Plain file names, relative file names with leading directories, file |
| names containing dots, etc. are all treated as described above; for |
| instance, if the source path is `/mnt/cross', and the source file is |
| recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then |
| `/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'. |
| |
| Note that the executable search path is _not_ used to locate the |
| source files. |
| |
| Whenever you reset or rearrange the source path, GDB clears out any |
| information it has cached about where source files are found and where |
| each line is in the file. |
| |
| When you start GDB, its source path includes only `cdir' and `cwd', |
| in that order. To add other directories, use the `directory' command. |
| |
| The search path is used to find both program source files and GDB |
| script files (read using the `-command' option and `source' command). |
| |
| In addition to the source path, GDB provides a set of commands that |
| manage a list of source path substitution rules. A "substitution rule" |
| specifies how to rewrite source directories stored in the program's |
| debug information in case the sources were moved to a different |
| directory between compilation and debugging. A rule is made of two |
| strings, the first specifying what needs to be rewritten in the path, |
| and the second specifying how it should be rewritten. In *Note set |
| substitute-path::, we name these two parts FROM and TO respectively. |
| GDB does a simple string replacement of FROM with TO at the start of |
| the directory part of the source file name, and uses that result |
| instead of the original file name to look up the sources. |
| |
| Using the previous example, suppose the `foo-1.0' tree has been |
| moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace |
| `/usr/src' in all source path names with `/mnt/cross'. The first |
| lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the |
| original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source |
| path substitution rule, use the `set substitute-path' command (*note |
| set substitute-path::). |
| |
| To avoid unexpected substitution results, a rule is applied only if |
| the FROM part of the directory name ends at a directory separator. For |
| instance, a rule substituting `/usr/source' into `/mnt/cross' will be |
| applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'. |
| And because the substitution is applied only at the beginning of the |
| directory name, this rule will not be applied to |
| `/root/usr/source/baz.c' either. |
| |
| In many cases, you can achieve the same result using the `directory' |
| command. However, `set substitute-path' can be more efficient in the |
| case where the sources are organized in a complex tree with multiple |
| subdirectories. With the `directory' command, you need to add each |
| subdirectory of your project. If you moved the entire tree while |
| preserving its internal organization, then `set substitute-path' allows |
| you to direct the debugger to all the sources with one single command. |
| |
| `set substitute-path' is also more than just a shortcut command. |
| The source path is only used if the file at the original location no |
| longer exists. On the other hand, `set substitute-path' modifies the |
| debugger behavior to look at the rewritten location instead. So, if |
| for any reason a source file that is not relevant to your executable is |
| located at the original location, a substitution rule is the only |
| method available to point GDB at the new location. |
| |
| `directory DIRNAME ...' |
| |
| `dir DIRNAME ...' |
| Add directory DIRNAME to the front of the source path. Several |
| directory names may be given to this command, separated by `:' |
| (`;' on MS-DOS and MS-Windows, where `:' usually appears as part |
| of absolute file names) or whitespace. You may specify a |
| directory that is already in the source path; this moves it |
| forward, so GDB searches it sooner. |
| |
| You can use the string `$cdir' to refer to the compilation |
| directory (if one is recorded), and `$cwd' to refer to the current |
| working directory. `$cwd' is not the same as `.'--the former |
| tracks the current working directory as it changes during your GDB |
| session, while the latter is immediately expanded to the current |
| directory at the time you add an entry to the source path. |
| |
| `directory' |
| Reset the source path to its default value (`$cdir:$cwd' on Unix |
| systems). This requires confirmation. |
| |
| `show directories' |
| Print the source path: show which directories it contains. |
| |
| `set substitute-path FROM TO' |
| Define a source path substitution rule, and add it at the end of |
| the current list of existing substitution rules. If a rule with |
| the same FROM was already defined, then the old rule is also |
| deleted. |
| |
| For example, if the file `/foo/bar/baz.c' was moved to |
| `/mnt/cross/baz.c', then the command |
| |
| (gdb) set substitute-path /usr/src /mnt/cross |
| |
| will tell GDB to replace `/usr/src' with `/mnt/cross', which will |
| allow GDB to find the file `baz.c' even though it was moved. |
| |
| In the case when more than one substitution rule have been defined, |
| the rules are evaluated one by one in the order where they have |
| been defined. The first one matching, if any, is selected to |
| perform the substitution. |
| |
| For instance, if we had entered the following commands: |
| |
| (gdb) set substitute-path /usr/src/include /mnt/include |
| (gdb) set substitute-path /usr/src /mnt/src |
| |
| GDB would then rewrite `/usr/src/include/defs.h' into |
| `/mnt/include/defs.h' by using the first rule. However, it would |
| use the second rule to rewrite `/usr/src/lib/foo.c' into |
| `/mnt/src/lib/foo.c'. |
| |
| `unset substitute-path [path]' |
| If a path is specified, search the current list of substitution |
| rules for a rule that would rewrite that path. Delete that rule |
| if found. A warning is emitted by the debugger if no rule could |
| be found. |
| |
| If no path is specified, then all substitution rules are deleted. |
| |
| `show substitute-path [path]' |
| If a path is specified, then print the source path substitution |
| rule which would rewrite that path, if any. |
| |
| If no path is specified, then print all existing source path |
| substitution rules. |
| |
| |
| If your source path is cluttered with directories that are no longer |
| of interest, GDB may sometimes cause confusion by finding the wrong |
| versions of source. You can correct the situation as follows: |
| |
| 1. Use `directory' with no argument to reset the source path to its |
| default value. |
| |
| 2. Use `directory' with suitable arguments to reinstall the |
| directories you want in the source path. You can add all the |
| directories in one command. |
| |
| |
| File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source |
| |
| 7.6 Source and Machine Code |
| =========================== |
| |
| You can use the command `info line' to map source lines to program |
| addresses (and vice versa), and the command `disassemble' to display a |
| range of addresses as machine instructions. When run under GNU Emacs |
| mode, the `info line' command causes the arrow to point to the line |
| specified. Also, `info line' prints addresses in symbolic form as well |
| as hex. |
| |
| `info line LINESPEC' |
| Print the starting and ending addresses of the compiled code for |
| source line LINESPEC. You can specify source lines in any of the |
| ways documented in *Note Specify Location::. |
| |
| For example, we can use `info line' to discover the location of the |
| object code for the first line of function `m4_changequote': |
| |
| (gdb) info line m4_changequote |
| Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. |
| |
| We can also inquire (using `*ADDR' as the form for LINESPEC) what |
| source line covers a particular address: |
| (gdb) info line *0x63ff |
| Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. |
| |
| After `info line', the default address for the `x' command is |
| changed to the starting address of the line, so that `x/i' is |
| sufficient to begin examining the machine code (*note Examining Memory: |
| Memory.). Also, this address is saved as the value of the convenience |
| variable `$_' (*note Convenience Variables: Convenience Vars.). |
| |
| `disassemble' |
| This specialized command dumps a range of memory as machine |
| instructions. The default memory range is the function |
| surrounding the program counter of the selected frame. A single |
| argument to this command is a program counter value; GDB dumps the |
| function surrounding this value. Two arguments specify a range of |
| addresses (first inclusive, second exclusive) to dump. |
| |
| The following example shows the disassembly of a range of addresses |
| of HP PA-RISC 2.0 code: |
| |
| (gdb) disas 0x32c4 0x32e4 |
| Dump of assembler code from 0x32c4 to 0x32e4: |
| 0x32c4 <main+204>: addil 0,dp |
| 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 |
| 0x32cc <main+212>: ldil 0x3000,r31 |
| 0x32d0 <main+216>: ble 0x3f8(sr4,r31) |
| 0x32d4 <main+220>: ldo 0(r31),rp |
| 0x32d8 <main+224>: addil -0x800,dp |
| 0x32dc <main+228>: ldo 0x588(r1),r26 |
| 0x32e0 <main+232>: ldil 0x3000,r31 |
| End of assembler dump. |
| |
| Some architectures have more than one commonly-used set of |
| instruction mnemonics or other syntax. |
| |
| For programs that were dynamically linked and use shared libraries, |
| instructions that call functions or branch to locations in the shared |
| libraries might show a seemingly bogus location--it's actually a |
| location of the relocation table. On some architectures, GDB might be |
| able to resolve these to actual function names. |
| |
| `set disassembly-flavor INSTRUCTION-SET' |
| Select the instruction set to use when disassembling the program |
| via the `disassemble' or `x/i' commands. |
| |
| Currently this command is only defined for the Intel x86 family. |
| You can set INSTRUCTION-SET to either `intel' or `att'. The |
| default is `att', the AT&T flavor used by default by Unix |
| assemblers for x86-based targets. |
| |
| `show disassembly-flavor' |
| Show the current setting of the disassembly flavor. |
| |
| |
| File: gdb.info, Node: Data, Next: Macros, Prev: Source, Up: Top |
| |
| 8 Examining Data |
| **************** |
| |
| The usual way to examine data in your program is with the `print' |
| command (abbreviated `p'), or its synonym `inspect'. It evaluates and |
| prints the value of an expression of the language your program is |
| written in (*note Using GDB with Different Languages: Languages.). |
| |
| `print EXPR' |
| `print /F EXPR' |
| EXPR is an expression (in the source language). By default the |
| value of EXPR is printed in a format appropriate to its data type; |
| you can choose a different format by specifying `/F', where F is a |
| letter specifying the format; see *Note Output Formats: Output |
| Formats. |
| |
| `print' |
| `print /F' |
| If you omit EXPR, GDB displays the last value again (from the |
| "value history"; *note Value History: Value History.). This |
| allows you to conveniently inspect the same value in an |
| alternative format. |
| |
| A more low-level way of examining data is with the `x' command. It |
| examines data in memory at a specified address and prints it in a |
| specified format. *Note Examining Memory: Memory. |
| |
| If you are interested in information about types, or about how the |
| fields of a struct or a class are declared, use the `ptype EXP' command |
| rather than `print'. *Note Examining the Symbol Table: Symbols. |
| |
| * Menu: |
| |
| * Expressions:: Expressions |
| * Variables:: Program variables |
| * Arrays:: Artificial arrays |
| * Output Formats:: Output formats |
| * Memory:: Examining memory |
| * Auto Display:: Automatic display |
| * Print Settings:: Print settings |
| * Value History:: Value history |
| * Convenience Vars:: Convenience variables |
| * Registers:: Registers |
| * Floating Point Hardware:: Floating point hardware |
| * Vector Unit:: Vector Unit |
| * OS Information:: Auxiliary data provided by operating system |
| * Memory Region Attributes:: Memory region attributes |
| * Dump/Restore Files:: Copy between memory and a file |
| * Core File Generation:: Cause a program dump its core |
| * Character Sets:: Debugging programs that use a different |
| character set than GDB does |
| * Caching Remote Data:: Data caching for remote targets |
| |
| |
| File: gdb.info, Node: Expressions, Next: Variables, Up: Data |
| |
| 8.1 Expressions |
| =============== |
| |
| `print' and many other GDB commands accept an expression and compute |
| its value. Any kind of constant, variable or operator defined by the |
| programming language you are using is valid in an expression in GDB. |
| This includes conditional expressions, function calls, casts, and |
| string constants. It also includes preprocessor macros, if you |
| compiled your program to include this information; see *Note |
| Compilation::. |
| |
| GDB supports array constants in expressions input by the user. The |
| syntax is {ELEMENT, ELEMENT...}. For example, you can use the command |
| `print {1, 2, 3}' to build up an array in memory that is `malloc'ed in |
| the target program. |
| |
| Because C is so widespread, most of the expressions shown in |
| examples in this manual are in C. *Note Using GDB with Different |
| Languages: Languages, for information on how to use expressions in other |
| languages. |
| |
| In this section, we discuss operators that you can use in GDB |
| expressions regardless of your programming language. |
| |
| Casts are supported in all languages, not just in C, because it is so |
| useful to cast a number into a pointer in order to examine a structure |
| at that address in memory. |
| |
| GDB supports these operators, in addition to those common to |
| programming languages: |
| |
| `@' |
| `@' is a binary operator for treating parts of memory as arrays. |
| *Note Artificial Arrays: Arrays, for more information. |
| |
| `::' |
| `::' allows you to specify a variable in terms of the file or |
| function where it is defined. *Note Program Variables: Variables. |
| |
| `{TYPE} ADDR' |
| Refers to an object of type TYPE stored at address ADDR in memory. |
| ADDR may be any expression whose value is an integer or pointer |
| (but parentheses are required around binary operators, just as in |
| a cast). This construct is allowed regardless of what kind of |
| data is normally supposed to reside at ADDR. |
| |
| |
| File: gdb.info, Node: Variables, Next: Arrays, Prev: Expressions, Up: Data |
| |
| 8.2 Program Variables |
| ===================== |
| |
| The most common kind of expression to use is the name of a variable in |
| your program. |
| |
| Variables in expressions are understood in the selected stack frame |
| (*note Selecting a Frame: Selection.); they must be either: |
| |
| * global (or file-static) |
| |
| or |
| |
| * visible according to the scope rules of the programming language |
| from the point of execution in that frame |
| |
| This means that in the function |
| |
| foo (a) |
| int a; |
| { |
| bar (a); |
| { |
| int b = test (); |
| bar (b); |
| } |
| } |
| |
| you can examine and use the variable `a' whenever your program is |
| executing within the function `foo', but you can only use or examine |
| the variable `b' while your program is executing inside the block where |
| `b' is declared. |
| |
| There is an exception: you can refer to a variable or function whose |
| scope is a single source file even if the current execution point is not |
| in this file. But it is possible to have more than one such variable or |
| function with the same name (in different source files). If that |
| happens, referring to that name has unpredictable effects. If you wish, |
| you can specify a static variable in a particular function or file, |
| using the colon-colon (`::') notation: |
| |
| FILE::VARIABLE |
| FUNCTION::VARIABLE |
| |
| Here FILE or FUNCTION is the name of the context for the static |
| VARIABLE. In the case of file names, you can use quotes to make sure |
| GDB parses the file name as a single word--for example, to print a |
| global value of `x' defined in `f2.c': |
| |
| (gdb) p 'f2.c'::x |
| |
| This use of `::' is very rarely in conflict with the very similar |
| use of the same notation in C++. GDB also supports use of the C++ |
| scope resolution operator in GDB expressions. |
| |
| _Warning:_ Occasionally, a local variable may appear to have the |
| wrong value at certain points in a function--just after entry to a |
| new scope, and just before exit. |
| You may see this problem when you are stepping by machine |
| instructions. This is because, on most machines, it takes more than |
| one instruction to set up a stack frame (including local variable |
| definitions); if you are stepping by machine instructions, variables |
| may appear to have the wrong values until the stack frame is completely |
| built. On exit, it usually also takes more than one machine |
| instruction to destroy a stack frame; after you begin stepping through |
| that group of instructions, local variable definitions may be gone. |
| |
| This may also happen when the compiler does significant |
| optimizations. To be sure of always seeing accurate values, turn off |
| all optimization when compiling. |
| |
| Another possible effect of compiler optimizations is to optimize |
| unused variables out of existence, or assign variables to registers (as |
| opposed to memory addresses). Depending on the support for such cases |
| offered by the debug info format used by the compiler, GDB might not be |
| able to display values for such local variables. If that happens, GDB |
| will print a message like this: |
| |
| No symbol "foo" in current context. |
| |
| To solve such problems, either recompile without optimizations, or |
| use a different debug info format, if the compiler supports several such |
| formats. For example, GCC, the GNU C/C++ compiler, usually supports |
| the `-gstabs+' option. `-gstabs+' produces debug info in a format that |
| is superior to formats such as COFF. You may be able to use DWARF 2 |
| (`-gdwarf-2'), which is also an effective form for debug info. *Note |
| Options for Debugging Your Program or GCC: (gcc.info)Debugging Options. |
| *Note C and C++: C, for more information about debug info formats that |
| are best suited to C++ programs. |
| |
| If you ask to print an object whose contents are unknown to GDB, |
| e.g., because its data type is not completely specified by the debug |
| information, GDB will say `<incomplete type>'. *Note incomplete type: |
| Symbols, for more about this. |
| |
| Strings are identified as arrays of `char' values without specified |
| signedness. Arrays of either `signed char' or `unsigned char' get |
| printed as arrays of 1 byte sized integers. `-fsigned-char' or |
| `-funsigned-char' GCC options have no effect as GDB defines literal |
| string type `"char"' as `char' without a sign. For program code |
| |
| char var0[] = "A"; |
| signed char var1[] = "A"; |
| |
| You get during debugging |
| (gdb) print var0 |
| $1 = "A" |
| (gdb) print var1 |
| $2 = {65 'A', 0 '\0'} |
| |
| |
| File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data |
| |
| 8.3 Artificial Arrays |
| ===================== |
| |
| It is often useful to print out several successive objects of the same |
| type in memory; a section of an array, or an array of dynamically |
| determined size for which only a pointer exists in the program. |
| |
| You can do this by referring to a contiguous span of memory as an |
| "artificial array", using the binary operator `@'. The left operand of |
| `@' should be the first element of the desired array and be an |
| individual object. The right operand should be the desired length of |
| the array. The result is an array value whose elements are all of the |
| type of the left argument. The first element is actually the left |
| argument; the second element comes from bytes of memory immediately |
| following those that hold the first element, and so on. Here is an |
| example. If a program says |
| |
| int *array = (int *) malloc (len * sizeof (int)); |
| |
| you can print the contents of `array' with |
| |
| p *array@len |
| |
| The left operand of `@' must reside in memory. Array values made |
| with `@' in this way behave just like other arrays in terms of |
| subscripting, and are coerced to pointers when used in expressions. |
| Artificial arrays most often appear in expressions via the value history |
| (*note Value History: Value History.), after printing one out. |
| |
| Another way to create an artificial array is to use a cast. This |
| re-interprets a value as if it were an array. The value need not be in |
| memory: |
| (gdb) p/x (short[2])0x12345678 |
| $1 = {0x1234, 0x5678} |
| |
| As a convenience, if you leave the array length out (as in |
| `(TYPE[])VALUE') GDB calculates the size to fill the value (as |
| `sizeof(VALUE)/sizeof(TYPE)': |
| (gdb) p/x (short[])0x12345678 |
| $2 = {0x1234, 0x5678} |
| |
| Sometimes the artificial array mechanism is not quite enough; in |
| moderately complex data structures, the elements of interest may not |
| actually be adjacent--for example, if you are interested in the values |
| of pointers in an array. One useful work-around in this situation is |
| to use a convenience variable (*note Convenience Variables: Convenience |
| Vars.) as a counter in an expression that prints the first interesting |
| value, and then repeat that expression via <RET>. For instance, |
| suppose you have an array `dtab' of pointers to structures, and you are |
| interested in the values of a field `fv' in each structure. Here is an |
| example of what you might type: |
| |
| set $i = 0 |
| p dtab[$i++]->fv |
| <RET> |
| <RET> |
| ... |
| |
| |
| File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data |
| |
| 8.4 Output Formats |
| ================== |
| |
| By default, GDB prints a value according to its data type. Sometimes |
| this is not what you want. For example, you might want to print a |
| number in hex, or a pointer in decimal. Or you might want to view data |
| in memory at a certain address as a character string or as an |
| instruction. To do these things, specify an "output format" when you |
| print a value. |
| |
| The simplest use of output formats is to say how to print a value |
| already computed. This is done by starting the arguments of the |
| `print' command with a slash and a format letter. The format letters |
| supported are: |
| |
| `x' |
| Regard the bits of the value as an integer, and print the integer |
| in hexadecimal. |
| |
| `d' |
| Print as integer in signed decimal. |
| |
| `u' |
| Print as integer in unsigned decimal. |
| |
| `o' |
| Print as integer in octal. |
| |
| `t' |
| Print as integer in binary. The letter `t' stands for "two". (1) |
| |
| `a' |
| Print as an address, both absolute in hexadecimal and as an offset |
| from the nearest preceding symbol. You can use this format used |
| to discover where (in what function) an unknown address is located: |
| |
| (gdb) p/a 0x54320 |
| $3 = 0x54320 <_initialize_vx+396> |
| |
| The command `info symbol 0x54320' yields similar results. *Note |
| info symbol: Symbols. |
| |
| `c' |
| Regard as an integer and print it as a character constant. This |
| prints both the numerical value and its character representation. |
| The character representation is replaced with the octal escape |
| `\nnn' for characters outside the 7-bit ASCII range. |
| |
| Without this format, GDB displays `char', `unsigned char', and |
| `signed char' data as character constants. Single-byte members of |
| vectors are displayed as integer data. |
| |
| `f' |
| Regard the bits of the value as a floating point number and print |
| using typical floating point syntax. |
| |
| `s' |
| Regard as a string, if possible. With this format, pointers to |
| single-byte data are displayed as null-terminated strings and |
| arrays of single-byte data are displayed as fixed-length strings. |
| Other values are displayed in their natural types. |
| |
| Without this format, GDB displays pointers to and arrays of |
| `char', `unsigned char', and `signed char' as strings. |
| Single-byte members of a vector are displayed as an integer array. |
| |
| For example, to print the program counter in hex (*note |
| Registers::), type |
| |
| p/x $pc |
| |
| Note that no space is required before the slash; this is because command |
| names in GDB cannot contain a slash. |
| |
| To reprint the last value in the value history with a different |
| format, you can use the `print' command with just a format and no |
| expression. For example, `p/x' reprints the last value in hex. |
| |
| ---------- Footnotes ---------- |
| |
| (1) `b' cannot be used because these format letters are also used |
| with the `x' command, where `b' stands for "byte"; see *Note Examining |
| Memory: Memory. |
| |
| |
| File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data |
| |
| 8.5 Examining Memory |
| ==================== |
| |
| You can use the command `x' (for "examine") to examine memory in any of |
| several formats, independently of your program's data types. |
| |
| `x/NFU ADDR' |
| `x ADDR' |
| `x' |
| Use the `x' command to examine memory. |
| |
| N, F, and U are all optional parameters that specify how much memory |
| to display and how to format it; ADDR is an expression giving the |
| address where you want to start displaying memory. If you use defaults |
| for NFU, you need not type the slash `/'. Several commands set |
| convenient defaults for ADDR. |
| |
| N, the repeat count |
| The repeat count is a decimal integer; the default is 1. It |
| specifies how much memory (counting by units U) to display. |
| |
| F, the display format |
| The display format is one of the formats used by `print' (`x', |
| `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for |
| machine instructions). The default is `x' (hexadecimal) |
| initially. The default changes each time you use either `x' or |
| `print'. |
| |
| U, the unit size |
| The unit size is any of |
| |
| `b' |
| Bytes. |
| |
| `h' |
| Halfwords (two bytes). |
| |
| `w' |
| Words (four bytes). This is the initial default. |
| |
| `g' |
| Giant words (eight bytes). |
| |
| Each time you specify a unit size with `x', that size becomes the |
| default unit the next time you use `x'. (For the `s' and `i' |
| formats, the unit size is ignored and is normally not written.) |
| |
| ADDR, starting display address |
| ADDR is the address where you want GDB to begin displaying memory. |
| The expression need not have a pointer value (though it may); it |
| is always interpreted as an integer address of a byte of memory. |
| *Note Expressions: Expressions, for more information on |
| expressions. The default for ADDR is usually just after the last |
| address examined--but several other commands also set the default |
| address: `info breakpoints' (to the address of the last breakpoint |
| listed), `info line' (to the starting address of a line), and |
| `print' (if you use it to display a value from memory). |
| |
| For example, `x/3uh 0x54320' is a request to display three halfwords |
| (`h') of memory, formatted as unsigned decimal integers (`u'), starting |
| at address `0x54320'. `x/4xw $sp' prints the four words (`w') of |
| memory above the stack pointer (here, `$sp'; *note Registers: |
| Registers.) in hexadecimal (`x'). |
| |
| Since the letters indicating unit sizes are all distinct from the |
| letters specifying output formats, you do not have to remember whether |
| unit size or format comes first; either order works. The output |
| specifications `4xw' and `4wx' mean exactly the same thing. (However, |
| the count N must come first; `wx4' does not work.) |
| |
| Even though the unit size U is ignored for the formats `s' and `i', |
| you might still want to use a count N; for example, `3i' specifies that |
| you want to see three machine instructions, including any operands. |
| For convenience, especially when used with the `display' command, the |
| `i' format also prints branch delay slot instructions, if any, beyond |
| the count specified, which immediately follow the last instruction that |
| is within the count. The command `disassemble' gives an alternative |
| way of inspecting machine instructions; see *Note Source and Machine |
| Code: Machine Code. |
| |
| All the defaults for the arguments to `x' are designed to make it |
| easy to continue scanning memory with minimal specifications each time |
| you use `x'. For example, after you have inspected three machine |
| instructions with `x/3i ADDR', you can inspect the next seven with just |
| `x/7'. If you use <RET> to repeat the `x' command, the repeat count N |
| is used again; the other arguments default as for successive uses of |
| `x'. |
| |
| The addresses and contents printed by the `x' command are not saved |
| in the value history because there is often too much of them and they |
| would get in the way. Instead, GDB makes these values available for |
| subsequent use in expressions as values of the convenience variables |
| `$_' and `$__'. After an `x' command, the last address examined is |
| available for use in expressions in the convenience variable `$_'. The |
| contents of that address, as examined, are available in the convenience |
| variable `$__'. |
| |
| If the `x' command has a repeat count, the address and contents saved |
| are from the last memory unit printed; this is not the same as the last |
| address printed if several units were printed on the last line of |
| output. |
| |
| When you are debugging a program running on a remote target machine |
| (*note Remote Debugging::), you may wish to verify the program's image |
| in the remote machine's memory against the executable file you |
| downloaded to the target. The `compare-sections' command is provided |
| for such situations. |
| |
| `compare-sections [SECTION-NAME]' |
| Compare the data of a loadable section SECTION-NAME in the |
| executable file of the program being debugged with the same |
| section in the remote machine's memory, and report any mismatches. |
| With no arguments, compares all loadable sections. This command's |
| availability depends on the target's support for the `"qCRC"' |
| remote request. |
| |
| |
| File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data |
| |
| 8.6 Automatic Display |
| ===================== |
| |
| If you find that you want to print the value of an expression frequently |
| (to see how it changes), you might want to add it to the "automatic |
| display list" so that GDB prints its value each time your program stops. |
| Each expression added to the list is given a number to identify it; to |
| remove an expression from the list, you specify that number. The |
| automatic display looks like this: |
| |
| 2: foo = 38 |
| 3: bar[5] = (struct hack *) 0x3804 |
| |
| This display shows item numbers, expressions and their current values. |
| As with displays you request manually using `x' or `print', you can |
| specify the output format you prefer; in fact, `display' decides |
| whether to use `print' or `x' depending your format specification--it |
| uses `x' if you specify either the `i' or `s' format, or a unit size; |
| otherwise it uses `print'. |
| |
| `display EXPR' |
| Add the expression EXPR to the list of expressions to display each |
| time your program stops. *Note Expressions: Expressions. |
| |
| `display' does not repeat if you press <RET> again after using it. |
| |
| `display/FMT EXPR' |
| For FMT specifying only a display format and not a size or count, |
| add the expression EXPR to the auto-display list but arrange to |
| display it each time in the specified format FMT. *Note Output |
| Formats: Output Formats. |
| |
| `display/FMT ADDR' |
| For FMT `i' or `s', or including a unit-size or a number of units, |
| add the expression ADDR as a memory address to be examined each |
| time your program stops. Examining means in effect doing `x/FMT |
| ADDR'. *Note Examining Memory: Memory. |
| |
| For example, `display/i $pc' can be helpful, to see the machine |
| instruction about to be executed each time execution stops (`$pc' is a |
| common name for the program counter; *note Registers: Registers.). |
| |
| `undisplay DNUMS...' |
| `delete display DNUMS...' |
| Remove item numbers DNUMS from the list of expressions to display. |
| |
| `undisplay' does not repeat if you press <RET> after using it. |
| (Otherwise you would just get the error `No display number ...'.) |
| |
| `disable display DNUMS...' |
| Disable the display of item numbers DNUMS. A disabled display |
| item is not printed automatically, but is not forgotten. It may be |
| enabled again later. |
| |
| `enable display DNUMS...' |
| Enable display of item numbers DNUMS. It becomes effective once |
| again in auto display of its expression, until you specify |
| otherwise. |
| |
| `display' |
| Display the current values of the expressions on the list, just as |
| is done when your program stops. |
| |
| `info display' |
| Print the list of expressions previously set up to display |
| automatically, each one with its item number, but without showing |
| the values. This includes disabled expressions, which are marked |
| as such. It also includes expressions which would not be |
| displayed right now because they refer to automatic variables not |
| currently available. |
| |
| If a display expression refers to local variables, then it does not |
| make sense outside the lexical context for which it was set up. Such an |
| expression is disabled when execution enters a context where one of its |
| variables is not defined. For example, if you give the command |
| `display last_char' while inside a function with an argument |
| `last_char', GDB displays this argument while your program continues to |
| stop inside that function. When it stops elsewhere--where there is no |
| variable `last_char'--the display is disabled automatically. The next |
| time your program stops where `last_char' is meaningful, you can enable |
| the display expression once again. |
| |
| |
| File: gdb.info, Node: Print Settings, Next: Value History, Prev: Auto Display, Up: Data |
| |
| 8.7 Print Settings |
| ================== |
| |
| GDB provides the following ways to control how arrays, structures, and |
| symbols are printed. |
| |
| These settings are useful for debugging programs in any language: |
| |
| `set print address' |
| `set print address on' |
| GDB prints memory addresses showing the location of stack traces, |
| structure values, pointer values, breakpoints, and so forth, even |
| when it also displays the contents of those addresses. The default |
| is `on'. For example, this is what a stack frame display looks |
| like with `set print address on': |
| |
| (gdb) f |
| #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") |
| at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| `set print address off' |
| Do not print addresses when displaying their contents. For |
| example, this is the same stack frame displayed with `set print |
| address off': |
| |
| (gdb) set print addr off |
| (gdb) f |
| #0 set_quotes (lq="<<", rq=">>") at input.c:530 |
| 530 if (lquote != def_lquote) |
| |
| You can use `set print address off' to eliminate all machine |
| dependent displays from the GDB interface. For example, with |
| `print address off', you should get the same text for backtraces on |
| all machines--whether or not they involve pointer arguments. |
| |
| `show print address' |
| Show whether or not addresses are to be printed. |
| |
| When GDB prints a symbolic address, it normally prints the closest |
| earlier symbol plus an offset. If that symbol does not uniquely |
| identify the address (for example, it is a name whose scope is a single |
| source file), you may need to clarify. One way to do this is with |
| `info line', for example `info line *0x4537'. Alternately, you can set |
| GDB to print the source file and line number when it prints a symbolic |
| address: |
| |
| `set print symbol-filename on' |
| Tell GDB to print the source file name and line number of a symbol |
| in the symbolic form of an address. |
| |
| `set print symbol-filename off' |
| Do not print source file name and line number of a symbol. This |
| is the default. |
| |
| `show print symbol-filename' |
| Show whether or not GDB will print the source file name and line |
| number of a symbol in the symbolic form of an address. |
| |
| Another situation where it is helpful to show symbol filenames and |
| line numbers is when disassembling code; GDB shows you the line number |
| and source file that corresponds to each instruction. |
| |
| Also, you may wish to see the symbolic form only if the address being |
| printed is reasonably close to the closest earlier symbol: |
| |
| `set print max-symbolic-offset MAX-OFFSET' |
| Tell GDB to only display the symbolic form of an address if the |
| offset between the closest earlier symbol and the address is less |
| than MAX-OFFSET. The default is 0, which tells GDB to always |
| print the symbolic form of an address if any symbol precedes it. |
| |
| `show print max-symbolic-offset' |
| Ask how large the maximum offset is that GDB prints in a symbolic |
| address. |
| |
| If you have a pointer and you are not sure where it points, try `set |
| print symbol-filename on'. Then you can determine the name and source |
| file location of the variable where it points, using `p/a POINTER'. |
| This interprets the address in symbolic form. For example, here GDB |
| shows that a variable `ptt' points at another variable `t', defined in |
| `hi2.c': |
| |
| (gdb) set print symbol-filename on |
| (gdb) p/a ptt |
| $4 = 0xe008 <t in hi2.c> |
| |
| _Warning:_ For pointers that point to a local variable, `p/a' does |
| not show the symbol name and filename of the referent, even with |
| the appropriate `set print' options turned on. |
| |
| Other settings control how different kinds of objects are printed: |
| |
| `set print array' |
| `set print array on' |
| Pretty print arrays. This format is more convenient to read, but |
| uses more space. The default is off. |
| |
| `set print array off' |
| Return to compressed format for arrays. |
| |
| `show print array' |
| Show whether compressed or pretty format is selected for displaying |
| arrays. |
| |
| `set print array-indexes' |
| `set print array-indexes on' |
| Print the index of each element when displaying arrays. May be |
| more convenient to locate a given element in the array or quickly |
| find the index of a given element in that printed array. The |
| default is off. |
| |
| `set print array-indexes off' |
| Stop printing element indexes when displaying arrays. |
| |
| `show print array-indexes' |
| Show whether the index of each element is printed when displaying |
| arrays. |
| |
| `set print elements NUMBER-OF-ELEMENTS' |
| Set a limit on how many elements of an array GDB will print. If |
| GDB is printing a large array, it stops printing after it has |
| printed the number of elements set by the `set print elements' |
| command. This limit also applies to the display of strings. When |
| GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS |
| to zero means that the printing is unlimited. |
| |
| `show print elements' |
| Display the number of elements of a large array that GDB will |
| print. If the number is 0, then the printing is unlimited. |
| |
| `set print frame-arguments VALUE' |
| This command allows to control how the values of arguments are |
| printed when the debugger prints a frame (*note Frames::). The |
| possible values are: |
| |
| `all' |
| The values of all arguments are printed. This is the default. |
| |
| `scalars' |
| Print the value of an argument only if it is a scalar. The |
| value of more complex arguments such as arrays, structures, |
| unions, etc, is replaced by `...'. Here is an example where |
| only scalar arguments are shown: |
| |
| #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) |
| at frame-args.c:23 |
| |
| `none' |
| None of the argument values are printed. Instead, the value |
| of each argument is replaced by `...'. In this case, the |
| example above now becomes: |
| |
| #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) |
| at frame-args.c:23 |
| |
| By default, all argument values are always printed. But this |
| command can be useful in several cases. For instance, it can be |
| used to reduce the amount of information printed in each frame, |
| making the backtrace more readable. Also, this command can be |
| used to improve performance when displaying Ada frames, because |
| the computation of large arguments can sometimes be CPU-intensive, |
| especiallly in large applications. Setting `print |
| frame-arguments' to `scalars' or `none' avoids this computation, |
| thus speeding up the display of each Ada frame. |
| |
| `show print frame-arguments' |
| Show how the value of arguments should be displayed when printing |
| a frame. |
| |
| `set print repeats' |
| Set the threshold for suppressing display of repeated array |
| elements. When the number of consecutive identical elements of an |
| array exceeds the threshold, GDB prints the string `"<repeats N |
| times>"', where N is the number of identical repetitions, instead |
| of displaying the identical elements themselves. Setting the |
| threshold to zero will cause all elements to be individually |
| printed. The default threshold is 10. |
| |
| `show print repeats' |
| Display the current threshold for printing repeated identical |
| elements. |
| |
| `set print null-stop' |
| Cause GDB to stop printing the characters of an array when the |
| first NULL is encountered. This is useful when large arrays |
| actually contain only short strings. The default is off. |
| |
| `show print null-stop' |
| Show whether GDB stops printing an array on the first NULL |
| character. |
| |
| `set print pretty on' |
| Cause GDB to print structures in an indented format with one member |
| per line, like this: |
| |
| $1 = { |
| next = 0x0, |
| flags = { |
| sweet = 1, |
| sour = 1 |
| }, |
| meat = 0x54 "Pork" |
| } |
| |
| `set print pretty off' |
| Cause GDB to print structures in a compact format, like this: |
| |
| $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ |
| meat = 0x54 "Pork"} |
| |
| This is the default format. |
| |
| `show print pretty' |
| Show which format GDB is using to print structures. |
| |
| `set print sevenbit-strings on' |
| Print using only seven-bit characters; if this option is set, GDB |
| displays any eight-bit characters (in strings or character values) |
| using the notation `\'NNN. This setting is best if you are |
| working in English (ASCII) and you use the high-order bit of |
| characters as a marker or "meta" bit. |
| |
| `set print sevenbit-strings off' |
| Print full eight-bit characters. This allows the use of more |
| international character sets, and is the default. |
| |
| `show print sevenbit-strings' |
| Show whether or not GDB is printing only seven-bit characters. |
| |
| `set print union on' |
| Tell GDB to print unions which are contained in structures and |
| other unions. This is the default setting. |
| |
| `set print union off' |
| Tell GDB not to print unions which are contained in structures and |
| other unions. GDB will print `"{...}"' instead. |
| |
| `show print union' |
| Ask GDB whether or not it will print unions which are contained in |
| structures and other unions. |
| |
| For example, given the declarations |
| |
| typedef enum {Tree, Bug} Species; |
| typedef enum {Big_tree, Acorn, Seedling} Tree_forms; |
| typedef enum {Caterpillar, Cocoon, Butterfly} |
| Bug_forms; |
| |
| struct thing { |
| Species it; |
| union { |
| Tree_forms tree; |
| Bug_forms bug; |
| } form; |
| }; |
| |
| struct thing foo = {Tree, {Acorn}}; |
| |
| with `set print union on' in effect `p foo' would print |
| |
| $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} |
| |
| and with `set print union off' in effect it would print |
| |
| $1 = {it = Tree, form = {...}} |
| |
| `set print union' affects programs written in C-like languages and |
| in Pascal. |
| |
| These settings are of interest when debugging C++ programs: |
| |
| `set print demangle' |
| `set print demangle on' |
| Print C++ names in their source form rather than in the encoded |
| ("mangled") form passed to the assembler and linker for type-safe |
| linkage. The default is on. |
| |
| `show print demangle' |
| Show whether C++ names are printed in mangled or demangled form. |
| |
| `set print asm-demangle' |
| `set print asm-demangle on' |
| Print C++ names in their source form rather than their mangled |
| form, even in assembler code printouts such as instruction |
| disassemblies. The default is off. |
| |
| `show print asm-demangle' |
| Show whether C++ names in assembly listings are printed in mangled |
| or demangled form. |
| |
| `set demangle-style STYLE' |
| Choose among several encoding schemes used by different compilers |
| to represent C++ names. The choices for STYLE are currently: |
| |
| `auto' |
| Allow GDB to choose a decoding style by inspecting your |
| program. |
| |
| `gnu' |
| Decode based on the GNU C++ compiler (`g++') encoding |
| algorithm. This is the default. |
| |
| `hp' |
| Decode based on the HP ANSI C++ (`aCC') encoding algorithm. |
| |
| `lucid' |
| Decode based on the Lucid C++ compiler (`lcc') encoding |
| algorithm. |
| |
| `arm' |
| Decode using the algorithm in the `C++ Annotated Reference |
| Manual'. *Warning:* this setting alone is not sufficient to |
| allow debugging `cfront'-generated executables. GDB would |
| require further enhancement to permit that. |
| |
| If you omit STYLE, you will see a list of possible formats. |
| |
| `show demangle-style' |
| Display the encoding style currently in use for decoding C++ |
| symbols. |
| |
| `set print object' |
| `set print object on' |
| When displaying a pointer to an object, identify the _actual_ |
| (derived) type of the object rather than the _declared_ type, using |
| the virtual function table. |
| |
| `set print object off' |
| Display only the declared type of objects, without reference to the |
| virtual function table. This is the default setting. |
| |
| `show print object' |
| Show whether actual, or declared, object types are displayed. |
| |
| `set print static-members' |
| `set print static-members on' |
| Print static members when displaying a C++ object. The default is |
| on. |
| |
| `set print static-members off' |
| Do not print static members when displaying a C++ object. |
| |
| `show print static-members' |
| Show whether C++ static members are printed or not. |
| |
| `set print pascal_static-members' |
| `set print pascal_static-members on' |
| Print static members when displaying a Pascal object. The default |
| is on. |
| |
| `set print pascal_static-members off' |
| Do not print static members when displaying a Pascal object. |
| |
| `show print pascal_static-members' |
| Show whether Pascal static members are printed or not. |
| |
| `set print vtbl' |
| `set print vtbl on' |
| Pretty print C++ virtual function tables. The default is off. |
| (The `vtbl' commands do not work on programs compiled with the HP |
| ANSI C++ compiler (`aCC').) |
| |
| `set print vtbl off' |
| Do not pretty print C++ virtual function tables. |
| |
| `show print vtbl' |
| Show whether C++ virtual function tables are pretty printed, or |
| not. |
| |
| |
| File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Print Settings, Up: Data |
| |
| 8.8 Value History |
| ================= |
| |
| Values printed by the `print' command are saved in the GDB "value |
| history". This allows you to refer to them in other expressions. |
| Values are kept until the symbol table is re-read or discarded (for |
| example with the `file' or `symbol-file' commands). When the symbol |
| table changes, the value history is discarded, since the values may |
| contain pointers back to the types defined in the symbol table. |
| |
| The values printed are given "history numbers" by which you can |
| refer to them. These are successive integers starting with one. |
| `print' shows you the history number assigned to a value by printing |
| `$NUM = ' before the value; here NUM is the history number. |
| |
| To refer to any previous value, use `$' followed by the value's |
| history number. The way `print' labels its output is designed to |
| remind you of this. Just `$' refers to the most recent value in the |
| history, and `$$' refers to the value before that. `$$N' refers to the |
| Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is |
| equivalent to `$$', and `$$0' is equivalent to `$'. |
| |
| For example, suppose you have just printed a pointer to a structure |
| and want to see the contents of the structure. It suffices to type |
| |
| p *$ |
| |
| If you have a chain of structures where the component `next' points |
| to the next one, you can print the contents of the next one with this: |
| |
| p *$.next |
| |
| You can print successive links in the chain by repeating this |
| command--which you can do by just typing <RET>. |
| |
| Note that the history records values, not expressions. If the value |
| of `x' is 4 and you type these commands: |
| |
| print x |
| set x=5 |
| |
| then the value recorded in the value history by the `print' command |
| remains 4 even though the value of `x' has changed. |
| |
| `show values' |
| Print the last ten values in the value history, with their item |
| numbers. This is like `p $$9' repeated ten times, except that |
| `show values' does not change the history. |
| |
| `show values N' |
| Print ten history values centered on history item number N. |
| |
| `show values +' |
| Print ten history values just after the values last printed. If |
| no more values are available, `show values +' produces no display. |
| |
| Pressing <RET> to repeat `show values N' has exactly the same effect |
| as `show values +'. |
| |
| |
| File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data |
| |
| 8.9 Convenience Variables |
| ========================= |
| |
| GDB provides "convenience variables" that you can use within GDB to |
| hold on to a value and refer to it later. These variables exist |
| entirely within GDB; they are not part of your program, and setting a |
| convenience variable has no direct effect on further execution of your |
| program. That is why you can use them freely. |
| |
| Convenience variables are prefixed with `$'. Any name preceded by |
| `$' can be used for a convenience variable, unless it is one of the |
| predefined machine-specific register names (*note Registers: |
| Registers.). (Value history references, in contrast, are _numbers_ |
| preceded by `$'. *Note Value History: Value History.) |
| |
| You can save a value in a convenience variable with an assignment |
| expression, just as you would set a variable in your program. For |
| example: |
| |
| set $foo = *object_ptr |
| |
| would save in `$foo' the value contained in the object pointed to by |
| `object_ptr'. |
| |
| Using a convenience variable for the first time creates it, but its |
| value is `void' until you assign a new value. You can alter the value |
| with another assignment at any time. |
| |
| Convenience variables have no fixed types. You can assign a |
| convenience variable any type of value, including structures and |
| arrays, even if that variable already has a value of a different type. |
| The convenience variable, when used as an expression, has the type of |
| its current value. |
| |
| `show convenience' |
| Print a list of convenience variables used so far, and their |
| values. Abbreviated `show conv'. |
| |
| `init-if-undefined $VARIABLE = EXPRESSION' |
| Set a convenience variable if it has not already been set. This |
| is useful for user-defined commands that keep some state. It is |
| similar, in concept, to using local static variables with |
| initializers in C (except that convenience variables are global). |
| It can also be used to allow users to override default values used |
| in a command script. |
| |
| If the variable is already defined then the expression is not |
| evaluated so any side-effects do not occur. |
| |
| One of the ways to use a convenience variable is as a counter to be |
| incremented or a pointer to be advanced. For example, to print a field |
| from successive elements of an array of structures: |
| |
| set $i = 0 |
| print bar[$i++]->contents |
| |
| Repeat that command by typing <RET>. |
| |
| Some convenience variables are created automatically by GDB and given |
| values likely to be useful. |
| |
| `$_' |
| The variable `$_' is automatically set by the `x' command to the |
| last address examined (*note Examining Memory: Memory.). Other |
| commands which provide a default address for `x' to examine also |
| set `$_' to that address; these commands include `info line' and |
| `info breakpoint'. The type of `$_' is `void *' except when set |
| by the `x' command, in which case it is a pointer to the type of |
| `$__'. |
| |
| `$__' |
| The variable `$__' is automatically set by the `x' command to the |
| value found in the last address examined. Its type is chosen to |
| match the format in which the data was printed. |
| |
| `$_exitcode' |
| The variable `$_exitcode' is automatically set to the exit code |
| when the program being debugged terminates. |
| |
| On HP-UX systems, if you refer to a function or variable name that |
| begins with a dollar sign, GDB searches for a user or system name |
| first, before it searches for a convenience variable. |
| |
| |
| File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data |
| |
| 8.10 Registers |
| ============== |
| |
| You can refer to machine register contents, in expressions, as variables |
| with names starting with `$'. The names of registers are different for |
| each machine; use `info registers' to see the names used on your |
| machine. |
| |
| `info registers' |
| Print the names and values of all registers except floating-point |
| and vector registers (in the selected stack frame). |
| |
| `info all-registers' |
| Print the names and values of all registers, including |
| floating-point and vector registers (in the selected stack frame). |
| |
| `info registers REGNAME ...' |
| Print the "relativized" value of each specified register REGNAME. |
| As discussed in detail below, register values are normally |
| relative to the selected stack frame. REGNAME may be any register |
| name valid on the machine you are using, with or without the |
| initial `$'. |
| |
| GDB has four "standard" register names that are available (in |
| expressions) on most machines--whenever they do not conflict with an |
| architecture's canonical mnemonics for registers. The register names |
| `$pc' and `$sp' are used for the program counter register and the stack |
| pointer. `$fp' is used for a register that contains a pointer to the |
| current stack frame, and `$ps' is used for a register that contains the |
| processor status. For example, you could print the program counter in |
| hex with |
| |
| p/x $pc |
| |
| or print the instruction to be executed next with |
| |
| x/i $pc |
| |
| or add four to the stack pointer(1) with |
| |
| set $sp += 4 |
| |
| Whenever possible, these four standard register names are available |
| on your machine even though the machine has different canonical |
| mnemonics, so long as there is no conflict. The `info registers' |
| command shows the canonical names. For example, on the SPARC, `info |
| registers' displays the processor status register as `$psr' but you can |
| also refer to it as `$ps'; and on x86-based machines `$ps' is an alias |
| for the EFLAGS register. |
| |
| GDB always considers the contents of an ordinary register as an |
| integer when the register is examined in this way. Some machines have |
| special registers which can hold nothing but floating point; these |
| registers are considered to have floating point values. There is no way |
| to refer to the contents of an ordinary register as floating point value |
| (although you can _print_ it as a floating point value with `print/f |
| $REGNAME'). |
| |
| Some registers have distinct "raw" and "virtual" data formats. This |
| means that the data format in which the register contents are saved by |
| the operating system is not the same one that your program normally |
| sees. For example, the registers of the 68881 floating point |
| coprocessor are always saved in "extended" (raw) format, but all C |
| programs expect to work with "double" (virtual) format. In such cases, |
| GDB normally works with the virtual format only (the format that makes |
| sense for your program), but the `info registers' command prints the |
| data in both formats. |
| |
| Some machines have special registers whose contents can be |
| interpreted in several different ways. For example, modern x86-based |
| machines have SSE and MMX registers that can hold several values packed |
| together in several different formats. GDB refers to such registers in |
| `struct' notation: |
| |
| (gdb) print $xmm1 |
| $1 = { |
| v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, |
| v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, |
| v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", |
| v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, |
| v4_int32 = {0, 20657912, 11, 13}, |
| v2_int64 = {88725056443645952, 55834574859}, |
| uint128 = 0x0000000d0000000b013b36f800000000 |
| } |
| |
| To set values of such registers, you need to tell GDB which view of the |
| register you wish to change, as if you were assigning value to a |
| `struct' member: |
| |
| (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF |
| |
| Normally, register values are relative to the selected stack frame |
| (*note Selecting a Frame: Selection.). This means that you get the |
| value that the register would contain if all stack frames farther in |
| were exited and their saved registers restored. In order to see the |
| true contents of hardware registers, you must select the innermost |
| frame (with `frame 0'). |
| |
| However, GDB must deduce where registers are saved, from the machine |
| code generated by your compiler. If some registers are not saved, or if |
| GDB is unable to locate the saved registers, the selected stack frame |
| makes no difference. |
| |
| ---------- Footnotes ---------- |
| |
| (1) This is a way of removing one word from the stack, on machines |
| where stacks grow downward in memory (most machines, nowadays). This |
| assumes that the innermost stack frame is selected; setting `$sp' is |
| not allowed when other stack frames are selected. To pop entire frames |
| off the stack, regardless of machine architecture, use `return'; see |
| *Note Returning from a Function: Returning. |
| |
| |
| File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data |
| |
| 8.11 Floating Point Hardware |
| ============================ |
| |
| Depending on the configuration, GDB may be able to give you more |
| information about the status of the floating point hardware. |
| |
| `info float' |
| Display hardware-dependent information about the floating point |
| unit. The exact contents and layout vary depending on the |
| floating point chip. Currently, `info float' is supported on the |
| ARM and x86 machines. |
| |
| |
| File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data |
| |
| 8.12 Vector Unit |
| ================ |
| |
| Depending on the configuration, GDB may be able to give you more |
| information about the status of the vector unit. |
| |
| `info vector' |
| Display information about the vector unit. The exact contents and |
| layout vary depending on the hardware. |
| |
| |
| File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data |
| |
| 8.13 Operating System Auxiliary Information |
| =========================================== |
| |
| GDB provides interfaces to useful OS facilities that can help you debug |
| your program. |
| |
| When GDB runs on a "Posix system" (such as GNU or Unix machines), it |
| interfaces with the inferior via the `ptrace' system call. The |
| operating system creates a special sata structure, called `struct |
| user', for this interface. You can use the command `info udot' to |
| display the contents of this data structure. |
| |
| `info udot' |
| Display the contents of the `struct user' maintained by the OS |
| kernel for the program being debugged. GDB displays the contents |
| of `struct user' as a list of hex numbers, similar to the |
| `examine' command. |
| |
| Some operating systems supply an "auxiliary vector" to programs at |
| startup. This is akin to the arguments and environment that you |
| specify for a program, but contains a system-dependent variety of |
| binary values that tell system libraries important details about the |
| hardware, operating system, and process. Each value's purpose is |
| identified by an integer tag; the meanings are well-known but |
| system-specific. Depending on the configuration and operating system |
| facilities, GDB may be able to show you this information. For remote |
| targets, this functionality may further depend on the remote stub's |
| support of the `qXfer:auxv:read' packet, see *Note qXfer auxiliary |
| vector read::. |
| |
| `info auxv' |
| Display the auxiliary vector of the inferior, which can be either a |
| live process or a core dump file. GDB prints each tag value |
| numerically, and also shows names and text descriptions for |
| recognized tags. Some values in the vector are numbers, some bit |
| masks, and some pointers to strings or other data. GDB displays |
| each value in the most appropriate form for a recognized tag, and |
| in hexadecimal for an unrecognized tag. |
| |
| |
| File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data |
| |
| 8.14 Memory Region Attributes |
| ============================= |
| |
| "Memory region attributes" allow you to describe special handling |
| required by regions of your target's memory. GDB uses attributes to |
| determine whether to allow certain types of memory accesses; whether to |
| use specific width accesses; and whether to cache target memory. By |
| default the description of memory regions is fetched from the target |
| (if the current target supports this), but the user can override the |
| fetched regions. |
| |
| Defined memory regions can be individually enabled and disabled. |
| When a memory region is disabled, GDB uses the default attributes when |
| accessing memory in that region. Similarly, if no memory regions have |
| been defined, GDB uses the default attributes when accessing all memory. |
| |
| When a memory region is defined, it is given a number to identify it; |
| to enable, disable, or remove a memory region, you specify that number. |
| |
| `mem LOWER UPPER ATTRIBUTES...' |
| Define a memory region bounded by LOWER and UPPER with attributes |
| ATTRIBUTES..., and add it to the list of regions monitored by GDB. |
| Note that UPPER == 0 is a special case: it is treated as the |
| target's maximum memory address. (0xffff on 16 bit targets, |
| 0xffffffff on 32 bit targets, etc.) |
| |
| `mem auto' |
| Discard any user changes to the memory regions and use |
| target-supplied regions, if available, or no regions if the target |
| does not support. |
| |
| `delete mem NUMS...' |
| Remove memory regions NUMS... from the list of regions monitored |
| by GDB. |
| |
| `disable mem NUMS...' |
| Disable monitoring of memory regions NUMS.... A disabled memory |
| region is not forgotten. It may be enabled again later. |
| |
| `enable mem NUMS...' |
| Enable monitoring of memory regions NUMS.... |
| |
| `info mem' |
| Print a table of all defined memory regions, with the following |
| columns for each region: |
| |
| _Memory Region Number_ |
| |
| _Enabled or Disabled._ |
| Enabled memory regions are marked with `y'. Disabled memory |
| regions are marked with `n'. |
| |
| _Lo Address_ |
| The address defining the inclusive lower bound of the memory |
| region. |
| |
| _Hi Address_ |
| The address defining the exclusive upper bound of the memory |
| region. |
| |
| _Attributes_ |
| The list of attributes set for this memory region. |
| |
| 8.14.1 Attributes |
| ----------------- |
| |
| 8.14.1.1 Memory Access Mode |
| ........................... |
| |
| The access mode attributes set whether GDB may make read or write |
| accesses to a memory region. |
| |
| While these attributes prevent GDB from performing invalid memory |
| accesses, they do nothing to prevent the target system, I/O DMA, etc. |
| from accessing memory. |
| |
| `ro' |
| Memory is read only. |
| |
| `wo' |
| Memory is write only. |
| |
| `rw' |
| Memory is read/write. This is the default. |
| |
| 8.14.1.2 Memory Access Size |
| ........................... |
| |
| The access size attribute tells GDB to use specific sized accesses in |
| the memory region. Often memory mapped device registers require |
| specific sized accesses. If no access size attribute is specified, GDB |
| may use accesses of any size. |
| |
| `8' |
| Use 8 bit memory accesses. |
| |
| `16' |
| Use 16 bit memory accesses. |
| |
| `32' |
| Use 32 bit memory accesses. |
| |
| `64' |
| Use 64 bit memory accesses. |
| |
| 8.14.1.3 Data Cache |
| ................... |
| |
| The data cache attributes set whether GDB will cache target memory. |
| While this generally improves performance by reducing debug protocol |
| overhead, it can lead to incorrect results because GDB does not know |
| about volatile variables or memory mapped device registers. |
| |
| `cache' |
| Enable GDB to cache target memory. |
| |
| `nocache' |
| Disable GDB from caching target memory. This is the default. |
| |
| 8.14.2 Memory Access Checking |
| ----------------------------- |
| |
| GDB can be instructed to refuse accesses to memory that is not |
| explicitly described. This can be useful if accessing such regions has |
| undesired effects for a specific target, or to provide better error |
| checking. The following commands control this behaviour. |
| |
| `set mem inaccessible-by-default [on|off]' |
| If `on' is specified, make GDB treat memory not explicitly |
| described by the memory ranges as non-existent and refuse accesses |
| to such memory. The checks are only performed if there's at least |
| one memory range defined. If `off' is specified, make GDB treat |
| the memory not explicitly described by the memory ranges as RAM. |
| The default value is `on'. |
| |
| `show mem inaccessible-by-default' |
| Show the current handling of accesses to unknown memory. |
| |
| |
| File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data |
| |
| 8.15 Copy Between Memory and a File |
| =================================== |
| |
| You can use the commands `dump', `append', and `restore' to copy data |
| between target memory and a file. The `dump' and `append' commands |
| write data to a file, and the `restore' command reads data from a file |
| back into the inferior's memory. Files may be in binary, Motorola |
| S-record, Intel hex, or Tektronix Hex format; however, GDB can only |
| append to binary files. |
| |
| `dump [FORMAT] memory FILENAME START_ADDR END_ADDR' |
| `dump [FORMAT] value FILENAME EXPR' |
| Dump the contents of memory from START_ADDR to END_ADDR, or the |
| value of EXPR, to FILENAME in the given format. |
| |
| The FORMAT parameter may be any one of: |
| `binary' |
| Raw binary form. |
| |
| `ihex' |
| Intel hex format. |
| |
| `srec' |
| Motorola S-record format. |
| |
| `tekhex' |
| Tektronix Hex format. |
| |
| GDB uses the same definitions of these formats as the GNU binary |
| utilities, like `objdump' and `objcopy'. If FORMAT is omitted, |
| GDB dumps the data in raw binary form. |
| |
| `append [binary] memory FILENAME START_ADDR END_ADDR' |
| `append [binary] value FILENAME EXPR' |
| Append the contents of memory from START_ADDR to END_ADDR, or the |
| value of EXPR, to the file FILENAME, in raw binary form. (GDB can |
| only append data to files in raw binary form.) |
| |
| `restore FILENAME [binary] BIAS START END' |
| Restore the contents of file FILENAME into memory. The `restore' |
| command can automatically recognize any known BFD file format, |
| except for raw binary. To restore a raw binary file you must |
| specify the optional keyword `binary' after the filename. |
| |
| If BIAS is non-zero, its value will be added to the addresses |
| contained in the file. Binary files always start at address zero, |
| so they will be restored at address BIAS. Other bfd files have a |
| built-in location; they will be restored at offset BIAS from that |
| location. |
| |
| If START and/or END are non-zero, then only data between file |
| offset START and file offset END will be restored. These offsets |
| are relative to the addresses in the file, before the BIAS |
| argument is applied. |
| |
| |
| |
| File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data |
| |
| 8.16 How to Produce a Core File from Your Program |
| ================================================= |
| |
| A "core file" or "core dump" is a file that records the memory image of |
| a running process and its process status (register values etc.). Its |
| primary use is post-mortem debugging of a program that crashed while it |
| ran outside a debugger. A program that crashes automatically produces |
| a core file, unless this feature is disabled by the user. *Note |
| Files::, for information on invoking GDB in the post-mortem debugging |
| mode. |
| |
| Occasionally, you may wish to produce a core file of the program you |
| are debugging in order to preserve a snapshot of its state. GDB has a |
| special command for that. |
| |
| `generate-core-file [FILE]' |
| `gcore [FILE]' |
| Produce a core dump of the inferior process. The optional argument |
| FILE specifies the file name where to put the core dump. If not |
| specified, the file name defaults to `core.PID', where PID is the |
| inferior process ID. |
| |
| Note that this command is implemented only for some systems (as of |
| this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390). |
| |
| |
| File: gdb.info, Node: Character Sets, Next: Caching Remote Data, Prev: Core File Generation, Up: Data |
| |
| 8.17 Character Sets |
| =================== |
| |
| If the program you are debugging uses a different character set to |
| represent characters and strings than the one GDB uses itself, GDB can |
| automatically translate between the character sets for you. The |
| character set GDB uses we call the "host character set"; the one the |
| inferior program uses we call the "target character set". |
| |
| For example, if you are running GDB on a GNU/Linux system, which |
| uses the ISO Latin 1 character set, but you are using GDB's remote |
| protocol (*note Remote Debugging::) to debug a program running on an |
| IBM mainframe, which uses the EBCDIC character set, then the host |
| character set is Latin-1, and the target character set is EBCDIC. If |
| you give GDB the command `set target-charset EBCDIC-US', then GDB |
| translates between EBCDIC and Latin 1 as you print character or string |
| values, or use character and string literals in expressions. |
| |
| GDB has no way to automatically recognize which character set the |
| inferior program uses; you must tell it, using the `set target-charset' |
| command, described below. |
| |
| Here are the commands for controlling GDB's character set support: |
| |
| `set target-charset CHARSET' |
| Set the current target character set to CHARSET. We list the |
| character set names GDB recognizes below, but if you type `set |
| target-charset' followed by <TAB><TAB>, GDB will list the target |
| character sets it supports. |
| |
| `set host-charset CHARSET' |
| Set the current host character set to CHARSET. |
| |
| By default, GDB uses a host character set appropriate to the |
| system it is running on; you can override that default using the |
| `set host-charset' command. |
| |
| GDB can only use certain character sets as its host character set. |
| We list the character set names GDB recognizes below, and |
| indicate which can be host character sets, but if you type `set |
| target-charset' followed by <TAB><TAB>, GDB will list the host |
| character sets it supports. |
| |
| `set charset CHARSET' |
| Set the current host and target character sets to CHARSET. As |
| above, if you type `set charset' followed by <TAB><TAB>, GDB will |
| list the name of the character sets that can be used for both host |
| and target. |
| |
| `show charset' |
| Show the names of the current host and target charsets. |
| |
| `show host-charset' |
| Show the name of the current host charset. |
| |
| `show target-charset' |
| Show the name of the current target charset. |
| |
| |
| GDB currently includes support for the following character sets: |
| |
| `ASCII' |
| Seven-bit U.S. ASCII. GDB can use this as its host character set. |
| |
| `ISO-8859-1' |
| The ISO Latin 1 character set. This extends ASCII with accented |
| characters needed for French, German, and Spanish. GDB can use |
| this as its host character set. |
| |
| `EBCDIC-US' |
| `IBM1047' |
| Variants of the EBCDIC character set, used on some of IBM's |
| mainframe operating systems. (GNU/Linux on the S/390 uses U.S. |
| ASCII.) GDB cannot use these as its host character set. |
| |
| |
| Note that these are all single-byte character sets. More work inside |
| GDB is needed to support multi-byte or variable-width character |
| encodings, like the UTF-8 and UCS-2 encodings of Unicode. |
| |
| Here is an example of GDB's character set support in action. Assume |
| that the following source code has been placed in the file |
| `charset-test.c': |
| |
| #include <stdio.h> |
| |
| char ascii_hello[] |
| = {72, 101, 108, 108, 111, 44, 32, 119, |
| 111, 114, 108, 100, 33, 10, 0}; |
| char ibm1047_hello[] |
| = {200, 133, 147, 147, 150, 107, 64, 166, |
| 150, 153, 147, 132, 90, 37, 0}; |
| |
| main () |
| { |
| printf ("Hello, world!\n"); |
| } |
| |
| In this program, `ascii_hello' and `ibm1047_hello' are arrays |
| containing the string `Hello, world!' followed by a newline, encoded in |
| the ASCII and IBM1047 character sets. |
| |
| We compile the program, and invoke the debugger on it: |
| |
| $ gcc -g charset-test.c -o charset-test |
| $ gdb -nw charset-test |
| GNU gdb 2001-12-19-cvs |
| Copyright 2001 Free Software Foundation, Inc. |
| ... |
| (gdb) |
| |
| We can use the `show charset' command to see what character sets GDB |
| is currently using to interpret and display characters and strings: |
| |
| (gdb) show charset |
| The current host and target character set is `ISO-8859-1'. |
| (gdb) |
| |
| For the sake of printing this manual, let's use ASCII as our initial |
| character set: |
| (gdb) set charset ASCII |
| (gdb) show charset |
| The current host and target character set is `ASCII'. |
| (gdb) |
| |
| Let's assume that ASCII is indeed the correct character set for our |
| host system -- in other words, let's assume that if GDB prints |
| characters using the ASCII character set, our terminal will display |
| them properly. Since our current target character set is also ASCII, |
| the contents of `ascii_hello' print legibly: |
| |
| (gdb) print ascii_hello |
| $1 = 0x401698 "Hello, world!\n" |
| (gdb) print ascii_hello[0] |
| $2 = 72 'H' |
| (gdb) |
| |
| GDB uses the target character set for character and string literals |
| you use in expressions: |
| |
| (gdb) print '+' |
| $3 = 43 '+' |
| (gdb) |
| |
| The ASCII character set uses the number 43 to encode the `+' |
| character. |
| |
| GDB relies on the user to tell it which character set the target |
| program uses. If we print `ibm1047_hello' while our target character |
| set is still ASCII, we get jibberish: |
| |
| (gdb) print ibm1047_hello |
| $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" |
| (gdb) print ibm1047_hello[0] |
| $5 = 200 '\310' |
| (gdb) |
| |
| If we invoke the `set target-charset' followed by <TAB><TAB>, GDB |
| tells us the character sets it supports: |
| |
| (gdb) set target-charset |
| ASCII EBCDIC-US IBM1047 ISO-8859-1 |
| (gdb) set target-charset |
| |
| We can select IBM1047 as our target character set, and examine the |
| program's strings again. Now the ASCII string is wrong, but GDB |
| translates the contents of `ibm1047_hello' from the target character |
| set, IBM1047, to the host character set, ASCII, and they display |
| correctly: |
| |
| (gdb) set target-charset IBM1047 |
| (gdb) show charset |
| The current host character set is `ASCII'. |
| The current target character set is `IBM1047'. |
| (gdb) print ascii_hello |
| $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" |
| (gdb) print ascii_hello[0] |
| $7 = 72 '\110' |
| (gdb) print ibm1047_hello |
| $8 = 0x4016a8 "Hello, world!\n" |
| (gdb) print ibm1047_hello[0] |
| $9 = 200 'H' |
| (gdb) |
| |
| As above, GDB uses the target character set for character and string |
| literals you use in expressions: |
| |
| (gdb) print '+' |
| $10 = 78 '+' |
| (gdb) |
| |
| The IBM1047 character set uses the number 78 to encode the `+' |
| character. |
| |
| |
| File: gdb.info, Node: Caching Remote Data, Prev: Character Sets, Up: Data |
| |
| 8.18 Caching Data of Remote Targets |
| =================================== |
| |
| GDB can cache data exchanged between the debugger and a remote target |
| (*note Remote Debugging::). Such caching generally improves |
| performance, because it reduces the overhead of the remote protocol by |
| bundling memory reads and writes into large chunks. Unfortunately, GDB |
| does not currently know anything about volatile registers, and thus |
| data caching will produce incorrect results when volatile registers are |
| in use. |
| |
| `set remotecache on' |
| `set remotecache off' |
| Set caching state for remote targets. When `ON', use data |
| caching. By default, this option is `OFF'. |
| |
| `show remotecache' |
| Show the current state of data caching for remote targets. |
| |
| `info dcache' |
| Print the information about the data cache performance. The |
| information displayed includes: the dcache width and depth; and for |
| each cache line, how many times it was referenced, and its data and |
| state (dirty, bad, ok, etc.). This command is useful for debugging |
| the data cache operation. |
| |
| |
| File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Data, Up: Top |
| |
| 9 C Preprocessor Macros |
| *********************** |
| |
| Some languages, such as C and C++, provide a way to define and invoke |
| "preprocessor macros" which expand into strings of tokens. GDB can |
| evaluate expressions containing macro invocations, show the result of |
| macro expansion, and show a macro's definition, including where it was |
| defined. |
| |
| You may need to compile your program specially to provide GDB with |
| information about preprocessor macros. Most compilers do not include |
| macros in their debugging information, even when you compile with the |
| `-g' flag. *Note Compilation::. |
| |
| A program may define a macro at one point, remove that definition |
| later, and then provide a different definition after that. Thus, at |
| different points in the program, a macro may have different |
| definitions, or have no definition at all. If there is a current stack |
| frame, GDB uses the macros in scope at that frame's source code line. |
| Otherwise, GDB uses the macros in scope at the current listing location; |
| see *Note List::. |
| |
| At the moment, GDB does not support the `##' token-splicing |
| operator, the `#' stringification operator, or variable-arity macros. |
| |
| Whenever GDB evaluates an expression, it always expands any macro |
| invocations present in the expression. GDB also provides the following |
| commands for working with macros explicitly. |
| |
| `macro expand EXPRESSION' |
| `macro exp EXPRESSION' |
| Show the results of expanding all preprocessor macro invocations in |
| EXPRESSION. Since GDB simply expands macros, but does not parse |
| the result, EXPRESSION need not be a valid expression; it can be |
| any string of tokens. |
| |
| `macro expand-once EXPRESSION' |
| `macro exp1 EXPRESSION' |
| (This command is not yet implemented.) Show the results of |
| expanding those preprocessor macro invocations that appear |
| explicitly in EXPRESSION. Macro invocations appearing in that |
| expansion are left unchanged. This command allows you to see the |
| effect of a particular macro more clearly, without being confused |
| by further expansions. Since GDB simply expands macros, but does |
| not parse the result, EXPRESSION need not be a valid expression; it |
| can be any string of tokens. |
| |
| `info macro MACRO' |
| Show the definition of the macro named MACRO, and describe the |
| source location where that definition was established. |
| |
| `macro define MACRO REPLACEMENT-LIST' |
| `macro define MACRO(ARGLIST) REPLACEMENT-LIST' |
| (This command is not yet implemented.) Introduce a definition for |
| a preprocessor macro named MACRO, invocations of which are replaced |
| by the tokens given in REPLACEMENT-LIST. The first form of this |
| command defines an "object-like" macro, which takes no arguments; |
| the second form defines a "function-like" macro, which takes the |
| arguments given in ARGLIST. |
| |
| A definition introduced by this command is in scope in every |
| expression evaluated in GDB, until it is removed with the `macro |
| undef' command, described below. The definition overrides all |
| definitions for MACRO present in the program being debugged, as |
| well as any previous user-supplied definition. |
| |
| `macro undef MACRO' |
| (This command is not yet implemented.) Remove any user-supplied |
| definition for the macro named MACRO. This command only affects |
| definitions provided with the `macro define' command, described |
| above; it cannot remove definitions present in the program being |
| debugged. |
| |
| `macro list' |
| (This command is not yet implemented.) List all the macros |
| defined using the `macro define' command. |
| |
| Here is a transcript showing the above commands in action. First, we |
| show our source files: |
| |
| $ cat sample.c |
| #include <stdio.h> |
| #include "sample.h" |
| |
| #define M 42 |
| #define ADD(x) (M + x) |
| |
| main () |
| { |
| #define N 28 |
| printf ("Hello, world!\n"); |
| #undef N |
| printf ("We're so creative.\n"); |
| #define N 1729 |
| printf ("Goodbye, world!\n"); |
| } |
| $ cat sample.h |
| #define Q < |
| $ |
| |
| Now, we compile the program using the GNU C compiler, GCC. We pass |
| the `-gdwarf-2' and `-g3' flags to ensure the compiler includes |
| information about preprocessor macros in the debugging information. |
| |
| $ gcc -gdwarf-2 -g3 sample.c -o sample |
| $ |
| |
| Now, we start GDB on our sample program: |
| |
| $ gdb -nw sample |
| GNU gdb 2002-05-06-cvs |
| Copyright 2002 Free Software Foundation, Inc. |
| GDB is free software, ... |
| (gdb) |
| |
| We can expand macros and examine their definitions, even when the |
| program is not running. GDB uses the current listing position to |
| decide which macro definitions are in scope: |
| |
| (gdb) list main |
| 3 |
| 4 #define M 42 |
| 5 #define ADD(x) (M + x) |
| 6 |
| 7 main () |
| 8 { |
| 9 #define N 28 |
| 10 printf ("Hello, world!\n"); |
| 11 #undef N |
| 12 printf ("We're so creative.\n"); |
| (gdb) info macro ADD |
| Defined at /home/jimb/gdb/macros/play/sample.c:5 |
| #define ADD(x) (M + x) |
| (gdb) info macro Q |
| Defined at /home/jimb/gdb/macros/play/sample.h:1 |
| included at /home/jimb/gdb/macros/play/sample.c:2 |
| #define Q < |
| (gdb) macro expand ADD(1) |
| expands to: (42 + 1) |
| (gdb) macro expand-once ADD(1) |
| expands to: once (M + 1) |
| (gdb) |
| |
| In the example above, note that `macro expand-once' expands only the |
| macro invocation explicit in the original text -- the invocation of |
| `ADD' -- but does not expand the invocation of the macro `M', which was |
| introduced by `ADD'. |
| |
| Once the program is running, GDB uses the macro definitions in force |
| at the source line of the current stack frame: |
| |
| (gdb) break main |
| Breakpoint 1 at 0x8048370: file sample.c, line 10. |
| (gdb) run |
| Starting program: /home/jimb/gdb/macros/play/sample |
| |
| Breakpoint 1, main () at sample.c:10 |
| 10 printf ("Hello, world!\n"); |
| (gdb) |
| |
| At line 10, the definition of the macro `N' at line 9 is in force: |
| |
| (gdb) info macro N |
| Defined at /home/jimb/gdb/macros/play/sample.c:9 |
| #define N 28 |
| (gdb) macro expand N Q M |
| expands to: 28 < 42 |
| (gdb) print N Q M |
| $1 = 1 |
| (gdb) |
| |
| As we step over directives that remove `N''s definition, and then |
| give it a new definition, GDB finds the definition (or lack thereof) in |
| force at each point: |
| |
| (gdb) next |
| Hello, world! |
| 12 printf ("We're so creative.\n"); |
| (gdb) info macro N |
| The symbol `N' has no definition as a C/C++ preprocessor macro |
| at /home/jimb/gdb/macros/play/sample.c:12 |
| (gdb) next |
| We're so creative. |
| 14 printf ("Goodbye, world!\n"); |
| (gdb) info macro N |
| Defined at /home/jimb/gdb/macros/play/sample.c:13 |
| #define N 1729 |
| (gdb) macro expand N Q M |
| expands to: 1729 < 42 |
| (gdb) print N Q M |
| $2 = 0 |
| (gdb) |
| |
| |
| File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top |
| |
| 10 Tracepoints |
| ************** |
| |
| In some applications, it is not feasible for the debugger to interrupt |
| the program's execution long enough for the developer to learn anything |
| helpful about its behavior. If the program's correctness depends on |
| its real-time behavior, delays introduced by a debugger might cause the |
| program to change its behavior drastically, or perhaps fail, even when |
| the code itself is correct. It is useful to be able to observe the |
| program's behavior without interrupting it. |
| |
| Using GDB's `trace' and `collect' commands, you can specify |
| locations in the program, called "tracepoints", and arbitrary |
| expressions to evaluate when those tracepoints are reached. Later, |
| using the `tfind' command, you can examine the values those expressions |
| had when the program hit the tracepoints. The expressions may also |
| denote objects in memory--structures or arrays, for example--whose |
| values GDB should record; while visiting a particular tracepoint, you |
| may inspect those objects as if they were in memory at that moment. |
| However, because GDB records these values without interacting with you, |
| it can do so quickly and unobtrusively, hopefully not disturbing the |
| program's behavior. |
| |
| The tracepoint facility is currently available only for remote |
| targets. *Note Targets::. In addition, your remote target must know |
| how to collect trace data. This functionality is implemented in the |
| remote stub; however, none of the stubs distributed with GDB support |
| tracepoints as of this writing. The format of the remote packets used |
| to implement tracepoints are described in *Note Tracepoint Packets::. |
| |
| This chapter describes the tracepoint commands and features. |
| |
| * Menu: |
| |
| * Set Tracepoints:: |
| * Analyze Collected Data:: |
| * Tracepoint Variables:: |
| |
| |
| File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints |
| |
| 10.1 Commands to Set Tracepoints |
| ================================ |
| |
| Before running such a "trace experiment", an arbitrary number of |
| tracepoints can be set. Like a breakpoint (*note Set Breaks::), a |
| tracepoint has a number assigned to it by GDB. Like with breakpoints, |
| tracepoint numbers are successive integers starting from one. Many of |
| the commands associated with tracepoints take the tracepoint number as |
| their argument, to identify which tracepoint to work on. |
| |
| For each tracepoint, you can specify, in advance, some arbitrary set |
| of data that you want the target to collect in the trace buffer when it |
| hits that tracepoint. The collected data can include registers, local |
| variables, or global data. Later, you can use GDB commands to examine |
| the values these data had at the time the tracepoint was hit. |
| |
| This section describes commands to set tracepoints and associated |
| conditions and actions. |
| |
| * Menu: |
| |
| * Create and Delete Tracepoints:: |
| * Enable and Disable Tracepoints:: |
| * Tracepoint Passcounts:: |
| * Tracepoint Actions:: |
| * Listing Tracepoints:: |
| * Starting and Stopping Trace Experiments:: |
| |
| |
| File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints |
| |
| 10.1.1 Create and Delete Tracepoints |
| ------------------------------------ |
| |
| `trace' |
| The `trace' command is very similar to the `break' command. Its |
| argument can be a source line, a function name, or an address in |
| the target program. *Note Set Breaks::. The `trace' command |
| defines a tracepoint, which is a point in the target program where |
| the debugger will briefly stop, collect some data, and then allow |
| the program to continue. Setting a tracepoint or changing its |
| commands doesn't take effect until the next `tstart' command; |
| thus, you cannot change the tracepoint attributes once a trace |
| experiment is running. |
| |
| Here are some examples of using the `trace' command: |
| |
| (gdb) trace foo.c:121 // a source file and line number |
| |
| (gdb) trace +2 // 2 lines forward |
| |
| (gdb) trace my_function // first source line of function |
| |
| (gdb) trace *my_function // EXACT start address of function |
| |
| (gdb) trace *0x2117c4 // an address |
| |
| You can abbreviate `trace' as `tr'. |
| |
| The convenience variable `$tpnum' records the tracepoint number of |
| the most recently set tracepoint. |
| |
| `delete tracepoint [NUM]' |
| Permanently delete one or more tracepoints. With no argument, the |
| default is to delete all tracepoints. |
| |
| Examples: |
| |
| (gdb) delete trace 1 2 3 // remove three tracepoints |
| |
| (gdb) delete trace // remove all tracepoints |
| |
| You can abbreviate this command as `del tr'. |
| |
| |
| File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints |
| |
| 10.1.2 Enable and Disable Tracepoints |
| ------------------------------------- |
| |
| `disable tracepoint [NUM]' |
| Disable tracepoint NUM, or all tracepoints if no argument NUM is |
| given. A disabled tracepoint will have no effect during the next |
| trace experiment, but it is not forgotten. You can re-enable a |
| disabled tracepoint using the `enable tracepoint' command. |
| |
| `enable tracepoint [NUM]' |
| Enable tracepoint NUM, or all tracepoints. The enabled |
| tracepoints will become effective the next time a trace experiment |
| is run. |
| |
| |
| File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Actions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints |
| |
| 10.1.3 Tracepoint Passcounts |
| ---------------------------- |
| |
| `passcount [N [NUM]]' |
| Set the "passcount" of a tracepoint. The passcount is a way to |
| automatically stop a trace experiment. If a tracepoint's |
| passcount is N, then the trace experiment will be automatically |
| stopped on the N'th time that tracepoint is hit. If the |
| tracepoint number NUM is not specified, the `passcount' command |
| sets the passcount of the most recently defined tracepoint. If no |
| passcount is given, the trace experiment will run until stopped |
| explicitly by the user. |
| |
| Examples: |
| |
| (gdb) passcount 5 2 // Stop on the 5th execution of |
| `// tracepoint 2' |
| |
| (gdb) passcount 12 // Stop on the 12th execution of the |
| `// most recently defined tracepoint.' |
| (gdb) trace foo |
| (gdb) pass 3 |
| (gdb) trace bar |
| (gdb) pass 2 |
| (gdb) trace baz |
| (gdb) pass 1 // Stop tracing when foo has been |
| `// executed 3 times OR when bar has' |
| `// been executed 2 times' |
| `// OR when baz has been executed 1 time.' |
| |
| |
| |
| File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Tracepoint Passcounts, Up: Set Tracepoints |
| |
| 10.1.4 Tracepoint Action Lists |
| ------------------------------ |
| |
| `actions [NUM]' |
| This command will prompt for a list of actions to be taken when the |
| tracepoint is hit. If the tracepoint number NUM is not specified, |
| this command sets the actions for the one that was most recently |
| defined (so that you can define a tracepoint and then say |
| `actions' without bothering about its number). You specify the |
| actions themselves on the following lines, one action at a time, |
| and terminate the actions list with a line containing just `end'. |
| So far, the only defined actions are `collect' and |
| `while-stepping'. |
| |
| To remove all actions from a tracepoint, type `actions NUM' and |
| follow it immediately with `end'. |
| |
| (gdb) collect DATA // collect some data |
| |
| (gdb) while-stepping 5 // single-step 5 times, collect data |
| |
| (gdb) end // signals the end of actions. |
| |
| In the following example, the action list begins with `collect' |
| commands indicating the things to be collected when the tracepoint |
| is hit. Then, in order to single-step and collect additional data |
| following the tracepoint, a `while-stepping' command is used, |
| followed by the list of things to be collected while stepping. The |
| `while-stepping' command is terminated by its own separate `end' |
| command. Lastly, the action list is terminated by an `end' |
| command. |
| |
| (gdb) trace foo |
| (gdb) actions |
| Enter actions for tracepoint 1, one per line: |
| > collect bar,baz |
| > collect $regs |
| > while-stepping 12 |
| > collect $fp, $sp |
| > end |
| end |
| |
| `collect EXPR1, EXPR2, ...' |
| Collect values of the given expressions when the tracepoint is hit. |
| This command accepts a comma-separated list of any valid |
| expressions. In addition to global, static, or local variables, |
| the following special arguments are supported: |
| |
| `$regs' |
| collect all registers |
| |
| `$args' |
| collect all function arguments |
| |
| `$locals' |
| collect all local variables. |
| |
| You can give several consecutive `collect' commands, each one with |
| a single argument, or one `collect' command with several arguments |
| separated by commas: the effect is the same. |
| |
| The command `info scope' (*note info scope: Symbols.) is |
| particularly useful for figuring out what data to collect. |
| |
| `while-stepping N' |
| Perform N single-step traces after the tracepoint, collecting new |
| data at each step. The `while-stepping' command is followed by |
| the list of what to collect while stepping (followed by its own |
| `end' command): |
| |
| > while-stepping 12 |
| > collect $regs, myglobal |
| > end |
| > |
| |
| You may abbreviate `while-stepping' as `ws' or `stepping'. |
| |
| |
| File: gdb.info, Node: Listing Tracepoints, Next: Starting and Stopping Trace Experiments, Prev: Tracepoint Actions, Up: Set Tracepoints |
| |
| 10.1.5 Listing Tracepoints |
| -------------------------- |
| |
| `info tracepoints [NUM]' |
| Display information about the tracepoint NUM. If you don't specify |
| a tracepoint number, displays information about all the tracepoints |
| defined so far. For each tracepoint, the following information is |
| shown: |
| |
| * its number |
| |
| * whether it is enabled or disabled |
| |
| * its address |
| |
| * its passcount as given by the `passcount N' command |
| |
| * its step count as given by the `while-stepping N' command |
| |
| * where in the source files is the tracepoint set |
| |
| * its action list as given by the `actions' command |
| |
| (gdb) info trace |
| Num Enb Address PassC StepC What |
| 1 y 0x002117c4 0 0 <gdb_asm> |
| 2 y 0x0020dc64 0 0 in g_test at g_test.c:1375 |
| 3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41 |
| (gdb) |
| |
| This command can be abbreviated `info tp'. |
| |
| |
| File: gdb.info, Node: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints |
| |
| 10.1.6 Starting and Stopping Trace Experiments |
| ---------------------------------------------- |
| |
| `tstart' |
| This command takes no arguments. It starts the trace experiment, |
| and begins collecting data. This has the side effect of |
| discarding all the data collected in the trace buffer during the |
| previous trace experiment. |
| |
| `tstop' |
| This command takes no arguments. It ends the trace experiment, and |
| stops collecting data. |
| |
| *Note*: a trace experiment and data collection may stop |
| automatically if any tracepoint's passcount is reached (*note |
| Tracepoint Passcounts::), or if the trace buffer becomes full. |
| |
| `tstatus' |
| This command displays the status of the current trace data |
| collection. |
| |
| Here is an example of the commands we described so far: |
| |
| (gdb) trace gdb_c_test |
| (gdb) actions |
| Enter actions for tracepoint #1, one per line. |
| > collect $regs,$locals,$args |
| > while-stepping 11 |
| > collect $regs |
| > end |
| > end |
| (gdb) tstart |
| [time passes ...] |
| (gdb) tstop |
| |
| |
| File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints |
| |
| 10.2 Using the Collected Data |
| ============================= |
| |
| After the tracepoint experiment ends, you use GDB commands for |
| examining the trace data. The basic idea is that each tracepoint |
| collects a trace "snapshot" every time it is hit and another snapshot |
| every time it single-steps. All these snapshots are consecutively |
| numbered from zero and go into a buffer, and you can examine them |
| later. The way you examine them is to "focus" on a specific trace |
| snapshot. When the remote stub is focused on a trace snapshot, it will |
| respond to all GDB requests for memory and registers by reading from |
| the buffer which belongs to that snapshot, rather than from _real_ |
| memory or registers of the program being debugged. This means that |
| *all* GDB commands (`print', `info registers', `backtrace', etc.) will |
| behave as if we were currently debugging the program state as it was |
| when the tracepoint occurred. Any requests for data that are not in |
| the buffer will fail. |
| |
| * Menu: |
| |
| * tfind:: How to select a trace snapshot |
| * tdump:: How to display all data for a snapshot |
| * save-tracepoints:: How to save tracepoints for a future run |
| |
| |
| File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data |
| |
| 10.2.1 `tfind N' |
| ---------------- |
| |
| The basic command for selecting a trace snapshot from the buffer is |
| `tfind N', which finds trace snapshot number N, counting from zero. If |
| no argument N is given, the next snapshot is selected. |
| |
| Here are the various forms of using the `tfind' command. |
| |
| `tfind start' |
| Find the first snapshot in the buffer. This is a synonym for |
| `tfind 0' (since 0 is the number of the first snapshot). |
| |
| `tfind none' |
| Stop debugging trace snapshots, resume _live_ debugging. |
| |
| `tfind end' |
| Same as `tfind none'. |
| |
| `tfind' |
| No argument means find the next trace snapshot. |
| |
| `tfind -' |
| Find the previous trace snapshot before the current one. This |
| permits retracing earlier steps. |
| |
| `tfind tracepoint NUM' |
| Find the next snapshot associated with tracepoint NUM. Search |
| proceeds forward from the last examined trace snapshot. If no |
| argument NUM is given, it means find the next snapshot collected |
| for the same tracepoint as the current snapshot. |
| |
| `tfind pc ADDR' |
| Find the next snapshot associated with the value ADDR of the |
| program counter. Search proceeds forward from the last examined |
| trace snapshot. If no argument ADDR is given, it means find the |
| next snapshot with the same value of PC as the current snapshot. |
| |
| `tfind outside ADDR1, ADDR2' |
| Find the next snapshot whose PC is outside the given range of |
| addresses. |
| |
| `tfind range ADDR1, ADDR2' |
| Find the next snapshot whose PC is between ADDR1 and ADDR2. |
| |
| `tfind line [FILE:]N' |
| Find the next snapshot associated with the source line N. If the |
| optional argument FILE is given, refer to line N in that source |
| file. Search proceeds forward from the last examined trace |
| snapshot. If no argument N is given, it means find the next line |
| other than the one currently being examined; thus saying `tfind |
| line' repeatedly can appear to have the same effect as stepping |
| from line to line in a _live_ debugging session. |
| |
| The default arguments for the `tfind' commands are specifically |
| designed to make it easy to scan through the trace buffer. For |
| instance, `tfind' with no argument selects the next trace snapshot, and |
| `tfind -' with no argument selects the previous trace snapshot. So, by |
| giving one `tfind' command, and then simply hitting <RET> repeatedly |
| you can examine all the trace snapshots in order. Or, by saying `tfind |
| -' and then hitting <RET> repeatedly you can examine the snapshots in |
| reverse order. The `tfind line' command with no argument selects the |
| snapshot for the next source line executed. The `tfind pc' command with |
| no argument selects the next snapshot with the same program counter |
| (PC) as the current frame. The `tfind tracepoint' command with no |
| argument selects the next trace snapshot collected by the same |
| tracepoint as the current one. |
| |
| In addition to letting you scan through the trace buffer manually, |
| these commands make it easy to construct GDB scripts that scan through |
| the trace buffer and print out whatever collected data you are |
| interested in. Thus, if we want to examine the PC, FP, and SP |
| registers from each trace frame in the buffer, we can say this: |
| |
| (gdb) tfind start |
| (gdb) while ($trace_frame != -1) |
| > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ |
| $trace_frame, $pc, $sp, $fp |
| > tfind |
| > end |
| |
| Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 |
| Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 |
| Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 |
| Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 |
| Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 |
| Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 |
| Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 |
| Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 |
| Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 |
| Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 |
| Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 |
| |
| Or, if we want to examine the variable `X' at each source line in |
| the buffer: |
| |
| (gdb) tfind start |
| (gdb) while ($trace_frame != -1) |
| > printf "Frame %d, X == %d\n", $trace_frame, X |
| > tfind line |
| > end |
| |
| Frame 0, X = 1 |
| Frame 7, X = 2 |
| Frame 13, X = 255 |
| |
| |
| File: gdb.info, Node: tdump, Next: save-tracepoints, Prev: tfind, Up: Analyze Collected Data |
| |
| 10.2.2 `tdump' |
| -------------- |
| |
| This command takes no arguments. It prints all the data collected at |
| the current trace snapshot. |
| |
| (gdb) trace 444 |
| (gdb) actions |
| Enter actions for tracepoint #2, one per line: |
| > collect $regs, $locals, $args, gdb_long_test |
| > end |
| |
| (gdb) tstart |
| |
| (gdb) tfind line 444 |
| #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) |
| at gdb_test.c:444 |
| 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) |
| |
| (gdb) tdump |
| Data collected at tracepoint 2, trace frame 1: |
| d0 0xc4aa0085 -995491707 |
| d1 0x18 24 |
| d2 0x80 128 |
| d3 0x33 51 |
| d4 0x71aea3d 119204413 |
| d5 0x22 34 |
| d6 0xe0 224 |
| d7 0x380035 3670069 |
| a0 0x19e24a 1696330 |
| a1 0x3000668 50333288 |
| a2 0x100 256 |
| a3 0x322000 3284992 |
| a4 0x3000698 50333336 |
| a5 0x1ad3cc 1758156 |
| fp 0x30bf3c 0x30bf3c |
| sp 0x30bf34 0x30bf34 |
| ps 0x0 0 |
| pc 0x20b2c8 0x20b2c8 |
| fpcontrol 0x0 0 |
| fpstatus 0x0 0 |
| fpiaddr 0x0 0 |
| p = 0x20e5b4 "gdb-test" |
| p1 = (void *) 0x11 |
| p2 = (void *) 0x22 |
| p3 = (void *) 0x33 |
| p4 = (void *) 0x44 |
| p5 = (void *) 0x55 |
| p6 = (void *) 0x66 |
| gdb_long_test = 17 '\021' |
| |
| (gdb) |
| |
| |
| File: gdb.info, Node: save-tracepoints, Prev: tdump, Up: Analyze Collected Data |
| |
| 10.2.3 `save-tracepoints FILENAME' |
| ---------------------------------- |
| |
| This command saves all current tracepoint definitions together with |
| their actions and passcounts, into a file `FILENAME' suitable for use |
| in a later debugging session. To read the saved tracepoint |
| definitions, use the `source' command (*note Command Files::). |
| |
| |
| File: gdb.info, Node: Tracepoint Variables, Prev: Analyze Collected Data, Up: Tracepoints |
| |
| 10.3 Convenience Variables for Tracepoints |
| ========================================== |
| |
| `(int) $trace_frame' |
| The current trace snapshot (a.k.a. "frame") number, or -1 if no |
| snapshot is selected. |
| |
| `(int) $tracepoint' |
| The tracepoint for the current trace snapshot. |
| |
| `(int) $trace_line' |
| The line number for the current trace snapshot. |
| |
| `(char []) $trace_file' |
| The source file for the current trace snapshot. |
| |
| `(char []) $trace_func' |
| The name of the function containing `$tracepoint'. |
| |
| Note: `$trace_file' is not suitable for use in `printf', use |
| `output' instead. |
| |
| Here's a simple example of using these convenience variables for |
| stepping through all the trace snapshots and printing some of their |
| data. |
| |
| (gdb) tfind start |
| |
| (gdb) while $trace_frame != -1 |
| > output $trace_file |
| > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint |
| > tfind |
| > end |
| |
| |
| File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top |
| |
| 11 Debugging Programs That Use Overlays |
| *************************************** |
| |
| If your program is too large to fit completely in your target system's |
| memory, you can sometimes use "overlays" to work around this problem. |
| GDB provides some support for debugging programs that use overlays. |
| |
| * Menu: |
| |
| * How Overlays Work:: A general explanation of overlays. |
| * Overlay Commands:: Managing overlays in GDB. |
| * Automatic Overlay Debugging:: GDB can find out which overlays are |
| mapped by asking the inferior. |
| * Overlay Sample Program:: A sample program using overlays. |
| |
| |
| File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays |
| |
| 11.1 How Overlays Work |
| ====================== |
| |
| Suppose you have a computer whose instruction address space is only 64 |
| kilobytes long, but which has much more memory which can be accessed by |
| other means: special instructions, segment registers, or memory |
| management hardware, for example. Suppose further that you want to |
| adapt a program which is larger than 64 kilobytes to run on this system. |
| |
| One solution is to identify modules of your program which are |
| relatively independent, and need not call each other directly; call |
| these modules "overlays". Separate the overlays from the main program, |
| and place their machine code in the larger memory. Place your main |
| program in instruction memory, but leave at least enough space there to |
| hold the largest overlay as well. |
| |
| Now, to call a function located in an overlay, you must first copy |
| that overlay's machine code from the large memory into the space set |
| aside for it in the instruction memory, and then jump to its entry point |
| there. |
| |
| Data Instruction Larger |
| Address Space Address Space Address Space |
| +-----------+ +-----------+ +-----------+ |
| | | | | | | |
| +-----------+ +-----------+ +-----------+<-- overlay 1 |
| | program | | main | .----| overlay 1 | load address |
| | variables | | program | | +-----------+ |
| | and heap | | | | | | |
| +-----------+ | | | +-----------+<-- overlay 2 |
| | | +-----------+ | | | load address |
| +-----------+ | | | .-| overlay 2 | |
| | | | | | | |
| mapped --->+-----------+ | | +-----------+ |
| address | | | | | | |
| | overlay | <-' | | | |
| | area | <---' +-----------+<-- overlay 3 |
| | | <---. | | load address |
| +-----------+ `--| overlay 3 | |
| | | | | |
| +-----------+ | | |
| +-----------+ |
| | | |
| +-----------+ |
| |
| A code overlay |
| |
| The diagram (*note A code overlay::) shows a system with separate |
| data and instruction address spaces. To map an overlay, the program |
| copies its code from the larger address space to the instruction |
| address space. Since the overlays shown here all use the same mapped |
| address, only one may be mapped at a time. For a system with a single |
| address space for data and instructions, the diagram would be similar, |
| except that the program variables and heap would share an address space |
| with the main program and the overlay area. |
| |
| An overlay loaded into instruction memory and ready for use is |
| called a "mapped" overlay; its "mapped address" is its address in the |
| instruction memory. An overlay not present (or only partially present) |
| in instruction memory is called "unmapped"; its "load address" is its |
| address in the larger memory. The mapped address is also called the |
| "virtual memory address", or "VMA"; the load address is also called the |
| "load memory address", or "LMA". |
| |
| Unfortunately, overlays are not a completely transparent way to |
| adapt a program to limited instruction memory. They introduce a new |
| set of global constraints you must keep in mind as you design your |
| program: |
| |
| * Before calling or returning to a function in an overlay, your |
| program must make sure that overlay is actually mapped. |
| Otherwise, the call or return will transfer control to the right |
| address, but in the wrong overlay, and your program will probably |
| crash. |
| |
| * If the process of mapping an overlay is expensive on your system, |
| you will need to choose your overlays carefully to minimize their |
| effect on your program's performance. |
| |
| * The executable file you load onto your system must contain each |
| overlay's instructions, appearing at the overlay's load address, |
| not its mapped address. However, each overlay's instructions must |
| be relocated and its symbols defined as if the overlay were at its |
| mapped address. You can use GNU linker scripts to specify |
| different load and relocation addresses for pieces of your |
| program; see *Note Overlay Description: (ld.info)Overlay |
| Description. |
| |
| * The procedure for loading executable files onto your system must |
| be able to load their contents into the larger address space as |
| well as the instruction and data spaces. |
| |
| |
| The overlay system described above is rather simple, and could be |
| improved in many ways: |
| |
| * If your system has suitable bank switch registers or memory |
| management hardware, you could use those facilities to make an |
| overlay's load area contents simply appear at their mapped address |
| in instruction space. This would probably be faster than copying |
| the overlay to its mapped area in the usual way. |
| |
| * If your overlays are small enough, you could set aside more than |
| one overlay area, and have more than one overlay mapped at a time. |
| |
| * You can use overlays to manage data, as well as instructions. In |
| general, data overlays are even less transparent to your design |
| than code overlays: whereas code overlays only require care when |
| you call or return to functions, data overlays require care every |
| time you access the data. Also, if you change the contents of a |
| data overlay, you must copy its contents back out to its load |
| address before you can copy a different data overlay into the same |
| mapped area. |
| |
| |
| |
| File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays |
| |
| 11.2 Overlay Commands |
| ===================== |
| |
| To use GDB's overlay support, each overlay in your program must |
| correspond to a separate section of the executable file. The section's |
| virtual memory address and load memory address must be the overlay's |
| mapped and load addresses. Identifying overlays with sections allows |
| GDB to determine the appropriate address of a function or variable, |
| depending on whether the overlay is mapped or not. |
| |
| GDB's overlay commands all start with the word `overlay'; you can |
| abbreviate this as `ov' or `ovly'. The commands are: |
| |
| `overlay off' |
| Disable GDB's overlay support. When overlay support is disabled, |
| GDB assumes that all functions and variables are always present at |
| their mapped addresses. By default, GDB's overlay support is |
| disabled. |
| |
| `overlay manual' |
| Enable "manual" overlay debugging. In this mode, GDB relies on |
| you to tell it which overlays are mapped, and which are not, using |
| the `overlay map-overlay' and `overlay unmap-overlay' commands |
| described below. |
| |
| `overlay map-overlay OVERLAY' |
| `overlay map OVERLAY' |
| Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of |
| the object file section containing the overlay. When an overlay |
| is mapped, GDB assumes it can find the overlay's functions and |
| variables at their mapped addresses. GDB assumes that any other |
| overlays whose mapped ranges overlap that of OVERLAY are now |
| unmapped. |
| |
| `overlay unmap-overlay OVERLAY' |
| `overlay unmap OVERLAY' |
| Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the |
| name of the object file section containing the overlay. When an |
| overlay is unmapped, GDB assumes it can find the overlay's |
| functions and variables at their load addresses. |
| |
| `overlay auto' |
| Enable "automatic" overlay debugging. In this mode, GDB consults |
| a data structure the overlay manager maintains in the inferior to |
| see which overlays are mapped. For details, see *Note Automatic |
| Overlay Debugging::. |
| |
| `overlay load-target' |
| `overlay load' |
| Re-read the overlay table from the inferior. Normally, GDB |
| re-reads the table GDB automatically each time the inferior stops, |
| so this command should only be necessary if you have changed the |
| overlay mapping yourself using GDB. This command is only useful |
| when using automatic overlay debugging. |
| |
| `overlay list-overlays' |
| `overlay list' |
| Display a list of the overlays currently mapped, along with their |
| mapped addresses, load addresses, and sizes. |
| |
| |
| Normally, when GDB prints a code address, it includes the name of |
| the function the address falls in: |
| |
| (gdb) print main |
| $3 = {int ()} 0x11a0 <main> |
| When overlay debugging is enabled, GDB recognizes code in unmapped |
| overlays, and prints the names of unmapped functions with asterisks |
| around them. For example, if `foo' is a function in an unmapped |
| overlay, GDB prints it this way: |
| |
| (gdb) overlay list |
| No sections are mapped. |
| (gdb) print foo |
| $5 = {int (int)} 0x100000 <*foo*> |
| When `foo''s overlay is mapped, GDB prints the function's name |
| normally: |
| |
| (gdb) overlay list |
| Section .ov.foo.text, loaded at 0x100000 - 0x100034, |
| mapped at 0x1016 - 0x104a |
| (gdb) print foo |
| $6 = {int (int)} 0x1016 <foo> |
| |
| When overlay debugging is enabled, GDB can find the correct address |
| for functions and variables in an overlay, whether or not the overlay |
| is mapped. This allows most GDB commands, like `break' and |
| `disassemble', to work normally, even on unmapped code. However, GDB's |
| breakpoint support has some limitations: |
| |
| * You can set breakpoints in functions in unmapped overlays, as long |
| as GDB can write to the overlay at its load address. |
| |
| * GDB can not set hardware or simulator-based breakpoints in |
| unmapped overlays. However, if you set a breakpoint at the end of |
| your overlay manager (and tell GDB which overlays are now mapped, |
| if you are using manual overlay management), GDB will re-set its |
| breakpoints properly. |
| |