| 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 |
| |