| This is gdb.info, produced by makeinfo version 6.5 from gdb.texinfo. |
| |
| Copyright (C) 1988-2020 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.3 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." |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| * gdbserver: (gdb) Server. The GNU debugging server. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Tenth Edition, of 'Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 9.2. |
| |
| Copyright (C) 1988-2020 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.3 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 Tenth Edition, for GDB (GDB) Version 9.2. |
| |
| Copyright (C) 1988-2020 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 |
| * Reverse Execution:: Running programs backward |
| * Process Record and Replay:: Recording inferior's execution and replaying it |
| * Stack:: Examining the stack |
| * Source:: Examining source files |
| * Data:: Examining data |
| * Optimized Code:: Debugging optimized code |
| * 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 |
| * Extending GDB:: Extending GDB |
| * 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. |
| * JIT Interface:: Using the JIT debugging interface. |
| * In-Process Agent:: In-Process Agent |
| |
| * GDB Bugs:: Reporting bugs in GDB |
| |
| * Command Line Editing:: Command Line Editing |
| * Using History Interactively:: Using History Interactively |
| * In Memoriam:: In Memoriam |
| * 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 |
| * Operating System Information:: Getting additional information from |
| the operating system |
| * Trace File Format:: GDB trace file format |
| * Index Section Format:: .gdb_index section format |
| * Man Pages:: Manual pages |
| * Copying:: GNU General Public License says |
| how you can copy and share GDB |
| * GNU Free Documentation License:: The license for this documentation |
| * Concept Index:: Index of GDB concepts |
| * Command and Variable Index:: Index of GDB commands, variables, |
| functions, and Python data types |
| |
| |
| File: gdb.info, Node: Summary, Next: Sample Session, 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 D is partial. For information on D, see *note D: D. |
| |
| Support for Modula-2 is partial. For information on Modula-2, see |
| *note Modula-2: Modula-2. |
| |
| Support for OpenCL C is partial. For information on OpenCL C, see |
| *note OpenCL C: OpenCL C. |
| |
| 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 |
| * Free Documentation:: Free Software Needs Free Documentation |
| * Contributors:: Contributors to GDB |
| |
| |
| File: gdb.info, Node: Free Software, Next: Free Documentation, 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. |
| |
| |
| File: gdb.info, Node: Free Documentation, Next: Contributors, Prev: Free Software, Up: Summary |
| |
| 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 Documentation, 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. |
| |
| Michael Eager and staff of Xilinx, Inc., contributed support for the |
| Xilinx MicroBlaze architecture. |
| |
| Initial support for the FreeBSD/mips target and native configuration |
| was developed by SRI International and the University of Cambridge |
| Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 |
| ("CTSRD"), as part of the DARPA CRASH research programme. |
| |
| Initial support for the FreeBSD/riscv target and native configuration |
| was developed by SRI International and the University of Cambridge |
| Computer Laboratory (Department of Computer Science and Technology) |
| under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA |
| SSITH research programme. |
| |
| The original port to the OpenRISC 1000 is believed to be due to |
| Alessandro Forin and Per Bothner. More recent ports have been the work |
| of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and Stafford |
| Horne. |
| |
| |
| 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 9.2, 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 or use |
| option '-p', if you want to debug a running process: |
| |
| gdb PROGRAM 1234 |
| gdb -p 1234 |
| |
| would attach GDB to process '1234'. With option '-p' you can omit the |
| PROGRAM filename. |
| |
| 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' (or |
| '-q'/'--quiet'): |
| |
| 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 commands from file FILE. The contents of this file is |
| evaluated exactly as the 'source' command would. *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 |
| |
| '-init-command FILE' |
| '-ix FILE' |
| Execute commands from file FILE before loading the inferior (but |
| after loading gdbinit files). *Note Startup::. |
| |
| '-init-eval-command COMMAND' |
| '-iex COMMAND' |
| Execute a single GDB command before loading the inferior (but after |
| loading gdbinit files). *Note Startup::. |
| |
| '-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. |
| |
| '--readnever' |
| Do not read each symbol file's symbolic debug information. This |
| makes startup faster but at the expense of not being able to |
| perform symbolic debugging. DWARF unwind information is also not |
| read, meaning backtraces may become incomplete or inaccurate. One |
| use of this is when a user simply wants to do the following |
| sequence: attach, dump core, detach. Loading the debugging |
| information in this case is an unnecessary cause of delay. |
| |
| |
| 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 file. There |
| are three init files, loaded in the following order: |
| |
| 'system.gdbinit' |
| This is the system-wide init file. Its location is specified |
| with the '--with-system-gdbinit' configure option (*note |
| System-wide configuration::). It is loaded first when GDB |
| starts, before command line options have been processed. |
| 'system.gdbinit.d' |
| This is the system-wide init directory. Its location is |
| specified with the '--with-system-gdbinit-dir' configure |
| option (*note System-wide configuration::). Files in this |
| directory are loaded in alphabetical order immediately after |
| system.gdbinit (if enabled) when GDB starts, before command |
| line options have been processed. Files need to have a |
| recognized scripting language extension ('.py'/'.scm') or be |
| named with a '.gdb' extension to be interpreted as regular GDB |
| commands. GDB will not recurse into any subdirectories of |
| this directory. |
| '~/.gdbinit' |
| This is the init file in your home directory. It is loaded |
| next, after 'system.gdbinit', and before command options have |
| been processed. |
| './.gdbinit' |
| This is the init file in the current directory. It is loaded |
| last, after command line options other than '-x' and '-ex' |
| have been processed. Command line options '-x' and '-ex' are |
| processed last, after './.gdbinit' has been loaded. |
| |
| For further documentation on startup processing, *Note Startup::. |
| For documentation on how to write command files, *Note Command |
| Files: Command Files. |
| |
| '-nh' |
| Do not execute commands found in '~/.gdbinit', the init file in |
| your home directory. *Note Startup::. |
| |
| '-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 also disables pagination, sets |
| unlimited terminal width and height *note Screen Size::, and acts |
| as if 'set confirm off' were in effect (*note Messages/Warnings::). |
| |
| 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. |
| |
| '-data-directory DIRECTORY' |
| '-D DIRECTORY' |
| Run GDB using DIRECTORY as its data directory. The data directory |
| is where GDB searches for its auxiliary files. *Note Data Files::. |
| |
| '-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. |
| |
| '-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.). 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=mi3') causes GDB to use the |
| "GDB/MI interface" version 3 (*note The GDB/MI Interface: GDB/MI.) |
| included since GDB version 9.1. GDB/MI version 2 ('mi2'), included |
| in GDB 6.0 and version 1 ('mi1'), included in GDB 5.3, are also |
| available. 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. |
| |
| '-configuration' |
| This option causes GDB to print details about its build-time |
| configuration parameters, and then exit. These details can be |
| important when reporting GDB bugs (*note GDB Bugs::). |
| |
| |
| 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 system-wide "init file" (if '--with-system-gdbinit' was |
| used when building GDB; *note System-wide configuration and |
| settings: System-wide configuration.) and the files in the |
| system-wide gdbinit directory (if '--with-system-gdbinit-dir' was |
| used) and executes all the commands in those files. The files need |
| to be named with a '.gdb' extension to be interpreted as GDB |
| commands, or they can be written in a supported scripting language |
| with an appropriate file extension. |
| |
| 3. Reads the init file (if any) in your home directory(1) and executes |
| all the commands in that file. |
| |
| 4. Executes commands and command files specified by the '-iex' and |
| '-ix' options in their specified order. Usually you should use the |
| '-ex' and '-x' options instead, but this way you can apply settings |
| before GDB init files get executed and before inferior gets loaded. |
| |
| 5. Processes command line options and operands. |
| |
| 6. Reads and executes the commands from init file (if any) in the |
| current working directory as long as 'set auto-load local-gdbinit' |
| is set to 'on' (*note Init File in the Current 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. |
| |
| 7. If the command line specified a program to debug, or a process to |
| attach to, or a core file, GDB loads any auto-loaded scripts |
| provided for the program or for its loaded shared libraries. *Note |
| Auto-loading::. |
| |
| If you wish to disable the auto-loading during startup, you must do |
| something like the following: |
| |
| $ gdb -iex "set auto-load python-scripts off" myprogram |
| |
| Option '-ex' does not work because the auto-loading is then turned |
| off too late. |
| |
| 8. Executes commands and command files specified by the '-ex' and '-x' |
| options in their specified order. *Note Command Files::, for more |
| details about GDB command files. |
| |
| 9. 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.). |
| |
| To display the list of init files loaded by gdb at startup, you can |
| use 'gdb --help'. |
| |
| 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 port of GDB uses the standard |
| name, but if it finds a 'gdb.ini' file in your home directory, it warns |
| you about that and suggests 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' |
| '!COMMAND-STRING' |
| Invoke a standard shell to execute COMMAND-STRING. Note that no |
| space is needed between '!' and 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'. |
| |
| 'pipe [COMMAND] | SHELL_COMMAND' |
| '| [COMMAND] | SHELL_COMMAND' |
| 'pipe -d DELIM COMMAND DELIM SHELL_COMMAND' |
| '| -d DELIM COMMAND DELIM SHELL_COMMAND' |
| Executes COMMAND and sends its output to SHELL_COMMAND. Note that |
| no space is needed around '|'. If no COMMAND is provided, the last |
| command executed is repeated. |
| |
| In case the COMMAND contains a '|', the option '-d DELIM' can be |
| used to specify an alternate delimiter string DELIM that separates |
| the COMMAND from the SHELL_COMMAND. |
| |
| Example: |
| (gdb) p var |
| $1 = { |
| black = 144, |
| red = 233, |
| green = 377, |
| blue = 610, |
| white = 987 |
| } |
| (gdb) pipe p var|wc |
| 7 19 80 |
| (gdb) |p var|wc -l |
| 7 |
| (gdb) p /x var |
| $4 = { |
| black = 0x90, |
| red = 0xe9, |
| green = 0x179, |
| blue = 0x262, |
| white = 0x3db |
| } |
| (gdb) ||grep red |
| red => 0xe9, |
| (gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/' |
| this contains a PIPE char |
| (gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/' |
| this contains a PIPE char! |
| (gdb) |
| |
| The convenience variables '$_shell_exitcode' and '$_shell_exitsignal' |
| can be used to examine the exit status of the last shell command |
| launched by 'shell', 'make', 'pipe' and '|'. *Note Convenience |
| Variables: Convenience Vars. |
| |
| |
| 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. |
| 'set logging debugredirect [on|off]' |
| By default, GDB debug output will go to both the terminal and the |
| logfile. Set 'debugredirect' if you want debug output to go only |
| to the log file. |
| 'show logging' |
| Show the current values of the logging settings. |
| |
| You can also redirect the output of a GDB command to a shell command. |
| *Note pipe::. |
| |
| |
| 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 |
| * Command Settings:: How to change default behavior of commands |
| * Completion:: Command completion |
| * Command Options:: Command options |
| * Help:: How to ask GDB for help |
| |
| |
| File: gdb.info, Node: Command Syntax, Next: Command Settings, 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: Command Settings, Next: Completion, Prev: Command Syntax, Up: Commands |
| |
| 3.2 Command Settings |
| ==================== |
| |
| Many commands change their behavior according to command-specific |
| variables or settings. These settings can be changed with the 'set' |
| subcommands. For example, the 'print' command (*note Examining Data: |
| Data.) prints arrays differently depending on settings changeable with |
| the commands 'set print elements NUMBER-OF-ELEMENTS' and 'set print |
| array-indexes', among others. |
| |
| You can change these settings to your preference in the gdbinit files |
| loaded at GDB startup. *Note Startup::. |
| |
| The settings can also be changed interactively during the debugging |
| session. For example, to change the limit of array elements to print, |
| you can do the following: |
| (GDB) set print elements 10 |
| (GDB) print some_array |
| $1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...} |
| |
| The above 'set print elements 10' command changes the number of |
| elements to print from the default of 200 to 10. If you only intend |
| this limit of 10 to be used for printing 'some_array', then you must |
| restore the limit back to 200, with 'set print elements 200'. |
| |
| Some commands allow overriding settings with command options. For |
| example, the 'print' command supports a number of options that allow |
| overriding relevant global print settings as set by 'set print' |
| subcommands. *Note print options::. The example above could be |
| rewritten as: |
| (GDB) print -elements 10 -- some_array |
| $1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...} |
| |
| Alternatively, you can use the 'with' command to change a setting |
| temporarily, for the duration of a command invocation. |
| |
| 'with SETTING [VALUE] [-- COMMAND]' |
| 'w SETTING [VALUE] [-- COMMAND]' |
| Temporarily set SETTING to VALUE for the duration of COMMAND. |
| |
| SETTING is any setting you can change with the 'set' subcommands. |
| VALUE is the value to assign to 'setting' while running 'command'. |
| |
| If no COMMAND is provided, the last command executed is repeated. |
| |
| If a COMMAND is provided, it must be preceded by a double dash |
| ('--') separator. This is required because some settings accept |
| free-form arguments, such as expressions or filenames. |
| |
| For example, the command |
| (GDB) with print array on -- print some_array |
| is equivalent to the following 3 commands: |
| (GDB) set print array on |
| (GDB) print some_array |
| (GDB) set print array off |
| |
| The 'with' command is particularly useful when you want to override |
| a setting while running user-defined commands, or commands defined |
| in Python or Guile. *Note Extending GDB: Extending GDB. |
| |
| (GDB) with print pretty on -- my_complex_command |
| |
| To change several settings for the same command, you can nest |
| 'with' commands. For example, 'with language ada -- with print |
| elements 10' temporarily changes the language to Ada and sets a |
| limit of 10 elements to print for arrays and strings. |
| |
| |
| File: gdb.info, Node: Completion, Next: Command Options, Prev: Command Settings, Up: Commands |
| |
| 3.3 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, command options, 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 '?'. |
| |
| If the number of possible completions is large, GDB will print as |
| much of the list as it has collected, as well as a message indicating |
| that the list may be truncated. |
| |
| (gdb) b m<TAB><TAB> |
| main |
| <... the rest of the possible completions ...> |
| *** List may be truncated, max-completions reached. *** |
| (gdb) b m |
| |
| This behavior can be controlled with the following commands: |
| |
| 'set max-completions LIMIT' |
| 'set max-completions unlimited' |
| Set the maximum number of completion candidates. GDB will stop |
| looking for more completions once it collects this many candidates. |
| This is useful when completing on things like function names as |
| collecting all the possible candidates can be time consuming. The |
| default value is 200. A value of zero disables tab-completion. |
| Note that setting either no limit or a very large limit can make |
| completion slow. |
| 'show max-completions' |
| Show the maximum number of candidates that GDB will collect and |
| show during completion. |
| |
| 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. |
| |
| A likely situation where you might need this is in typing an |
| expression that involves a C++ symbol name with template parameters. |
| This is because when completing expressions, GDB treats the '<' |
| character as word delimiter, assuming that it's the less-than comparison |
| operator (*note C and C++ Operators: C Operators.). |
| |
| For example, when you want to call a C++ template function |
| interactively using the 'print' or 'call' commands, you may need to |
| distinguish whether you mean the version of 'name' that was specialized |
| for 'int', 'name<int>()', or the version that was specialized for |
| 'float', '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) p 'func< M-? |
| func<int>() func<float>() |
| (gdb) p 'func< |
| |
| When setting breakpoints however (*note Specify Location::), you |
| don't usually need to type a quote before the function name, because GDB |
| understands that you want to set a breakpoint on a function: |
| |
| (gdb) b func< M-? |
| func<int>() func<float>() |
| (gdb) b func< |
| |
| This is true even in the case of typing the name of C++ overloaded |
| functions (multiple definitions of the same function, distinguished by |
| argument type). For example, when you want to set a breakpoint you |
| don't 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)'. |
| |
| (gdb) b bubble( M-? |
| bubble(int) bubble(double) |
| (gdb) b bubble(dou M-? |
| bubble(double) |
| |
| See *note quoting names:: for a description of other scenarios that |
| require quoting. |
| |
| 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. |
| |
| When completing in an expression which looks up a field in a |
| structure, GDB also tries(1) to limit completions to the field names |
| available in the type of the left-hand-side: |
| |
| (gdb) p gdb_stdout.M-? |
| magic to_fputs to_rewind |
| to_data to_isatty to_write |
| to_delete to_put to_write_async_safe |
| to_flush to_read |
| |
| This is because the 'gdb_stdout' is a variable of the type 'struct |
| ui_file' that is defined in GDB sources as follows: |
| |
| struct ui_file |
| { |
| int *magic; |
| ui_file_flush_ftype *to_flush; |
| ui_file_write_ftype *to_write; |
| ui_file_write_async_safe_ftype *to_write_async_safe; |
| ui_file_fputs_ftype *to_fputs; |
| ui_file_read_ftype *to_read; |
| ui_file_delete_ftype *to_delete; |
| ui_file_isatty_ftype *to_isatty; |
| ui_file_rewind_ftype *to_rewind; |
| ui_file_put_ftype *to_put; |
| void *to_data; |
| } |
| |
| ---------- Footnotes ---------- |
| |
| (1) The completer can be confused by certain kinds of invalid |
| expressions. Also, it only examines the static type of the expression, |
| not the dynamic type. |
| |
| |
| File: gdb.info, Node: Command Options, Next: Help, Prev: Completion, Up: Commands |
| |
| 3.4 Command options |
| =================== |
| |
| Some commands accept options starting with a leading dash. For example, |
| 'print -pretty'. Similarly to command names, you can abbreviate a GDB |
| option to the first few letters of the option name, if that abbreviation |
| is unambiguous, and you can also use the <TAB> key to get GDB to fill |
| out the rest of a word in an option (or to show you the alternatives |
| available, if there is more than one possibility). |
| |
| Some commands take raw input as argument. For example, the print |
| command processes arbitrary expressions in any of the languages |
| supported by GDB. With such commands, because raw input may start with |
| a leading dash that would be confused with an option or any of its |
| abbreviations, e.g. 'print -p' (short for 'print -pretty' or printing |
| negative 'p'?), if you specify any command option, then you must use a |
| double-dash ('--') delimiter to indicate the end of options. |
| |
| Some options are described as accepting an argument which can be |
| either 'on' or 'off'. These are known as "boolean options". Similarly |
| to boolean settings commands--'on' and 'off' are the typical values, but |
| any of '1', 'yes' and 'enable' can also be used as "true" value, and any |
| of '0', 'no' and 'disable' can also be used as "false" value. You can |
| also omit a "true" value, as it is implied by default. |
| |
| For example, these are equivalent: |
| |
| (gdb) print -object on -pretty off -element unlimited -- *myptr |
| (gdb) p -o -p 0 -e u -- *myptr |
| |
| You can discover the set of options some command accepts by |
| completing on '-' after the command name. For example: |
| |
| (gdb) print -<TAB><TAB> |
| -address -max-depth -raw-values -union |
| -array -null-stop -repeats -vtbl |
| -array-indexes -object -static-members |
| -elements -pretty -symbol |
| |
| Completion will in some cases guide you with a suggestion of what |
| kind of argument an option expects. For example: |
| |
| (gdb) print -elements <TAB><TAB> |
| NUMBER unlimited |
| |
| Here, the option expects a number (e.g., '100'), not literal |
| 'NUMBER'. Such metasyntactical arguments are always presented in |
| uppercase. |
| |
| (For more on using the 'print' command, see *note Examining Data: |
| Data.) |
| |
| |
| File: gdb.info, Node: Help, Prev: Command Options, Up: Commands |
| |
| 3.5 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 [-v] REGEXP' |
| 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. The optional flag '-v', which |
| stands for 'verbose', indicates to output the full documentation of |
| the matching commands and highlight the parts of the documentation |
| matching REGEXP. For example: |
| |
| apropos alias |
| |
| results in: |
| |
| alias -- Define a new command that is an alias of an existing command |
| aliases -- Aliases of other commands |
| d -- Delete some breakpoints or auto-display expressions |
| del -- Delete some breakpoints or auto-display expressions |
| delete -- Delete some breakpoints or auto-display expressions |
| |
| while |
| |
| apropos -v cut.*thread apply |
| |
| results in the below output, where 'cut for 'thread apply' is |
| highlighted if styling is enabled. |
| |
| taas -- Apply a command to all threads (ignoring errors |
| and empty output). |
| Usage: taas COMMAND |
| shortcut for 'thread apply all -s COMMAND' |
| |
| tfaas -- Apply a command to all frames of all threads |
| (ignoring errors and empty output). |
| Usage: tfaas COMMAND |
| shortcut for 'thread apply all -s frame apply all -s COMMAND' |
| |
| '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 Command, Variable, and Function Index point to all |
| the sub-commands. *Note Command and Variable 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 several 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. |
| |
| 'show configuration' |
| Display detailed information about the way GDB was configured when |
| it was built. This displays the optional arguments passed to the |
| 'configure' script and also configuration parameters detected |
| automatically by 'configure'. When reporting a GDB bug (*note GDB |
| Bugs::), it is important to include this information in your |
| report. |
| |
| |
| 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 |
| |
| * Inferiors and Programs:: Debugging multiple inferiors and programs |
| * Threads:: Debugging programs with multiple threads |
| * Forks:: Debugging forks |
| * 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, some 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. For |
| more information, see *note 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. Version 3.1 and later of GCC, the GNU C compiler, provides |
| macro information if you are using the DWARF debugging format, and |
| specify the option '-g3'. |
| |
| *Note Options for Debugging Your Program or GCC: (gcc)Debugging |
| Options, for more information on GCC options affecting debug |
| information. |
| |
| You will have the best debugging experience if you use the latest |
| version of the DWARF debugging format that your compiler supports. |
| DWARF is currently the most expressive and best supported debugging |
| format in GDB. |
| |
| |
| 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 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 some environments without processes, 'run' |
| jumps to the start of your program. Other targets, like 'remote', are |
| always running. If you get an error message like this one: |
| |
| The "remote" target does not support "run". |
| Try "help target" or "continue". |
| |
| then use 'continue' to run your program. You may need 'load' first |
| (*note load::). |
| |
| 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. If you |
| do not define 'SHELL', GDB uses the default shell ('/bin/sh'). You |
| can disable use of any shell with the 'set startup-with-shell' |
| command (see below for details). |
| |
| 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._ |
| You can set your program's working directory with the command 'set |
| cwd'. If you do not set any working directory with this command, |
| your program will inherit GDB's working directory if native |
| debugging, or the remote server's working directory if remote |
| debugging. *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, either |
| insert breakpoints in your elaboration code before running your |
| program or use the 'starti' command. |
| |
| 'starti' |
| The 'starti' command does the equivalent of setting a temporary |
| breakpoint at the first instruction of a program's execution and |
| then invoking the 'run' command. For programs containing an |
| elaboration phase, the 'starti' command will stop execution at the |
| start of the elaboration phase. |
| |
| 'set exec-wrapper WRAPPER' |
| 'show exec-wrapper' |
| 'unset exec-wrapper' |
| When 'exec-wrapper' is set, the specified wrapper is used to launch |
| programs for debugging. GDB starts your program with a shell |
| command of the form 'exec WRAPPER PROGRAM'. Quoting is added to |
| PROGRAM and its arguments, but not to WRAPPER, so you should add |
| quotes if appropriate for your shell. The wrapper runs until it |
| executes your program, and then GDB takes control. |
| |
| You can use any program that eventually calls 'execve' with its |
| arguments as a wrapper. Several standard Unix utilities do this, |
| e.g. 'env' and 'nohup'. Any Unix shell script ending with 'exec |
| "$@"' will also work. |
| |
| For example, you can use 'env' to pass an environment variable to |
| the debugged program, without setting the variable in your shell's |
| environment: |
| |
| (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' |
| (gdb) run |
| |
| This command is available when debugging locally on most targets, |
| excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino. |
| |
| 'set startup-with-shell' |
| 'set startup-with-shell on' |
| 'set startup-with-shell off' |
| 'show startup-with-shell' |
| On Unix systems, by default, if a shell is available on your |
| target, GDB) uses it to start your program. Arguments of the 'run' |
| command are passed to the shell, which does variable substitution, |
| expands wildcard characters and performs redirection of I/O. In |
| some circumstances, it may be useful to disable such use of a |
| shell, for example, when debugging the shell itself or diagnosing |
| startup failures such as: |
| |
| (gdb) run |
| Starting program: ./a.out |
| During startup program terminated with signal SIGSEGV, Segmentation fault. |
| |
| which indicates the shell or the wrapper specified with |
| 'exec-wrapper' crashed, not your program. Most often, this is |
| caused by something odd in your shell's non-interactive mode |
| initialization file--such as '.cshrc' for C-shell, $'.zshenv' for |
| the Z shell, or the file specified in the 'BASH_ENV' environment |
| variable for BASH. |
| |
| 'set auto-connect-native-target' |
| 'set auto-connect-native-target on' |
| 'set auto-connect-native-target off' |
| 'show auto-connect-native-target' |
| |
| By default, if not connected to any target yet (e.g., with 'target |
| remote'), the 'run' command starts your program as a native process |
| under GDB, on your local machine. If you're sure you don't want to |
| debug programs on your local machine, you can tell GDB to not |
| connect to the native target automatically with the 'set |
| auto-connect-native-target off' command. |
| |
| If 'on', which is the default, and if GDB is not connected to a |
| target already, the 'run' command automaticaly connects to the |
| native target, if one is available. |
| |
| If 'off', and if GDB is not connected to a target already, the |
| 'run' command fails with an error: |
| |
| (gdb) run |
| Don't know how to run. Try "help target". |
| |
| If GDB is already connected to a target, GDB always uses it with |
| the 'run' command. |
| |
| In any case, you can explicitly connect to the native target with |
| the 'target native' command. For example, |
| |
| (gdb) set auto-connect-native-target off |
| (gdb) run |
| Don't know how to run. Try "help target". |
| (gdb) target native |
| (gdb) run |
| Starting program: ./a.out |
| [Inferior 1 (process 10421) exited normally] |
| |
| In case you connected explicitly to the 'native' target, GDB |
| remains connected even if all inferiors exit, ready for the next |
| 'run' command. Use the 'disconnect' command to disconnect. |
| |
| Examples of other commands that likewise respect the |
| 'auto-connect-native-target' setting: 'attach', 'info proc', 'info |
| os'. |
| |
| 'set disable-randomization' |
| 'set disable-randomization on' |
| This option (enabled by default in GDB) will turn off the native |
| randomization of the virtual address space of the started program. |
| This option is useful for multiple debugging sessions to make the |
| execution better reproducible and memory addresses reusable across |
| debugging sessions. |
| |
| This feature is implemented only on certain targets, including |
| GNU/Linux. On GNU/Linux you can get the same behavior using |
| |
| (gdb) set exec-wrapper setarch `uname -m` -R |
| |
| 'set disable-randomization off' |
| Leave the behavior of the started executable unchanged. Some bugs |
| rear their ugly heads only when the program is loaded at certain |
| addresses. If your bug disappears when you run the program under |
| GDB, that might be because GDB by default disables the address |
| randomization on platforms, such as GNU/Linux, which do that for |
| stand-alone programs. Use 'set disable-randomization off' to try |
| to reproduce such elusive bugs. |
| |
| On targets where it is available, virtual address space |
| randomization protects the programs against certain kinds of |
| security attacks. In these cases the attacker needs to know the |
| exact location of a concrete executable code. Randomizing its |
| location makes it impossible to inject jumps misusing a code at its |
| expected addresses. |
| |
| Prelinking shared libraries provides a startup performance |
| advantage but it makes addresses in these libraries predictable for |
| privileged processes by having just unprivileged access at the |
| target system. Reading the shared library binary gives enough |
| information for assembling the malicious code misusing it. Still |
| even a prelinked shared library can get loaded at a new random |
| address just requiring the regular relocation process during the |
| startup. Shared libraries not already prelinked are always loaded |
| at a randomly chosen address. |
| |
| Position independent executables (PIE) contain position independent |
| code similar to the shared libraries and therefore such executables |
| get loaded at a randomly chosen address upon startup. PIE |
| executables always load even already prelinked shared libraries at |
| a random address. You can build such executable using 'gcc -fPIE |
| -pie'. |
| |
| Heap (malloc storage), stack and custom mmap areas are always |
| placed randomly (as long as the randomization is enabled). |
| |
| 'show disable-randomization' |
| Show the current setting of the explicit disable of the native |
| randomization of the virtual address space of the started 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 (and the shell GDB uses to launch it), not for GDB |
| itself. The 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.) |
| |
| Note that on Unix systems, GDB runs your program via a shell, which |
| also inherits the environment set with 'set environment'. If |
| necessary, you can avoid that by using the 'env' program as a |
| wrapper instead of using 'set environment'. *Note set |
| exec-wrapper::, for an example doing just that. |
| |
| Environment variables that are set by the user are also transmitted |
| to 'gdbserver' to be used when starting the remote inferior. *note |
| QEnvironmentHexEncoded::. |
| |
| '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. |
| |
| Environment variables that are unset by the user are also unset on |
| 'gdbserver' when starting the remote inferior. *note |
| QEnvironmentUnset::. |
| |
| _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 when started non-interactively--such as '.cshrc' for |
| C-shell, $'.zshenv' for the Z shell, or the file specified in the |
| 'BASH_ENV' environment variable 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', the inferior will be |
| initialized with the current working directory specified by the 'set |
| cwd' command. If no directory has been specified by this command, then |
| the inferior will inherit GDB's current working directory as its working |
| directory if native debugging, or it will inherit the remote server's |
| current working directory if remote debugging. |
| |
| 'set cwd [DIRECTORY]' |
| Set the inferior's working directory to DIRECTORY, which will be |
| 'glob'-expanded in order to resolve tildes ('~'). If no argument |
| has been specified, the command clears the setting and resets it to |
| an empty state. This setting has no effect on GDB's working |
| directory, and it only takes effect the next time you start the |
| inferior. The '~' in DIRECTORY is a short for the "home |
| directory", usually pointed to by the 'HOME' environment variable. |
| On MS-Windows, if 'HOME' is not defined, GDB uses the concatenation |
| of 'HOMEDRIVE' and 'HOMEPATH' as fallback. |
| |
| You can also change GDB's current working directory by using the |
| 'cd' command. *Note cd command::. |
| |
| 'show cwd' |
| Show the inferior's working directory. If no directory has been |
| specified by 'set cwd', then the default inferior's working |
| directory is the same as GDB's working directory. |
| |
| 'cd [DIRECTORY]' |
| Set the GDB working directory to DIRECTORY. If not given, |
| DIRECTORY uses ''~''. |
| |
| The GDB working directory serves as a default for the commands that |
| specify files for GDB to operate on. *Note Commands to Specify |
| Files: Files. *Note set cwd command::. |
| |
| '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 supports the 'info |
| proc' command (*note Process Information::), you can use the 'info proc' |
| command 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 [ TTY ]' |
| Set the tty for the program being debugged to TTY. Omitting TTY |
| restores the default behavior, which is to use the same terminal as |
| GDB. |
| |
| '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: Inferiors and Programs, 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: Inferiors and Programs, Next: Threads, Prev: Kill Process, Up: Running |
| |
| 4.9 Debugging Multiple Inferiors and Programs |
| ============================================= |
| |
| GDB lets you run and debug multiple programs in a single session. In |
| addition, GDB on some systems may let you run several programs |
| simultaneously (otherwise you have to exit from one before starting |
| another). In the most general case, you can have multiple threads of |
| execution in each of multiple processes, launched from multiple |
| executables. |
| |
| GDB represents the state of each program execution with an object |
| called an "inferior". An inferior typically corresponds to a process, |
| but is more general and applies also to targets that do not have |
| processes. Inferiors may be created before a process runs, and may be |
| retained after a process exits. Inferiors have unique identifiers that |
| are different from process ids. Usually each inferior will also have |
| its own distinct address space, although some embedded targets may have |
| several inferiors running in different parts of a single address space. |
| Each inferior may in turn have multiple threads running in it. |
| |
| To find out what inferiors exist at any moment, use 'info inferiors': |
| |
| 'info inferiors' |
| Print a list of all inferiors currently being managed by GDB. By |
| default all inferiors are printed, but the argument ID... - a space |
| separated list of inferior numbers - can be used to limit the |
| display to just the requested inferiors. |
| |
| GDB displays for each inferior (in this order): |
| |
| 1. the inferior number assigned by GDB |
| |
| 2. the target system's inferior identifier |
| |
| 3. the name of the executable the inferior is running. |
| |
| An asterisk '*' preceding the GDB inferior number indicates the |
| current inferior. |
| |
| For example, |
| |
| (gdb) info inferiors |
| Num Description Executable |
| 2 process 2307 hello |
| * 1 process 3401 goodbye |
| |
| To switch focus between inferiors, use the 'inferior' command: |
| |
| 'inferior INFNO' |
| Make inferior number INFNO the current inferior. The argument |
| INFNO is the inferior number assigned by GDB, as shown in the first |
| field of the 'info inferiors' display. |
| |
| The debugger convenience variable '$_inferior' contains the number of |
| the current inferior. You may find this useful in writing breakpoint |
| conditional expressions, command scripts, and so forth. *Note |
| Convenience Variables: Convenience Vars, for general information on |
| convenience variables. |
| |
| You can get multiple executables into a debugging session via the |
| 'add-inferior' and 'clone-inferior' commands. On some systems GDB can |
| add inferiors to the debug session automatically by following calls to |
| 'fork' and 'exec'. To remove inferiors from the debugging session use |
| the 'remove-inferiors' command. |
| |
| 'add-inferior [ -copies N ] [ -exec EXECUTABLE ]' |
| Adds N inferiors to be run using EXECUTABLE as the executable; N |
| defaults to 1. If no executable is specified, the inferiors begins |
| empty, with no program. You can still assign or change the program |
| assigned to the inferior at any time by using the 'file' command |
| with the executable name as its argument. |
| |
| 'clone-inferior [ -copies N ] [ INFNO ]' |
| Adds N inferiors ready to execute the same program as inferior |
| INFNO; N defaults to 1, and INFNO defaults to the number of the |
| current inferior. This is a convenient command when you want to |
| run another instance of the inferior you are debugging. |
| |
| (gdb) info inferiors |
| Num Description Executable |
| * 1 process 29964 helloworld |
| (gdb) clone-inferior |
| Added inferior 2. |
| 1 inferiors added. |
| (gdb) info inferiors |
| Num Description Executable |
| 2 <null> helloworld |
| * 1 process 29964 helloworld |
| |
| You can now simply switch focus to inferior 2 and run it. |
| |
| 'remove-inferiors INFNO...' |
| Removes the inferior or inferiors INFNO.... It is not possible to |
| remove an inferior that is running with this command. For those, |
| use the 'kill' or 'detach' command first. |
| |
| To quit debugging one of the running inferiors that is not the |
| current inferior, you can either detach from it by using the |
| 'detach inferior' command (allowing it to run independently), or kill it |
| using the 'kill inferiors' command: |
| |
| 'detach inferior INFNO...' |
| Detach from the inferior or inferiors identified by GDB inferior |
| number(s) INFNO.... Note that the inferior's entry still stays on |
| the list of inferiors shown by 'info inferiors', but its |
| Description will show '<null>'. |
| |
| 'kill inferiors INFNO...' |
| Kill the inferior or inferiors identified by GDB inferior number(s) |
| INFNO.... Note that the inferior's entry still stays on the list |
| of inferiors shown by 'info inferiors', but its Description will |
| show '<null>'. |
| |
| After the successful completion of a command such as 'detach', |
| 'detach inferiors', 'kill' or 'kill inferiors', or after a normal |
| process exit, the inferior is still valid and listed with 'info |
| inferiors', ready to be restarted. |
| |
| To be notified when inferiors are started or exit under GDB's control |
| use 'set print inferior-events': |
| |
| 'set print inferior-events' |
| 'set print inferior-events on' |
| 'set print inferior-events off' |
| The 'set print inferior-events' command allows you to enable or |
| disable printing of messages when GDB notices that new inferiors |
| have started or that inferiors have exited or have been detached. |
| By default, these messages will not be printed. |
| |
| 'show print inferior-events' |
| Show whether messages will be printed when GDB detects that |
| inferiors have started, exited or have been detached. |
| |
| Many commands will work the same with multiple programs as with a |
| single program: e.g., 'print myglobal' will simply display the value of |
| 'myglobal' in the current inferior. |
| |
| Occasionally, when debugging GDB itself, it may be useful to get more |
| info about the relationship of inferiors, programs, address spaces in a |
| debug session. You can do that with the 'maint info program-spaces' |
| command. |
| |
| 'maint info program-spaces' |
| Print a list of all program spaces currently being managed by GDB. |
| |
| GDB displays for each program space (in this order): |
| |
| 1. the program space number assigned by GDB |
| |
| 2. the name of the executable loaded into the program space, with |
| e.g., the 'file' command. |
| |
| An asterisk '*' preceding the GDB program space number indicates |
| the current program space. |
| |
| In addition, below each program space line, GDB prints extra |
| information that isn't suitable to display in tabular form. For |
| example, the list of inferiors bound to the program space. |
| |
| (gdb) maint info program-spaces |
| Id Executable |
| * 1 hello |
| 2 goodbye |
| Bound inferiors: ID 1 (process 21561) |
| |
| Here we can see that no inferior is running the program 'hello', |
| while 'process 21561' is running the program 'goodbye'. On some |
| targets, it is possible that multiple inferiors are bound to the |
| same program space. The most common example is that of debugging |
| both the parent and child processes of a 'vfork' call. For |
| example, |
| |
| (gdb) maint info program-spaces |
| Id Executable |
| * 1 vfork-test |
| Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) |
| |
| Here, both inferior 2 and inferior 1 are running in the same |
| program space as a result of inferior 1 having executed a 'vfork' |
| call. |
| |
| |
| File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors and Programs, Up: Running |
| |
| 4.10 Debugging Programs with Multiple Threads |
| ============================================= |
| |
| In some operating systems, such as GNU/Linux 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 THREAD-ID', a command to switch among threads |
| * 'info threads', a command to inquire about existing threads |
| * 'thread apply [THREAD-ID-LIST | 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. |
| * 'set libthread-db-search-path PATH', which lets the user specify |
| which 'libthread_db' to use if the default choice isn't compatible |
| with the program. |
| |
| 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]', where SYSTAG is a thread identifier whose form varies |
| depending on the particular system. For example, on GNU/Linux, you |
| might see |
| |
| [New Thread 0x41e02940 (LWP 25582)] |
| |
| when GDB notices a new thread. In contrast, on other systems, 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 of an inferior. This number is |
| unique between all threads of an inferior, but not unique between |
| threads of different inferiors. |
| |
| You can refer to a given thread in an inferior using the qualified |
| INFERIOR-NUM.THREAD-NUM syntax, also known as "qualified thread ID", |
| with INFERIOR-NUM being the inferior number and THREAD-NUM being the |
| thread number of the given inferior. For example, thread '2.3' refers |
| to thread number 3 of inferior 2. If you omit INFERIOR-NUM (e.g., |
| 'thread 3'), then GDB infers you're referring to a thread of the current |
| inferior. |
| |
| Until you create a second inferior, GDB does not show the |
| INFERIOR-NUM part of thread IDs, even though you can always use the full |
| INFERIOR-NUM.THREAD-NUM form to refer to threads of inferior 1, the |
| initial inferior. |
| |
| Some commands accept a space-separated "thread ID list" as argument. |
| A list element can be: |
| |
| 1. A thread ID as shown in the first field of the 'info threads' |
| display, with or without an inferior qualifier. E.g., '2.1' or |
| '1'. |
| |
| 2. A range of thread numbers, again with or without an inferior |
| qualifier, as in INF.THR1-THR2 or THR1-THR2. E.g., '1.2-4' or |
| '2-4'. |
| |
| 3. All threads of an inferior, specified with a star wildcard, with or |
| without an inferior qualifier, as in INF.'*' (e.g., '1.*') or '*'. |
| The former refers to all threads of the given inferior, and the |
| latter form without an inferior qualifier refers to all threads of |
| the current inferior. |
| |
| For example, if the current inferior is 1, and inferior 7 has one |
| thread with ID 7.1, the thread list '1 2-3 4.5 6.7-9 7.*' includes |
| threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads 7 to 9 of |
| inferior 6 and all threads of inferior 7. That is, in expanded |
| qualified form, the same as '1.1 1.2 1.3 4.5 6.7 6.8 6.9 7.1'. |
| |
| In addition to a _per-inferior_ number, each thread is also assigned |
| a unique _global_ number, also known as "global thread ID", a single |
| integer. Unlike the thread number component of the thread ID, no two |
| threads have the same global ID, even when you're debugging multiple |
| inferiors. |
| |
| From GDB's perspective, a process always has at least one thread. In |
| other words, GDB assigns a thread number to the program's "main thread" |
| even if the program is not multi-threaded. |
| |
| The debugger convenience variables '$_thread' and '$_gthread' |
| contain, respectively, the per-inferior thread number and the global |
| thread number of the current thread. You may find this useful in |
| writing breakpoint conditional expressions, command scripts, and so |
| forth. *Note Convenience Variables: Convenience Vars, for general |
| information on convenience variables. |
| |
| If GDB detects the program is multi-threaded, it augments the usual |
| message about stopping at a breakpoint with the ID and name of the |
| thread that hit the breakpoint. |
| |
| Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68 |
| |
| Likewise when the program receives a signal: |
| |
| Thread 1 "main" received signal SIGINT, Interrupt. |
| |
| 'info threads [THREAD-ID-LIST]' |
| |
| Display information about one or more threads. With no arguments |
| displays information about all threads. You can specify the list |
| of threads that you want to display using the thread ID list syntax |
| (*note thread ID lists::). |
| |
| GDB displays for each thread (in this order): |
| |
| 1. the per-inferior thread number assigned by GDB |
| |
| 2. the global thread number assigned by GDB, if the '-gid' option |
| was specified |
| |
| 3. the target system's thread identifier (SYSTAG) |
| |
| 4. the thread's name, if one is known. A thread can either be |
| named by the user (see 'thread name', below), or, in some |
| cases, by the program itself. |
| |
| 5. 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 |
| Id Target Id Frame |
| * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) |
| 2 process 35 thread 23 0x34e5 in sigpause () |
| 3 process 35 thread 27 0x34e5 in sigpause () |
| at threadtest.c:68 |
| |
| If you're debugging multiple inferiors, GDB displays thread IDs using |
| the qualified INFERIOR-NUM.THREAD-NUM format. Otherwise, only |
| THREAD-NUM is shown. |
| |
| If you specify the '-gid' option, GDB displays a column indicating |
| each thread's global thread ID: |
| |
| (gdb) info threads |
| Id GId Target Id Frame |
| 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) |
| 1.2 3 process 35 thread 23 0x34e5 in sigpause () |
| 1.3 4 process 35 thread 27 0x34e5 in sigpause () |
| * 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8) |
| |
| 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 THREAD-ID' |
| Make thread ID THREAD-ID the current thread. The command argument |
| THREAD-ID is the GDB thread ID, as shown in the first field of the |
| 'info threads' display, with or without an inferior qualifier |
| (e.g., '2.1' or '1'). |
| |
| GDB responds by displaying the system identifier of the thread you |
| selected, and its current stack frame summary: |
| |
| (gdb) thread 2 |
| [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] |
| #0 some_function (ignore=0x0) at example.c:8 |
| 8 printf ("hello\n"); |
| |
| As with the '[New ...]' message, the form of the text after |
| 'Switching to' depends on your system's conventions for identifying |
| threads. |
| |
| 'thread apply [THREAD-ID-LIST | all [-ascending]] [FLAG]... COMMAND' |
| The 'thread apply' command allows you to apply the named COMMAND to |
| one or more threads. Specify the threads that you want affected |
| using the thread ID list syntax (*note thread ID lists::), or |
| specify 'all' to apply to all threads. To apply a command to all |
| threads in descending order, type 'thread apply all COMMAND'. To |
| apply a command to all threads in ascending order, type 'thread |
| apply all -ascending COMMAND'. |
| |
| The FLAG arguments control what output to produce and how to handle |
| errors raised when applying COMMAND to a thread. FLAG must start |
| with a '-' directly followed by one letter in 'qcs'. If several |
| flags are provided, they must be given individually, such as '-c |
| -q'. |
| |
| By default, GDB displays some thread information before the output |
| produced by COMMAND, and an error raised during the execution of a |
| COMMAND will abort 'thread apply'. The following flags can be used |
| to fine-tune this behavior: |
| |
| '-c' |
| The flag '-c', which stands for 'continue', causes any errors |
| in COMMAND to be displayed, and the execution of 'thread |
| apply' then continues. |
| '-s' |
| The flag '-s', which stands for 'silent', causes any errors or |
| empty output produced by a COMMAND to be silently ignored. |
| That is, the execution continues, but the thread information |
| and errors are not printed. |
| '-q' |
| The flag '-q' ('quiet') disables printing the thread |
| information. |
| |
| Flags '-c' and '-s' cannot be used together. |
| |
| 'taas [OPTION]... COMMAND' |
| Shortcut for 'thread apply all -s [OPTION]... COMMAND'. Applies |
| COMMAND on all threads, ignoring errors and empty output. |
| |
| The 'taas' command accepts the same options as the 'thread apply |
| all' command. *Note thread apply all::. |
| |
| 'tfaas [OPTION]... COMMAND' |
| Shortcut for 'thread apply all -s -- frame apply all -s [OPTION]... |
| COMMAND'. Applies COMMAND on all frames of all threads, ignoring |
| errors and empty output. Note that the flag '-s' is specified |
| twice: The first '-s' ensures that 'thread apply' only shows the |
| thread information of the threads for which 'frame apply' produces |
| some output. The second '-s' is needed to ensure that 'frame |
| apply' shows the frame information of a frame only if the COMMAND |
| successfully produced some output. |
| |
| It can for example be used to print a local variable or a function |
| argument without knowing the thread or frame where this variable or |
| argument is, using: |
| (gdb) tfaas p some_local_var_i_do_not_remember_where_it_is |
| |
| The 'tfaas' command accepts the same options as the 'frame apply' |
| command. *Note frame apply::. |
| |
| 'thread name [NAME]' |
| This command assigns a name to the current thread. If no argument |
| is given, any existing user-specified name is removed. The thread |
| name appears in the 'info threads' display. |
| |
| On some systems, such as GNU/Linux, GDB is able to determine the |
| name of the thread as given by the OS. On these systems, a name |
| specified with 'thread name' will override the system-give name, |
| and removing the user-specified name will cause GDB to once again |
| display the system-specified name. |
| |
| 'thread find [REGEXP]' |
| Search for and display thread ids whose name or SYSTAG matches the |
| supplied regular expression. |
| |
| As well as being the complement to the 'thread name' command, this |
| command also allows you to identify a thread by its target SYSTAG. |
| For instance, on GNU/Linux, the target SYSTAG is the LWP id. |
| |
| (GDB) thread find 26688 |
| Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' |
| (GDB) info thread 4 |
| Id Target Id Frame |
| 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () |
| |
| '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. |
| |
| *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. |
| |
| 'set libthread-db-search-path [PATH]' |
| If this variable is set, PATH is a colon-separated list of |
| directories GDB will use to search for 'libthread_db'. If you omit |
| PATH, 'libthread-db-search-path' will be reset to its default value |
| ('$sdir:$pdir' on GNU/Linux and Solaris systems). Internally, the |
| default value comes from the 'LIBTHREAD_DB_SEARCH_PATH' macro. |
| |
| On GNU/Linux and Solaris systems, GDB uses a "helper" |
| 'libthread_db' library to obtain information about threads in the |
| inferior process. GDB will use 'libthread-db-search-path' to find |
| 'libthread_db'. GDB also consults first if inferior specific |
| thread debugging library loading is enabled by 'set auto-load |
| libthread-db' (*note libthread_db.so.1 file::). |
| |
| A special entry '$sdir' for 'libthread-db-search-path' refers to |
| the default system directories that are normally searched for |
| loading shared libraries. The '$sdir' entry is the only kind not |
| needing to be enabled by 'set auto-load libthread-db' (*note |
| libthread_db.so.1 file::). |
| |
| A special entry '$pdir' for 'libthread-db-search-path' refers to |
| the directory from which 'libpthread' was loaded in the inferior |
| process. |
| |
| For any 'libthread_db' library GDB finds in above directories, GDB |
| attempts to initialize it with the current inferior process. If |
| this initialization fails (which could happen because of a version |
| mismatch between 'libthread_db' and 'libpthread'), GDB will unload |
| 'libthread_db', and continue with the next directory. If none of |
| 'libthread_db' libraries initialize successfully, GDB will issue a |
| warning and thread debugging will be disabled. |
| |
| Setting 'libthread-db-search-path' is currently implemented only on |
| some platforms. |
| |
| 'show libthread-db-search-path' |
| Display current libthread_db search path. |
| |
| 'set debug libthread-db' |
| 'show debug libthread-db' |
| Turns on or off display of 'libthread_db'-related events. Use '1' |
| to enable, '0' to disable. |
| |
| |
| File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running |
| |
| 4.11 Debugging Forks |
| ==================== |
| |
| 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. On |
| GNU/Linux platforms, this feature is supported with kernel version |
| 2.5.46 and later. |
| |
| The fork debugging commands are supported in native mode and when |
| connected to 'gdbserver' in either 'target remote' mode or 'target |
| extended-remote' mode. |
| |
| 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 inferiors' command, and switch from one fork to another by using |
| the 'inferior' command (*note Debugging Multiple Inferiors and Programs: |
| Inferiors and Programs.). |
| |
| To quit debugging one of the forked processes, you can either detach |
| from it by using the 'detach inferiors' command (allowing it to run |
| independently), or kill it using the 'kill inferiors' command. *Note |
| Debugging Multiple Inferiors and Programs: Inferiors and Programs. |
| |
| 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'. |
| |
| On some systems, 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. By default, |
| after an 'exec' call executes, GDB discards the symbols of the previous |
| executable image. You can change this behaviour with the |
| 'set follow-exec-mode' command. |
| |
| 'set follow-exec-mode MODE' |
| |
| Set debugger response to a program call of 'exec'. An 'exec' call |
| replaces the program image of a process. |
| |
| 'follow-exec-mode' can be: |
| |
| 'new' |
| GDB creates a new inferior and rebinds the process to this new |
| inferior. The program the process was running before the |
| 'exec' call can be restarted afterwards by restarting the |
| original inferior. |
| |
| For example: |
| |
| (gdb) info inferiors |
| (gdb) info inferior |
| Id Description Executable |
| * 1 <null> prog1 |
| (gdb) run |
| process 12020 is executing new program: prog2 |
| Program exited normally. |
| (gdb) info inferiors |
| Id Description Executable |
| 1 <null> prog1 |
| * 2 <null> prog2 |
| |
| 'same' |
| GDB keeps the process bound to the same inferior. The new |
| executable image replaces the previous executable loaded in |
| the inferior. Restarting the inferior after the 'exec' call, |
| with e.g., the 'run' command, restarts the executable the |
| process was running after the 'exec' call. This is the |
| default mode. |
| |
| For example: |
| |
| (gdb) info inferiors |
| Id Description Executable |
| * 1 <null> prog1 |
| (gdb) run |
| process 12020 is executing new program: prog2 |
| Program exited normally. |
| (gdb) info inferiors |
| Id Description Executable |
| * 1 <null> prog2 |
| |
| 'follow-exec-mode' is supported in native mode and 'target |
| extended-remote' mode. |
| |
| 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: Forks, Up: Running |
| |
| 4.12 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.12.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: Reverse Execution, 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 |
| * Skipping Over Functions and Files:: |
| Skipping over functions and files |
| * 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. |
| |
| 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 space-separated list of breakpoints on |
| which to operate. A list element can be either a single breakpoint |
| number, like '5', or a range of such numbers, like '5-7'. When a |
| breakpoint list is given to a command, all breakpoints in that list 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 |
| * Dynamic Printf:: Dynamic printf |
| * Save Breakpoints:: How to save breakpoints in a file |
| * Static Probe Points:: Listing static probe points |
| * 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 Ambiguous Expressions: Ambiguous |
| Expressions, for a discussion of that situation. |
| |
| It is also possible to insert a breakpoint that will stop the |
| program only if a specific thread (*note Thread-Specific |
| Breakpoints::) or a specific task (*note Ada Tasks::) hits that |
| breakpoint. |
| |
| '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. The 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. The 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. The |
| 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. |
| |
| In programs using different languages, GDB chooses the syntax to |
| print the list of all breakpoints it sets according to the 'set |
| language' value: using 'set language auto' (see *note Set Language |
| Automatically: Automatically.) means to use the language of the |
| breakpoint's function, other values mean to use the manually |
| specified language (see *note Set Language Manually: Manually.). |
| |
| 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 . |
| |
| 'rbreak FILE:REGEX' |
| If 'rbreak' is called with a filename qualification, it limits the |
| search for functions matching the given regular expression to the |
| specified FILE. This can be used, for example, to set breakpoints |
| on every function in a given file: |
| |
| (gdb) rbreak file.c:. |
| |
| The colon separating the filename qualifier from the regex may |
| optionally be surrounded by spaces. |
| |
| 'info breakpoints [LIST...]' |
| 'info break [LIST...]' |
| Print a table of all breakpoints, watchpoints, and catchpoints set |
| and not deleted. Optional argument N means print information only |
| about the specified breakpoint(s) (or watchpoint(s) or |
| catchpoint(s)). 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, there are two evaluation modes: |
| "host" and "target". If mode is "host", breakpoint condition |
| evaluation is done by GDB on the host's side. If it is "target", |
| then the condition is evaluated by the target. The 'info break' |
| command shows the condition on the line following the affected |
| breakpoint, together with its condition evaluation mode in between |
| parentheses. |
| |
| 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. |
| |
| For a breakpoints with an enable count (xref) greater than 1, 'info |
| break' also displays that count. |
| |
| 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: |
| |
| * Multiple functions in the program may have the same name. |
| |
| * 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 |
| |
| You cannot delete the individual locations from a breakpoint. |
| However, each location can be individually enabled or disabled by |
| passing BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the 'enable' |
| and 'disable' commands. It's also possible to 'enable' and 'disable' a |
| range of LOCATION-NUMBER locations using a BREAKPOINT-NUMBER and two |
| LOCATION-NUMBERs, in increasing order, separated by a hyphen, like |
| 'BREAKPOINT-NUMBER.LOCATION-NUMBER1-LOCATION-NUMBER2', in which case GDB |
| acts on all the locations in the range (inclusive). 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 normally implements breakpoints by replacing the program code at |
| the breakpoint address with a special instruction, which, when executed, |
| given control to the debugger. By default, the program code is so |
| modified only when the program is resumed. As soon as the program |
| stops, GDB restores the original instructions. This behaviour guards |
| against leaving breakpoints inserted in the target should gdb abrubptly |
| disconnect. However, with slow remote targets, inserting and removing |
| breakpoint can reduce the performance. This behavior can be controlled |
| with the following commands:: |
| |
| 'set breakpoint always-inserted off' |
| All breakpoints, including newly added by the user, are inserted in |
| the target only when the target is resumed. All breakpoints are |
| removed from the target when it stops. This is the default mode. |
| |
| 'set breakpoint always-inserted on' |
| Causes all breakpoints to be inserted in the target at all times. |
| If the user adds a new breakpoint, or changes an existing |
| breakpoint, the breakpoints in the target are updated immediately. |
| A breakpoint is removed from the target only when breakpoint itself |
| is deleted. |
| |
| GDB handles conditional breakpoints by evaluating these conditions |
| when a breakpoint breaks. If the condition is true, then the process |
| being debugged stops, otherwise the process is resumed. |
| |
| If the target supports evaluating conditions on its end, GDB may |
| download the breakpoint, together with its conditions, to it. |
| |
| This feature can be controlled via the following commands: |
| |
| 'set breakpoint condition-evaluation host' |
| This option commands GDB to evaluate the breakpoint conditions on |
| the host's side. Unconditional breakpoints are sent to the target |
| which in turn receives the triggers and reports them back to GDB |
| for condition evaluation. This is the standard evaluation mode. |
| |
| 'set breakpoint condition-evaluation target' |
| This option commands GDB to download breakpoint conditions to the |
| target at the moment of their insertion. The target is responsible |
| for evaluating the conditional expression and reporting breakpoint |
| stop events back to GDB whenever the condition is true. Due to |
| limitations of target-side evaluation, some conditions cannot be |
| evaluated there, e.g., conditions that depend on local data that is |
| only known to the host. Examples include conditional expressions |
| involving convenience variables, complex types that cannot be |
| handled by the agent expression parser and expressions that are too |
| long to be sent over to the target, specially when the target is a |
| remote system. In these cases, the conditions will be evaluated by |
| GDB. |
| |
| 'set breakpoint condition-evaluation auto' |
| This is the default mode. If the target supports evaluating |
| breakpoint conditions on its end, GDB will download breakpoint |
| conditions to the target (limitations mentioned previously apply). |
| If the target does not support breakpoint condition evaluation, |
| then GDB will fallback to evaluating all these conditions on the |
| host's side. |
| |
| 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::). |
| |
| You can set a watchpoint on an expression even if the expression can |
| not be evaluated yet. For instance, you can set a watchpoint on |
| '*global_ptr' before 'global_ptr' is initialized. GDB will stop when |
| your program sets 'global_ptr' and the expression produces a valid |
| value. If the expression becomes valid in some other way than changing |
| a variable (e.g. if the memory pointed to by '*global_ptr' becomes |
| readable as the result of a 'malloc' call), GDB may not stop until the |
| next time the expression changes. |
| |
| 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 most PowerPC or x86-based targets, GDB |
| includes support for hardware watchpoints, which do not slow down the |
| running of your program. |
| |
| 'watch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]' |
| 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 THREAD-ID]' argument, GDB breaks |
| only when the thread identified by THREAD-ID 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. |
| |
| Ordinarily a watchpoint respects the scope of variables in EXPR |
| (see below). The '-location' argument tells GDB to instead watch |
| the memory referred to by EXPR. In this case, GDB will evaluate |
| EXPR, take the address of the result, and watch the memory at that |
| address. The type of the result is used to determine the size of |
| the watched memory. If the expression's result does not have an |
| address, then GDB will print an error. |
| |
| The '[mask MASKVALUE]' argument allows creation of masked |
| watchpoints, if the current architecture supports this feature |
| (e.g., PowerPC Embedded architecture, see *note PowerPC |
| Embedded::.) A "masked watchpoint" specifies a mask in addition to |
| an address to watch. The mask specifies that some bits of an |
| address (the bits which are reset in the mask) should be ignored |
| when matching the address accessed by the inferior against the |
| watchpoint address. Thus, a masked watchpoint watches many |
| addresses simultaneously--those addresses whose unmasked bits are |
| identical to the unmasked bits in the watchpoint address. The |
| 'mask' argument implies '-location'. Examples: |
| |
| (gdb) watch foo mask 0xffff00ff |
| (gdb) watch *0xdeadbeef mask 0xffffff00 |
| |
| 'rwatch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]' |
| Set a watchpoint that will break when the value of EXPR is read by |
| the program. |
| |
| 'awatch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]' |
| Set a watchpoint that will break when EXPR is either read from or |
| written into by the program. |
| |
| 'info watchpoints [LIST...]' |
| This command prints a list of watchpoints, using the same format as |
| 'info break' (*note Set Breaks::). |
| |
| If you watch for a change in a numerically entered address you need |
| to dereference it, as the address itself is just a constant number which |
| will never change. GDB refuses to create a watchpoint that watches a |
| never-changing value: |
| |
| (gdb) watch 0x600850 |
| Cannot watch constant value 0x600850. |
| (gdb) watch *(int *) 0x600850 |
| Watchpoint 1: *(int *) 6293584 |
| |
| 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. |
| |
| 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. The EVENT can be any of the following: |
| |
| 'throw [REGEXP]' |
| 'rethrow [REGEXP]' |
| 'catch [REGEXP]' |
| The throwing, re-throwing, or catching of a C++ exception. |
| |
| If REGEXP is given, then only exceptions whose type matches |
| the regular expression will be caught. |
| |
| The convenience variable '$_exception' is available at an |
| exception-related catchpoint, on some systems. This holds the |
| exception being thrown. |
| |
| There are currently some limitations to C++ exception handling |
| in GDB: |
| |
| * The support for these commands is system-dependent. |
| Currently, only systems using the 'gnu-v3' C++ ABI (*note |
| ABI::) are supported. |
| |
| * The regular expression feature and the '$_exception' |
| convenience variable rely on the presence of some SDT |
| probes in 'libstdc++'. If these probes are not present, |
| then these features cannot be used. These probes were |
| first available in the GCC 4.8 release, but whether or |
| not they are available in your GCC also depends on how it |
| was built. |
| |
| * The '$_exception' convenience variable is only valid at |
| the instruction at which an exception-related catchpoint |
| is set. |
| |
| * When an exception-related catchpoint is hit, GDB stops at |
| a location in the system library which implements runtime |
| exception support for C++, usually 'libstdc++'. You can |
| use 'up' (*note Selection::) to get to your code. |
| |
| * 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. *Note Calling::, for information on controlling |
| this with 'set unwind-on-terminating-exception'. |
| |
| * You cannot raise an exception interactively. |
| |
| * You cannot install an exception handler interactively. |
| |
| 'exception [NAME]' |
| 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. |
| |
| When inserting an exception catchpoint on a user-defined |
| exception whose name is identical to one of the exceptions |
| defined by the language, the fully qualified name must be used |
| as the exception name. Otherwise, GDB will assume that it |
| should stop on the pre-defined exception rather than the |
| user-defined one. For instance, assuming an exception called |
| 'Constraint_Error' is defined in package 'Pck', then the |
| command to use to catch such exceptions is 'catch exception |
| Pck.Constraint_Error'. |
| |
| The convenience variable '$_ada_exception' holds the address |
| of the exception being thrown. This can be useful when |
| setting a condition for such a catchpoint. |
| |
| 'exception unhandled' |
| An exception that was raised but is not handled by the |
| program. The convenience variable '$_ada_exception' is set as |
| for 'catch exception'. |
| |
| 'handlers [NAME]' |
| An Ada exception being handled. If an exception name is |
| specified at the end of the command (eg 'catch handlers |
| Program_Error'), the debugger will stop only when this |
| specific exception is handled. Otherwise, the debugger stops |
| execution when any Ada exception is handled. |
| |
| When inserting a handlers catchpoint on a user-defined |
| exception whose name is identical to one of the exceptions |
| defined by the language, the fully qualified name must be used |
| as the exception name. Otherwise, GDB will assume that it |
| should stop on the pre-defined exception rather than the |
| user-defined one. For instance, assuming an exception called |
| 'Constraint_Error' is defined in package 'Pck', then the |
| command to use to catch such exceptions handling is 'catch |
| handlers Pck.Constraint_Error'. |
| |
| The convenience variable '$_ada_exception' is set as for |
| 'catch exception'. |
| |
| 'assert' |
| A failed Ada assertion. Note that the convenience variable |
| '$_ada_exception' is _not_ set by this catchpoint. |
| |
| 'exec' |
| A call to 'exec'. |
| |
| 'syscall' |
| 'syscall [NAME | NUMBER | group:GROUPNAME | g:GROUPNAME] ...' |
| A call to or return from a system call, a.k.a. "syscall". A |
| syscall is a mechanism for application programs to request a |
| service from the operating system (OS) or one of the OS system |
| services. GDB can catch some or all of the syscalls issued by |
| the debuggee, and show the related information for each |
| syscall. If no argument is specified, calls to and returns |
| from all system calls will be caught. |
| |
| NAME can be any system call name that is valid for the |
| underlying OS. Just what syscalls are valid depends on the OS. |
| On GNU and Unix systems, you can find the full list of valid |
| syscall names on '/usr/include/asm/unistd.h'. |
| |
| Normally, GDB knows in advance which syscalls are valid for |
| each OS, so you can use the GDB command-line completion |
| facilities (*note command completion: Completion.) to list the |
| available choices. |
| |
| You may also specify the system call numerically. A syscall's |
| number is the value passed to the OS's syscall dispatcher to |
| identify the requested service. When you specify the syscall |
| by its name, GDB uses its database of syscalls to convert the |
| name into the corresponding numeric code, but using the number |
| directly may be useful if GDB's database does not have the |
| complete list of syscalls on your system (e.g., because GDB |
| lags behind the OS upgrades). |
| |
| You may specify a group of related syscalls to be caught at |
| once using the 'group:' syntax ('g:' is a shorter equivalent). |
| For instance, on some platforms GDB allows you to catch all |
| network related syscalls, by passing the argument |
| 'group:network' to 'catch syscall'. Note that not all syscall |
| groups are available in every system. You can use the command |
| completion facilities (*note command completion: Completion.) |
| to list the syscall groups available on your environment. |
| |
| The example below illustrates how this command works if you |
| don't provide arguments to it: |
| |
| (gdb) catch syscall |
| Catchpoint 1 (syscall) |
| (gdb) r |
| Starting program: /tmp/catch-syscall |
| |
| Catchpoint 1 (call to syscall 'close'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) c |
| Continuing. |
| |
| Catchpoint 1 (returned from syscall 'close'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) |
| |
| Here is an example of catching a system call by name: |
| |
| (gdb) catch syscall chroot |
| Catchpoint 1 (syscall 'chroot' [61]) |
| (gdb) r |
| Starting program: /tmp/catch-syscall |
| |
| Catchpoint 1 (call to syscall 'chroot'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) c |
| Continuing. |
| |
| Catchpoint 1 (returned from syscall 'chroot'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) |
| |
| An example of specifying a system call numerically. In the |
| case below, the syscall number has a corresponding entry in |
| the XML file, so GDB finds its name and prints it: |
| |
| (gdb) catch syscall 252 |
| Catchpoint 1 (syscall(s) 'exit_group') |
| (gdb) r |
| Starting program: /tmp/catch-syscall |
| |
| Catchpoint 1 (call to syscall 'exit_group'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) c |
| Continuing. |
| |
| Program exited normally. |
| (gdb) |
| |
| Here is an example of catching a syscall group: |
| |
| (gdb) catch syscall group:process |
| Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7] |
| 'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190] |
| 'exit_group' [252] 'waitid' [284] 'unshare' [310]) |
| (gdb) r |
| Starting program: /tmp/catch-syscall |
| |
| Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 () |
| from /lib64/ld-linux-x86-64.so.2 |
| |
| (gdb) c |
| Continuing. |
| |
| However, there can be situations when there is no |
| corresponding name in XML file for that syscall number. In |
| this case, GDB prints a warning message saying that it was not |
| able to find the syscall name, but the catchpoint will be set |
| anyway. See the example below: |
| |
| (gdb) catch syscall 764 |
| warning: The number '764' does not represent a known syscall. |
| Catchpoint 2 (syscall 764) |
| (gdb) |
| |
| If you configure GDB using the '--without-expat' option, it |
| will not be able to display syscall names. Also, if your |
| architecture does not have an XML file describing its system |
| calls, you will not be able to see the syscall names. It is |
| important to notice that these two features are used for |
| accessing the syscall name database. In either case, you will |
| see a warning like this: |
| |
| (gdb) catch syscall |
| warning: Could not open "syscalls/i386-linux.xml" |
| warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. |
| GDB will not be able to display syscall names. |
| Catchpoint 1 (syscall) |
| (gdb) |
| |
| Of course, the file name will change depending on your |
| architecture and system. |
| |
| Still using the example above, you can also try to catch a |
| syscall by its number. In this case, you would see something |
| like: |
| |
| (gdb) catch syscall 252 |
| Catchpoint 1 (syscall(s) 252) |
| |
| Again, in this case GDB would not be able to display syscall's |
| names. |
| |
| 'fork' |
| A call to 'fork'. |
| |
| 'vfork' |
| A call to 'vfork'. |
| |
| 'load [REGEXP]' |
| 'unload [REGEXP]' |
| The loading or unloading of a shared library. If REGEXP is |
| given, then the catchpoint will stop only if the regular |
| expression matches one of the affected libraries. |
| |
| 'signal [SIGNAL... | 'all']' |
| The delivery of a signal. |
| |
| With no arguments, this catchpoint will catch any signal that |
| is not used internally by GDB, specifically, all signals |
| except 'SIGTRAP' and 'SIGINT'. |
| |
| With the argument 'all', all signals, including those used by |
| GDB, will be caught. This argument cannot be used with other |
| signal names. |
| |
| Otherwise, the arguments are a list of signal names as given |
| to 'handle' (*note Signals::). Only signals specified in this |
| list will be caught. |
| |
| One reason that 'catch signal' can be more useful than |
| 'handle' is that you can attach commands and conditions to the |
| catchpoint. |
| |
| When a signal is caught by a catchpoint, the signal's 'stop' |
| and 'print' settings, as specified by 'handle', are ignored. |
| However, whether the signal is still delivered to the inferior |
| depends on the 'pass' setting; this can be changed in the |
| catchpoint's commands. |
| |
| '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. |
| |
| |
| 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] [LIST...]' |
| Delete the breakpoints, watchpoints, or catchpoints of the |
| breakpoint list specified as argument. 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' to print a list of |
| all 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 several |
| 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 a count. The breakpoint stops your program for the |
| next N times, 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] [LIST...]' |
| 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] [LIST...]' |
| Enable the specified breakpoints (or all defined breakpoints). |
| They become effective once again in stopping your program. |
| |
| 'enable [breakpoints] once LIST...' |
| Enable the specified breakpoints temporarily. GDB disables any of |
| these breakpoints immediately after stopping your program. |
| |
| 'enable [breakpoints] count COUNT LIST...' |
| Enable the specified breakpoints temporarily. GDB records COUNT |
| with each of the specified breakpoints, and decrements a |
| breakpoint's count when it is hit. When any count reaches 0, GDB |
| disables that breakpoint. If a breakpoint has an ignore count |
| (*note Break Conditions: Conditions.), that will be decremented to |
| 0 before COUNT is affected. |
| |
| 'enable [breakpoints] delete LIST...' |
| 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.). |
| |
| Breakpoint conditions can also be evaluated on the target's side if |
| the target supports it. Instead of evaluating the conditions locally, |
| GDB encodes the expression into an agent expression (*note Agent |
| Expressions::) suitable for execution on the target, independently of |
| GDB. Global variables become raw memory locations, locals become stack |
| accesses, and so forth. |
| |
| In this case, GDB will only be notified of a breakpoint trigger when |
| its condition evaluates to true. This mechanism may provide faster |
| response times depending on the performance characteristics of the |
| target since it does not need to keep GDB informed about every |
| breakpoint trigger, even those with false conditions. |
| |
| 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: Dynamic Printf, 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 [LIST...]' |
| '... COMMAND-LIST ...' |
| 'end' |
| Specify a list of commands for the given breakpoints. 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 argument, 'commands' refers to the last breakpoint, |
| watchpoint, or catchpoint set (not to the breakpoint most recently |
| encountered). If the most recent breakpoints were set with a |
| single command, then the 'commands' will apply to all the |
| breakpoints set by that command. This applies to breakpoints set |
| by 'rbreak', and also applies when a single 'break' command creates |
| multiple breakpoints (*note Ambiguous Expressions: Ambiguous |
| Expressions.). |
| |
| 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: Dynamic Printf, Next: Save Breakpoints, Prev: Break Commands, Up: Breakpoints |
| |
| 5.1.8 Dynamic Printf |
| -------------------- |
| |
| The dynamic printf command 'dprintf' combines a breakpoint with |
| formatted printing of your program's data to give you the effect of |
| inserting 'printf' calls into your program on-the-fly, without having to |
| recompile it. |
| |
| In its most basic form, the output goes to the GDB console. However, |
| you can set the variable 'dprintf-style' for alternate handling. For |
| instance, you can ask to format the output by calling your program's |
| 'printf' function. This has the advantage that the characters go to the |
| program's output device, so they can recorded in redirects to files and |
| so forth. |
| |
| If you are doing remote debugging with a stub or agent, you can also |
| ask to have the printf handled by the remote agent. In addition to |
| ensuring that the output goes to the remote program's device along with |
| any other output the program might produce, you can also ask that the |
| dprintf remain active even after disconnecting from the remote target. |
| Using the stub/agent is also more efficient, as it can do everything |
| without needing to communicate with GDB. |
| |
| 'dprintf LOCATION,TEMPLATE,EXPRESSION[,EXPRESSION...]' |
| Whenever execution reaches LOCATION, print the values of one or |
| more EXPRESSIONS under the control of the string TEMPLATE. To |
| print several values, separate them with commas. |
| |
| 'set dprintf-style STYLE' |
| Set the dprintf output to be handled in one of several different |
| styles enumerated below. A change of style affects all existing |
| dynamic printfs immediately. (If you need individual control over |
| the print commands, simply define normal breakpoints with |
| explicitly-supplied command lists.) |
| |
| 'gdb' |
| Handle the output using the GDB 'printf' command. |
| |
| 'call' |
| Handle the output by calling a function in your program |
| (normally 'printf'). |
| |
| 'agent' |
| Have the remote debugging agent (such as 'gdbserver') handle |
| the output itself. This style is only available for agents |
| that support running commands on the target. |
| |
| 'set dprintf-function FUNCTION' |
| Set the function to call if the dprintf style is 'call'. By |
| default its value is 'printf'. You may set it to any expression. |
| that GDB can evaluate to a function, as per the 'call' command. |
| |
| 'set dprintf-channel CHANNEL' |
| Set a "channel" for dprintf. If set to a non-empty value, GDB will |
| evaluate it as an expression and pass the result as a first |
| argument to the 'dprintf-function', in the manner of 'fprintf' and |
| similar functions. Otherwise, the dprintf format string will be |
| the first argument, in the manner of 'printf'. |
| |
| As an example, if you wanted 'dprintf' output to go to a logfile |
| that is a standard I/O stream assigned to the variable 'mylog', you |
| could do the following: |
| |
| (gdb) set dprintf-style call |
| (gdb) set dprintf-function fprintf |
| (gdb) set dprintf-channel mylog |
| (gdb) dprintf 25,"at line 25, glob=%d\n",glob |
| Dprintf 1 at 0x123456: file main.c, line 25. |
| (gdb) info break |
| 1 dprintf keep y 0x00123456 in main at main.c:25 |
| call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) |
| continue |
| (gdb) |
| |
| Note that the 'info break' displays the dynamic printf commands as |
| normal breakpoint commands; you can thus easily see the effect of |
| the variable settings. |
| |
| 'set disconnected-dprintf on' |
| 'set disconnected-dprintf off' |
| Choose whether 'dprintf' commands should continue to run if GDB has |
| disconnected from the target. This only applies if the |
| 'dprintf-style' is 'agent'. |
| |
| 'show disconnected-dprintf off' |
| Show the current choice for disconnected 'dprintf'. |
| |
| GDB does not check the validity of function and channel, relying on |
| you to supply values that are meaningful for the contexts in which they |
| are being used. For instance, the function and channel may be the |
| values of local variables, but if that is the case, then all enabled |
| dynamic prints must be at locations within the scope of those locals. |
| If evaluation fails, GDB will report an error. |
| |
| |
| File: gdb.info, Node: Save Breakpoints, Next: Static Probe Points, Prev: Dynamic Printf, Up: Breakpoints |
| |
| 5.1.9 How to save breakpoints to a file |
| --------------------------------------- |
| |
| To save breakpoint definitions to a file use the 'save breakpoints' |
| command. |
| |
| 'save breakpoints [FILENAME]' |
| This command saves all current breakpoint definitions together with |
| their commands and ignore counts, into a file 'FILENAME' suitable |
| for use in a later debugging session. This includes all types of |
| breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). |
| To read the saved breakpoint definitions, use the 'source' command |
| (*note Command Files::). Note that watchpoints with expressions |
| involving local variables may fail to be recreated because it may |
| not be possible to access the context where the watchpoint is valid |
| anymore. Because the saved breakpoint definitions are simply a |
| sequence of GDB commands that recreate the breakpoints, you can |
| edit the file in your favorite editing program, and remove the |
| breakpoint definitions you're not interested in, or that can no |
| longer be recreated. |
| |
| |
| File: gdb.info, Node: Static Probe Points, Next: Error in Breakpoints, Prev: Save Breakpoints, Up: Breakpoints |
| |
| 5.1.10 Static Probe Points |
| -------------------------- |
| |
| GDB supports "SDT" probes in the code. SDT stands for Statically |
| Defined Tracing, and the probes are designed to have a tiny runtime code |
| and data footprint, and no dynamic relocations. |
| |
| Currently, the following types of probes are supported on |
| ELF-compatible systems: |
| |
| * 'SystemTap' (<http://sourceware.org/systemtap/>) SDT probes(1). |
| 'SystemTap' probes are usable from assembly, C and C++ |
| languages(2). |
| |
| * 'DTrace' (<http://oss.oracle.com/projects/DTrace>) USDT probes. |
| 'DTrace' probes are usable from C and C++ languages. |
| |
| Some 'SystemTap' probes have an associated semaphore variable; for |
| instance, this happens automatically if you defined your probe using a |
| DTrace-style '.d' file. If your probe has a semaphore, GDB will |
| automatically enable it when you specify a breakpoint using the |
| '-probe-stap' notation. But, if you put a breakpoint at a probe's |
| location by some other method (e.g., 'break file:line'), then GDB will |
| not automatically set the semaphore. 'DTrace' probes do not support |
| semaphores. |
| |
| You can examine the available static static probes using 'info |
| probes', with optional arguments: |
| |
| 'info probes [TYPE] [PROVIDER [NAME [OBJFILE]]]' |
| If given, TYPE is either 'stap' for listing 'SystemTap' probes or |
| 'dtrace' for listing 'DTrace' probes. If omitted all probes are |
| listed regardless of their types. |
| |
| If given, PROVIDER is a regular expression used to match against |
| provider names when selecting which probes to list. If omitted, |
| probes by all probes from all providers are listed. |
| |
| If given, NAME is a regular expression to match against probe names |
| when selecting which probes to list. If omitted, probe names are |
| not considered when deciding whether to display them. |
| |
| If given, OBJFILE is a regular expression used to select which |
| object files (executable or shared libraries) to examine. If not |
| given, all object files are considered. |
| |
| 'info probes all' |
| List the available static probes, from all types. |
| |
| Some probe points can be enabled and/or disabled. The effect of |
| enabling or disabling a probe depends on the type of probe being |
| handled. Some 'DTrace' probes can be enabled or disabled, but |
| 'SystemTap' probes cannot be disabled. |
| |
| You can enable (or disable) one or more probes using the following |
| commands, with optional arguments: |
| |
| 'enable probes [PROVIDER [NAME [OBJFILE]]]' |
| If given, PROVIDER is a regular expression used to match against |
| provider names when selecting which probes to enable. If omitted, |
| all probes from all providers are enabled. |
| |
| If given, NAME is a regular expression to match against probe names |
| when selecting which probes to enable. If omitted, probe names are |
| not considered when deciding whether to enable them. |
| |
| If given, OBJFILE is a regular expression used to select which |
| object files (executable or shared libraries) to examine. If not |
| given, all object files are considered. |
| |
| 'disable probes [PROVIDER [NAME [OBJFILE]]]' |
| See the 'enable probes' command above for a description of the |
| optional arguments accepted by this command. |
| |
| A probe may specify up to twelve arguments. These are available at |
| the point at which the probe is defined--that is, when the current PC is |
| at the probe's location. The arguments are available using the |
| convenience variables (*note Convenience Vars::) |
| '$_probe_arg0'...'$_probe_arg11'. In 'SystemTap' probes each probe |
| argument is an integer of the appropriate size; types are not preserved. |
| In 'DTrace' probes types are preserved provided that they are recognized |
| as such by GDB; otherwise the value of the probe argument will be a long |
| integer. The convenience variable '$_probe_argc' holds the number of |
| arguments at the current probe point. |
| |
| These variables are always available, but attempts to access them at |
| any location other than a probe point will cause GDB to give an error |
| message. |
| |
| ---------- Footnotes ---------- |
| |
| (1) See |
| <http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps> for |
| more information on how to add 'SystemTap' SDT probes in your |
| applications. |
| |
| (2) See |
| <http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation> for |
| a good reference on how the SDT probes are implemented. |
| |
| |
| File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Static Probe Points, Up: Breakpoints |
| |
| 5.1.11 "Cannot insert breakpoints" |
| ---------------------------------- |
| |
| If you request too many active hardware-assisted breakpoints and |
| watchpoints, you will see this error message: |
| |
| 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.12 "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: Skipping Over Functions and Files, 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.), or you may step into the signal's |
| handler (*note stepping and signal handlers::).) |
| |
| '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). This command |
| can be abbreviated as 'fin'. |
| |
| Contrast this with the 'return' command (*note Returning from a |
| Function: Returning.). |
| |
| 'set print finish [on|off]' |
| 'show print finish' |
| By default the 'finish' command will show the value that is |
| returned by the function. This can be disabled using 'set print |
| finish off'. When disabled, the value is still entered into the |
| value history (*note Value History::), but not displayed. |
| |
| '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. The 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'. |
| |
| By default, and if available, GDB makes use of target-assisted "range |
| stepping". In other words, whenever you use a stepping command (e.g., |
| 'step', 'next'), GDB tells the target to step the corresponding range of |
| instruction addresses instead of issuing multiple single-steps. This |
| speeds up line stepping, particularly for remote targets. Ideally, |
| there should be no reason you would want to turn range stepping off. |
| However, it's possible that a bug in the debug info, a bug in the remote |
| stub (for remote targets), or even a bug in GDB could make line stepping |
| behave incorrectly when target-assisted range stepping is enabled. You |
| can use the following command to turn off range stepping if necessary: |
| |
| 'set range-stepping' |
| 'show range-stepping' |
| Control whether range stepping is enabled. |
| |
| If 'on', and the target supports it, GDB tells the target to step a |
| range of addresses itself, instead of issuing multiple |
| single-steps. If 'off', GDB always issues single-steps, even if |
| range stepping is supported by the target. The default is 'on'. |
| |
| |
| File: gdb.info, Node: Skipping Over Functions and Files, Next: Signals, Prev: Continuing and Stepping, Up: Stopping |
| |
| 5.3 Skipping Over Functions and Files |
| ===================================== |
| |
| The program you are debugging may contain some functions which are |
| uninteresting to debug. The 'skip' command lets you tell GDB to skip a |
| function, all functions in a file or a particular function in a |
| particular file when stepping. |
| |
| For example, consider the following C function: |
| |
| 101 int func() |
| 102 { |
| 103 foo(boring()); |
| 104 bar(boring()); |
| 105 } |
| |
| Suppose you wish to step into the functions 'foo' and 'bar', but you are |
| not interested in stepping through 'boring'. If you run 'step' at line |
| 103, you'll enter 'boring()', but if you run 'next', you'll step over |
| both 'foo' and 'boring'! |
| |
| One solution is to 'step' into 'boring' and use the 'finish' command |
| to immediately exit it. But this can become tedious if 'boring' is |
| called from many places. |
| |
| A more flexible solution is to execute 'skip boring'. This instructs |
| GDB never to step into 'boring'. Now when you execute 'step' at line |
| 103, you'll step over 'boring' and directly into 'foo'. |
| |
| Functions may be skipped by providing either a function name, |
| linespec (*note Specify Location::), regular expression that matches the |
| function's name, file name or a 'glob'-style pattern that matches the |
| file name. |
| |
| On Posix systems the form of the regular expression is "Extended |
| Regular Expressions". See for example 'man 7 regex' on GNU/Linux |
| systems. On non-Posix systems the form of the regular expression is |
| whatever is provided by the 'regcomp' function of the underlying system. |
| See for example 'man 7 glob' on GNU/Linux systems for a description of |
| 'glob'-style patterns. |
| |
| 'skip [OPTIONS]' |
| The basic form of the 'skip' command takes zero or more options |
| that specify what to skip. The OPTIONS argument is any useful |
| combination of the following: |
| |
| '-file FILE' |
| '-fi FILE' |
| Functions in FILE will be skipped over when stepping. |
| |
| '-gfile FILE-GLOB-PATTERN' |
| '-gfi FILE-GLOB-PATTERN' |
| Functions in files matching FILE-GLOB-PATTERN will be skipped |
| over when stepping. |
| |
| (gdb) skip -gfi utils/*.c |
| |
| '-function LINESPEC' |
| '-fu LINESPEC' |
| Functions named by LINESPEC or the function containing the |
| line named by LINESPEC will be skipped over when stepping. |
| *Note Specify Location::. |
| |
| '-rfunction REGEXP' |
| '-rfu REGEXP' |
| Functions whose name matches REGEXP will be skipped over when |
| stepping. |
| |
| This form is useful for complex function names. For example, |
| there is generally no need to step into C++ 'std::string' |
| constructors or destructors. Plus with C++ templates it can |
| be hard to write out the full name of the function, and often |
| it doesn't matter what the template arguments are. Specifying |
| the function to be skipped as a regular expression makes this |
| easier. |
| |
| (gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\( |
| |
| If you want to skip every templated C++ constructor and |
| destructor in the 'std' namespace you can do: |
| |
| (gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\( |
| |
| If no options are specified, the function you're currently |
| debugging will be skipped. |
| |
| 'skip function [LINESPEC]' |
| After running this command, the function named by LINESPEC or the |
| function containing the line named by LINESPEC will be skipped over |
| when stepping. *Note Specify Location::. |
| |
| If you do not specify LINESPEC, the function you're currently |
| debugging will be skipped. |
| |
| (If you have a function called 'file' that you want to skip, use |
| 'skip function file'.) |
| |
| 'skip file [FILENAME]' |
| After running this command, any function whose source lives in |
| FILENAME will be skipped over when stepping. |
| |
| (gdb) skip file boring.c |
| File boring.c will be skipped when stepping. |
| |
| If you do not specify FILENAME, functions whose source lives in the |
| file you're currently debugging will be skipped. |
| |
| Skips can be listed, deleted, disabled, and enabled, much like |
| breakpoints. These are the commands for managing your list of skips: |
| |
| 'info skip [RANGE]' |
| Print details about the specified skip(s). If RANGE is not |
| specified, print a table with details about all functions and files |
| marked for skipping. 'info skip' prints the following information |
| about each skip: |
| |
| _Identifier_ |
| A number identifying this skip. |
| _Enabled or Disabled_ |
| Enabled skips are marked with 'y'. Disabled skips are marked |
| with 'n'. |
| _Glob_ |
| If the file name is a 'glob' pattern this is 'y'. Otherwise |
| it is 'n'. |
| _File_ |
| The name or 'glob' pattern of the file to be skipped. If no |
| file is specified this is '<none>'. |
| _RE_ |
| If the function name is a 'regular expression' this is 'y'. |
| Otherwise it is 'n'. |
| _Function_ |
| The name or regular expression of the function to skip. If no |
| function is specified this is '<none>'. |
| |
| 'skip delete [RANGE]' |
| Delete the specified skip(s). If RANGE is not specified, delete |
| all skips. |
| |
| 'skip enable [RANGE]' |
| Enable the specified skip(s). If RANGE is not specified, enable |
| all skips. |
| |
| 'skip disable [RANGE]' |
| Disable the specified skip(s). If RANGE is not specified, disable |
| all skips. |
| |
| 'set debug skip [on|off]' |
| Set whether to print the debug output about skipping files and |
| functions. |
| |
| 'show debug skip' |
| Show whether the debug output about skipping files and functions is |
| printed. |
| |
| |
| File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Skipping Over Functions and Files, Up: Stopping |
| |
| 5.4 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'. |
| |
| 'catch signal [SIGNAL... | 'all']' |
| Set a catchpoint for the indicated signals. *Note Set |
| Catchpoints::, for details about this command. |
| |
| 'handle SIGNAL [KEYWORDS...]' |
| Change the way GDB handles signal SIGNAL. The 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. |
| |
| GDB optimizes for stepping the mainline code. If a signal that has |
| 'handle nostop' and 'handle pass' set arrives while a stepping command |
| (e.g., 'stepi', 'step', 'next') is in progress, GDB lets the signal |
| handler run and then resumes stepping the mainline code once the signal |
| handler returns. In other words, GDB steps over the signal handler. |
| This prevents signals that you've specified as not interesting (with |
| 'handle nostop') from changing the focus of debugging unexpectedly. |
| Note that the signal handler itself may still hit a breakpoint, stop for |
| another signal that has 'handle stop' in effect, or for any other event |
| that normally results in stopping the stepping command sooner. Also |
| note that GDB still informs you that the program received a signal if |
| 'handle print' is set. |
| |
| If you set 'handle pass' for a signal, and your program sets up a |
| handler for it, then issuing a stepping command, such as 'step' or |
| 'stepi', when your program is stopped due to the signal will step _into_ |
| the signal handler (if the target supports that). |
| |
| Likewise, if you use the 'queue-signal' command to queue a signal to |
| be delivered to the current thread when execution of the thread resumes |
| (*note Giving your Program a Signal: Signaling.), then a stepping |
| command will step into the signal handler. |
| |
| Here's an example, using 'stepi' to step to the first instruction of |
| 'SIGUSR1''s handler: |
| |
| (gdb) handle SIGUSR1 |
| Signal Stop Print Pass to program Description |
| SIGUSR1 Yes Yes Yes User defined signal 1 |
| (gdb) c |
| Continuing. |
| |
| Program received signal SIGUSR1, User defined signal 1. |
| main () sigusr1.c:28 |
| 28 p = 0; |
| (gdb) si |
| sigusr1_handler () at sigusr1.c:9 |
| 9 { |
| |
| The same, but using 'queue-signal' instead of waiting for the program |
| to receive the signal first: |
| |
| (gdb) n |
| 28 p = 0; |
| (gdb) queue-signal SIGUSR1 |
| (gdb) si |
| sigusr1_handler () at sigusr1.c:9 |
| 9 { |
| (gdb) |
| |
| On some targets, GDB can inspect extra signal information associated |
| with the intercepted signal, before it is actually delivered to the |
| program being debugged. This information is exported by the convenience |
| variable '$_siginfo', and consists of data that is passed by the kernel |
| to the signal handler at the time of the receipt of a signal. The data |
| type of the information itself is target dependent. You can see the |
| data type using the 'ptype $_siginfo' command. On Unix systems, it |
| typically corresponds to the standard 'siginfo_t' type, as defined in |
| the 'signal.h' system header. |
| |
| Here's an example, on a GNU/Linux system, printing the stray |
| referenced address that raised a segmentation fault. |
| |
| (gdb) continue |
| Program received signal SIGSEGV, Segmentation fault. |
| 0x0000000000400766 in main () |
| 69 *(int *)p = 0; |
| (gdb) ptype $_siginfo |
| type = struct { |
| int si_signo; |
| int si_errno; |
| int si_code; |
| union { |
| int _pad[28]; |
| struct {...} _kill; |
| struct {...} _timer; |
| struct {...} _rt; |
| struct {...} _sigchld; |
| struct {...} _sigfault; |
| struct {...} _sigpoll; |
| } _sifields; |
| } |
| (gdb) ptype $_siginfo._sifields._sigfault |
| type = struct { |
| void *si_addr; |
| } |
| (gdb) p $_siginfo._sifields._sigfault.si_addr |
| $1 = (void *) 0x7ffff7ff7000 |
| |
| Depending on target support, '$_siginfo' may also be writable. |
| |
| On some targets, a 'SIGSEGV' can be caused by a boundary violation, |
| i.e., accessing an address outside of the allowed range. In those cases |
| GDB may displays additional information, depending on how GDB has been |
| told to handle the signal. With 'handle stop SIGSEGV', GDB displays the |
| violation kind: "Upper" or "Lower", the memory address accessed and the |
| bounds, while with 'handle nostop SIGSEGV' no additional information is |
| displayed. |
| |
| The usual output of a segfault is: |
| Program received signal SIGSEGV, Segmentation fault |
| 0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 |
| 68 value = *(p + len); |
| |
| While a bound violation is presented as: |
| Program received signal SIGSEGV, Segmentation fault |
| Upper bound violation while accessing address 0x7fffffffc3b3 |
| Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3] |
| 0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 |
| 68 value = *(p + len); |
| |
| |
| File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping |
| |
| 5.5 Stopping and Starting Multi-thread Programs |
| =============================================== |
| |
| GDB supports debugging programs with multiple threads (*note Debugging |
| Programs with Multiple Threads: Threads.). There are two modes of |
| controlling execution of your program within the debugger. In the |
| default mode, referred to as "all-stop mode", when any thread in your |
| program stops (for example, at a breakpoint or while being stepped), all |
| other threads in the program are also stopped by GDB. On some targets, |
| GDB also supports "non-stop mode", in which other threads can continue |
| to run freely while you examine the stopped thread in the debugger. |
| |
| * Menu: |
| |
| * All-Stop Mode:: All threads stop when GDB takes control |
| * Non-Stop Mode:: Other threads continue to execute |
| * Background Execution:: Running your program asynchronously |
| * Thread-Specific Breakpoints:: Controlling breakpoints |
| * Interrupted System Calls:: GDB may interfere with system calls |
| * Observer Mode:: GDB does not alter program behavior |
| |
| |
| File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops |
| |
| 5.5.1 All-Stop Mode |
| ------------------- |
| |
| In all-stop mode, 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. |
| |
| 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. |
| |
| 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 such as |
| '[Switching to Thread N]' to identify the thread. |
| |
| On some OSes, you can modify GDB's default behavior by locking the OS |
| scheduler to allow only a single thread to run. |
| |
| 'set scheduler-locking MODE' |
| Set the scheduler locking mode. It applies to normal execution, |
| record mode, and replay 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 prevents other threads from |
| preempting the current thread while you are stepping, so that the |
| focus of debugging does not change unexpectedly. Other threads |
| never get a chance to run when you step, 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, GDB does not change the current thread away from the |
| thread that you are debugging. The 'replay' mode behaves like |
| 'off' in record mode and like 'on' in replay mode. |
| |
| 'show scheduler-locking' |
| Display the current scheduler locking mode. |
| |
| By default, when you issue one of the execution commands such as |
| 'continue', 'next' or 'step', GDB allows only threads of the current |
| inferior to run. For example, if GDB is attached to two inferiors, each |
| with two threads, the 'continue' command resumes only the two threads of |
| the current inferior. This is useful, for example, when you debug a |
| program that forks and you want to hold the parent stopped (so that, for |
| instance, it doesn't run to exit), while you debug the child. In other |
| situations, you may not be interested in inspecting the current state of |
| any of the processes GDB is attached to, and you may want to resume them |
| all until some breakpoint is hit. In the latter case, you can instruct |
| GDB to allow all threads of all the inferiors to run with the |
| 'set schedule-multiple' command. |
| |
| 'set schedule-multiple' |
| Set the mode for allowing threads of multiple processes to be |
| resumed when an execution command is issued. When 'on', all |
| threads of all processes are allowed to run. When 'off', only the |
| threads of the current process are resumed. The default is 'off'. |
| The 'scheduler-locking' mode takes precedence when set to 'on', or |
| while you are stepping and set to 'step'. |
| |
| 'show schedule-multiple' |
| Display the current mode for resuming the execution of threads of |
| multiple processes. |
| |
| |
| File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops |
| |
| 5.5.2 Non-Stop Mode |
| ------------------- |
| |
| For some multi-threaded targets, GDB supports an optional mode of |
| operation in which you can examine stopped program threads in the |
| debugger while other threads continue to execute freely. This minimizes |
| intrusion when debugging live systems, such as programs where some |
| threads have real-time constraints or must continue to respond to |
| external events. This is referred to as "non-stop" mode. |
| |
| In non-stop mode, when a thread stops to report a debugging event, |
| _only_ that thread is stopped; GDB does not stop other threads as well, |
| in contrast to the all-stop mode behavior. Additionally, execution |
| commands such as 'continue' and 'step' apply by default only to the |
| current thread in non-stop mode, rather than all threads as in all-stop |
| mode. This allows you to control threads explicitly in ways that are |
| not possible in all-stop mode -- for example, stepping one thread while |
| allowing others to run freely, stepping one thread while holding all |
| others stopped, or stepping several threads independently and |
| simultaneously. |
| |
| To enter non-stop mode, use this sequence of commands before you run |
| or attach to your program: |
| |
| # If using the CLI, pagination breaks non-stop. |
| set pagination off |
| |
| # Finally, turn it on! |
| set non-stop on |
| |
| You can use these commands to manipulate the non-stop mode setting: |
| |
| 'set non-stop on' |
| Enable selection of non-stop mode. |
| 'set non-stop off' |
| Disable selection of non-stop mode. |
| 'show non-stop' |
| Show the current non-stop enablement setting. |
| |
| Note these commands only reflect whether non-stop mode is enabled, |
| not whether the currently-executing program is being run in non-stop |
| mode. In particular, the 'set non-stop' preference is only consulted |
| when GDB starts or connects to the target program, and it is generally |
| not possible to switch modes once debugging has started. Furthermore, |
| since not all targets support non-stop mode, even when you have enabled |
| non-stop mode, GDB may still fall back to all-stop operation by default. |
| |
| In non-stop mode, all execution commands apply only to the current |
| thread by default. That is, 'continue' only continues one thread. To |
| continue all threads, issue 'continue -a' or 'c -a'. |
| |
| You can use GDB's background execution commands (*note Background |
| Execution::) to run some threads in the background while you continue to |
| examine or step others from GDB. The MI execution commands (*note |
| GDB/MI Program Execution::) are always executed asynchronously in |
| non-stop mode. |
| |
| Suspending execution is done with the 'interrupt' command when |
| running in the background, or 'Ctrl-c' during foreground execution. In |
| all-stop mode, this stops the whole process; but in non-stop mode the |
| interrupt applies only to the current thread. To stop the whole |
| program, use 'interrupt -a'. |
| |
| Other execution commands do not currently support the '-a' option. |
| |
| In non-stop mode, when a thread stops, GDB doesn't automatically make |
| that thread current, as it does in all-stop mode. This is because the |
| thread stop notifications are asynchronous with respect to GDB's command |
| interpreter, and it would be confusing if GDB unexpectedly changed to a |
| different thread just as you entered a command to operate on the |
| previously current thread. |
| |
| |
| File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops |
| |
| 5.5.3 Background Execution |
| -------------------------- |
| |
| GDB's execution commands have two variants: the normal foreground |
| (synchronous) behavior, and a background (asynchronous) behavior. In |
| foreground execution, GDB waits for the program to report that some |
| thread has stopped before prompting for another command. In background |
| execution, GDB immediately gives a command prompt so that you can issue |
| other commands while your program runs. |
| |
| If the target doesn't support async mode, GDB issues an error message |
| if you attempt to use the background execution commands. |
| |
| To specify background execution, add a '&' to the command. For |
| example, the background form of the 'continue' command is 'continue&', |
| or just 'c&'. The execution commands that accept background execution |
| are: |
| |
| 'run' |
| *Note Starting your Program: Starting. |
| |
| 'attach' |
| *Note Debugging an Already-running Process: Attach. |
| |
| 'step' |
| *Note step: Continuing and Stepping. |
| |
| 'stepi' |
| *Note stepi: Continuing and Stepping. |
| |
| 'next' |
| *Note next: Continuing and Stepping. |
| |
| 'nexti' |
| *Note nexti: Continuing and Stepping. |
| |
| 'continue' |
| *Note continue: Continuing and Stepping. |
| |
| 'finish' |
| *Note finish: Continuing and Stepping. |
| |
| 'until' |
| *Note until: Continuing and Stepping. |
| |
| Background execution is especially useful in conjunction with |
| non-stop mode for debugging programs with multiple threads; see *note |
| Non-Stop Mode::. However, you can also use these commands in the normal |
| all-stop mode with the restriction that you cannot issue another |
| execution command until the previous one finishes. Examples of commands |
| that are valid in all-stop mode while the program is running include |
| 'help' and 'info break'. |
| |
| You can interrupt your program while it is running in the background |
| by using the 'interrupt' command. |
| |
| 'interrupt' |
| 'interrupt -a' |
| |
| Suspend execution of the running program. In all-stop mode, |
| 'interrupt' stops the whole process, but in non-stop mode, it stops |
| only the current thread. To stop the whole program in non-stop |
| mode, use 'interrupt -a'. |
| |
| |
| File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops |
| |
| 5.5.4 Thread-Specific Breakpoints |
| --------------------------------- |
| |
| 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 LOCATION thread THREAD-ID' |
| 'break LOCATION thread THREAD-ID if ...' |
| LOCATION 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 THREAD-ID' with a breakpoint command to |
| specify that you only want GDB to stop the program when a |
| particular thread reaches this breakpoint. The THREAD-ID specifier |
| is one of the thread identifiers assigned by GDB, shown in the |
| first column of the 'info threads' display. |
| |
| If you do not specify 'thread THREAD-ID' 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 THREAD-ID' before or after the |
| breakpoint condition, like this: |
| |
| (gdb) break frik.c:13 thread 28 if bartab > lim |
| |
| Thread-specific breakpoints are automatically deleted when GDB |
| detects the corresponding thread is no longer in the thread list. For |
| example: |
| |
| (gdb) c |
| Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list. |
| |
| There are several ways for a thread to disappear, such as a regular |
| thread exit, but also when you detach from the process with the 'detach' |
| command (*note Debugging an Already-running Process: Attach.), or if GDB |
| loses the remote connection (*note Remote Debugging::), etc. Note that |
| with some targets, GDB is only able to detect a thread has exited when |
| the user explictly asks for the thread list with the 'info threads' |
| command. |
| |
| |
| File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops |
| |
| 5.5.5 Interrupted System Calls |
| ------------------------------ |
| |
| There is an unfortunate side effect when using GDB to debug |
| multi-threaded programs. 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. |
| |
| |
| File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops |
| |
| 5.5.6 Observer Mode |
| ------------------- |
| |
| If you want to build on non-stop mode and observe program behavior |
| without any chance of disruption by GDB, you can set variables to |
| disable all of the debugger's attempts to modify state, whether by |
| writing memory, inserting breakpoints, etc. These operate at a low |
| level, intercepting operations from all commands. |
| |
| When all of these are set to 'off', then GDB is said to be "observer |
| mode". As a convenience, the variable 'observer' can be set to disable |
| these, plus enable non-stop mode. |
| |
| Note that GDB will not prevent you from making nonsensical |
| combinations of these settings. For instance, if you have enabled |
| 'may-insert-breakpoints' but disabled 'may-write-memory', then |
| breakpoints that work by writing trap instructions into the code stream |
| will still not be able to be placed. |
| |
| 'set observer on' |
| 'set observer off' |
| When set to 'on', this disables all the permission variables below |
| (except for 'insert-fast-tracepoints'), plus enables non-stop |
| debugging. Setting this to 'off' switches back to normal |
| debugging, though remaining in non-stop mode. |
| |
| 'show observer' |
| Show whether observer mode is on or off. |
| |
| 'set may-write-registers on' |
| 'set may-write-registers off' |
| This controls whether GDB will attempt to alter the values of |
| registers, such as with assignment expressions in 'print', or the |
| 'jump' command. It defaults to 'on'. |
| |
| 'show may-write-registers' |
| Show the current permission to write registers. |
| |
| 'set may-write-memory on' |
| 'set may-write-memory off' |
| This controls whether GDB will attempt to alter the contents of |
| memory, such as with assignment expressions in 'print'. It |
| defaults to 'on'. |
| |
| 'show may-write-memory' |
| Show the current permission to write memory. |
| |
| 'set may-insert-breakpoints on' |
| 'set may-insert-breakpoints off' |
| This controls whether GDB will attempt to insert breakpoints. This |
| affects all breakpoints, including internal breakpoints defined by |
| GDB. It defaults to 'on'. |
| |
| 'show may-insert-breakpoints' |
| Show the current permission to insert breakpoints. |
| |
| 'set may-insert-tracepoints on' |
| 'set may-insert-tracepoints off' |
| This controls whether GDB will attempt to insert (regular) |
| tracepoints at the beginning of a tracing experiment. It affects |
| only non-fast tracepoints, fast tracepoints being under the control |
| of 'may-insert-fast-tracepoints'. It defaults to 'on'. |
| |
| 'show may-insert-tracepoints' |
| Show the current permission to insert tracepoints. |
| |
| 'set may-insert-fast-tracepoints on' |
| 'set may-insert-fast-tracepoints off' |
| This controls whether GDB will attempt to insert fast tracepoints |
| at the beginning of a tracing experiment. It affects only fast |
| tracepoints, regular (non-fast) tracepoints being under the control |
| of 'may-insert-tracepoints'. It defaults to 'on'. |
| |
| 'show may-insert-fast-tracepoints' |
| Show the current permission to insert fast tracepoints. |
| |
| 'set may-interrupt on' |
| 'set may-interrupt off' |
| This controls whether GDB will attempt to interrupt or stop program |
| execution. When this variable is 'off', the 'interrupt' command |
| will have no effect, nor will 'Ctrl-c'. It defaults to 'on'. |
| |
| 'show may-interrupt' |
| Show the current permission to interrupt or stop the program. |
| |
| |
| File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top |
| |
| 6 Running programs backward |
| *************************** |
| |
| When you are debugging a program, it is not unusual to realize that you |
| have gone too far, and some event of interest has already happened. If |
| the target environment supports it, GDB can allow you to "rewind" the |
| program by running it backward. |
| |
| A target environment that supports reverse execution should be able |
| to "undo" the changes in machine state that have taken place as the |
| program was executing normally. Variables, registers etc. should revert |
| to their previous values. Obviously this requires a great deal of |
| sophistication on the part of the target environment; not all target |
| environments can support reverse execution. |
| |
| When a program is executed in reverse, the instructions that have |
| most recently been executed are "un-executed", in reverse order. The |
| program counter runs backward, following the previous thread of |
| execution in reverse. As each instruction is "un-executed", the values |
| of memory and/or registers that were changed by that instruction are |
| reverted to their previous states. After executing a piece of source |
| code in reverse, all side effects of that code should be "undone", and |
| all variables should be returned to their prior values(1). |
| |
| On some platforms, GDB has built-in support for reverse execution, |
| activated with the 'record' or 'record btrace' commands. *Note Process |
| Record and Replay::. Some remote targets, typically full system |
| emulators, support reverse execution directly without requiring any |
| special command. |
| |
| If you are debugging in a target environment that supports reverse |
| execution, GDB provides the following commands. |
| |
| 'reverse-continue [IGNORE-COUNT]' |
| 'rc [IGNORE-COUNT]' |
| Beginning at the point where your program last stopped, start |
| executing in reverse. Reverse execution will stop for breakpoints |
| and synchronous exceptions (signals), just like normal execution. |
| Behavior of asynchronous signals depends on the target environment. |
| |
| 'reverse-step [COUNT]' |
| Run the program backward until control reaches the start of a |
| different source line; then stop it, and return control to GDB. |
| |
| Like the 'step' command, 'reverse-step' will only stop at the |
| beginning of a source line. It "un-executes" the previously |
| executed source line. If the previous source line included calls |
| to debuggable functions, 'reverse-step' will step (backward) into |
| the called function, stopping at the beginning of the _last_ |
| statement in the called function (typically a return statement). |
| |
| Also, as with the 'step' command, if non-debuggable functions are |
| called, 'reverse-step' will run thru them backward without |
| stopping. |
| |
| 'reverse-stepi [COUNT]' |
| Reverse-execute one machine instruction. Note that the instruction |
| to be reverse-executed is _not_ the one pointed to by the program |
| counter, but the instruction executed prior to that one. For |
| instance, if the last instruction was a jump, 'reverse-stepi' will |
| take you back from the destination of the jump to the jump |
| instruction itself. |
| |
| 'reverse-next [COUNT]' |
| Run backward to the beginning of the previous line executed in the |
| current (innermost) stack frame. If the line contains function |
| calls, they will be "un-executed" without stopping. Starting from |
| the first line of a function, 'reverse-next' will take you back to |
| the caller of that function, _before_ the function was called, just |
| as the normal 'next' command would take you from the last line of a |
| function back to its return to its caller (2). |
| |
| 'reverse-nexti [COUNT]' |
| Like 'nexti', 'reverse-nexti' executes a single instruction in |
| reverse, except that called functions are "un-executed" atomically. |
| That is, if the previously executed instruction was a return from |
| another function, 'reverse-nexti' will continue to execute in |
| reverse until the call to that function (from the current stack |
| frame) is reached. |
| |
| 'reverse-finish' |
| Just as the 'finish' command takes you to the point where the |
| current function returns, 'reverse-finish' takes you to the point |
| where it was called. Instead of ending up at the end of the |
| current function invocation, you end up at the beginning. |
| |
| 'set exec-direction' |
| Set the direction of target execution. |
| 'set exec-direction reverse' |
| GDB will perform all execution commands in reverse, until the |
| exec-direction mode is changed to "forward". Affected commands |
| include 'step, stepi, next, nexti, continue, and finish'. The |
| 'return' command cannot be used in reverse mode. |
| 'set exec-direction forward' |
| GDB will perform all execution commands in the normal fashion. |
| This is the default. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Note that some side effects are easier to undo than others. For |
| instance, memory and registers are relatively easy, but device I/O is |
| hard. Some targets may be able undo things like device I/O, and some |
| may not. |
| |
| The contract between GDB and the reverse executing target requires |
| only that the target do something reasonable when GDB tells it to |
| execute backwards, and then report the results back to GDB. Whatever |
| the target reports back to GDB, GDB will report back to the user. GDB |
| assumes that the memory and registers that the target reports are in a |
| consistent state, but GDB accepts whatever it is given. |
| |
| (2) Unless the code is too heavily optimized. |
| |
| |
| File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top |
| |
| 7 Recording Inferior's Execution and Replaying It |
| ************************************************* |
| |
| On some platforms, GDB provides a special "process record and replay" |
| target that can record a log of the process execution, and replay it |
| later with both forward and reverse execution commands. |
| |
| When this target is in use, if the execution log includes the record |
| for the next instruction, GDB will debug in "replay mode". In the |
| replay mode, the inferior does not really execute code instructions. |
| Instead, all the events that normally happen during code execution are |
| taken from the execution log. While code is not really executed in |
| replay mode, the values of registers (including the program counter |
| register) and the memory of the inferior are still changed as they |
| normally would. Their contents are taken from the execution log. |
| |
| If the record for the next instruction is not in the execution log, |
| GDB will debug in "record mode". In this mode, the inferior executes |
| normally, and GDB records the execution log for future replay. |
| |
| The process record and replay target supports reverse execution |
| (*note Reverse Execution::), even if the platform on which the inferior |
| runs does not. However, the reverse execution is limited in this case |
| by the range of the instructions recorded in the execution log. In |
| other words, reverse execution on platforms that don't support it |
| directly can only be done in the replay mode. |
| |
| When debugging in the reverse direction, GDB will work in replay mode |
| as long as the execution log includes the record for the previous |
| instruction; otherwise, it will work in record mode, if the platform |
| supports reverse execution, or stop if not. |
| |
| Currently, process record and replay is supported on ARM, Aarch64, |
| Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running |
| GNU/Linux. Process record and replay can be used both when native |
| debugging, and when remote debugging via 'gdbserver'. |
| |
| For architecture environments that support process record and replay, |
| GDB provides the following commands: |
| |
| 'record METHOD' |
| This command starts the process record and replay target. The |
| recording method can be specified as parameter. Without a |
| parameter the command uses the 'full' recording method. The |
| following recording methods are available: |
| |
| 'full' |
| Full record/replay recording using GDB's software record and |
| replay implementation. This method allows replaying and |
| reverse execution. |
| |
| 'btrace FORMAT' |
| Hardware-supported instruction recording, supported on Intel |
| processors. This method does not record data. Further, the |
| data is collected in a ring buffer so old data will be |
| overwritten when the buffer is full. It allows limited |
| reverse execution. Variables and registers are not available |
| during reverse execution. In remote debugging, recording |
| continues on disconnect. Recorded data can be inspected after |
| reconnecting. The recording may be stopped using 'record |
| stop'. |
| |
| The recording format can be specified as parameter. Without a |
| parameter the command chooses the recording format. The |
| following recording formats are available: |
| |
| 'bts' |
| Use the "Branch Trace Store" (BTS) recording format. In |
| this format, the processor stores a from/to record for |
| each executed branch in the btrace ring buffer. |
| |
| 'pt' |
| Use the "Intel Processor Trace" recording format. In |
| this format, the processor stores the execution trace in |
| a compressed form that is afterwards decoded by GDB. |
| |
| The trace can be recorded with very low overhead. The |
| compressed trace format also allows small trace buffers |
| to already contain a big number of instructions compared |
| to BTS. |
| |
| Decoding the recorded execution trace, on the other hand, |
| is more expensive than decoding BTS trace. This is |
| mostly due to the increased number of instructions to |
| process. You should increase the buffer-size with care. |
| |
| Not all recording formats may be available on all processors. |
| |
| The process record and replay target can only debug a process that |
| is already running. Therefore, you need first to start the process |
| with the 'run' or 'start' commands, and then start the recording |
| with the 'record METHOD' command. |
| |
| Displaced stepping (*note displaced stepping: Maintenance |
| Commands.) will be automatically disabled when process record and |
| replay target is started. That's because the process record and |
| replay target doesn't support displaced stepping. |
| |
| If the inferior is in the non-stop mode (*note Non-Stop Mode::) or |
| in the asynchronous execution mode (*note Background Execution::), |
| not all recording methods are available. The 'full' recording |
| method does not support these two modes. |
| |
| 'record stop' |
| Stop the process record and replay target. When process record and |
| replay target stops, the entire execution log will be deleted and |
| the inferior will either be terminated, or will remain in its final |
| state. |
| |
| When you stop the process record and replay target in record mode |
| (at the end of the execution log), the inferior will be stopped at |
| the next instruction that would have been recorded. In other |
| words, if you record for a while and then stop recording, the |
| inferior process will be left in the same state as if the recording |
| never happened. |
| |
| On the other hand, if the process record and replay target is |
| stopped while in replay mode (that is, not at the end of the |
| execution log, but at some earlier point), the inferior process |
| will become "live" at that earlier state, and it will then be |
| possible to continue the usual "live" debugging of the process from |
| that state. |
| |
| When the inferior process exits, or GDB detaches from it, process |
| record and replay target will automatically stop itself. |
| |
| 'record goto' |
| Go to a specific location in the execution log. There are several |
| ways to specify the location to go to: |
| |
| 'record goto begin' |
| 'record goto start' |
| Go to the beginning of the execution log. |
| |
| 'record goto end' |
| Go to the end of the execution log. |
| |
| 'record goto N' |
| Go to instruction number N in the execution log. |
| |
| 'record save FILENAME' |
| Save the execution log to a file 'FILENAME'. Default filename is |
| 'gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the |
| inferior. |
| |
| This command may not be available for all recording methods. |
| |
| 'record restore FILENAME' |
| Restore the execution log from a file 'FILENAME'. File must have |
| been created with 'record save'. |
| |
| 'set record full insn-number-max LIMIT' |
| 'set record full insn-number-max unlimited' |
| Set the limit of instructions to be recorded for the 'full' |
| recording method. Default value is 200000. |
| |
| If LIMIT is a positive number, then GDB will start deleting |
| instructions from the log once the number of the record |
| instructions becomes greater than LIMIT. For every new recorded |
| instruction, GDB will delete the earliest recorded instruction to |
| keep the number of recorded instructions at the limit. (Since |
| deleting recorded instructions loses information, GDB lets you |
| control what happens when the limit is reached, by means of the |
| 'stop-at-limit' option, described below.) |
| |
| If LIMIT is 'unlimited' or zero, GDB will never delete recorded |
| instructions from the execution log. The number of recorded |
| instructions is limited only by the available memory. |
| |
| 'show record full insn-number-max' |
| Show the limit of instructions to be recorded with the 'full' |
| recording method. |
| |
| 'set record full stop-at-limit' |
| Control the behavior of the 'full' recording method when the number |
| of recorded instructions reaches the limit. If ON (the default), |
| GDB will stop when the limit is reached for the first time and ask |
| you whether you want to stop the inferior or continue running it |
| and recording the execution log. If you decide to continue |
| recording, each new recorded instruction will cause the oldest one |
| to be deleted. |
| |
| If this option is OFF, GDB will automatically delete the oldest |
| record to make room for each new one, without asking. |
| |
| 'show record full stop-at-limit' |
| Show the current setting of 'stop-at-limit'. |
| |
| 'set record full memory-query' |
| Control the behavior when GDB is unable to record memory changes |
| caused by an instruction for the 'full' recording method. If ON, |
| GDB will query whether to stop the inferior in that case. |
| |
| If this option is OFF (the default), GDB will automatically ignore |
| the effect of such instructions on memory. Later, when GDB replays |
| this execution log, it will mark the log of this instruction as not |
| accessible, and it will not affect the replay results. |
| |
| 'show record full memory-query' |
| Show the current setting of 'memory-query'. |
| |
| The 'btrace' record target does not trace data. As a convenience, |
| when replaying, GDB reads read-only memory off the live program |
| directly, assuming that the addresses of the read-only areas don't |
| change. This for example makes it possible to disassemble code |
| while replaying, but not to print variables. In some cases, being |
| able to inspect variables might be useful. You can use the |
| following command for that: |
| |
| 'set record btrace replay-memory-access' |
| Control the behavior of the 'btrace' recording method when |
| accessing memory during replay. If 'read-only' (the default), GDB |
| will only allow accesses to read-only memory. If 'read-write', GDB |
| will allow accesses to read-only and to read-write memory. Beware |
| that the accessed memory corresponds to the live target and not |
| necessarily to the current replay position. |
| |
| 'set record btrace cpu IDENTIFIER' |
| Set the processor to be used for enabling workarounds for processor |
| errata when decoding the trace. |
| |
| Processor errata are defects in processor operation, caused by its |
| design or manufacture. They can cause a trace not to match the |
| specification. This, in turn, may cause trace decode to fail. GDB |
| can detect erroneous trace packets and correct them, thus avoiding |
| the decoding failures. These corrections are known as "errata |
| workarounds", and are enabled based on the processor on which the |
| trace was recorded. |
| |
| By default, GDB attempts to detect the processor automatically, and |
| apply the necessary workarounds for it. However, you may need to |
| specify the processor if GDB does not yet support it. This command |
| allows you to do that, and also allows to disable the workarounds. |
| |
| The argument IDENTIFIER identifies the CPU and is of the form: |
| 'VENDOR:PROCESSOR IDENTIFIER'. In addition, there are two special |
| identifiers, 'none' and 'auto' (default). |
| |
| The following vendor identifiers and corresponding processor |
| identifiers are currently supported: |
| |
| 'intel' FAMILY/MODEL[/STEPPING] |
| |
| |
| On GNU/Linux systems, the processor FAMILY, MODEL, and STEPPING can |
| be obtained from '/proc/cpuinfo'. |
| |
| If IDENTIFIER is 'auto', enable errata workarounds for the |
| processor on which the trace was recorded. If IDENTIFIER is |
| 'none', errata workarounds are disabled. |
| |
| For example, when using an old GDB on a new system, decode may fail |
| because GDB does not support the new processor. It often suffices |
| to specify an older processor that GDB supports. |
| |
| (gdb) info record |
| Active record target: record-btrace |
| Recording format: Intel Processor Trace. |
| Buffer size: 16kB. |
| Failed to configure the Intel Processor Trace decoder: unknown cpu. |
| (gdb) set record btrace cpu intel:6/158 |
| (gdb) info record |
| Active record target: record-btrace |
| Recording format: Intel Processor Trace. |
| Buffer size: 16kB. |
| Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...). |
| |
| 'show record btrace replay-memory-access' |
| Show the current setting of 'replay-memory-access'. |
| |
| 'show record btrace cpu' |
| Show the processor to be used for enabling trace decode errata |
| workarounds. |
| |
| 'set record btrace bts buffer-size SIZE' |
| 'set record btrace bts buffer-size unlimited' |
| Set the requested ring buffer size for branch tracing in BTS |
| format. Default is 64KB. |
| |
| If SIZE is a positive number, then GDB will try to allocate a |
| buffer of at least SIZE bytes for each new thread that uses the |
| btrace recording method and the BTS format. The actually obtained |
| buffer size may differ from the requested SIZE. Use the 'info |
| record' command to see the actual buffer size for each thread that |
| uses the btrace recording method and the BTS format. |
| |
| If LIMIT is 'unlimited' or zero, GDB will try to allocate a buffer |
| of 4MB. |
| |
| Bigger buffers mean longer traces. On the other hand, GDB will |
| also need longer to process the branch trace data before it can be |
| used. |
| |
| 'show record btrace bts buffer-size SIZE' |
| Show the current setting of the requested ring buffer size for |
| branch tracing in BTS format. |
| |
| 'set record btrace pt buffer-size SIZE' |
| 'set record btrace pt buffer-size unlimited' |
| Set the requested ring buffer size for branch tracing in Intel |
| Processor Trace format. Default is 16KB. |
| |
| If SIZE is a positive number, then GDB will try to allocate a |
| buffer of at least SIZE bytes for each new thread that uses the |
| btrace recording method and the Intel Processor Trace format. The |
| actually obtained buffer size may differ from the requested SIZE. |
| Use the 'info record' command to see the actual buffer size for |
| each thread. |
| |
| If LIMIT is 'unlimited' or zero, GDB will try to allocate a buffer |
| of 4MB. |
| |
| Bigger buffers mean longer traces. On the other hand, GDB will |
| also need longer to process the branch trace data before it can be |
| used. |
| |
| 'show record btrace pt buffer-size SIZE' |
| Show the current setting of the requested ring buffer size for |
| branch tracing in Intel Processor Trace format. |
| |
| 'info record' |
| Show various statistics about the recording depending on the |
| recording method: |
| |
| 'full' |
| For the 'full' recording method, it shows the state of process |
| record and its in-memory execution log buffer, including: |
| |
| * Whether in record mode or replay mode. |
| * Lowest recorded instruction number (counting from when |
| the current execution log started recording |
| instructions). |
| * Highest recorded instruction number. |
| * Current instruction about to be replayed (if in replay |
| mode). |
| * Number of instructions contained in the execution log. |
| * Maximum number of instructions that may be contained in |
| the execution log. |
| |
| 'btrace' |
| For the 'btrace' recording method, it shows: |
| |
| * Recording format. |
| * Number of instructions that have been recorded. |
| * Number of blocks of sequential control-flow formed by the |
| recorded instructions. |
| * Whether in record mode or replay mode. |
| |
| For the 'bts' recording format, it also shows: |
| * Size of the perf ring buffer. |
| |
| For the 'pt' recording format, it also shows: |
| * Size of the perf ring buffer. |
| |
| 'record delete' |
| When record target runs in replay mode ("in the past"), delete the |
| subsequent execution log and begin to record a new execution log |
| starting from the current address. This means you will abandon the |
| previously recorded "future" and begin recording a new "future". |
| |
| 'record instruction-history' |
| Disassembles instructions from the recorded execution log. By |
| default, ten instructions are disassembled. This can be changed |
| using the 'set record instruction-history-size' command. |
| Instructions are printed in execution order. |
| |
| It can also print mixed source+disassembly if you specify the the |
| '/m' or '/s' modifier, and print the raw instructions in hex as |
| well as in symbolic form by specifying the '/r' modifier. |
| |
| The current position marker is printed for the instruction at the |
| current program counter value. This instruction can appear |
| multiple times in the trace and the current position marker will be |
| printed every time. To omit the current position marker, specify |
| the '/p' modifier. |
| |
| To better align the printed instructions when the trace contains |
| instructions from more than one function, the function name may be |
| omitted by specifying the '/f' modifier. |
| |
| Speculatively executed instructions are prefixed with '?'. This |
| feature is not available for all recording formats. |
| |
| There are several ways to specify what part of the execution log to |
| disassemble: |
| |
| 'record instruction-history INSN' |
| Disassembles ten instructions starting from instruction number |
| INSN. |
| |
| 'record instruction-history INSN, +/-N' |
| Disassembles N instructions around instruction number INSN. |
| If N is preceded with '+', disassembles N instructions after |
| instruction number INSN. If N is preceded with '-', |
| disassembles N instructions before instruction number INSN. |
| |
| 'record instruction-history' |
| Disassembles ten more instructions after the last disassembly. |
| |
| 'record instruction-history -' |
| Disassembles ten more instructions before the last |
| disassembly. |
| |
| 'record instruction-history BEGIN, END' |
| Disassembles instructions beginning with instruction number |
| BEGIN until instruction number END. The instruction number |
| END is included. |
| |
| This command may not be available for all recording methods. |
| |
| 'set record instruction-history-size SIZE' |
| 'set record instruction-history-size unlimited' |
| Define how many instructions to disassemble in the 'record |
| instruction-history' command. The default value is 10. A SIZE of |
| 'unlimited' means unlimited instructions. |
| |
| 'show record instruction-history-size' |
| Show how many instructions to disassemble in the 'record |
| instruction-history' command. |
| |
| 'record function-call-history' |
| Prints the execution history at function granularity. It prints |
| one line for each sequence of instructions that belong to the same |
| function giving the name of that function, the source lines for |
| this instruction sequence (if the '/l' modifier is specified), and |
| the instructions numbers that form the sequence (if the '/i' |
| modifier is specified). The function names are indented to reflect |
| the call stack depth if the '/c' modifier is specified. The '/l', |
| '/i', and '/c' modifiers can be given together. |
| |
| (gdb) list 1, 10 |
| 1 void foo (void) |
| 2 { |
| 3 } |
| 4 |
| 5 void bar (void) |
| 6 { |
| 7 ... |
| 8 foo (); |
| 9 ... |
| 10 } |
| (gdb) record function-call-history /ilc |
| 1 bar inst 1,4 at foo.c:6,8 |
| 2 foo inst 5,10 at foo.c:2,3 |
| 3 bar inst 11,13 at foo.c:9,10 |
| |
| By default, ten lines are printed. This can be changed using the |
| 'set record function-call-history-size' command. Functions are |
| printed in execution order. There are several ways to specify what |
| to print: |
| |
| 'record function-call-history FUNC' |
| Prints ten functions starting from function number FUNC. |
| |
| 'record function-call-history FUNC, +/-N' |
| Prints N functions around function number FUNC. If N is |
| preceded with '+', prints N functions after function number |
| FUNC. If N is preceded with '-', prints N functions before |
| function number FUNC. |
| |
| 'record function-call-history' |
| Prints ten more functions after the last ten-line print. |
| |
| 'record function-call-history -' |
| Prints ten more functions before the last ten-line print. |
| |
| 'record function-call-history BEGIN, END' |
| Prints functions beginning with function number BEGIN until |
| function number END. The function number END is included. |
| |
| This command may not be available for all recording methods. |
| |
| 'set record function-call-history-size SIZE' |
| 'set record function-call-history-size unlimited' |
| Define how many lines to print in the 'record |
| function-call-history' command. The default value is 10. A size |
| of 'unlimited' means unlimited lines. |
| |
| 'show record function-call-history-size' |
| Show how many lines to print in the 'record function-call-history' |
| command. |
| |
| |
| File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top |
| |
| 8 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 |
| * Frame Apply:: Applying a command to several frames |
| * Frame Filter Management:: Managing frame filters |
| |
| |
| File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack |
| |
| 8.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 labels each existing stack frame with a "level", a number that is |
| zero for the innermost frame, one for the frame that called it, and so |
| on upward. These level numbers give you a way of designating stack |
| frames in GDB commands. The terms "frame number" and "frame level" can |
| be used interchangeably to describe this number. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack |
| |
| 8.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. |
| |
| To print a backtrace of the entire stack, use the 'backtrace' |
| command, or its alias 'bt'. This command will print one line per frame |
| for frames in the stack. By default, all stack frames are printed. You |
| can stop the backtrace at any time by typing the system interrupt |
| character, normally 'Ctrl-c'. |
| |
| 'backtrace [OPTION]... [QUALIFIER]... [COUNT]' |
| 'bt [OPTION]... [QUALIFIER]... [COUNT]' |
| Print the backtrace of the entire stack. |
| |
| The optional COUNT can be one of the following: |
| |
| 'N' |
| 'N' |
| Print only the innermost N frames, where N is a positive |
| number. |
| |
| '-N' |
| '-N' |
| Print only the outermost N frames, where N is a positive |
| number. |
| |
| Options: |
| |
| '-full' |
| Print the values of the local variables also. This can be |
| combined with the optional COUNT to limit the number of frames |
| shown. |
| |
| '-no-filters' |
| Do not run Python frame filters on this backtrace. *Note |
| Frame Filter API::, for more information. Additionally use |
| *note disable frame-filter all:: to turn off all frame |
| filters. This is only relevant when GDB has been configured |
| with 'Python' support. |
| |
| '-hide' |
| A Python frame filter might decide to "elide" some frames. |
| Normally such elided frames are still printed, but they are |
| indented relative to the filtered frames that cause them to be |
| elided. The '-hide' option causes elided frames to not be |
| printed at all. |
| |
| The 'backtrace' command also supports a number of options that |
| allow overriding relevant global print settings as set by 'set |
| backtrace' and 'set print' subcommands: |
| |
| '-past-main [on|off]' |
| Set whether backtraces should continue past 'main'. Related |
| setting: *note set backtrace past-main::. |
| |
| '-past-entry [on|off]' |
| Set whether backtraces should continue past the entry point of |
| a program. Related setting: *note set backtrace past-entry::. |
| |
| '-entry-values no|only|preferred|if-needed|both|compact|default' |
| Set printing of function arguments at function entry. Related |
| setting: *note set print entry-values::. |
| |
| '-frame-arguments all|scalars|none' |
| Set printing of non-scalar frame arguments. Related setting: |
| *note set print frame-arguments::. |
| |
| '-raw-frame-arguments [on|off]' |
| Set whether to print frame arguments in raw form. Related |
| setting: *note set print raw-frame-arguments::. |
| |
| '-frame-info auto|source-line|location|source-and-location|location-and-address|short-location' |
| Set printing of frame information. Related setting: *note set |
| print frame-info::. |
| |
| The optional QUALIFIER is maintained for backward compatibility. |
| It can be one of the following: |
| |
| 'full' |
| Equivalent to the '-full' option. |
| |
| 'no-filters' |
| Equivalent to the '-no-filters' option. |
| |
| 'hide' |
| Equivalent to the '-hide' option. |
| |
| 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, data=...) 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'. |
| |
| The value of parameter 'data' in frame 1 has been replaced by '...'. By |
| default, GDB prints the value of a parameter only if it is a scalar |
| (integer, pointer, enumeration, etc). See command 'set print |
| frame-arguments' in *note Print Settings:: for more details on how to |
| configure the way function parameter values are printed. The command |
| 'set print frame-info' (*note Print Settings::) controls what frame |
| information is printed. |
| |
| 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=<optimized out>) at macro.c:242 |
| #2 0x6840 in expand_token (obs=0x0, t=<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 '<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' |
| 'set backtrace limit unlimited' |
| Limit the backtrace to N levels. A value of 'unlimited' or zero |
| means unlimited levels. |
| |
| 'show backtrace limit' |
| Display the current limit on backtrace levels. |
| |
| You can control how file names are displayed. |
| |
| 'set filename-display' |
| 'set filename-display relative' |
| Display file names relative to the compilation directory. This is |
| the default. |
| |
| 'set filename-display basename' |
| Display only basename of a filename. |
| |
| 'set filename-display absolute' |
| Display an absolute filename. |
| |
| 'show filename-display' |
| Show the current way to display filenames. |
| |
| ---------- 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 |
| |
| 8.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 [ FRAME-SELECTION-SPEC ]' |
| 'f [ FRAME-SELECTION-SPEC ]' |
| The 'frame' command allows different stack frames to be selected. |
| The FRAME-SELECTION-SPEC can be any of the following: |
| |
| 'NUM' |
| 'level NUM' |
| Select frame level NUM. 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 level |
| frame is usually the one for 'main'. |
| |
| As this is the most common method of navigating the frame |
| stack, the string 'level' can be omitted. For example, the |
| following two commands are equivalent: |
| |
| (gdb) frame 3 |
| (gdb) frame level 3 |
| |
| 'address STACK-ADDRESS' |
| Select the frame with stack address STACK-ADDRESS. The |
| STACK-ADDRESS for a frame can be seen in the output of 'info |
| frame', for example: |
| |
| (gdb) info frame |
| Stack level 1, frame at 0x7fffffffda30: |
| rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 |
| tail call frame, caller of frame at 0x7fffffffda30 |
| source language c++. |
| Arglist at unknown address. |
| Locals at unknown address, Previous frame's sp is 0x7fffffffda30 |
| |
| The STACK-ADDRESS for this frame is '0x7fffffffda30' as |
| indicated by the line: |
| |
| Stack level 1, frame at 0x7fffffffda30: |
| |
| 'function FUNCTION-NAME' |
| Select the stack frame for function FUNCTION-NAME. If there |
| are multiple stack frames for function FUNCTION-NAME then the |
| inner most stack frame is selected. |
| |
| 'view STACK-ADDRESS [ PC-ADDR ]' |
| View a frame that is not part of GDB's backtrace. The frame |
| viewed has stack address STACK-ADDR, and optionally, a program |
| counter address of PC-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. |
| |
| When viewing a frame outside the current backtrace using |
| 'frame view' then you can always return to the original stack |
| using one of the previous stack frame selection instructions, |
| for example 'frame level 0'. |
| |
| 'up N' |
| Move N frames up the stack; N defaults to 1. For positive numbers |
| N, this advances toward the outermost frame, to higher frame |
| numbers, to frames that have existed longer. |
| |
| 'down N' |
| Move N frames down the stack; N defaults to 1. For positive |
| numbers N, this advances toward the innermost frame, to lower frame |
| numbers, to frames that were created more recently. 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. |
| |
| 'select-frame [ FRAME-SELECTION-SPEC ]' |
| The 'select-frame' command is a variant of 'frame' that does not |
| display the new frame after selecting it. This command is intended |
| primarily for use in GDB command scripts, where the output might be |
| unnecessary and distracting. The FRAME-SELECTION-SPEC is as for |
| the 'frame' command described in *note Selecting a Frame: |
| Selection. |
| |
| '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, Next: Frame Apply, Prev: Selection, Up: Stack |
| |
| 8.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 [ FRAME-SELECTION-SPEC ]' |
| 'info f [ FRAME-SELECTION-SPEC ]' |
| Print a verbose description of the frame selected by |
| FRAME-SELECTION-SPEC. The FRAME-SELECTION-SPEC is the same as for |
| the 'frame' command (*note Selecting a Frame: Selection.). The |
| selected frame remains unchanged by this command. |
| |
| 'info args [-q]' |
| Print the arguments of the selected frame, each on a separate line. |
| |
| The optional flag '-q', which stands for 'quiet', disables printing |
| header information and messages explaining why no argument have |
| been printed. |
| |
| 'info args [-q] [-t TYPE_REGEXP] [REGEXP]' |
| Like 'info args', but only print the arguments selected with the |
| provided regexp(s). |
| |
| If REGEXP is provided, print only the arguments whose names match |
| the regular expression REGEXP. |
| |
| If TYPE_REGEXP is provided, print only the arguments whose types, |
| as printed by the 'whatis' command, match the regular expression |
| TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be |
| enclosed in quote characters. If needed, use backslash to escape |
| the meaning of special characters or quotes. |
| |
| If both REGEXP and TYPE_REGEXP are provided, an argument is printed |
| only if its name matches REGEXP and its type matches TYPE_REGEXP. |
| |
| 'info locals [-q]' |
| 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. |
| |
| The optional flag '-q', which stands for 'quiet', disables printing |
| header information and messages explaining why no local variables |
| have been printed. |
| |
| 'info locals [-q] [-t TYPE_REGEXP] [REGEXP]' |
| Like 'info locals', but only print the local variables selected |
| with the provided regexp(s). |
| |
| If REGEXP is provided, print only the local variables whose names |
| match the regular expression REGEXP. |
| |
| If TYPE_REGEXP is provided, print only the local variables whose |
| types, as printed by the 'whatis' command, match the regular |
| expression TYPE_REGEXP. If TYPE_REGEXP contains space(s), it |
| should be enclosed in quote characters. If needed, use backslash |
| to escape the meaning of special characters or quotes. |
| |
| If both REGEXP and TYPE_REGEXP are provided, a local variable is |
| printed only if its name matches REGEXP and its type matches |
| TYPE_REGEXP. |
| |
| The command 'info locals -q -t TYPE_REGEXP' can usefully be |
| combined with the commands 'frame apply' and 'thread apply'. For |
| example, your program might use Resource Acquisition Is |
| Initialization types (RAII) such as 'lock_something_t': each local |
| variable of type 'lock_something_t' automatically places a lock |
| that is destroyed when the variable goes out of scope. You can |
| then list all acquired locks in your program by doing |
| thread apply all -s frame apply all -s info locals -q -t lock_something_t |
| or the equivalent shorter form |
| tfaas i lo -q -t lock_something_t |
| |