diff options
Diffstat (limited to 'share/info/gdb.info')
| -rw-r--r-- | share/info/gdb.info | 39097 |
1 files changed, 0 insertions, 39097 deletions
diff --git a/share/info/gdb.info b/share/info/gdb.info deleted file mode 100644 index 5838703..0000000 --- a/share/info/gdb.info +++ /dev/null @@ -1,39097 +0,0 @@ -This is gdb.info, produced by makeinfo version 4.13 from -/Volumes/androidtc/androidtoolchain/./src/build/../gdb/gdb-7.3.x/gdb/doc/gdb.texinfo. - -INFO-DIR-SECTION Software development -START-INFO-DIR-ENTRY -* Gdb: (gdb). The GNU debugger. -END-INFO-DIR-ENTRY - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010 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." - - 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 7.3.1-gg2. - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010 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 7.3.1-gg2. - - Copyright (C) 1988-2010 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. - -* 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 -* Copying:: GNU General Public License says - how you can copy and share GDB -* GNU Free Documentation License:: The license for this documentation -* Index:: Index - - -File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top - -Summary of GDB -************** - -The purpose of a debugger such as GDB is to allow you to see what is -going on "inside" another program while it executes--or what another -program was doing at the moment it crashed. - - GDB can do four main kinds of things (plus other things in support of -these) to help you catch bugs in the act: - - * Start your program, specifying anything that might affect its - behavior. - - * Make your program stop on specified conditions. - - * Examine what has happened, when your program has stopped. - - * Change things in your program, so you can experiment with - correcting the effects of one bug and go on to learn about another. - - You can use GDB to debug programs written in C and C++. For more -information, see *note Supported Languages: Supported Languages. For -more information, see *note C and C++: C. - - Support for 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 -* Contributors:: Contributors to GDB - - -File: gdb.info, Node: Free Software, Next: Contributors, Up: Summary - -Free Software -============= - -GDB is "free software", protected by the GNU General Public License -(GPL). The GPL gives you the freedom to copy or adapt a licensed -program--but every person getting a copy also gets with it the freedom -to modify that copy (which means that they must get access to the -source code), and the freedom to distribute further copies. Typical -software companies use copyrights to limit your freedoms; the Free -Software Foundation uses the GPL to preserve these freedoms. - - Fundamentally, the General Public License is a license which says -that you have these freedoms and that you cannot take these freedoms -away from anyone else. - -Free Software Needs Free Documentation -====================================== - -The biggest deficiency in the free software community today is not in -the software--it is the lack of good free documentation that we can -include with the free software. Many of our most important programs do -not come with free reference manuals and free introductory texts. -Documentation is an essential part of any software package; when an -important free software package does not come with a free manual and a -free tutorial, that is a major gap. We have many such gaps today. - - Consider Perl, for instance. The tutorial manuals that people -normally use are non-free. How did this come about? Because the -authors of those manuals published them with restrictive terms--no -copying, no modification, source files not available--which exclude -them from the free software world. - - That wasn't the first time this sort of thing happened, and it was -far from the last. Many times we have heard a GNU user eagerly -describe a manual that he is writing, his intended contribution to the -community, only to learn that he had ruined everything by signing a -publication contract to make it non-free. - - Free documentation, like free software, is a matter of freedom, not -price. The problem with the non-free manual is not that publishers -charge a price for printed copies--that in itself is fine. (The Free -Software Foundation sells printed copies of manuals, too.) The problem -is the restrictions on the use of the manual. Free manuals are -available in source code form, and give you permission to copy and -modify. Non-free manuals do not allow this. - - The criteria of freedom for a free manual are roughly the same as for -free software. Redistribution (including the normal kinds of -commercial redistribution) must be permitted, so that the manual can -accompany every copy of the program, both on-line and on paper. - - Permission for modification of the technical content is crucial too. -When people modify the software, adding or changing features, if they -are conscientious they will change the manual too--so they can provide -accurate and clear documentation for the modified program. A manual -that leaves you no choice but to write a new manual to document a -changed version of the program is not really available to our community. - - Some kinds of limits on the way modification is handled are -acceptable. For example, requirements to preserve the original -author's copyright notice, the distribution terms, or the list of -authors, are ok. It is also no problem to require modified versions to -include notice that they were modified. Even entire sections that may -not be deleted or changed are acceptable, as long as they deal with -nontechnical topics (like this one). These kinds of restrictions are -acceptable because they don't obstruct the community's normal use of -the manual. - - However, it must be possible to modify all the _technical_ content -of the manual, and then distribute the result in all the usual media, -through all the usual channels. Otherwise, the restrictions obstruct -the use of the manual, it is not free, and we need another manual to -replace it. - - Please spread the word about this issue. Our community continues to -lose manuals to proprietary publishing. If we spread the word that -free software needs free reference manuals and free tutorials, perhaps -the next person who wants to contribute by writing documentation will -realize, before it is too late, that only free manuals contribute to -the free software community. - - If you are writing documentation, please insist on publishing it -under the GNU Free Documentation License or another free documentation -license. Remember that this decision requires your approval--you don't -have to let the publisher decide. Some commercial publishers will use -a free license if you insist, but they will not propose the option; it -is up to you to raise the issue and say firmly that this is what you -want. If the publisher you are dealing with refuses, please try other -publishers. If you're not sure whether a proposed license is free, -write to <licensing@gnu.org>. - - You can encourage commercial publishers to sell more free, copylefted -manuals and tutorials by buying them, and particularly by buying copies -from the publishers that paid for their writing or for major -improvements. Meanwhile, try to avoid buying non-free documentation at -all. Check the distribution terms of a manual before you buy it, and -insist that whoever seeks your business must respect your freedom. -Check the history of the book, and try to reward the publishers that -have paid or pay the authors to work on it. - - The Free Software Foundation maintains a list of free documentation -published by other publishers, at -`http://www.fsf.org/doc/other-free-books.html'. - - -File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary - -Contributors to GDB -=================== - -Richard Stallman was the original author of GDB, and of many other GNU -programs. Many others have contributed to its development. This -section attempts to credit major contributors. One of the virtues of -free software is that everyone is free to contribute to it; with -regret, we cannot actually acknowledge everyone here. The file -`ChangeLog' in the GDB distribution approximates a blow-by-blow account. - - Changes much prior to version 2.0 are lost in the mists of time. - - _Plea:_ Additions to this section are particularly welcome. If you - or your friends (or enemies, to be evenhanded) have been unfairly - omitted from this list, we would like to add your names! - - So that they may not regard their many labors as thankless, we -particularly thank those who shepherded GDB through major releases: -Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim -Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs -(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, -and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, -and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim -Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, -3.1, and 3.0). - - Richard Stallman, assisted at various times by Peter TerMaat, Chris -Hanson, and Richard Mlynarik, handled releases through 2.8. - - Michael Tiemann is the author of most of the GNU C++ support in GDB, -with significant additional contributions from Per Bothner and Daniel -Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ -was by Peter TerMaat (who also did much general update work leading to -release 3.0). - - GDB uses the BFD subroutine library to examine multiple object-file -formats; BFD was a joint project of David V. Henkel-Wallace, Rich -Pixley, Steve Chamberlain, and John Gilmore. - - David Johnson wrote the original COFF support; Pace Willison did the -original support for encapsulated COFF. - - Brent Benson of Harris Computer Systems contributed DWARF 2 support. - - Adam de Boor and Bradley Davis contributed the ISI Optimum V support. -Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS -support. Jean-Daniel Fekete contributed Sun 386i support. Chris -Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki -Hasei contributed Sony/News OS 3 support. David Johnson contributed -Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. -Jeff Law contributed HP PA and SOM support. Keith Packard contributed -NS32K support. Doug Rabson contributed Acorn Risc Machine support. -Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith -contributed Convex support (and Fortran debugging). Jonathan Stone -contributed Pyramid support. Michael Tiemann contributed SPARC support. -Tim Tucker contributed support for the Gould NP1 and Gould Powernode. -Pace Willison contributed Intel 386 support. Jay Vosburgh contributed -Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. - - Andreas Schwab contributed M68K GNU/Linux support. - - Rich Schaefer and Peter Schauer helped with support of SunOS shared -libraries. - - Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about -several machine instruction sets. - - Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped -develop remote debugging. Intel Corporation, Wind River Systems, AMD, -and ARM contributed remote debugging modules for the i960, VxWorks, -A29K UDI, and RDI targets, respectively. - - Brian Fox is the author of the readline libraries providing -command-line editing and command history. - - Andrew Beers of SUNY Buffalo wrote the language-switching code, the -Modula-2 support, and contributed the Languages chapter of this manual. - - Fred Fish wrote most of the support for Unix System Vr4. He also -enhanced the command-completion support to cover C++ overloaded symbols. - - Hitachi America (now Renesas America), Ltd. sponsored the support for -H8/300, H8/500, and Super-H processors. - - NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx -processors. - - Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and -M32R/D processors. - - Toshiba sponsored the support for the TX39 Mips processor. - - Matsushita sponsored the support for the MN10200 and MN10300 -processors. - - Fujitsu sponsored the support for SPARClite and FR30 processors. - - Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware -watchpoints. - - Michael Snyder added support for tracepoints. - - Stu Grossman wrote gdbserver. - - Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly -innumerable bug fixes and cleanups throughout GDB. - - The following people at the Hewlett-Packard Company contributed -support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 -(narrow mode), HP's implementation of kernel threads, HP's aC++ -compiler, and the Text User Interface (nee Terminal User Interface): -Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, -Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase -provided HP-specific information in this manual. - - DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert -Hoehne made significant contributions to the DJGPP port. - - Cygnus Solutions has sponsored GDB maintenance and much of its -development since 1991. Cygnus engineers who have worked on GDB -fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin -Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim -Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, -Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek -Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In -addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, -JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug -Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff -Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, -Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin -Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela -Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David -Zuhn have made contributions both large and small. - - Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for -Cygnus Solutions, implemented the original GDB/MI interface. - - Jim Blandy added support for preprocessor macros, while working for -Red Hat. - - Andrew Cagney designed GDB's architecture vector. Many people -including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, -Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, -Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna -Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration -of old architectures to this new framework. - - Andrew Cagney completely re-designed and re-implemented GDB's -unwinder framework, this consisting of a fresh new design featuring -frame IDs, independent frame sniffers, and the sentinel frame. Mark -Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind -unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad -unwinders. The architecture-specific changes, each involving a -complete rewrite of the architecture's frame code, were carried out by -Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane -Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel -Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei -Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich -Weigand. - - Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from -Tensilica, Inc. contributed support for Xtensa processors. Others who -have worked on the Xtensa port of GDB in the past include Steve Tjiang, -John Newlin, and Scott Foehner. - - Michael Eager and staff of Xilinx, Inc., contributed support for the -Xilinx MicroBlaze architecture. - - -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 7.3.1-gg2, Copyright 1999 Free Software Foundation, Inc... - (gdb) - -GDB reads only enough symbol data to know where to find the rest when -needed; as a result, the first prompt comes up very quickly. We now -tell GDB to use a narrower display width than usual, so that examples -fit in this manual. - - (gdb) set width 70 - -We need to see how the `m4' built-in `changequote' works. Having -looked at the source, we know the relevant subroutine is -`m4_changequote', so we set a breakpoint there with the GDB `break' -command. - - (gdb) break m4_changequote - Breakpoint 1 at 0x62f4: file builtin.c, line 879. - -Using the `run' command, we start `m4' running under GDB control; as -long as control does not reach the `m4_changequote' subroutine, the -program runs as usual: - - (gdb) run - Starting program: /work/Editorial/gdb/gnu/m4/m4 - define(foo,0000) - - foo - 0000 - -To trigger the breakpoint, we call `changequote'. GDB suspends -execution of `m4', displaying information about the context where it -stops. - - changequote(<QUOTE>,<UNQUOTE>) - - Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) - at builtin.c:879 - 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) - -Now we use the command `n' (`next') to advance execution to the next -line of the current function. - - (gdb) n - 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ - : nil, - -`set_quotes' looks like a promising subroutine. We can go into it by -using the command `s' (`step') instead of `next'. `step' goes to the -next line to be executed in _any_ subroutine, so it steps into -`set_quotes'. - - (gdb) s - set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") - at input.c:530 - 530 if (lquote != def_lquote) - -The display that shows the subroutine where `m4' is now suspended (and -its arguments) is called a stack frame display. It shows a summary of -the stack. We can use the `backtrace' command (which can also be -spelled `bt'), to see where we are in the stack as a whole: the -`backtrace' command displays a stack frame for each active subroutine. - - (gdb) bt - #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") - at input.c:530 - #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) - at builtin.c:882 - #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 - #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) - at macro.c:71 - #4 0x79dc in expand_input () at macro.c:40 - #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 - -We step through a few more lines to see what happens. The first two -times, we can use `s'; the next two times we use `n' to avoid falling -into the `xstrdup' subroutine. - - (gdb) s - 0x3b5c 532 if (rquote != def_rquote) - (gdb) s - 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ - def_lquote : xstrdup(lq); - (gdb) n - 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ - : xstrdup(rq); - (gdb) n - 538 len_lquote = strlen(rquote); - -The last line displayed looks a little odd; we can examine the variables -`lquote' and `rquote' to see if they are in fact the new left and right -quotes we specified. We use the command `p' (`print') to see their -values. - - (gdb) p lquote - $1 = 0x35d40 "<QUOTE>" - (gdb) p rquote - $2 = 0x35d50 "<UNQUOTE>" - -`lquote' and `rquote' are indeed the new left and right quotes. To -look at some context, we can display ten lines of source surrounding -the current line with the `l' (`list') command. - - (gdb) l - 533 xfree(rquote); - 534 - 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ - : xstrdup (lq); - 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ - : xstrdup (rq); - 537 - 538 len_lquote = strlen(rquote); - 539 len_rquote = strlen(lquote); - 540 } - 541 - 542 void - -Let us step past the two lines that set `len_lquote' and `len_rquote', -and then examine the values of those variables. - - (gdb) n - 539 len_rquote = strlen(lquote); - (gdb) n - 540 } - (gdb) p len_lquote - $3 = 9 - (gdb) p len_rquote - $4 = 7 - -That certainly looks wrong, assuming `len_lquote' and `len_rquote' are -meant to be the lengths of `lquote' and `rquote' respectively. We can -set them to better values using the `p' command, since it can print the -value of any expression--and that expression can include subroutine -calls and assignments. - - (gdb) p len_lquote=strlen(lquote) - $5 = 7 - (gdb) p len_rquote=strlen(rquote) - $6 = 9 - -Is that enough to fix the problem of using the new quotes with the `m4' -built-in `defn'? We can allow `m4' to continue executing with the `c' -(`continue') command, and then try the example that caused trouble -initially: - - (gdb) c - Continuing. - - define(baz,defn(<QUOTE>foo<UNQUOTE>)) - - baz - 0000 - -Success! The new quotes now work just as well as the default ones. The -problem seems to have been just the two typos defining the wrong -lengths. We allow `m4' exit by giving it an EOF as input: - - Ctrl-d - Program exited normally. - -The message `Program exited normally.' is from GDB; it indicates `m4' -has finished executing. We can end our GDB session with the GDB `quit' -command. - - (gdb) quit - - -File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top - -2 Getting In and Out of GDB -*************************** - -This chapter discusses how to start GDB, and how to get out of it. The -essentials are: - * type `gdb' to start GDB. - - * type `quit' or `Ctrl-d' to exit. - -* Menu: - -* Invoking GDB:: How to start GDB -* Quitting GDB:: How to quit GDB -* Shell Commands:: How to use shell commands inside GDB -* Logging Output:: How to log GDB's output to a file - - -File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation - -2.1 Invoking GDB -================ - -Invoke GDB by running the program `gdb'. Once started, GDB reads -commands from the terminal until you tell it to exit. - - You can also run `gdb' with a variety of arguments and options, to -specify more of your debugging environment at the outset. - - The command-line options described here are designed to cover a -variety of situations; in some environments, some of these options may -effectively be unavailable. - - The most usual way to start GDB is with one argument, specifying an -executable program: - - gdb PROGRAM - -You can also start with both an executable program and a core file -specified: - - gdb PROGRAM CORE - - You can, instead, specify a process ID as a second argument, if you -want to debug a running process: - - gdb PROGRAM 1234 - -would attach GDB to process `1234' (unless you also have a file named -`1234'; GDB does check for a core file first). - - Taking advantage of the second command-line argument requires a -fairly complete operating system; when you use GDB as a remote debugger -attached to a bare board, there may not be any notion of "process", and -there is often no way to get a core dump. GDB will warn you if it is -unable to attach or to read core dumps. - - You can optionally have `gdb' pass any arguments after the -executable file to the inferior using `--args'. This option stops -option processing. - gdb --args gcc -O2 -c foo.c - This will cause `gdb' to debug `gcc', and to set `gcc''s -command-line arguments (*note Arguments::) to `-O2 -c foo.c'. - - You can run `gdb' without printing the front material, which -describes GDB's non-warranty, by specifying `-silent': - - gdb -silent - -You can further control how GDB starts up by using command-line -options. GDB itself can remind you of the options available. - -Type - - gdb -help - -to display all available options and briefly describe their use (`gdb --h' is a shorter equivalent). - - All options and command line arguments you give are processed in -sequential order. The order makes a difference when the `-x' option is -used. - -* Menu: - -* File Options:: Choosing files -* Mode Options:: Choosing modes -* Startup:: What GDB does during startup - - -File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB - -2.1.1 Choosing Files --------------------- - -When GDB starts, it reads any arguments other than options as -specifying an executable file and core file (or process ID). This is -the same as if the arguments were specified by the `-se' and `-c' (or -`-p') options respectively. (GDB reads the first argument that does -not have an associated option flag as equivalent to the `-se' option -followed by that argument; and the second argument that does not have -an associated option flag, if any, as equivalent to the `-c'/`-p' -option followed by that argument.) If the second argument begins with -a decimal digit, GDB will first attempt to attach to it as a process, -and if that fails, attempt to open it as a corefile. If you have a -corefile whose name begins with a digit, you can prevent GDB from -treating it as a pid by prefixing it with `./', e.g. `./12345'. - - If GDB has not been configured to included core file support, such -as for most embedded targets, then it will complain about a second -argument and ignore it. - - Many options have both long and short forms; both are shown in the -following list. GDB also recognizes the long forms if you truncate -them, so long as enough of the option is present to be unambiguous. -(If you prefer, you can flag option arguments with `--' rather than -`-', though we illustrate the more usual convention.) - -`-symbols FILE' -`-s FILE' - Read symbol table from file FILE. - -`-exec FILE' -`-e FILE' - Use file FILE as the executable file to execute when appropriate, - and for examining pure data in conjunction with a core dump. - -`-se FILE' - Read symbol table from file FILE and use it as the executable file. - -`-core FILE' -`-c FILE' - Use file FILE as a core dump to examine. - -`-pid NUMBER' -`-p NUMBER' - Connect to process ID NUMBER, as with the `attach' command. - -`-command FILE' -`-x FILE' - Execute 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 - -`-directory DIRECTORY' -`-d DIRECTORY' - Add DIRECTORY to the path to search for source and script files. - -`-r' -`-readnow' - Read each symbol file's entire symbol table immediately, rather - than the default, which is to read it incrementally as it is - needed. This makes startup slower, but makes future operations - faster. - - - -File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB - -2.1.2 Choosing Modes --------------------- - -You can run GDB in various alternative modes--for example, in batch -mode or quiet mode. - -`-nx' -`-n' - Do not execute commands found in any initialization files. - Normally, GDB executes the commands in these files after all the - command options and arguments have been processed. *Note Command - Files: Command Files. - -`-quiet' -`-silent' -`-q' - "Quiet". Do not print the introductory and copyright messages. - These messages are also suppressed in batch mode. - -`-batch' - Run in batch mode. Exit with status `0' after processing all the - command files specified with `-x' (and all commands from - initialization files, if not inhibited with `-n'). Exit with - nonzero status if an error occurs in executing the GDB commands in - the command files. Batch mode 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' - 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. - -`-epoch' - The Epoch Emacs-GDB interface sets this option when it runs GDB as - a subprocess. It tells GDB to modify its print routines so as to - allow Epoch to display values of expressions in a separate window. - -`-annotate LEVEL' - This option sets the "annotation level" inside GDB. Its effect is - identical to using `set annotate LEVEL' (*note Annotations::). - The annotation LEVEL controls how much information GDB prints - together with its prompt, values of expressions, source lines, and - other types of output. Level 0 is the normal, level 1 is for use - when GDB is run as a subprocess of GNU Emacs, level 3 is the - maximum annotation suitable for programs that control GDB, and - level 2 has been deprecated. - - The annotation mechanism has largely been superseded by GDB/MI - (*note GDB/MI::). - -`--args' - Change interpretation of command line so that arguments following - the executable file are passed as command line arguments to the - inferior. This option stops option processing. - -`-baud BPS' -`-b BPS' - Set the line speed (baud rate or bits per second) of any serial - interface used by GDB for remote debugging. - -`-l TIMEOUT' - Set the timeout (in seconds) of any communication used by GDB for - remote debugging. - -`-tty DEVICE' -`-t DEVICE' - Run using DEVICE for your program's standard input and output. - -`-tui' - Activate the "Text User Interface" when starting. The Text User - Interface manages several text windows on the terminal, showing - source, assembly, registers and GDB command outputs (*note GDB - Text User Interface: TUI.). Alternatively, the Text User - Interface can be enabled by invoking the program `gdbtui'. Do not - use this option if you run GDB from Emacs (*note Using GDB under - GNU Emacs: Emacs.). - -`-interpreter INTERP' - Use the interpreter INTERP for interface with the controlling - program or device. This option is meant to be set by programs - which communicate with GDB using it as a back end. *Note Command - Interpreters: Interpreters. - - `--interpreter=mi' (or `--interpreter=mi2') causes GDB to use the - "GDB/MI interface" (*note The GDB/MI Interface: GDB/MI.) included - since GDB version 6.0. The previous GDB/MI interface, included in - GDB version 5.3 and selected with `--interpreter=mi1', is - deprecated. Earlier GDB/MI interfaces are no longer supported. - -`-write' - Open the executable and core files for both reading and writing. - This is equivalent to the `set write on' command inside GDB (*note - Patching::). - -`-statistics' - This option causes GDB to print statistics about time and memory - usage after it completes each command and returns to the prompt. - -`-version' - This option causes GDB to print its version number and no-warranty - blurb, and exit. - -`-disable-gdb-index' - This option causes GDB to avoid using the `.gdb_index' ELF - section, even if present in the executable or a shared library. - This section improves the speed of loading of debug information. - This option is present as an escape hatch in case there is a - problem with the contents of this section. - - - -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 executes all the - commands in that file. - - 3. Reads the init file (if any) in your home directory(1) and - executes all the commands in that file. - - 4. Processes command line options and operands. - - 5. Reads and executes the commands from init file (if any) in the - current working directory. This is only done if the current - directory is different from your home directory. Thus, you can - have more than one init file, one generic in your home directory, - and another, specific to the program you are debugging, in the - directory where you invoke GDB. - - 6. 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 -ex "set auto-load-scripts off" -ex "file myprogram" - - The following does not work because the auto-loading is turned off - too late: - - $ gdb -ex "set auto-load-scripts off" myprogram - - 7. Reads command files specified by the `-x' option. *Note Command - Files::, for more details about GDB command files. - - 8. 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 ports of GDB use the standard -name, but if they find a `gdb.ini' file, they warn you about that and -suggest to rename the file to the standard name. - - ---------- Footnotes ---------- - - (1) On DOS/Windows systems, the home directory is the one pointed to -by the `HOME' environment variable. - - -File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation - -2.2 Quitting GDB -================ - -`quit [EXPRESSION]' -`q' - To exit GDB, use the `quit' command (abbreviated `q'), or type an - end-of-file character (usually `Ctrl-d'). If you do not supply - EXPRESSION, GDB will terminate normally; otherwise it will - terminate using the result of EXPRESSION as the error code. - - An interrupt (often `Ctrl-c') does not exit from GDB, but rather -terminates the action of any GDB command that is in progress and -returns to GDB command level. It is safe to type the interrupt -character at any time because GDB does not allow it to take effect -until a time when it is safe. - - If you have been using GDB to control an attached process or device, -you can release it with the `detach' command (*note Debugging an -Already-running Process: Attach.). - - -File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation - -2.3 Shell Commands -================== - -If you need to execute occasional shell commands during your debugging -session, there is no need to leave or suspend GDB; you can just use the -`shell' command. - -`shell COMMAND STRING' - Invoke a standard shell to execute COMMAND STRING. If it exists, - the environment variable `SHELL' determines which shell to run. - Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, - `COMMAND.COM' on MS-DOS, etc.). - - The utility `make' is often needed in development environments. You -do not have to use the `shell' command for this purpose in GDB: - -`make MAKE-ARGS' - Execute the `make' program with the specified arguments. This is - equivalent to `shell make MAKE-ARGS'. - - -File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation - -2.4 Logging Output -================== - -You may want to save the output of GDB commands to a file. There are -several commands to control GDB's logging. - -`set logging on' - Enable logging. - -`set logging off' - Disable logging. - -`set logging file FILE' - Change the name of the current logfile. The default logfile is - `gdb.txt'. - -`set logging overwrite [on|off]' - By default, GDB will append to the logfile. Set `overwrite' if - you want `set logging on' to overwrite the logfile instead. - -`set logging redirect [on|off]' - By default, GDB output will go to both the terminal and the - logfile. Set `redirect' if you want output to go only to the log - file. - -`show logging' - Show the current values of the logging settings. - - -File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top - -3 GDB Commands -************** - -You can abbreviate a GDB command to the first few letters of the command -name, if that abbreviation is unambiguous; and you can repeat certain -GDB commands by typing just <RET>. You can also use the <TAB> key to -get GDB to fill out the rest of a word in a command (or to show you the -alternatives available, if there is more than one possibility). - -* Menu: - -* Command Syntax:: How to give commands to GDB -* Completion:: Command completion -* Help:: How to ask GDB for help - - -File: gdb.info, Node: Command Syntax, Next: Completion, Up: Commands - -3.1 Command Syntax -================== - -A GDB command is a single line of input. There is no limit on how long -it can be. It starts with a command name, which is followed by -arguments whose meaning depends on the command name. For example, the -command `step' accepts an argument which is the number of times to -step, as in `step 5'. You can also use the `step' command with no -arguments. Some commands do not allow any arguments. - - GDB command names may always be truncated if that abbreviation is -unambiguous. Other possible command abbreviations are listed in the -documentation for individual commands. In some cases, even ambiguous -abbreviations are allowed; for example, `s' is specially defined as -equivalent to `step' even though there are other commands whose names -start with `s'. You can test abbreviations by using them as arguments -to the `help' command. - - A blank line as input to GDB (typing just <RET>) means to repeat the -previous command. Certain commands (for example, `run') will not -repeat this way; these are commands whose unintentional repetition -might cause trouble and which you are unlikely to want to repeat. -User-defined commands can disable this feature; see *note dont-repeat: -Define. - - The `list' and `x' commands, when you repeat them with <RET>, -construct new arguments rather than repeating exactly as typed. This -permits easy scanning of source or memory. - - GDB can also use <RET> in another way: to partition lengthy output, -in a way similar to the common utility `more' (*note Screen Size: -Screen Size.). Since it is easy to press one <RET> too many in this -situation, GDB disables command repetition after any command that -generates this sort of display. - - Any text from a `#' to the end of the line is a comment; it does -nothing. This is useful mainly in command files (*note Command Files: -Command Files.). - - The `Ctrl-o' binding is useful for repeating a complex sequence of -commands. This command accepts the current line, like <RET>, and then -fetches the next line relative to the current line from the history for -editing. - - -File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands - -3.2 Command Completion -====================== - -GDB can fill in the rest of a word in a command for you, if there is -only one possibility; it can also show you what the valid possibilities -are for the next word in a command, at any time. This works for GDB -commands, GDB subcommands, and the names of symbols in your program. - - Press the <TAB> key whenever you want GDB to fill out the rest of a -word. If there is only one possibility, GDB fills in the word, and -waits for you to finish the command (or press <RET> to enter it). For -example, if you type - - (gdb) info bre <TAB> - -GDB fills in the rest of the word `breakpoints', since that is the only -`info' subcommand beginning with `bre': - - (gdb) info breakpoints - -You can either press <RET> at this point, to run the `info breakpoints' -command, or backspace and enter something else, if `breakpoints' does -not look like the command you expected. (If you were sure you wanted -`info breakpoints' in the first place, you might as well just type -<RET> immediately after `info bre', to exploit command abbreviations -rather than command completion). - - If there is more than one possibility for the next word when you -press <TAB>, GDB sounds a bell. You can either supply more characters -and try again, or just press <TAB> a second time; GDB displays all the -possible completions for that word. For example, you might want to set -a breakpoint on a subroutine whose name begins with `make_', but when -you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again -displays all the function names in your program that begin with those -characters, for example: - - (gdb) b make_ <TAB> -GDB sounds bell; press <TAB> again, to see: - make_a_section_from_file make_environ - make_abs_section make_function_type - make_blockvector make_pointer_type - make_cleanup make_reference_type - make_command make_symbol_completion_list - (gdb) b make_ - -After displaying the available possibilities, GDB copies your partial -input (`b make_' in the example) so you can finish the command. - - If you just want to see the list of alternatives in the first place, -you can press `M-?' rather than pressing <TAB> twice. `M-?' means -`<META> ?'. You can type this either by holding down a key designated -as the <META> shift on your keyboard (if there is one) while typing -`?', or as <ESC> followed by `?'. - - Sometimes the string you need, while logically a "word", may contain -parentheses or other characters that GDB normally excludes from its -notion of a word. To permit word completion to work in this situation, -you may enclose words in `'' (single quote marks) in GDB commands. - - The most likely situation where you might need this is in typing the -name of a C++ function. This is because C++ allows function -overloading (multiple definitions of the same function, distinguished -by argument type). For example, when you want to set a breakpoint you -may need to distinguish whether you mean the version of `name' that -takes an `int' parameter, `name(int)', or the version that takes a -`float' parameter, `name(float)'. To use the word-completion -facilities in this situation, type a single quote `'' at the beginning -of the function name. This alerts GDB that it may need to consider -more information than usual when you press <TAB> or `M-?' to request -word completion: - - (gdb) b 'bubble( M-? - bubble(double,double) bubble(int,int) - (gdb) b 'bubble( - - In some cases, GDB can tell that completing a name requires using -quotes. When this happens, GDB inserts the quote for you (while -completing as much as it can) if you do not type the quote in the first -place: - - (gdb) b bub <TAB> -GDB alters your input line to the following, and rings a bell: - (gdb) b 'bubble( - -In general, GDB can tell that a quote is needed (and inserts it) if you -have not yet started typing the argument list when you ask for -completion on an overloaded symbol. - - For more information about overloaded functions, see *note C++ -Expressions: C Plus Plus Expressions. You can use the command `set -overload-resolution off' to disable overload resolution; see *note GDB -Features for C++: Debugging C Plus Plus. - - 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_delete to_fputs to_put to_rewind - to_data to_flush to_isatty to_read to_write - -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_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: Help, Prev: Completion, Up: Commands - -3.3 Getting Help -================ - -You can always ask GDB itself for information on its commands, using -the command `help'. - -`help' -`h' - You can use `help' (abbreviated `h') with no arguments to display - a short list of named classes of commands: - - (gdb) help - List of classes of commands: - - aliases -- Aliases of other commands - breakpoints -- Making program stop at certain points - data -- Examining data - files -- Specifying and examining files - internals -- Maintenance commands - obscure -- Obscure features - running -- Running the program - stack -- Examining the stack - status -- Status inquiries - support -- Support facilities - tracepoints -- Tracing of program execution without - stopping the program - user-defined -- User-defined commands - - Type "help" followed by a class name for a list of - commands in that class. - Type "help" followed by command name for full - documentation. - Command name abbreviations are allowed if unambiguous. - (gdb) - -`help CLASS' - Using one of the general help classes as an argument, you can get a - list of the individual commands in that class. For example, here - is the help display for the class `status': - - (gdb) help status - Status inquiries. - - List of commands: - - info -- Generic command for showing things - about the program being debugged - show -- Generic command for showing things - about the debugger - - Type "help" followed by command name for full - documentation. - Command name abbreviations are allowed if unambiguous. - (gdb) - -`help COMMAND' - With a command name as `help' argument, GDB displays a short - paragraph on how to use that command. - -`apropos ARGS' - The `apropos' command searches through all of the GDB commands, - and their documentation, for the regular expression specified in - ARGS. It prints out all matches found. For example: - - apropos reload - - results in: - - set symbol-reloading -- Set dynamic symbol table reloading - multiple times in one run - show symbol-reloading -- Show dynamic symbol table reloading - multiple times in one run - -`complete ARGS' - The `complete ARGS' command lists all the possible completions for - the beginning of a command. Use ARGS to specify the beginning of - the command you want completed. For example: - - complete i - - results in: - - if - ignore - info - inspect - - This is intended for use by GNU Emacs. - - In addition to `help', you can use the GDB commands `info' and -`show' to inquire about the state of your program, or the state of GDB -itself. Each command supports many topics of inquiry; this manual -introduces each of them in the appropriate context. The listings under -`info' and under `show' in the Index point to all the sub-commands. -*Note Index::. - -`info' - This command (abbreviated `i') is for describing the state of your - program. For example, you can show the arguments passed to a - function with `info args', list the registers currently in use - with `info registers', or list the breakpoints you have set with - `info breakpoints'. You can get a complete list of the `info' - sub-commands with `help info'. - -`set' - You can assign the result of an expression to an environment - variable with `set'. For example, you can set the GDB prompt to a - $-sign with `set prompt $'. - -`show' - In contrast to `info', `show' is for describing the state of GDB - itself. You can change most of the things you can `show', by - using the related command `set'; for example, you can control what - number system is used for displays with `set radix', or simply - inquire which is currently in use with `show radix'. - - To display all the settable parameters and their current values, - you can use `show' with no arguments; you may also use `info set'. - Both commands produce the same display. - - Here are three miscellaneous `show' subcommands, all of which are -exceptional in lacking corresponding `set' commands: - -`show version' - Show what version of GDB is running. You should include this - information in GDB bug-reports. If multiple versions of GDB are - in use at your site, you may need to determine which version of - GDB you are running; as GDB evolves, new commands are introduced, - and old ones may wither away. Also, many system vendors ship - variant versions of GDB, and there are variant versions of GDB in - GNU/Linux distributions as well. The version number is the same - as the one announced when you start GDB. - -`show copying' -`info copying' - Display information about permission for copying GDB. - -`show warranty' -`info warranty' - Display the GNU "NO WARRANTY" statement, or a warranty, if your - version of GDB comes with one. - - - -File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top - -4 Running Programs Under GDB -**************************** - -When you run a program under GDB, you must first generate debugging -information when you compile it. - - You may start GDB with its arguments, if any, in an environment of -your choice. If you are doing native debugging, you may redirect your -program's input and output, debug an already running process, or kill a -child process. - -* Menu: - -* Compilation:: Compiling for debugging -* Starting:: Starting your program -* Arguments:: Your program's arguments -* Environment:: Your program's environment - -* Working Directory:: Your program's working directory -* Input/Output:: Your program's input and output -* Attach:: Debugging an already-running process -* Kill Process:: Killing the child process - -* 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, because this information is rather large. Version 3.1 -and later of GCC, the GNU C compiler, provides macro information if you -specify the options `-gdwarf-2' and `-g3'; the former option requests -debugging information in the Dwarf 2 format, and the latter requests -"extra information". In the future, we hope to find more compact ways -to represent macro information, so that it can be included with `-g' -alone. - - -File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running - -4.2 Starting your Program -========================= - -`run' -`r' - Use the `run' command to start your program under GDB. You must - first specify the program name (except on VxWorks) with an - argument to GDB (*note Getting In and Out of GDB: Invocation.), or - by using the `file' or `exec-file' command (*note Commands to - Specify Files: Files.). - - - If you are running your program in an execution environment that -supports processes, `run' creates an inferior process and makes that -process run your program. In 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. *Note - Your Program's Arguments: Arguments. - -The _environment._ - Your program normally inherits its environment from GDB, but you - can use the GDB commands `set environment' and `unset environment' - to change parts of the environment that affect your program. - *Note Your Program's Environment: Environment. - -The _working directory._ - Your program inherits its working directory from GDB. You can set - the GDB working directory with the `cd' command in GDB. *Note - Your Program's Working Directory: Working Directory. - -The _standard input and output._ - Your program normally uses the same device for standard input and - standard output as GDB is using. You can redirect input and output - in the `run' command line, or you can use the `tty' command to set - a different device for your program. *Note Your Program's Input - and Output: Input/Output. - - _Warning:_ While input and output redirection work, you cannot use - pipes to pass the output of the program you are debugging to - another program; if you attempt this, GDB is likely to wind up - debugging the wrong program. - - When you issue the `run' command, your program begins to execute -immediately. *Note Stopping and Continuing: Stopping, for discussion -of how to arrange for your program to stop. Once your program has -stopped, you may call functions in your program, using the `print' or -`call' commands. *Note Examining Data: Data. - - If the modification time of your symbol file has changed since the -last time GDB read its symbols, GDB discards its symbol table, and -reads it again. When it does this, GDB tries to retain your current -breakpoints. - -`start' - The name of the main procedure can vary from language to language. - With C or C++, the main procedure name is always `main', but other - languages such as Ada do not require a specific name for their - main procedure. The debugger provides a convenient way to start - the execution of the program and to stop at the beginning of the - main procedure, depending on the language used. - - The `start' command does the equivalent of setting a temporary - breakpoint at the beginning of the main procedure and then invoking - the `run' command. - - Some programs contain an "elaboration" phase where some startup - code is executed before the main procedure is called. This - depends on the languages used to write your program. In C++, for - instance, constructors for static and global objects are executed - before `main' is called. It is therefore possible that the - debugger stops before reaching the main procedure. However, the - temporary breakpoint will remain to halt execution. - - Specify the arguments to give to your program as arguments to the - `start' command. These arguments will be given verbatim to the - underlying `run' command. Note that the same arguments will be - reused if no argument is provided during subsequent calls to - `start' or `run'. - - It is sometimes necessary to debug the program during elaboration. - In these cases, using the `start' command would stop the execution - of your program too late, as the program would have already - completed the elaboration phase. Under these circumstances, - insert breakpoints in your elaboration code before running your - program. - -`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 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 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. - - The virtual address space randomization is implemented only on - GNU/Linux. It protects the programs against some 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 only, not for GDB itself. VALUE may be any string; - the values of environment variables are just strings, and any - interpretation is supplied by your program itself. The VALUE - parameter is optional; if it is eliminated, the variable is set to - a null value. - - For example, this command: - - set env USER = foo - - tells the debugged program, when subsequently run, that its user - is named `foo'. (The spaces around `=' are used for clarity here; - they are not actually required.) - -`unset environment VARNAME' - Remove variable VARNAME from the environment to be passed to your - program. This is different from `set env VARNAME ='; `unset - environment' removes the variable from the environment, rather - than assigning it an empty value. - - _Warning:_ On Unix systems, GDB runs your program using the shell -indicated by your `SHELL' environment variable if it exists (or -`/bin/sh' if not). If your `SHELL' variable names a shell that runs an -initialization file--such as `.cshrc' for C-shell, or `.bashrc' for -BASH--any variables you set in that file affect your program. You may -wish to move setting of environment variables to files that are only -run when you sign on, such as `.login' or `.profile'. - - -File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running - -4.5 Your Program's Working Directory -==================================== - -Each time you start your program with `run', it inherits its working -directory from the current working directory of GDB. The GDB working -directory is initially whatever it inherited from its parent process -(typically the shell), but you can specify a new working directory in -GDB with the `cd' command. - - The GDB working directory also serves as a default for the commands -that specify files for GDB to operate on. *Note Commands to Specify -Files: Files. - -`cd DIRECTORY' - Set the GDB working directory to DIRECTORY. - -`pwd' - Print the GDB working directory. - - It is generally impossible to find the current working directory of -the process being debugged (since a program can change its directory -during its run). If you work on a system where GDB is configured with -the `/proc' support, you can use the `info proc' command (*note SVR4 -Process Information::) to find out the current working directory of the -debuggee. - - -File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running - -4.6 Your Program's Input and Output -=================================== - -By default, the program you run under GDB does input and output to the -same terminal that GDB uses. GDB switches the terminal to its own -terminal modes to interact with you, but it records the terminal modes -your program was using and switches back to them when you continue -running your program. - -`info terminal' - Displays information recorded by GDB about the terminal modes your - program is using. - - You can redirect your program's input and/or output using shell -redirection with the `run' command. For example, - - run > outfile - -starts your program, diverting its output to the file `outfile'. - - Another way to specify where your program should do input and output -is with the `tty' command. This command accepts a file name as -argument, and causes this file to be the default for future `run' -commands. It also resets the controlling terminal for the child -process, for future `run' commands. For example, - - tty /dev/ttyb - -directs that processes started with subsequent `run' commands default -to do input and output on the terminal `/dev/ttyb' and have that as -their controlling terminal. - - An explicit redirection in `run' overrides the `tty' command's -effect on the input/output device, but not its effect on the controlling -terminal. - - When you use the `tty' command or redirect input in the `run' -command, only the input _for your program_ is affected. The input for -GDB still comes from your terminal. `tty' is an alias for `set -inferior-tty'. - - You can use the `show inferior-tty' command to tell GDB to display -the name of the terminal that will be used for future runs of your -program. - -`set inferior-tty /dev/ttyb' - Set the tty for the program being debugged to /dev/ttyb. - -`show inferior-tty' - Show the current tty for the program being debugged. - - -File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running - -4.7 Debugging an Already-running Process -======================================== - -`attach PROCESS-ID' - This command attaches to a running process--one that was started - outside GDB. (`info files' shows your active targets.) The - command takes as argument a process ID. The usual way to find out - the PROCESS-ID of a Unix process is with the `ps' utility, or with - the `jobs -l' shell command. - - `attach' does not repeat if you press <RET> a second time after - executing the command. - - To use `attach', your program must be running in an environment -which supports processes; for example, `attach' does not work for -programs on bare-board targets that lack an operating system. You must -also have permission to send the process a signal. - - When you use `attach', the debugger finds the program running in the -process first by looking in the current working directory, then (if the -program is not found) by using the source file search path (*note -Specifying Source Directories: Source Path.). You can also use the -`file' command to load the program. *Note Commands to Specify Files: -Files. - - The first thing GDB does after arranging to debug the specified -process is to stop it. You can examine and modify an attached process -with all the GDB commands that are ordinarily available when you start -processes with `run'. You can insert breakpoints; you can step and -continue; you can modify storage. If you would rather the process -continue running, you may use the `continue' command after attaching -GDB to the process. - -`detach' - When you have finished debugging the attached process, you can use - the `detach' command to release it from GDB control. Detaching - the process continues its execution. After the `detach' command, - that process and GDB become completely independent once more, and - you are ready to `attach' another process or start one with `run'. - `detach' does not repeat if you press <RET> again after executing - the command. - - If you exit GDB while you have an attached process, you detach that -process. If you use the `run' command, you kill that process. By -default, GDB asks for confirmation if you try to do either of these -things; you can control whether or not you need to confirm by using the -`set confirm' command (*note Optional Warnings and Messages: -Messages/Warnings.). - - -File: gdb.info, Node: Kill Process, Next: 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. - - 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. - - 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. 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. - - Occasionaly, 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 - 2 goodbye - Bound inferiors: ID 1 (process 21561) - * 1 hello - - 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 HP-UX and Solaris, a single program -may have more than one "thread" of execution. The precise semantics of -threads differ from one operating system to another, but in general the -threads of a single program are akin to multiple processes--except that -they share one address space (that is, they can all examine and modify -the same variables). On the other hand, each thread has its own -registers and execution stack, and perhaps private memory. - - GDB provides these facilities for debugging multi-thread programs: - - * automatic notification of new threads - - * `thread THREADNO', a command to switch among threads - - * `info threads', a command to inquire about existing threads - - * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command - to a list of threads - - * thread-specific breakpoints - - * `set print thread-events', which controls printing of messages on - thread start and exit. - - * `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. - - _Warning:_ These facilities are not yet available on every GDB - configuration where the operating system supports threads. If - your GDB does not support threads, these commands have no effect. - For example, a system without thread support shows no output from - `info threads', and always rejects the `thread' command, like this: - - (gdb) info threads - (gdb) thread 1 - Thread ID 1 not known. Use the "info threads" command to - see the IDs of currently known threads. - - The GDB thread debugging facility allows you to observe all threads -while your program runs--but whenever GDB takes control, one thread in -particular is always the focus of debugging. This thread is called the -"current thread". Debugging commands show program information from the -perspective of the current thread. - - Whenever GDB detects a new thread in your program, it displays the -target system's identification for the thread with a message in the -form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies -depending on the particular system. For example, on GNU/Linux, you -might see - - [New Thread 0x41e02940 (LWP 25582)] - -when GDB notices a new thread. In contrast, on an SGI system, the -SYSTAG is simply something like `process 368', with no further -qualifier. - - For debugging purposes, GDB associates its own thread number--always -a single integer--with each thread in your program. - -`info threads [ID...]' - Display a summary of all threads currently in your program. - Optional argument ID... is one or more thread ids separated by - spaces, and means to print information only about the specified - thread or threads. GDB displays for each thread (in this order): - - 1. the thread number assigned by GDB - - 2. the target system's thread identifier (SYSTAG) - - 3. the 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. - - 4. 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 - 3 process 35 thread 27 0x34e5 in sigpause () - 2 process 35 thread 23 0x34e5 in sigpause () - * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) - at threadtest.c:68 - - On Solaris, you can display more information about user threads with -a Solaris-specific command: - -`maint info sol-threads' - Display info on Solaris user threads. - -`thread THREADNO' - Make thread number THREADNO the current thread. The command - argument THREADNO is the internal GDB thread number, as shown in - the first field of the `info threads' display. GDB responds by - displaying the system identifier of the thread you selected, and - its current stack frame summary: - - (gdb) thread 2 - [Switching to 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. - - The debugger convenience variable `$_thread' contains the number - of the current thread. You may find this useful in writing - breakpoint conditional expressions, command scripts, and so forth. - See *Note Convenience Variables: Convenience Vars, for general - information on convenience variables. - -`thread apply [THREADNO | all] COMMAND' - The `thread apply' command allows you to apply the named COMMAND - to one or more threads. Specify the numbers of the threads that - you want affected with the command argument THREADNO. It can be a - single thread number, one of the numbers shown in the first field - of the `info threads' display; or it could be a range of thread - numbers, as in `2-4'. To apply a command to all threads, type - `thread apply all COMMAND'. - -`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'. - - A special entry `$sdir' for `libthread-db-search-path' refers to - the default system directories that are normally searched for - loading shared libraries. - - 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. -Currently, the only platforms with this feature are HP-UX (11.x and -later only?) and GNU/Linux (kernel version 2.5.60 and later). - - By default, when a program forks, GDB will continue to debug the -parent process and the child process will run unimpeded. - - If you want to follow the child process instead of the parent -process, use the command `set follow-fork-mode'. - -`set follow-fork-mode MODE' - Set the debugger response to a program call of `fork' or `vfork'. - A call to `fork' or `vfork' creates a new process. The MODE - argument can be: - - `parent' - The original process is debugged after a fork. The child - process runs unimpeded. This is the default. - - `child' - The new process is debugged after a fork. The parent process - runs unimpeded. - - -`show follow-fork-mode' - Display the current debugger response to a `fork' or `vfork' call. - - On Linux, if you want to debug both the parent and child processes, -use the command `set detach-on-fork'. - -`set detach-on-fork MODE' - Tells gdb whether to detach one of the processes after a fork, or - retain debugger control over them both. - - `on' - The child process (or parent process, depending on the value - of `follow-fork-mode') will be detached and allowed to run - independently. This is the default. - - `off' - Both processes will be held under the control of GDB. One - process (child or parent, depending on the value of - `follow-fork-mode') is debugged as usual, while the other is - held suspended. - - -`show detach-on-fork' - Show whether detach-on-fork mode is on/off. - - If you choose to set `detach-on-fork' mode off, then GDB will retain -control of all forked processes (including nested forks). You can list -the forked processes under the control of GDB by using the -`info 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 - * 2 <null> prog2 - 1 <null> prog1 - - `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 - - - 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 -* Signals:: Signals -* Thread Stops:: Stopping and starting multi-thread programs - - -File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping - -5.1 Breakpoints, Watchpoints, and Catchpoints -============================================= - -A "breakpoint" makes your program stop whenever a certain point in the -program is reached. For each breakpoint, you can add conditions to -control in finer detail whether your program stops. You can set -breakpoints with the `break' command and its variants (*note Setting -Breakpoints: Set Breaks.), to specify the place where your program -should stop by line number, function name or exact address in the -program. - - On some systems, you can set breakpoints in shared libraries before -the executable is run. There is a minor limitation on HP-UX systems: -you must wait until the executable is run in order to set breakpoints -in shared library routines that are not called directly by the program -(for example, routines that are arguments in a `pthread_create' call). - - A "watchpoint" is a special breakpoint that stops your program when -the value of an expression changes. The expression may be a value of a -variable, or it could involve values of one or more variables combined -by operators, such as `a + b'. This is sometimes called "data -breakpoints". You must use a different command to set watchpoints -(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you -can manage a watchpoint like any other breakpoint: you enable, disable, -and delete both breakpoints and watchpoints using the same commands. - - You can arrange to have values from your program displayed -automatically whenever GDB stops at a breakpoint. *Note Automatic -Display: Auto Display. - - A "catchpoint" is another special breakpoint that stops your program -when a certain kind of event occurs, such as the throwing of a C++ -exception or the loading of a library. As with watchpoints, you use a -different command to set a catchpoint (*note Setting Catchpoints: Set -Catchpoints.), but aside from that, you can manage a catchpoint like any -other breakpoint. (To stop when your program receives a signal, use the -`handle' command; see *note Signals: Signals.) - - GDB assigns a number to each breakpoint, watchpoint, or catchpoint -when you create it; these numbers are successive integers starting with -one. In many of the commands for controlling various features of -breakpoints you use the breakpoint number to say which breakpoint you -want to change. Each breakpoint may be "enabled" or "disabled"; if -disabled, it has no effect on your program until you enable it again. - - Some GDB commands accept a range of breakpoints on which to operate. -A breakpoint range is either a single breakpoint number, like `5', or -two such numbers, in increasing order, separated by a hyphen, like -`5-7'. When a breakpoint range is given to a command, all breakpoints -in that range are operated on. - -* Menu: - -* Set Breaks:: Setting breakpoints -* Set Watchpoints:: Setting watchpoints -* Set Catchpoints:: Setting catchpoints -* Delete Breaks:: Deleting breakpoints -* Disabling:: Disabling breakpoints -* Conditions:: Break conditions -* Break Commands:: Breakpoint command lists -* Save Breakpoints:: How to save breakpoints in a file -* 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. ARGS are the same as - for the `break' command, and the breakpoint is set in the same - way, but the breakpoint is automatically deleted after the first - time your program stops there. *Note Disabling Breakpoints: - Disabling. - -`hbreak ARGS' - Set a hardware-assisted breakpoint. ARGS are the same as for the - `break' command and the breakpoint is set in the same way, but the - breakpoint requires hardware support and some target hardware may - not have this support. The main purpose of this is EPROM/ROM code - debugging, so you can set a breakpoint at an instruction without - changing the instruction. This can be used with the new - trap-generation provided by SPARClite DSU and most x86-based - targets. These targets will generate traps when a program - accesses some data or instruction address that is assigned to the - debug registers. However the hardware breakpoint registers can - take a limited number of breakpoints. For example, on the DSU, - only two data breakpoints can be set at a time, and GDB will - reject this command if more than two are used. Delete or disable - unused hardware breakpoints before setting new ones (*note - Disabling Breakpoints: Disabling.). *Note Break Conditions: - Conditions. For remote targets, you can restrict the number of - hardware breakpoints GDB will use, see *note set remote - hardware-breakpoint-limit::. - -`thbreak ARGS' - Set a hardware-assisted breakpoint enabled only for one stop. ARGS - are the same as for the `hbreak' command and the breakpoint is set - in the same way. However, like the `tbreak' command, the - breakpoint is automatically deleted after the first time your - program stops there. Also, like the `hbreak' command, the - breakpoint requires hardware support and some target hardware may - not have this support. *Note Disabling Breakpoints: Disabling. - See also *note Break Conditions: Conditions. - -`rbreak REGEX' - Set breakpoints on all functions matching the regular expression - REGEX. This command sets an unconditional breakpoint on all - matches, printing a list of all breakpoints it set. Once these - breakpoints are set, they are treated just like the breakpoints - set with the `break' command. You can delete them, disable them, - or make them conditional the same way as any other breakpoint. - - The syntax of the regular expression is the standard one used with - tools like `grep'. Note that this is different from the syntax - used by shells, so for instance `foo*' matches all functions that - include an `fo' followed by zero or more `o's. There is an - implicit `.*' leading and trailing the regular expression you - supply, so to match only functions that begin with `foo', use - `^foo'. - - When debugging C++ programs, `rbreak' is useful for setting - breakpoints on overloaded functions that are not members of any - special classes. - - The `rbreak' command can be used to set breakpoints in *all* the - functions in a program, like this: - - (gdb) rbreak . - -`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 [N...]' -`info break [N...]' - Print a table of all breakpoints, watchpoints, and catchpoints set - and not deleted. Optional argument N means print information only - about the specified breakpoint(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, `info break' shows the condition on - the line following the affected breakpoint; breakpoint commands, - if any, are listed after that. A pending breakpoint is allowed to - have a condition specified for it. The condition is not parsed - for validity until a shared library is loaded that allows the - pending breakpoint to resolve to a valid location. - - `info break' with a breakpoint number N as argument lists only - that breakpoint. The convenience variable `$_' and the default - examining-address for the `x' command are set to the address of - the last breakpoint listed (*note Examining Memory: Memory.). - - `info break' displays a count of the number of times the breakpoint - has been hit. This is especially useful in conjunction with the - `ignore' command. You can ignore a large number of breakpoint - hits, look at the breakpoint info to see how many times the - breakpoint was hit, and then run again, ignoring one less than - that number. This will get you quickly to the last hit of that - breakpoint. - - GDB allows you to set any number of breakpoints at the same place in -your program. There is nothing silly or meaningless about this. When -the breakpoints are conditional, this is even useful (*note Break -Conditions: Conditions.). - - It is possible that a breakpoint corresponds to several locations in -your program. Examples of this situation are: - - * For a C++ constructor, the GCC compiler generates several - instances of the function body, used in different cases. - - * For a C++ template function, a given line in the function can - correspond to any number of instantiations. - - * For an inlined function, a given source line can correspond to - several places where that function is inlined. - - In all those cases, GDB will insert a breakpoint at all the relevant -locations(1). - - A breakpoint with multiple locations is displayed in the breakpoint -table using several rows--one header row, followed by one row for each -breakpoint location. The header row has `<MULTIPLE>' in the address -column. The rows for individual locations contain the actual addresses -for locations, and show the functions to which those locations belong. -The number column for a location is of the form -BREAKPOINT-NUMBER.LOCATION-NUMBER. - - For example: - - Num Type Disp Enb Address What - 1 breakpoint keep y <MULTIPLE> - stop only if i==1 - breakpoint already hit 1 time - 1.1 y 0x080486a2 in void foo<int>() at t.cc:8 - 1.2 y 0x080486ca in void foo<double>() at t.cc:8 - - Each location can be individually enabled or disabled by passing -BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the `enable' and -`disable' commands. Note that you cannot delete the individual -locations from the list, you can only delete the entire list of -locations that belong to their parent breakpoint (with the `delete NUM' -command, where NUM is the number of the parent breakpoint, 1 in the -above example). Disabling or enabling the parent breakpoint (*note -Disabling::) affects all of the locations that belong to that -breakpoint. - - It's quite common to have a breakpoint inside a shared library. -Shared libraries can be loaded and unloaded explicitly, and possibly -repeatedly, as the program is executed. To support this use case, GDB -updates breakpoint locations whenever any shared library is loaded or -unloaded. Typically, you would set a breakpoint in a shared library at -the beginning of your debugging session, when the library is not -loaded, and when the symbols from the library are not available. When -you try to set breakpoint, GDB will ask you if you want to set a so -called "pending breakpoint"--breakpoint whose address is not yet -resolved. - - After the program is run, whenever a new shared library is loaded, -GDB reevaluates all the breakpoints. When a newly loaded shared -library contains the symbol or line referred to by some pending -breakpoint, that breakpoint is resolved and becomes an ordinary -breakpoint. When a library is unloaded, all breakpoints that refer to -its symbols or source lines become pending again. - - This logic works for breakpoints with multiple locations, too. For -example, if you have a breakpoint in a C++ template function, and a -newly loaded shared library has an instantiation of that template, a -new location is added to the list of locations for the breakpoint. - - Except for having unresolved address, pending breakpoints do not -differ from regular breakpoints. You can set conditions or commands, -enable and disable them and perform other breakpoint operations. - - GDB provides some additional commands for controlling what happens -when the `break' command cannot resolve breakpoint address -specification to an address: - -`set breakpoint pending auto' - This is the default behavior. When GDB cannot find the breakpoint - location, it queries you whether a pending breakpoint should be - created. - -`set breakpoint pending on' - This indicates that an unrecognized breakpoint location should - automatically result in a pending breakpoint being created. - -`set breakpoint pending off' - This indicates that pending breakpoints are not to be created. Any - unrecognized breakpoint location results in an error. This - setting does not affect any pending breakpoints previously created. - -`show breakpoint pending' - Show the current behavior setting for creating pending breakpoints. - - The settings above only affect the `break' command and its variants. -Once breakpoint is set, it will be automatically updated as shared -libraries are loaded and unloaded. - - For some targets, GDB can automatically decide if hardware or -software breakpoints should be used, depending on whether the -breakpoint address is read-only or read-write. This applies to -breakpoints set with the `break' command as well as to internal -breakpoints set by commands like `next' and `finish'. For breakpoints -set with `hbreak', GDB will always use hardware breakpoints. - - You can control this automatic behaviour with the following -commands:: - -`set breakpoint auto-hw on' - This is the default behavior. When GDB sets a breakpoint, it will - try to use the target memory map to decide if software or hardware - breakpoint must be used. - -`set breakpoint auto-hw off' - This indicates GDB should not automatically select breakpoint - type. If the target provides a memory map, GDB will warn when - trying to set software breakpoint at a read-only address. - - GDB 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. - -`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 removed. - -`set breakpoint always-inserted auto' - This is the default mode. If GDB is controlling the inferior in - non-stop mode (*note Non-Stop Mode::), gdb behaves as if - `breakpoint always-inserted' mode is on. If GDB is controlling - the inferior in all-stop mode, GDB behaves as if `breakpoint - always-inserted' mode is off. - - 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::). - - ---------- Footnotes ---------- - - (1) As of this writing, multiple-location breakpoints work only if -there's line number information for all the locations. This means that -they will generally not work in system libraries, unless you have debug -info with line numbers for them. - - -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 HP-UX, PowerPC, GNU/Linux and most other -x86-based targets, GDB includes support for hardware watchpoints, which -do not slow down the running of your program. - -`watch [-l|-location] EXPR [thread THREADNUM]' - Set a watchpoint for an expression. GDB will break when the - expression EXPR is written into by the program and its value - changes. The simplest (and the most popular) use of this command - is to watch the value of a single variable: - - (gdb) watch foo - - If the command includes a `[thread THREADNUM]' clause, GDB breaks - only when the thread identified by THREADNUM changes the value of - EXPR. If any other threads change the value of EXPR, GDB will not - break. Note that watchpoints restricted to a single thread in - this way only work with Hardware Watchpoints. - - 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. - -`rwatch [-l|-location] EXPR [thread THREADNUM]' - Set a watchpoint that will break when the value of EXPR is read by - the program. - -`awatch [-l|-location] EXPR [thread THREADNUM]' - Set a watchpoint that will break when EXPR is either read from or - written into by the program. - -`info watchpoints [N...]' - 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. EVENT can be any of the following: - `throw' - The throwing of a C++ exception. - - `catch' - The catching of a C++ exception. - - `exception' - An Ada exception being raised. If an exception name is - specified at the end of the command (eg `catch exception - Program_Error'), the debugger will stop only when this - specific exception is raised. Otherwise, the debugger stops - execution when any Ada exception is raised. - - 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'. - - `exception unhandled' - An exception that was raised but is not handled by the - program. - - `assert' - A failed Ada assertion. - - `exec' - A call to `exec'. This is currently only available for HP-UX - and GNU/Linux. - - `syscall' - `syscall [NAME | NUMBER] ...' - 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). - - 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) - - 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'. This is currently only available for HP-UX - and GNU/Linux. - - `vfork' - A call to `vfork'. This is currently only available for HP-UX - and GNU/Linux. - - -`tcatch EVENT' - Set a catchpoint that is enabled only for one stop. The - catchpoint is automatically deleted after the first time the event - is caught. - - - Use the `info break' command to list the current catchpoints. - - There are currently some limitations to C++ exception handling -(`catch throw' and `catch catch') in GDB: - - * If you call a function interactively, GDB normally returns control - to you when the function has finished executing. If the call - raises an exception, however, the call may bypass the mechanism - that returns control to you and cause your program either to abort - or to simply continue running until it hits a breakpoint, catches - a signal that GDB is listening for, or exits. This is the case - even if you set a catchpoint for the exception; catchpoints on - exceptions are disabled within interactive calls. - - * You cannot raise an exception interactively. - - * You cannot install an exception handler interactively. - - Sometimes `catch' is not the best way to debug exception handling: -if you need to know exactly where an exception is raised, it is better -to stop _before_ the exception handler is called, since that way you -can see the stack before any unwinding takes place. If you set a -breakpoint in an exception handler instead, it may not be easy to find -out where the exception was raised. - - To stop just before an exception handler is called, you need some -knowledge of the implementation. In the case of GNU C++, exceptions are -raised by calling a library function named `__raise_exception' which -has the following ANSI C interface: - - /* ADDR is where the exception identifier is stored. - ID is the exception identifier. */ - void __raise_exception (void **addr, void *id); - -To make the debugger catch all exceptions before any stack unwinding -takes place, set a breakpoint on `__raise_exception' (*note -Breakpoints; Watchpoints; and Exceptions: Breakpoints.). - - With a conditional breakpoint (*note Break Conditions: Conditions.) -that depends on the value of ID, you can stop your program when a -specific exception is raised. You can use multiple conditional -breakpoints to stop your program when any of a number of exceptions are -raised. - - -File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints - -5.1.4 Deleting Breakpoints --------------------------- - -It is often necessary to eliminate a breakpoint, watchpoint, or -catchpoint once it has done its job and you no longer want your program -to stop there. This is called "deleting" the breakpoint. A breakpoint -that has been deleted no longer exists; it is forgotten. - - With the `clear' command you can delete breakpoints according to -where they are in your program. With the `delete' command you can -delete individual breakpoints, watchpoints, or catchpoints by specifying -their breakpoint numbers. - - It is not necessary to delete a breakpoint to proceed past it. GDB -automatically ignores breakpoints on the first instruction to be -executed when you continue execution without changing the execution -address. - -`clear' - Delete any breakpoints at the next instruction to be executed in - the selected stack frame (*note Selecting a Frame: Selection.). - When the innermost frame is selected, this is a good way to delete - a breakpoint where your program just stopped. - -`clear LOCATION' - Delete any breakpoints set at the specified LOCATION. *Note - Specify Location::, for the various forms of LOCATION; the most - useful ones are listed below: - - `clear FUNCTION' - `clear FILENAME:FUNCTION' - Delete any breakpoints set at entry to the named FUNCTION. - - `clear LINENUM' - `clear FILENAME:LINENUM' - Delete any breakpoints set at or within the code of the - specified LINENUM of the specified FILENAME. - -`delete [breakpoints] [RANGE...]' - Delete the breakpoints, watchpoints, or catchpoints of the - breakpoint ranges specified as arguments. If no argument is - specified, delete all breakpoints (GDB asks confirmation, unless - you have `set confirm off'). You can abbreviate this command as - `d'. - - -File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints - -5.1.5 Disabling Breakpoints ---------------------------- - -Rather than deleting a breakpoint, watchpoint, or catchpoint, you might -prefer to "disable" it. This makes the breakpoint inoperative as if it -had been deleted, but remembers the information on the breakpoint so -that you can "enable" it again later. - - You disable and enable breakpoints, watchpoints, and catchpoints with -the `enable' and `disable' commands, optionally specifying one or more -breakpoint numbers as arguments. Use `info break' 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 four -different states of enablement: - - * Enabled. The breakpoint stops your program. A breakpoint set - with the `break' command starts out in this state. - - * Disabled. The breakpoint has no effect on your program. - - * Enabled once. The breakpoint stops your program, but then becomes - disabled. - - * Enabled for deletion. The breakpoint stops your program, but - immediately after it does so it is deleted permanently. A - breakpoint set with the `tbreak' command starts out in this state. - - You can use the following commands to enable or disable breakpoints, -watchpoints, and catchpoints: - -`disable [breakpoints] [RANGE...]' - Disable the specified breakpoints--or all breakpoints, if none are - listed. A disabled breakpoint has no effect but is not forgotten. - All options such as ignore-counts, conditions and commands are - remembered in case the breakpoint is enabled again later. You may - abbreviate `disable' as `dis'. - -`enable [breakpoints] [RANGE...]' - Enable the specified breakpoints (or all defined breakpoints). - They become effective once again in stopping your program. - -`enable [breakpoints] once RANGE...' - Enable the specified breakpoints temporarily. GDB disables any of - these breakpoints immediately after stopping your program. - -`enable [breakpoints] delete RANGE...' - Enable the specified breakpoints to work once, then die. GDB - deletes any of these breakpoints as soon as your program stops - there. Breakpoints set by the `tbreak' command start out in this - state. - - Except for a breakpoint set with `tbreak' (*note Setting -Breakpoints: Set Breaks.), breakpoints that you set are initially -enabled; subsequently, they become disabled or enabled only when you -use one of the commands above. (The command `until' can set and delete -a breakpoint of its own, but it does not change the state of your other -breakpoints; see *note Continuing and Stepping: Continuing and -Stepping.) - - -File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints - -5.1.6 Break Conditions ----------------------- - -The simplest sort of breakpoint breaks every time your program reaches a -specified place. You can also specify a "condition" for a breakpoint. -A condition is just a Boolean expression in your programming language -(*note Expressions: Expressions.). A breakpoint with a condition -evaluates the expression each time your program reaches it, and your -program stops only if the condition is _true_. - - This is the converse of using assertions for program validation; in -that situation, you want to stop when the assertion is violated--that -is, when the condition is false. In C, if you want to test an -assertion expressed by the condition ASSERT, you should set the -condition `! ASSERT' on the appropriate breakpoint. - - Conditions are also accepted for watchpoints; you may not need them, -since a watchpoint is inspecting the value of an expression anyhow--but -it might be simpler, say, to just set a watchpoint on a variable name, -and specify a condition that tests whether the new value is an -interesting one. - - Break conditions can have side effects, and may even call functions -in your program. This can be useful, for example, to activate functions -that log program progress, or to use your own print functions to format -special data structures. The effects are completely predictable unless -there is another enabled breakpoint at the same address. (In that -case, GDB might see the other breakpoint first and stop your program -without checking the condition of this one.) Note that breakpoint -commands are usually more convenient and flexible than break conditions -for the purpose of performing side effects when a breakpoint is reached -(*note Breakpoint Command Lists: Break Commands.). - - Break conditions can be specified when a breakpoint is set, by using -`if' in the arguments to the `break' command. *Note Setting -Breakpoints: Set Breaks. They can also be changed at any time with the -`condition' command. - - You can also use the `if' keyword with the `watch' command. The -`catch' command does not recognize the `if' keyword; `condition' is the -only way to impose a further condition on a catchpoint. - -`condition BNUM EXPRESSION' - Specify EXPRESSION as the break condition for breakpoint, - watchpoint, or catchpoint number BNUM. After you set a condition, - breakpoint BNUM stops your program only if the value of EXPRESSION - is true (nonzero, in C). When you use `condition', GDB checks - EXPRESSION immediately for syntactic correctness, and to determine - whether symbols in it have referents in the context of your - breakpoint. If EXPRESSION uses symbols not referenced in the - context of the breakpoint, GDB prints an error message: - - No symbol "foo" in current context. - - GDB does not actually evaluate EXPRESSION at the time the - `condition' command (or a command that sets a breakpoint with a - condition, like `break if ...') is given, however. *Note - Expressions: Expressions. - -`condition BNUM' - Remove the condition from breakpoint number BNUM. It becomes an - ordinary unconditional breakpoint. - - A special case of a breakpoint condition is to stop only when the -breakpoint has been reached a certain number of times. This is so -useful that there is a special way to do it, using the "ignore count" -of the breakpoint. Every breakpoint has an ignore count, which is an -integer. Most of the time, the ignore count is zero, and therefore has -no effect. But if your program reaches a breakpoint whose ignore count -is positive, then instead of stopping, it just decrements the ignore -count by one and continues. As a result, if the ignore count value is -N, the breakpoint does not stop the next N times your program reaches -it. - -`ignore BNUM COUNT' - Set the ignore count of breakpoint number BNUM to COUNT. The next - COUNT times the breakpoint is reached, your program's execution - does not stop; other than to decrement the ignore count, GDB takes - no action. - - To make the breakpoint stop the next time it is reached, specify a - count of zero. - - When you use `continue' to resume execution of your program from a - breakpoint, you can specify an ignore count directly as an - argument to `continue', rather than using `ignore'. *Note - Continuing and Stepping: Continuing and Stepping. - - If a breakpoint has a positive ignore count and a condition, the - condition is not checked. Once the ignore count reaches zero, GDB - resumes checking the condition. - - You could achieve the effect of the ignore count with a condition - such as `$foo-- <= 0' using a debugger convenience variable that - is decremented each time. *Note Convenience Variables: - Convenience Vars. - - Ignore counts apply to breakpoints, watchpoints, and catchpoints. - - -File: gdb.info, Node: Break Commands, Next: Save Breakpoints, 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 [RANGE...]' -`... 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: Save Breakpoints, Next: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints - -5.1.8 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: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Save Breakpoints, Up: Breakpoints - -5.1.9 "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.10 "Breakpoint address adjusted..." ---------------------------------------- - -Some processor architectures place constraints on the addresses at -which breakpoints may be placed. For architectures thus constrained, -GDB will attempt to adjust the breakpoint's address to comply with the -constraints dictated by the architecture. - - One example of such an architecture is the Fujitsu FR-V. The FR-V is -a VLIW architecture in which a number of RISC-like instructions may be -bundled together for parallel execution. The FR-V architecture -constrains the location of a breakpoint instruction within such a -bundle to the instruction with the lowest address. GDB honors this -constraint by adjusting a breakpoint's address to the first in the -bundle. - - It is not uncommon for optimized code to have bundles which contain -instructions from different source statements, thus it may happen that -a breakpoint's address will be adjusted from one source statement to -another. Since this adjustment may significantly alter GDB's -breakpoint related behavior from what the user expects, a warning is -printed when the breakpoint is first set and also when the breakpoint -is hit. - - A warning like the one below is printed when setting a breakpoint -that's been subject to address adjustment: - - warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. - - Such warnings are printed both for user settable and GDB's internal -breakpoints. If you see one of these warnings, you should verify that -a breakpoint set at the adjusted address will have the desired affect. -If not, the breakpoint in question may be removed and other breakpoints -may be set which will have the desired behavior. E.g., it may be -sufficient to place the breakpoint at a later instruction. A -conditional breakpoint may also be useful in some cases to prevent the -breakpoint from triggering too often. - - GDB will also issue a warning when stopping at one of these adjusted -breakpoints: - - warning: Breakpoint 1 address previously adjusted from 0x00010414 - to 0x00010410. - - When this warning is encountered, it may be too late to take remedial -action except in cases where the breakpoint is hit earlier or more -frequently than expected. - - -File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping - -5.2 Continuing and Stepping -=========================== - -"Continuing" means resuming program execution until your program -completes normally. In contrast, "stepping" means executing just one -more "step" of your program, where "step" may mean either one line of -source code, or one machine instruction (depending on what particular -command you use). Either when continuing or when stepping, your -program may stop even sooner, due to a breakpoint or a signal. (If it -stops due to a signal, you may want to use `handle', or use `signal 0' -to resume execution. *Note Signals: Signals.) - -`continue [IGNORE-COUNT]' -`c [IGNORE-COUNT]' -`fg [IGNORE-COUNT]' - Resume program execution, at the address where your program last - stopped; any breakpoints set at that address are bypassed. The - optional argument IGNORE-COUNT allows you to specify a further - number of times to ignore a breakpoint at this location; its - effect is like that of `ignore' (*note Break Conditions: - Conditions.). - - The argument IGNORE-COUNT is meaningful only when your program - stopped due to a breakpoint. At other times, the argument to - `continue' is ignored. - - The synonyms `c' and `fg' (for "foreground", as the debugged - program is deemed to be the foreground program) are provided - purely for convenience, and have exactly the same behavior as - `continue'. - - To resume execution at a different place, you can use `return' -(*note Returning from a Function: Returning.) to go back to the calling -function; or `jump' (*note Continuing at a Different Address: Jumping.) -to go to an arbitrary location in your program. - - A typical technique for using stepping is to set a breakpoint (*note -Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the -beginning of the function or the section of your program where a problem -is believed to lie, run your program until it stops at that breakpoint, -and then step through the suspect area, examining the variables that are -interesting, until you see the problem happen. - -`step' - Continue running your program until control reaches a different - source line, then stop it and return control to GDB. This command - is abbreviated `s'. - - _Warning:_ If you use the `step' command while control is - within a function that was compiled without debugging - information, execution proceeds until control reaches a - function that does have debugging information. Likewise, it - will not step into a function which is compiled without - debugging information. To step through functions without - debugging information, use the `stepi' command, described - below. - - The `step' command only stops at the first instruction of a source - line. This prevents the multiple stops that could otherwise occur - in `switch' statements, `for' loops, etc. `step' continues to - stop if a function that has debugging information is called within - the line. In other words, `step' _steps inside_ any functions - called within the line. - - Also, the `step' command only enters a function if there is line - number information for the function. Otherwise it acts like the - `next' command. This avoids problems when using `cc -gl' on MIPS - machines. Previously, `step' entered subroutines if there was any - debugging information about the routine. - -`step COUNT' - Continue running as in `step', but do so COUNT times. If a - breakpoint is reached, or a signal not related to stepping occurs - before COUNT steps, stepping stops right away. - -`next [COUNT]' - Continue to the next source line in the current (innermost) stack - frame. This is similar to `step', but function calls that appear - within the line of code are executed without stopping. Execution - stops when control reaches a different line of code at the - original stack level that was executing when you gave the `next' - command. This command is abbreviated `n'. - - An argument COUNT is a repeat count, as for `step'. - - The `next' command only stops at the first instruction of a source - line. This prevents multiple stops that could otherwise occur in - `switch' statements, `for' loops, etc. - -`set step-mode' -`set step-mode on' - The `set step-mode on' command causes the `step' command to stop - at the first instruction of a function which contains no debug line - information rather than stepping over it. - - This is useful in cases where you may be interested in inspecting - the machine instructions of a function which has no symbolic info - and do not want GDB to automatically skip over this function. - -`set step-mode off' - Causes the `step' command to step over any functions which - contains no debug information. This is the default. - -`show step-mode' - Show whether GDB will stop in or step over functions without - source line debug information. - -`finish' - Continue running until just after function in the selected stack - frame returns. Print the returned value (if any). This command - can be abbreviated as `fin'. - - Contrast this with the `return' command (*note Returning from a - Function: Returning.). - -`until' -`u' - Continue running until a source line past the current line, in the - current stack frame, is reached. This command is used to avoid - single stepping through a loop more than once. It is like the - `next' command, except that when `until' encounters a jump, it - automatically continues execution until the program counter is - greater than the address of the jump. - - This means that when you reach the end of a loop after single - stepping though it, `until' makes your program continue execution - until it exits the loop. In contrast, a `next' command at the end - of a loop simply steps back to the beginning of the loop, which - forces you to step through the next iteration. - - `until' always stops your program if it attempts to exit the - current stack frame. - - `until' may produce somewhat counterintuitive results if the order - of machine code does not match the order of the source lines. For - example, in the following excerpt from a debugging session, the `f' - (`frame') command shows that execution is stopped at line `206'; - yet when we use `until', we get to line `195': - - (gdb) f - #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 - 206 expand_input(); - (gdb) until - 195 for ( ; argc > 0; NEXTARG) { - - This happened because, for execution efficiency, the compiler had - generated code for the loop closure test at the end, rather than - the start, of the loop--even though the test in a C `for'-loop is - written before the body of the loop. The `until' command appeared - to step back to the beginning of the loop when it advanced to this - expression; however, it has not really gone to an earlier - statement--not in terms of the actual machine code. - - `until' with no argument works by means of single instruction - stepping, and hence is slower than `until' with an argument. - -`until LOCATION' -`u LOCATION' - Continue running your program until either the specified location - is reached, or the current stack frame returns. LOCATION is any of - the forms described in *note Specify Location::. This form of the - command uses temporary breakpoints, and hence is quicker than - `until' without an argument. The specified location is actually - reached only if it is in the current frame. This implies that - `until' can be used to skip over recursive function invocations. - For instance in the code below, if the current location is line - `96', issuing `until 99' will execute the program up to line `99' - in the same invocation of factorial, i.e., after the inner - invocations have returned. - - 94 int factorial (int value) - 95 { - 96 if (value > 1) { - 97 value *= factorial (value - 1); - 98 } - 99 return (value); - 100 } - -`advance LOCATION' - Continue running the program up to the given LOCATION. An - argument is required, which should be of one of the forms - described in *note Specify Location::. Execution will also stop - upon exit from the current stack frame. This command is similar - to `until', but `advance' will not skip over recursive function - calls, and the target location doesn't have to be in the same - frame as the current one. - -`stepi' -`stepi ARG' -`si' - Execute one machine instruction, then stop and return to the - debugger. - - It is often useful to do `display/i $pc' when stepping by machine - instructions. This makes GDB automatically display the next - instruction to be executed, each time your program stops. *Note - Automatic Display: Auto Display. - - An argument is a repeat count, as in `step'. - -`nexti' -`nexti ARG' -`ni' - Execute one machine instruction, but if it is a function call, - proceed until the function returns. - - An argument is a repeat count, as in `next'. - - -File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping - -5.3 Signals -=========== - -A signal is an asynchronous event that can happen in a program. The -operating system defines the possible kinds of signals, and gives each -kind a name and a number. For example, in Unix `SIGINT' is the signal -a program gets when you type an interrupt character (often `Ctrl-c'); -`SIGSEGV' is the signal a program gets from referencing a place in -memory far away from all the areas in use; `SIGALRM' occurs when the -alarm clock timer goes off (which happens only if your program has -requested an alarm). - - Some signals, including `SIGALRM', are a normal part of the -functioning of your program. Others, such as `SIGSEGV', indicate -errors; these signals are "fatal" (they kill your program immediately) -if the program has not specified in advance some other way to handle -the signal. `SIGINT' does not indicate an error in your program, but -it is normally fatal so it can carry out the purpose of the interrupt: -to kill the program. - - GDB has the ability to detect any occurrence of a signal in your -program. You can tell GDB in advance what to do for each kind of -signal. - - Normally, GDB is set up to let the non-erroneous signals like -`SIGALRM' be silently passed to your program (so as not to interfere -with their role in the program's functioning) but to stop your program -immediately whenever an error signal happens. You can change these -settings with the `handle' command. - -`info signals' -`info handle' - Print a table of all the kinds of signals and how GDB has been - told to handle each one. You can use this to see the signal - numbers of all the defined types of signals. - -`info signals SIG' - Similar, but print information only about the specified signal - number. - - `info handle' is an alias for `info signals'. - -`handle SIGNAL [KEYWORDS...]' - Change the way GDB handles signal SIGNAL. SIGNAL can be the - number of a signal or its name (with or without the `SIG' at the - beginning); a list of signal numbers of the form `LOW-HIGH'; or - the word `all', meaning all the known signals. Optional arguments - KEYWORDS, described below, say what change to make. - - The keywords allowed by the `handle' command can be abbreviated. -Their full names are: - -`nostop' - GDB should not stop your program when this signal happens. It may - still print a message telling you that the signal has come in. - -`stop' - GDB should stop your program when this signal happens. This - implies the `print' keyword as well. - -`print' - GDB should print a message when this signal happens. - -`noprint' - GDB should not mention the occurrence of the signal at all. This - implies the `nostop' keyword as well. - -`pass' -`noignore' - GDB should allow your program to see this signal; your program can - handle the signal, or else it may terminate if the signal is fatal - and not handled. `pass' and `noignore' are synonyms. - -`nopass' -`ignore' - GDB should not allow your program to see this signal. `nopass' - and `ignore' are synonyms. - - When a signal stops your program, the signal is not visible to the -program until you continue. Your program sees the signal then, if -`pass' is in effect for the signal in question _at that time_. In -other words, after GDB reports a signal, you can use the `handle' -command with `pass' or `nopass' to control whether your program sees -that signal when you continue. - - The default is set to `nostop', `noprint', `pass' for non-erroneous -signals such as `SIGALRM', `SIGWINCH' and `SIGCHLD', and to `stop', -`print', `pass' for the erroneous signals. - - You can also use the `signal' command to prevent your program from -seeing a signal, or cause it to see a signal it normally would not see, -or to give it any signal at any time. For example, if your program -stopped due to some sort of memory reference error, you might store -correct values into the erroneous variables and continue, hoping to see -more execution; but your program would probably terminate immediately as -a result of the fatal signal once it saw the signal. To prevent this, -you can continue with `signal 0'. *Note Giving your Program a Signal: -Signaling. - - 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. - - -File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping - -5.4 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.4.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. 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 - only rarely (or never) get a chance to run when you step. They - are more likely to run when you `next' over a function call, and - they are completely free to run when you use commands like - `continue', `until', or `finish'. However, unless another thread - hits a breakpoint during its timeslice, GDB does not change the - current thread away from the thread that you are debugging. - -`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.4.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: - - # Enable the async interface. - set target-async 1 - - # 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.4.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. - - You need to explicitly enable asynchronous mode before you can use -background execution commands. You can use these commands to -manipulate the asynchronous mode setting: - -`set target-async on' - Enable asynchronous mode. - -`set target-async off' - Disable asynchronous mode. - -`show target-async' - Show the current target-async setting. - - 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.4.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 LINESPEC thread THREADNO' -`break LINESPEC thread THREADNO if ...' - LINESPEC specifies source lines; there are several ways of writing - them (*note Specify Location::), but the effect is always to - specify some source line. - - Use the qualifier `thread THREADNO' with a breakpoint command to - specify that you only want GDB to stop the program when a - particular thread reaches this breakpoint. THREADNO is one of the - numeric thread identifiers assigned by GDB, shown in the first - column of the `info threads' display. - - If you do not specify `thread THREADNO' when you set a breakpoint, - the breakpoint applies to _all_ threads of your program. - - You can use the `thread' qualifier on conditional breakpoints as - well; in this case, place `thread THREADNO' before or after the - breakpoint condition, like this: - - (gdb) break frik.c:13 thread 28 if bartab > lim - - - -File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops - -5.4.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.4.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). - - 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 -consistant 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. - - For architecture environments that support process record and replay, -GDB provides the following commands: - -`target record' - This command starts the process record and replay target. 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 `target record' command. - - Both `record' and `rec' are aliases of `target record'. - - 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::), - the process record and replay target cannot be started because it - doesn't 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 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. - -`record restore FILENAME' - Restore the execution log from a file `FILENAME'. File must have - been created with `record save'. - -`set record insn-number-max LIMIT' - Set the limit of instructions to be recorded. 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 zero, GDB will never delete recorded instructions from - the execution log. The number of recorded instructions is - unlimited in this case. - -`show record insn-number-max' - Show the limit of instructions to be recorded. - -`set record stop-at-limit' - Control the behavior 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 stop-at-limit' - Show the current setting of `stop-at-limit'. - -`set record memory-query' - Control the behavior when GDB is unable to record memory changes - caused by an instruction. 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 memory-query' - Show the current setting of `memory-query'. - -`info record' - Show various statistics about 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. - -`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". - - -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 - - -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 assigns numbers to all existing stack frames, starting with zero -for the innermost frame, one for the frame that called it, and so on -upward. These numbers do not really exist in your program; they are -assigned by GDB to give you a way of designating stack frames in GDB -commands. - - Some compilers provide a way to compile functions so that they -operate without stack frames. (For example, the GCC option - `-fomit-frame-pointer' - generates functions without a frame.) This is occasionally done -with heavily used library functions to save the frame setup time. GDB -has limited facilities for dealing with these function invocations. If -the innermost function invocation has no stack frame, GDB nevertheless -regards it as though it had a separate frame, which is numbered zero as -usual, allowing correct tracing of the function call chain. However, -GDB has no provision for frameless functions elsewhere in the stack. - -`frame ARGS' - The `frame' command allows you to move from one stack frame to - another, and to print the stack frame you select. ARGS may be - either the address of the frame or the stack frame number. - Without an argument, `frame' prints the current stack frame. - -`select-frame' - The `select-frame' command allows you to move from one stack frame - to another without printing the frame. This is the silent version - of `frame'. - - -File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack - -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. - -`backtrace' -`bt' - Print a backtrace of the entire stack: one line per frame for all - frames in the stack. - - You can stop the backtrace at any time by typing the system - interrupt character, normally `Ctrl-c'. - -`backtrace N' -`bt N' - Similar, but print only the innermost N frames. - -`backtrace -N' -`bt -N' - Similar, but print only the outermost N frames. - -`backtrace full' -`bt full' -`bt full N' -`bt full -N' - Print the values of the local variables also. N specifies the - number of frames to print, as described above. - - The names `where' and `info stack' (abbreviated `info s') are -additional aliases for `backtrace'. - - In a multi-threaded program, GDB by default shows the backtrace only -for the current thread. To display the backtrace for several or all of -the threads, use the command `thread apply' (*note thread apply: -Threads.). For example, if you type `thread apply all backtrace', GDB -will display the backtrace for all the threads; this is handy when you -debug a core dump of a multi-threaded program. - - Each line in the backtrace shows the frame number and the function -name. The program counter value is also shown--unless you use `set -print address off'. The backtrace also shows the source file name and -line number, as well as the arguments to the function. The program -counter value is omitted if it is at the beginning of the code for that -line number. - - Here is an example of a backtrace. It was made with the command `bt -3', so it shows the innermost three frames. - - #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) - at builtin.c:993 - #1 0x6e38 in expand_macro (sym=0x2b600, 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. - - 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' - Limit the backtrace to N levels. A value of zero means unlimited. - -`show backtrace limit' - Display the current limit on backtrace levels. - - ---------- Footnotes ---------- - - (1) Note that embedded programs (the so-called "free-standing" -environment) are not required to have a `main' function as the entry -point. They could even have multiple entry points. - - -File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack - -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 N' -`f N' - Select frame number N. Recall that frame zero is the innermost - (currently executing) frame, frame one is the frame that called the - innermost one, and so on. The highest-numbered frame is the one - for `main'. - -`frame ADDR' -`f ADDR' - Select the frame at address ADDR. This is useful mainly if the - chaining of stack frames has been damaged by a bug, making it - impossible for GDB to assign numbers properly to all frames. In - addition, this can be useful when your program has multiple stacks - and switches between them. - - On the SPARC architecture, `frame' needs two addresses to select - an arbitrary frame: a frame pointer and a stack pointer. - - On the MIPS and Alpha architecture, it needs two addresses: a stack - pointer and a program counter. - - On the 29k architecture, it needs three addresses: a register stack - pointer, a program counter, and a memory stack pointer. - -`up N' - Move N frames up the stack. For positive numbers N, this advances - toward the outermost frame, to higher frame numbers, to frames - that have existed longer. N defaults to one. - -`down N' - Move N frames down the stack. For positive numbers N, this - advances toward the innermost frame, to lower frame numbers, to - frames that were created more recently. N defaults to one. You - may abbreviate `down' as `do'. - - All of these commands end by printing two lines of output describing -the frame. The first line shows the frame number, the function name, -the arguments, and the source file and line number of execution in that -frame. The second line shows the text of that source line. - - For example: - - (gdb) up - #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) - at env.c:10 - 10 read_input_file (argv[i]); - - After such a printout, the `list' command with no arguments prints -ten lines centered on the point of execution in the frame. You can -also edit the program at the point of execution with your favorite -editing program by typing `edit'. *Note Printing Source Lines: List, -for details. - -`up-silently N' -`down-silently N' - These two commands are variants of `up' and `down', respectively; - they differ in that they do their work silently, without causing - display of the new frame. They are intended primarily for use in - GDB command scripts, where the output might be unnecessary and - distracting. - - -File: gdb.info, Node: Frame Info, Prev: Selection, Up: Stack - -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 ADDR' -`info f ADDR' - Print a verbose description of the frame at address ADDR, without - selecting that frame. The selected frame remains unchanged by this - command. This requires the same kind of address (more than one - for some architectures) that you specify in the `frame' command. - *Note Selecting a Frame: Selection. - -`info args' - Print the arguments of the selected frame, each on a separate line. - -`info locals' - Print the local variables of the selected frame, each on a separate - line. These are all variables (declared either static or - automatic) accessible at the point of execution of the selected - frame. - -`info catch' - Print a list of all the exception handlers that are active in the - current stack frame at the current point of execution. To see - other exception handlers, visit the associated frame (using the - `up', `down', or `frame' commands); then type `info catch'. *Note - Setting Catchpoints: Set Catchpoints. - - - -File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top - -9 Examining Source Files -************************ - -GDB can print parts of your program's source, since the debugging -information recorded in the program tells GDB what source files were -used to build it. When your program stops, GDB spontaneously prints -the line where it stopped. Likewise, when you select a stack frame -(*note Selecting a Frame: Selection.), GDB prints the line where -execution in that frame has stopped. You can print other portions of -source files by explicit command. - - If you use GDB through its GNU Emacs interface, you may prefer to -use Emacs facilities to view source; see *note Using GDB under GNU -Emacs: Emacs. - -* Menu: - -* List:: Printing source lines -* Specify Location:: How to specify code locations -* Edit:: Editing source files -* Search:: Searching source files -* Source Path:: Specifying source directories -* Machine Code:: Source and machine code - - -File: gdb.info, Node: List, Next: Specify Location, Up: Source - -9.1 Printing Source Lines -========================= - -To print lines from a source file, use the `list' command (abbreviated -`l'). By default, ten lines are printed. There are several ways to -specify what part of the file you want to print; see *note Specify -Location::, for the full list. - - Here are the forms of the `list' command most commonly used: - -`list LINENUM' - Print lines centered around line number LINENUM in the current - source file. - -`list FUNCTION' - Print lines centered around the beginning of function FUNCTION. - -`list' - Print more lines. If the last lines printed were printed with a - `list' command, this prints lines following the last lines - printed; however, if the last line printed was a solitary line - printed as part of displaying a stack frame (*note Examining the - Stack: Stack.), this prints lines centered around that line. - -`list -' - Print lines just before the lines last printed. - - By default, GDB prints ten source lines with any of these forms of -the `list' command. You can change this using `set listsize': - -`set listsize COUNT' - Make the `list' command display COUNT source lines (unless the - `list' argument explicitly specifies some other number). - -`show listsize' - Display the number of lines that `list' prints. - - Repeating a `list' command with <RET> discards the argument, so it -is equivalent to typing just `list'. This is more useful than listing -the same lines again. An exception is made for an argument of `-'; -that argument is preserved in repetition so that each repetition moves -up in the source file. - - In general, the `list' command expects you to supply zero, one or two -"linespecs". Linespecs specify source lines; there are several ways of -writing them (*note Specify Location::), but the effect is always to -specify some source line. - - Here is a complete description of the possible arguments for `list': - -`list LINESPEC' - Print lines centered around the line specified by LINESPEC. - -`list FIRST,LAST' - Print lines from FIRST to LAST. Both arguments are linespecs. - When a `list' command has two linespecs, and the source file of - the second linespec is omitted, this refers to the same source - file as the first linespec. - -`list ,LAST' - Print lines ending with LAST. - -`list FIRST,' - Print lines starting with FIRST. - -`list +' - Print lines just after the lines last printed. - -`list -' - Print lines just before the lines last printed. - -`list' - As described in the preceding table. - - -File: gdb.info, Node: Specify Location, Next: Edit, Prev: List, Up: Source - -9.2 Specifying a Location -========================= - -Several GDB commands accept arguments that specify a location of your -program's code. Since GDB is a source-level debugger, a location -usually specifies some line in the source code; for that reason, -locations are also known as "linespecs". - - Here are all the different ways of specifying a code location that -GDB understands: - -`LINENUM' - Specifies the line number LINENUM of the current source file. - -`-OFFSET' -`+OFFSET' - Specifies the line OFFSET lines before or after the "current - line". For the `list' command, the current line is the last one - printed; for the breakpoint commands, this is the line at which - execution stopped in the currently selected "stack frame" (*note - Frames: Frames, for a description of stack frames.) When used as - the second of the two linespecs in a `list' command, this - specifies the line OFFSET lines up or down from the first linespec. - -`FILENAME:LINENUM' - Specifies the line LINENUM in the source file FILENAME. - -`FUNCTION' - Specifies the line that begins the body of the function FUNCTION. - For example, in C, this is the line with the open brace. - -`FUNCTION:LABEL' - Specifies the line where LABEL appears in FUNCTION. - -`FILENAME:FUNCTION' - Specifies the line that begins the body of the function FUNCTION - in the file FILENAME. You only need the file name with a function - name to avoid ambiguity when there are identically named functions - in different source files. - -`LABEL' - Specifies the line at which the label named LABEL appears. GDB - searches for the label in the function corresponding to the - currently selected stack frame. If there is no current selected - stack frame (for instance, if the inferior is not running), then - GDB will not search for a label. - -`*ADDRESS' - Specifies the program address ADDRESS. For line-oriented - commands, such as `list' and `edit', this specifies a source line - that contains ADDRESS. For `break' and other breakpoint oriented - commands, this can be used to set breakpoints in parts of your - program which do not have debugging information or source files. - - Here ADDRESS may be any expression valid in the current working - language (*note working language: Languages.) that specifies a code - address. In addition, as a convenience, GDB extends the semantics - of expressions used in locations to cover the situations that - frequently happen during debugging. Here are the various forms of - ADDRESS: - - `EXPRESSION' - Any expression valid in the current working language. - - `FUNCADDR' - An address of a function or procedure derived from its name. - In C, C++, Java, Objective-C, Fortran, minimal, and assembly, - this is simply the function's name FUNCTION (and actually a - special case of a valid expression). In Pascal and Modula-2, - this is `&FUNCTION'. In Ada, this is `FUNCTION'Address' - (although the Pascal form also works). - - This form specifies the address of the function's first - instruction, before the stack frame and arguments have been - set up. - - `'FILENAME'::FUNCADDR' - Like FUNCADDR above, but also specifies the name of the source - file explicitly. This is useful if the name of the function - does not specify the function unambiguously, e.g., if there - are several functions with identical names in different - source files. - - - -File: gdb.info, Node: Edit, Next: Search, Prev: Specify Location, Up: Source - -9.3 Editing Source Files -======================== - -To edit the lines in a source file, use the `edit' command. The -editing program of your choice is invoked with the current line set to -the active line in the program. Alternatively, there are several ways -to specify what part of the file you want to print if you want to see -other parts of the program: - -`edit LOCATION' - Edit the source file specified by `location'. Editing starts at - that LOCATION, e.g., at the specified source line of the specified - file. *Note Specify Location::, for all the possible forms of the - LOCATION argument; here are the forms of the `edit' command most - commonly used: - - `edit NUMBER' - Edit the current source file with NUMBER as the active line - number. - - `edit FUNCTION' - Edit the file containing FUNCTION at the beginning of its - definition. - - -9.3.1 Choosing your Editor --------------------------- - -You can customize GDB to use any editor you want (1). By default, it -is `/bin/ex', but you can change this by setting the environment -variable `EDITOR' before using GDB. For example, to configure GDB to -use the `vi' editor, you could use these commands with the `sh' shell: - EDITOR=/usr/bin/vi - export EDITOR - gdb ... - or in the `csh' shell, - setenv EDITOR /usr/bin/vi - gdb ... - - ---------- Footnotes ---------- - - (1) The only restriction is that your editor (say `ex'), recognizes -the following command-line syntax: - ex +NUMBER file - The optional numeric value +NUMBER specifies the number of the line -in the file where to start editing. - - -File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source - -9.4 Searching Source Files -========================== - -There are two commands for searching through the current source file -for a regular expression. - -`forward-search REGEXP' -`search REGEXP' - The command `forward-search REGEXP' checks each line, starting - with the one following the last line listed, for a match for - REGEXP. It lists the line that is found. You can use the synonym - `search REGEXP' or abbreviate the command name as `fo'. - -`reverse-search REGEXP' - The command `reverse-search REGEXP' checks each line, starting - with the one before the last line listed and going backward, for a - match for REGEXP. It lists the line that is found. You can - abbreviate this command as `rev'. - - -File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source - -9.5 Specifying Source Directories -================================= - -Executable programs sometimes do not record the directories of the -source files from which they were compiled, just the names. Even when -they do, the directories could be moved between the compilation and -your debugging session. GDB has a list of directories to search for -source files; this is called the "source path". Each time GDB wants a -source file, it tries all the directories in the list, in the order -they are present in the list, until it finds a file with the desired -name. - - For example, suppose an executable references the file -`/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The -file is first looked up literally; if this fails, -`/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, -`/mnt/cross/foo.c' is opened; if this fails, an error message is -printed. GDB does not look up the parts of the source file name, such -as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of -the source path are not searched: if the source path is `/mnt/cross', -and the binary refers to `foo.c', GDB would not find it under -`/mnt/cross/usr/src/foo-1.0/lib'. - - Plain file names, relative file names with leading directories, file -names containing dots, etc. are all treated as described above; for -instance, if the source path is `/mnt/cross', and the source file is -recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then -`/mnt/cross/../lib/foo.c', and after that--`/mnt/cross/foo.c'. - - Note that the executable search path is _not_ used to locate the -source files. - - Whenever you reset or rearrange the source path, GDB clears out any -information it has cached about where source files are found and where -each line is in the file. - - When you start GDB, its source path includes only `cdir' and `cwd', -in that order. To add other directories, use the `directory' command. - - The search path is used to find both program source files and GDB -script files (read using the `-command' option and `source' command). - - In addition to the source path, GDB provides a set of commands that -manage a list of source path substitution rules. A "substitution rule" -specifies how to rewrite source directories stored in the program's -debug information in case the sources were moved to a different -directory between compilation and debugging. A rule is made of two -strings, the first specifying what needs to be rewritten in the path, -and the second specifying how it should be rewritten. In *note set -substitute-path::, we name these two parts FROM and TO respectively. -GDB does a simple string replacement of FROM with TO at the start of -the directory part of the source file name, and uses that result -instead of the original file name to look up the sources. - - Using the previous example, suppose the `foo-1.0' tree has been -moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace -`/usr/src' in all source path names with `/mnt/cross'. The first -lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the -original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source -path substitution rule, use the `set substitute-path' command (*note -set substitute-path::). - - To avoid unexpected substitution results, a rule is applied only if -the FROM part of the directory name ends at a directory separator. For -instance, a rule substituting `/usr/source' into `/mnt/cross' will be -applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'. -And because the substitution is applied only at the beginning of the -directory name, this rule will not be applied to -`/root/usr/source/baz.c' either. - - In many cases, you can achieve the same result using the `directory' -command. However, `set substitute-path' can be more efficient in the -case where the sources are organized in a complex tree with multiple -subdirectories. With the `directory' command, you need to add each -subdirectory of your project. If you moved the entire tree while -preserving its internal organization, then `set substitute-path' allows -you to direct the debugger to all the sources with one single command. - - `set substitute-path' is also more than just a shortcut command. -The source path is only used if the file at the original location no -longer exists. On the other hand, `set substitute-path' modifies the -debugger behavior to look at the rewritten location instead. So, if -for any reason a source file that is not relevant to your executable is -located at the original location, a substitution rule is the only -method available to point GDB at the new location. - - You can configure a default source path substitution rule by -configuring GDB with the `--with-relocated-sources=DIR' option. The DIR -should be the name of a directory under GDB's configured prefix (set -with `--prefix' or `--exec-prefix'), and directory names in debug -information under DIR will be adjusted automatically if the installed -GDB is moved to a new location. This is useful if GDB, libraries or -executables with debug information and corresponding source code are -being moved together. - -`directory DIRNAME ...' - -`dir DIRNAME ...' - Add directory DIRNAME to the front of the source path. Several - directory names may be given to this command, separated by `:' - (`;' on MS-DOS and MS-Windows, where `:' usually appears as part - of absolute file names) or whitespace. You may specify a - directory that is already in the source path; this moves it - forward, so GDB searches it sooner. - - You can use the string `$cdir' to refer to the compilation - directory (if one is recorded), and `$cwd' to refer to the current - working directory. `$cwd' is not the same as `.'--the former - tracks the current working directory as it changes during your GDB - session, while the latter is immediately expanded to the current - directory at the time you add an entry to the source path. - -`directory' - Reset the source path to its default value (`$cdir:$cwd' on Unix - systems). This requires confirmation. - -`set directories PATH-LIST' - Set the source path to PATH-LIST. `$cdir:$cwd' are added if - missing. - -`show directories' - Print the source path: show which directories it contains. - -`set substitute-path FROM TO' - Define a source path substitution rule, and add it at the end of - the current list of existing substitution rules. If a rule with - the same FROM was already defined, then the old rule is also - deleted. - - For example, if the file `/foo/bar/baz.c' was moved to - `/mnt/cross/baz.c', then the command - - (gdb) set substitute-path /usr/src /mnt/cross - - will tell GDB to replace `/usr/src' with `/mnt/cross', which will - allow GDB to find the file `baz.c' even though it was moved. - - In the case when more than one substitution rule have been defined, - the rules are evaluated one by one in the order where they have - been defined. The first one matching, if any, is selected to - perform the substitution. - - For instance, if we had entered the following commands: - - (gdb) set substitute-path /usr/src/include /mnt/include - (gdb) set substitute-path /usr/src /mnt/src - - GDB would then rewrite `/usr/src/include/defs.h' into - `/mnt/include/defs.h' by using the first rule. However, it would - use the second rule to rewrite `/usr/src/lib/foo.c' into - `/mnt/src/lib/foo.c'. - -`unset substitute-path [path]' - If a path is specified, search the current list of substitution - rules for a rule that would rewrite that path. Delete that rule - if found. A warning is emitted by the debugger if no rule could - be found. - - If no path is specified, then all substitution rules are deleted. - -`show substitute-path [path]' - If a path is specified, then print the source path substitution - rule which would rewrite that path, if any. - - If no path is specified, then print all existing source path - substitution rules. - - - If your source path is cluttered with directories that are no longer -of interest, GDB may sometimes cause confusion by finding the wrong -versions of source. You can correct the situation as follows: - - 1. Use `directory' with no argument to reset the source path to its - default value. - - 2. Use `directory' with suitable arguments to reinstall the - directories you want in the source path. You can add all the - directories in one command. - - -File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source - -9.6 Source and Machine Code -=========================== - -You can use the command `info line' to map source lines to program -addresses (and vice versa), and the command `disassemble' to display a -range of addresses as machine instructions. You can use the command -`set disassemble-next-line' to set whether to disassemble next source -line when execution stops. When run under GNU Emacs mode, the `info -line' command causes the arrow to point to the line specified. Also, -`info line' prints addresses in symbolic form as well as hex. - -`info line LINESPEC' - Print the starting and ending addresses of the compiled code for - source line LINESPEC. You can specify source lines in any of the - ways documented in *note Specify Location::. - - For example, we can use `info line' to discover the location of the -object code for the first line of function `m4_changequote': - - (gdb) info line m4_changequote - Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. - -We can also inquire (using `*ADDR' as the form for LINESPEC) what -source line covers a particular address: - (gdb) info line *0x63ff - Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. - - After `info line', the default address for the `x' command is -changed to the starting address of the line, so that `x/i' is -sufficient to begin examining the machine code (*note Examining Memory: -Memory.). Also, this address is saved as the value of the convenience -variable `$_' (*note Convenience Variables: Convenience Vars.). - -`disassemble' -`disassemble /m' -`disassemble /r' - This specialized command dumps a range of memory as machine - instructions. It can also print mixed source+disassembly by - specifying the `/m' modifier and print the raw instructions in hex - as well as in symbolic form by specifying the `/r'. The default - memory range is the function surrounding the program counter of - the selected frame. A single argument to this command is a - program counter value; GDB dumps the function surrounding this - value. When two arguments are given, they should be separated by - a comma, possibly surrounded by whitespace. The arguments specify - a range of addresses to dump, in one of two forms: - - `START,END' - the addresses from START (inclusive) to END (exclusive) - - `START,+LENGTH' - the addresses from START (inclusive) to `START+LENGTH' - (exclusive). - - When 2 arguments are specified, the name of the function is also - printed (since there could be several functions in the given - range). - - The argument(s) can be any expression yielding a numeric value, - such as `0x32c4', `&main+10' or `$pc - 8'. - - If the range of memory being disassembled contains current program - counter, the instruction at that location is shown with a `=>' - marker. - - The following example shows the disassembly of a range of addresses -of HP PA-RISC 2.0 code: - - (gdb) disas 0x32c4, 0x32e4 - Dump of assembler code from 0x32c4 to 0x32e4: - 0x32c4 <main+204>: addil 0,dp - 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 - 0x32cc <main+212>: ldil 0x3000,r31 - 0x32d0 <main+216>: ble 0x3f8(sr4,r31) - 0x32d4 <main+220>: ldo 0(r31),rp - 0x32d8 <main+224>: addil -0x800,dp - 0x32dc <main+228>: ldo 0x588(r1),r26 - 0x32e0 <main+232>: ldil 0x3000,r31 - End of assembler dump. - - Here is an example showing mixed source+assembly for Intel x86, when -the program is stopped just after function prologue: - - (gdb) disas /m main - Dump of assembler code for function main: - 5 { - 0x08048330 <+0>: push %ebp - 0x08048331 <+1>: mov %esp,%ebp - 0x08048333 <+3>: sub $0x8,%esp - 0x08048336 <+6>: and $0xfffffff0,%esp - 0x08048339 <+9>: sub $0x10,%esp - - 6 printf ("Hello.\n"); - => 0x0804833c <+12>: movl $0x8048440,(%esp) - 0x08048343 <+19>: call 0x8048284 <puts@plt> - - 7 return 0; - 8 } - 0x08048348 <+24>: mov $0x0,%eax - 0x0804834d <+29>: leave - 0x0804834e <+30>: ret - - End of assembler dump. - - Here is another example showing raw instructions in hex for AMD -x86-64, - - (gdb) disas /r 0x400281,+10 - Dump of assembler code from 0x400281 to 0x40028b: - 0x0000000000400281: 38 36 cmp %dh,(%rsi) - 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax - 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) - 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al - End of assembler dump. - - Some architectures have more than one commonly-used set of -instruction mnemonics or other syntax. - - For programs that were dynamically linked and use shared libraries, -instructions that call functions or branch to locations in the shared -libraries might show a seemingly bogus location--it's actually a -location of the relocation table. On some architectures, GDB might be -able to resolve these to actual function names. - -`set disassembly-flavor INSTRUCTION-SET' - Select the instruction set to use when disassembling the program - via the `disassemble' or `x/i' commands. - - Currently this command is only defined for the Intel x86 family. - You can set INSTRUCTION-SET to either `intel' or `att'. The - default is `att', the AT&T flavor used by default by Unix - assemblers for x86-based targets. - -`show disassembly-flavor' - Show the current setting of the disassembly flavor. - -`set disassemble-next-line' -`show disassemble-next-line' - Control whether or not GDB will disassemble the next source line - or instruction when execution stops. If ON, GDB will display - disassembly of the next source line when execution of the program - being debugged stops. This is _in addition_ to displaying the - source line itself, which GDB always does if possible. If the - next source line cannot be displayed for some reason (e.g., if GDB - cannot find the source file, or there's no line info in the debug - info), GDB will display disassembly of the next _instruction_ - instead of showing the next source line. If AUTO, GDB will - display disassembly of next instruction only if the source line - cannot be displayed. This setting causes GDB to display some - feedback when you step through a function with no line info or - whose source file is unavailable. The default is OFF, which means - never display the disassembly of the next line or instruction. - - -File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top - -10 Examining Data -***************** - -The usual way to examine data in your program is with the `print' -command (abbreviated `p'), or its synonym `inspect'. It evaluates and -prints the value of an expression of the language your program is -written in (*note Using GDB with Different Languages: Languages.). It -may also print the expression using a Python-based pretty-printer -(*note Pretty Printing::). - -`print EXPR' -`print /F EXPR' - EXPR is an expression (in the source language). By default the - value of EXPR is printed in a format appropriate to its data type; - you can choose a different format by specifying `/F', where F is a - letter specifying the format; see *note Output Formats: Output - Formats. - -`print' -`print /F' - If you omit EXPR, GDB displays the last value again (from the - "value history"; *note Value History: Value History.). This - allows you to conveniently inspect the same value in an - alternative format. - - A more low-level way of examining data is with the `x' command. It -examines data in memory at a specified address and prints it in a -specified format. *Note Examining Memory: Memory. - - If you are interested in information about types, or about how the -fields of a struct or a class are declared, use the `ptype EXP' command -rather than `print'. *Note Examining the Symbol Table: Symbols. - -* Menu: - -* Expressions:: Expressions -* Ambiguous Expressions:: Ambiguous Expressions -* Variables:: Program variables -* Arrays:: Artificial arrays -* Output Formats:: Output formats -* Memory:: Examining memory -* Auto Display:: Automatic display -* Print Settings:: Print settings -* Pretty Printing:: Python pretty printing -* Value History:: Value history -* Convenience Vars:: Convenience variables -* Registers:: Registers -* Floating Point Hardware:: Floating point hardware -* Vector Unit:: Vector Unit -* OS Information:: Auxiliary data provided by operating system -* Memory Region Attributes:: Memory region attributes -* Dump/Restore Files:: Copy between memory and a file -* Core File Generation:: Cause a program dump its core -* Character Sets:: Debugging programs that use a different - character set than GDB does -* Caching Remote Data:: Data caching for remote targets -* Searching Memory:: Searching memory for a sequence of bytes - - -File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data - -10.1 Expressions -================ - -`print' and many other GDB commands accept an expression and compute -its value. Any kind of constant, variable or operator defined by the -programming language you are using is valid in an expression in GDB. -This includes conditional expressions, function calls, casts, and -string constants. It also includes preprocessor macros, if you -compiled your program to include this information; see *note -Compilation::. - - GDB supports array constants in expressions input by the user. The -syntax is {ELEMENT, ELEMENT...}. For example, you can use the command -`print {1, 2, 3}' to create an array of three integers. If you pass an -array to a function or assign it to a program variable, GDB copies the -array to memory that is `malloc'ed in the target program. - - Because C is so widespread, most of the expressions shown in -examples in this manual are in C. *Note Using GDB with Different -Languages: Languages, for information on how to use expressions in other -languages. - - In this section, we discuss operators that you can use in GDB -expressions regardless of your programming language. - - Casts are supported in all languages, not just in C, because it is so -useful to cast a number into a pointer in order to examine a structure -at that address in memory. - - GDB supports these operators, in addition to those common to -programming languages: - -`@' - `@' is a binary operator for treating parts of memory as arrays. - *Note Artificial Arrays: Arrays, for more information. - -`::' - `::' allows you to specify a variable in terms of the file or - function where it is defined. *Note Program Variables: Variables. - -`{TYPE} ADDR' - Refers to an object of type TYPE stored at address ADDR in memory. - ADDR may be any expression whose value is an integer or pointer - (but parentheses are required around binary operators, just as in - a cast). This construct is allowed regardless of what kind of - data is normally supposed to reside at ADDR. - - -File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data - -10.2 Ambiguous Expressions -========================== - -Expressions can sometimes contain some ambiguous elements. For -instance, some programming languages (notably Ada, C++ and Objective-C) -permit a single function name to be defined several times, for -application in different contexts. This is called "overloading". -Another example involving Ada is generics. A "generic package" is -similar to C++ templates and is typically instantiated several times, -resulting in the same function name being defined in different contexts. - - In some cases and depending on the language, it is possible to adjust -the expression to remove the ambiguity. For instance in C++, you can -specify the signature of the function you want to break on, as in -`break FUNCTION(TYPES)'. In Ada, using the fully qualified name of -your function often makes the expression unambiguous as well. - - When an ambiguity that needs to be resolved is detected, the debugger -has the capability to display a menu of numbered choices for each -possibility, and then waits for the selection with the prompt `>'. The -first option is always `[0] cancel', and typing `0 <RET>' aborts the -current command. If the command in which the expression was used -allows more than one choice to be selected, the next option in the menu -is `[1] all', and typing `1 <RET>' selects all possible choices. - - For example, the following session excerpt shows an attempt to set a -breakpoint at the overloaded symbol `String::after'. We choose three -particular definitions of that function name: - - (gdb) b String::after - [0] cancel - [1] all - [2] file:String.cc; line number:867 - [3] file:String.cc; line number:860 - [4] file:String.cc; line number:875 - [5] file:String.cc; line number:853 - [6] file:String.cc; line number:846 - [7] file:String.cc; line number:735 - > 2 4 6 - Breakpoint 1 at 0xb26c: file String.cc, line 867. - Breakpoint 2 at 0xb344: file String.cc, line 875. - Breakpoint 3 at 0xafcc: file String.cc, line 846. - Multiple breakpoints were set. - Use the "delete" command to delete unwanted - breakpoints. - (gdb) - -`set multiple-symbols MODE' - This option allows you to adjust the debugger behavior when an - expression is ambiguous. - - By default, MODE is set to `all'. If the command with which the - expression is used allows more than one choice, then GDB - automatically selects all possible choices. For instance, - inserting a breakpoint on a function using an ambiguous name - results in a breakpoint inserted on each possible match. However, - if a unique choice must be made, then GDB uses the menu to help - you disambiguate the expression. For instance, printing the - address of an overloaded function will result in the use of the - menu. - - When MODE is set to `ask', the debugger always uses the menu when - an ambiguity is detected. - - Finally, when MODE is set to `cancel', the debugger reports an - error due to the ambiguity and the command is aborted. - -`show multiple-symbols' - Show the current value of the `multiple-symbols' setting. - - -File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data - -10.3 Program Variables -====================== - -The most common kind of expression to use is the name of a variable in -your program. - - Variables in expressions are understood in the selected stack frame -(*note Selecting a Frame: Selection.); they must be either: - - * global (or file-static) - -or - - * visible according to the scope rules of the programming language - from the point of execution in that frame - -This means that in the function - - foo (a) - int a; - { - bar (a); - { - int b = test (); - bar (b); - } - } - -you can examine and use the variable `a' whenever your program is -executing within the function `foo', but you can only use or examine -the variable `b' while your program is executing inside the block where -`b' is declared. - - There is an exception: you can refer to a variable or function whose -scope is a single source file even if the current execution point is not -in this file. But it is possible to have more than one such variable or -function with the same name (in different source files). If that -happens, referring to that name has unpredictable effects. If you wish, -you can specify a static variable in a particular function or file, -using the colon-colon (`::') notation: - - FILE::VARIABLE - FUNCTION::VARIABLE - -Here FILE or FUNCTION is the name of the context for the static -VARIABLE. In the case of file names, you can use quotes to make sure -GDB parses the file name as a single word--for example, to print a -global value of `x' defined in `f2.c': - - (gdb) p 'f2.c'::x - - This use of `::' is very rarely in conflict with the very similar -use of the same notation in C++. GDB also supports use of the C++ -scope resolution operator in GDB expressions. - - _Warning:_ Occasionally, a local variable may appear to have the - wrong value at certain points in a function--just after entry to a - new scope, and just before exit. - You may see this problem when you are stepping by machine -instructions. This is because, on most machines, it takes more than -one instruction to set up a stack frame (including local variable -definitions); if you are stepping by machine instructions, variables -may appear to have the wrong values until the stack frame is completely -built. On exit, it usually also takes more than one machine -instruction to destroy a stack frame; after you begin stepping through -that group of instructions, local variable definitions may be gone. - - This may also happen when the compiler does significant -optimizations. To be sure of always seeing accurate values, turn off -all optimization when compiling. - - Another possible effect of compiler optimizations is to optimize -unused variables out of existence, or assign variables to registers (as -opposed to memory addresses). Depending on the support for such cases -offered by the debug info format used by the compiler, GDB might not be -able to display values for such local variables. If that happens, GDB -will print a message like this: - - No symbol "foo" in current context. - - To solve such problems, either recompile without optimizations, or -use a different debug info format, if the compiler supports several such -formats. For example, GCC, the GNU C/C++ compiler, usually supports -the `-gstabs+' option. `-gstabs+' produces debug info in a format that -is superior to formats such as COFF. You may be able to use DWARF 2 -(`-gdwarf-2'), which is also an effective form for debug info. *Note -Options for Debugging Your Program or GCC: (gcc.info)Debugging Options. -*Note C and C++: C, for more information about debug info formats that -are best suited to C++ programs. - - If you ask to print an object whose contents are unknown to GDB, -e.g., because its data type is not completely specified by the debug -information, GDB will say `<incomplete type>'. *Note incomplete type: -Symbols, for more about this. - - Strings are identified as arrays of `char' values without specified -signedness. Arrays of either `signed char' or `unsigned char' get -printed as arrays of 1 byte sized integers. `-fsigned-char' or -`-funsigned-char' GCC options have no effect as GDB defines literal -string type `"char"' as `char' without a sign. For program code - - char var0[] = "A"; - signed char var1[] = "A"; - - You get during debugging - (gdb) print var0 - $1 = "A" - (gdb) print var1 - $2 = {65 'A', 0 '\0'} - - -File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data - -10.4 Artificial Arrays -====================== - -It is often useful to print out several successive objects of the same -type in memory; a section of an array, or an array of dynamically -determined size for which only a pointer exists in the program. - - You can do this by referring to a contiguous span of memory as an -"artificial array", using the binary operator `@'. The left operand of -`@' should be the first element of the desired array and be an -individual object. The right operand should be the desired length of -the array. The result is an array value whose elements are all of the -type of the left argument. The first element is actually the left -argument; the second element comes from bytes of memory immediately -following those that hold the first element, and so on. Here is an -example. If a program says - - int *array = (int *) malloc (len * sizeof (int)); - -you can print the contents of `array' with - - p *array@len - - The left operand of `@' must reside in memory. Array values made -with `@' in this way behave just like other arrays in terms of -subscripting, and are coerced to pointers when used in expressions. -Artificial arrays most often appear in expressions via the value history -(*note Value History: Value History.), after printing one out. - - Another way to create an artificial array is to use a cast. This -re-interprets a value as if it were an array. The value need not be in -memory: - (gdb) p/x (short[2])0x12345678 - $1 = {0x1234, 0x5678} - - As a convenience, if you leave the array length out (as in -`(TYPE[])VALUE') GDB calculates the size to fill the value (as -`sizeof(VALUE)/sizeof(TYPE)': - (gdb) p/x (short[])0x12345678 - $2 = {0x1234, 0x5678} - - Sometimes the artificial array mechanism is not quite enough; in -moderately complex data structures, the elements of interest may not -actually be adjacent--for example, if you are interested in the values -of pointers in an array. One useful work-around in this situation is -to use a convenience variable (*note Convenience Variables: Convenience -Vars.) as a counter in an expression that prints the first interesting -value, and then repeat that expression via <RET>. For instance, -suppose you have an array `dtab' of pointers to structures, and you are -interested in the values of a field `fv' in each structure. Here is an -example of what you might type: - - set $i = 0 - p dtab[$i++]->fv - <RET> - <RET> - ... - - -File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data - -10.5 Output Formats -=================== - -By default, GDB prints a value according to its data type. Sometimes -this is not what you want. For example, you might want to print a -number in hex, or a pointer in decimal. Or you might want to view data -in memory at a certain address as a character string or as an -instruction. To do these things, specify an "output format" when you -print a value. - - The simplest use of output formats is to say how to print a value -already computed. This is done by starting the arguments of the -`print' command with a slash and a format letter. The format letters -supported are: - -`x' - Regard the bits of the value as an integer, and print the integer - in hexadecimal. - -`d' - Print as integer in signed decimal. - -`u' - Print as integer in unsigned decimal. - -`o' - Print as integer in octal. - -`t' - Print as integer in binary. The letter `t' stands for "two". (1) - -`a' - Print as an address, both absolute in hexadecimal and as an offset - from the nearest preceding symbol. You can use this format used - to discover where (in what function) an unknown address is located: - - (gdb) p/a 0x54320 - $3 = 0x54320 <_initialize_vx+396> - - The command `info symbol 0x54320' yields similar results. *Note - info symbol: Symbols. - -`c' - Regard as an integer and print it as a character constant. This - prints both the numerical value and its character representation. - The character representation is replaced with the octal escape - `\nnn' for characters outside the 7-bit ASCII range. - - Without this format, GDB displays `char', `unsigned char', and - `signed char' data as character constants. Single-byte members of - vectors are displayed as integer data. - -`f' - Regard the bits of the value as a floating point number and print - using typical floating point syntax. - -`s' - Regard as a string, if possible. With this format, pointers to - single-byte data are displayed as null-terminated strings and - arrays of single-byte data are displayed as fixed-length strings. - Other values are displayed in their natural types. - - Without this format, GDB displays pointers to and arrays of - `char', `unsigned char', and `signed char' as strings. - Single-byte members of a vector are displayed as an integer array. - -`r' - Print using the `raw' formatting. By default, GDB will use a - Python-based pretty-printer, if one is available (*note Pretty - Printing::). This typically results in a higher-level display of - the value's contents. The `r' format bypasses any Python - pretty-printer which might exist. - - For example, to print the program counter in hex (*note -Registers::), type - - p/x $pc - -Note that no space is required before the slash; this is because command -names in GDB cannot contain a slash. - - To reprint the last value in the value history with a different -format, you can use the `print' command with just a format and no -expression. For example, `p/x' reprints the last value in hex. - - ---------- Footnotes ---------- - - (1) `b' cannot be used because these format letters are also used -with the `x' command, where `b' stands for "byte"; see *note Examining -Memory: Memory. - - -File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data - -10.6 Examining Memory -===================== - -You can use the command `x' (for "examine") to examine memory in any of -several formats, independently of your program's data types. - -`x/NFU ADDR' -`x ADDR' -`x' - Use the `x' command to examine memory. - - N, F, and U are all optional parameters that specify how much memory -to display and how to format it; ADDR is an expression giving the -address where you want to start displaying memory. If you use defaults -for NFU, you need not type the slash `/'. Several commands set -convenient defaults for ADDR. - -N, the repeat count - The repeat count is a decimal integer; the default is 1. It - specifies how much memory (counting by units U) to display. - -F, the display format - The display format is one of the formats used by `print' (`x', - `d', `u', `o', `t', `a', `c', `f', `s'), and in addition `i' (for - machine instructions). The default is `x' (hexadecimal) - initially. The default changes each time you use either `x' or - `print'. - -U, the unit size - The unit size is any of - - `b' - Bytes. - - `h' - Halfwords (two bytes). - - `w' - Words (four bytes). This is the initial default. - - `g' - Giant words (eight bytes). - - Each time you specify a unit size with `x', that size becomes the - default unit the next time you use `x'. For the `i' format, the - unit size is ignored and is normally not written. For the `s' - format, the unit size defaults to `b', unless it is explicitly - given. Use `x /hs' to display 16-bit char strings and `x /ws' to - display 32-bit strings. The next use of `x /s' will again display - 8-bit strings. Note that the results depend on the programming - language of the current compilation unit. If the language is C, - the `s' modifier will use the UTF-16 encoding while `w' will use - UTF-32. The encoding is set by the programming language and cannot - be altered. - -ADDR, starting display address - ADDR is the address where you want GDB to begin displaying memory. - The expression need not have a pointer value (though it may); it - is always interpreted as an integer address of a byte of memory. - *Note Expressions: Expressions, for more information on - expressions. The default for ADDR is usually just after the last - address examined--but several other commands also set the default - address: `info breakpoints' (to the address of the last breakpoint - listed), `info line' (to the starting address of a line), and - `print' (if you use it to display a value from memory). - - For example, `x/3uh 0x54320' is a request to display three halfwords -(`h') of memory, formatted as unsigned decimal integers (`u'), starting -at address `0x54320'. `x/4xw $sp' prints the four words (`w') of -memory above the stack pointer (here, `$sp'; *note Registers: -Registers.) in hexadecimal (`x'). - - Since the letters indicating unit sizes are all distinct from the -letters specifying output formats, you do not have to remember whether -unit size or format comes first; either order works. The output -specifications `4xw' and `4wx' mean exactly the same thing. (However, -the count N must come first; `wx4' does not work.) - - Even though the unit size U is ignored for the formats `s' and `i', -you might still want to use a count N; for example, `3i' specifies that -you want to see three machine instructions, including any operands. -For convenience, especially when used with the `display' command, the -`i' format also prints branch delay slot instructions, if any, beyond -the count specified, which immediately follow the last instruction that -is within the count. The command `disassemble' gives an alternative -way of inspecting machine instructions; see *note Source and Machine -Code: Machine Code. - - All the defaults for the arguments to `x' are designed to make it -easy to continue scanning memory with minimal specifications each time -you use `x'. For example, after you have inspected three machine -instructions with `x/3i ADDR', you can inspect the next seven with just -`x/7'. If you use <RET> to repeat the `x' command, the repeat count N -is used again; the other arguments default as for successive uses of -`x'. - - When examining machine instructions, the instruction at current -program counter is shown with a `=>' marker. For example: - - (gdb) x/5i $pc-6 - 0x804837f <main+11>: mov %esp,%ebp - 0x8048381 <main+13>: push %ecx - 0x8048382 <main+14>: sub $0x4,%esp - => 0x8048385 <main+17>: movl $0x8048460,(%esp) - 0x804838c <main+24>: call 0x80482d4 <puts@plt> - - The addresses and contents printed by the `x' command are not saved -in the value history because there is often too much of them and they -would get in the way. Instead, GDB makes these values available for -subsequent use in expressions as values of the convenience variables -`$_' and `$__'. After an `x' command, the last address examined is -available for use in expressions in the convenience variable `$_'. The -contents of that address, as examined, are available in the convenience -variable `$__'. - - If the `x' command has a repeat count, the address and contents saved -are from the last memory unit printed; this is not the same as the last -address printed if several units were printed on the last line of -output. - - When you are debugging a program running on a remote target machine -(*note Remote Debugging::), you may wish to verify the program's image -in the remote machine's memory against the executable file you -downloaded to the target. The `compare-sections' command is provided -for such situations. - -`compare-sections [SECTION-NAME]' - Compare the data of a loadable section SECTION-NAME in the - executable file of the program being debugged with the same - section in the remote machine's memory, and report any mismatches. - With no arguments, compares all loadable sections. This command's - availability depends on the target's support for the `"qCRC"' - remote request. - - -File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data - -10.7 Automatic Display -====================== - -If you find that you want to print the value of an expression frequently -(to see how it changes), you might want to add it to the "automatic -display list" so that GDB prints its value each time your program stops. -Each expression added to the list is given a number to identify it; to -remove an expression from the list, you specify that number. The -automatic display looks like this: - - 2: foo = 38 - 3: bar[5] = (struct hack *) 0x3804 - -This display shows item numbers, expressions and their current values. -As with displays you request manually using `x' or `print', you can -specify the output format you prefer; in fact, `display' decides -whether to use `print' or `x' depending your format specification--it -uses `x' if you specify either the `i' or `s' format, or a unit size; -otherwise it uses `print'. - -`display EXPR' - Add the expression EXPR to the list of expressions to display each - time your program stops. *Note Expressions: Expressions. - - `display' does not repeat if you press <RET> again after using it. - -`display/FMT EXPR' - For FMT specifying only a display format and not a size or count, - add the expression EXPR to the auto-display list but arrange to - display it each time in the specified format FMT. *Note Output - Formats: Output Formats. - -`display/FMT ADDR' - For FMT `i' or `s', or including a unit-size or a number of units, - add the expression ADDR as a memory address to be examined each - time your program stops. Examining means in effect doing `x/FMT - ADDR'. *Note Examining Memory: Memory. - - For example, `display/i $pc' can be helpful, to see the machine -instruction about to be executed each time execution stops (`$pc' is a -common name for the program counter; *note Registers: Registers.). - -`undisplay DNUMS...' -`delete display DNUMS...' - Remove items from the list of expressions to display. Specify the - numbers of the displays that you want affected with the command - argument DNUMS. It can be a single display number, one of the - numbers shown in the first field of the `info display' display; or - it could be a range of display numbers, as in `2-4'. - - `undisplay' does not repeat if you press <RET> after using it. - (Otherwise you would just get the error `No display number ...'.) - -`disable display DNUMS...' - Disable the display of item numbers DNUMS. A disabled display - item is not printed automatically, but is not forgotten. It may be - enabled again later. Specify the numbers of the displays that you - want affected with the command argument DNUMS. It can be a single - display number, one of the numbers shown in the first field of the - `info display' display; or it could be a range of display numbers, - as in `2-4'. - -`enable display DNUMS...' - Enable display of item numbers DNUMS. It becomes effective once - again in auto display of its expression, until you specify - otherwise. Specify the numbers of the displays that you want - affected with the command argument DNUMS. It can be a single - display number, one of the numbers shown in the first field of the - `info display' display; or it could be a range of display numbers, - as in `2-4'. - -`display' - Display the current values of the expressions on the list, just as - is done when your program stops. - -`info display' - Print the list of expressions previously set up to display - automatically, each one with its item number, but without showing - the values. This includes disabled expressions, which are marked - as such. It also includes expressions which would not be - displayed right now because they refer to automatic variables not - currently available. - - If a display expression refers to local variables, then it does not -make sense outside the lexical context for which it was set up. Such an -expression is disabled when execution enters a context where one of its -variables is not defined. For example, if you give the command -`display last_char' while inside a function with an argument -`last_char', GDB displays this argument while your program continues to -stop inside that function. When it stops elsewhere--where there is no -variable `last_char'--the display is disabled automatically. The next -time your program stops where `last_char' is meaningful, you can enable -the display expression once again. - - -File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data - -10.8 Print Settings -=================== - -GDB provides the following ways to control how arrays, structures, and -symbols are printed. - -These settings are useful for debugging programs in any language: - -`set print address' -`set print address on' - GDB prints memory addresses showing the location of stack traces, - structure values, pointer values, breakpoints, and so forth, even - when it also displays the contents of those addresses. The default - is `on'. For example, this is what a stack frame display looks - like with `set print address on': - - (gdb) f - #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") - at input.c:530 - 530 if (lquote != def_lquote) - -`set print address off' - Do not print addresses when displaying their contents. For - example, this is the same stack frame displayed with `set print - address off': - - (gdb) set print addr off - (gdb) f - #0 set_quotes (lq="<<", rq=">>") at input.c:530 - 530 if (lquote != def_lquote) - - You can use `set print address off' to eliminate all machine - dependent displays from the GDB interface. For example, with - `print address off', you should get the same text for backtraces on - all machines--whether or not they involve pointer arguments. - -`show print address' - Show whether or not addresses are to be printed. - - When GDB prints a symbolic address, it normally prints the closest -earlier symbol plus an offset. If that symbol does not uniquely -identify the address (for example, it is a name whose scope is a single -source file), you may need to clarify. One way to do this is with -`info line', for example `info line *0x4537'. Alternately, you can set -GDB to print the source file and line number when it prints a symbolic -address: - -`set print symbol-filename on' - Tell GDB to print the source file name and line number of a symbol - in the symbolic form of an address. - -`set print symbol-filename off' - Do not print source file name and line number of a symbol. This - is the default. - -`show print symbol-filename' - Show whether or not GDB will print the source file name and line - number of a symbol in the symbolic form of an address. - - Another situation where it is helpful to show symbol filenames and -line numbers is when disassembling code; GDB shows you the line number -and source file that corresponds to each instruction. - - Also, you may wish to see the symbolic form only if the address being -printed is reasonably close to the closest earlier symbol: - -`set print max-symbolic-offset MAX-OFFSET' - Tell GDB to only display the symbolic form of an address if the - offset between the closest earlier symbol and the address is less - than MAX-OFFSET. The default is 0, which tells GDB to always - print the symbolic form of an address if any symbol precedes it. - -`show print max-symbolic-offset' - Ask how large the maximum offset is that GDB prints in a symbolic - address. - - If you have a pointer and you are not sure where it points, try `set -print symbol-filename on'. Then you can determine the name and source -file location of the variable where it points, using `p/a POINTER'. -This interprets the address in symbolic form. For example, here GDB -shows that a variable `ptt' points at another variable `t', defined in -`hi2.c': - - (gdb) set print symbol-filename on - (gdb) p/a ptt - $4 = 0xe008 <t in hi2.c> - - _Warning:_ For pointers that point to a local variable, `p/a' does - not show the symbol name and filename of the referent, even with - the appropriate `set print' options turned on. - - Other settings control how different kinds of objects are printed: - -`set print array' -`set print array on' - Pretty print arrays. This format is more convenient to read, but - uses more space. The default is off. - -`set print array off' - Return to compressed format for arrays. - -`show print array' - Show whether compressed or pretty format is selected for displaying - arrays. - -`set print array-indexes' -`set print array-indexes on' - Print the index of each element when displaying arrays. May be - more convenient to locate a given element in the array or quickly - find the index of a given element in that printed array. The - default is off. - -`set print array-indexes off' - Stop printing element indexes when displaying arrays. - -`show print array-indexes' - Show whether the index of each element is printed when displaying - arrays. - -`set print elements NUMBER-OF-ELEMENTS' - Set a limit on how many elements of an array GDB will print. If - GDB is printing a large array, it stops printing after it has - printed the number of elements set by the `set print elements' - command. This limit also applies to the display of strings. When - GDB starts, this limit is set to 200. Setting NUMBER-OF-ELEMENTS - to zero means that the printing is unlimited. - -`show print elements' - Display the number of elements of a large array that GDB will - print. If the number is 0, then the printing is unlimited. - -`set print frame-arguments VALUE' - This command allows to control how the values of arguments are - printed when the debugger prints a frame (*note Frames::). The - possible values are: - - `all' - The values of all arguments are printed. - - `scalars' - Print the value of an argument only if it is a scalar. The - value of more complex arguments such as arrays, structures, - unions, etc, is replaced by `...'. This is the default. - Here is an example where only scalar arguments are shown: - - #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) - at frame-args.c:23 - - `none' - None of the argument values are printed. Instead, the value - of each argument is replaced by `...'. In this case, the - example above now becomes: - - #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) - at frame-args.c:23 - - By default, only scalar arguments are printed. This command can - be used to configure the debugger to print the value of all - arguments, regardless of their type. However, it is often - advantageous to not print the value of more complex parameters. - For instance, it reduces the amount of information printed in each - frame, making the backtrace more readable. Also, it improves - performance when displaying Ada frames, because the computation of - large arguments can sometimes be CPU-intensive, especially in - large applications. Setting `print frame-arguments' to `scalars' - (the default) or `none' avoids this computation, thus speeding up - the display of each Ada frame. - -`show print frame-arguments' - Show how the value of arguments should be displayed when printing - a frame. - -`set print repeats' - Set the threshold for suppressing display of repeated array - elements. When the number of consecutive identical elements of an - array exceeds the threshold, GDB prints the string `"<repeats N - times>"', where N is the number of identical repetitions, instead - of displaying the identical elements themselves. Setting the - threshold to zero will cause all elements to be individually - printed. The default threshold is 10. - -`show print repeats' - Display the current threshold for printing repeated identical - elements. - -`set print null-stop' - Cause GDB to stop printing the characters of an array when the - first NULL is encountered. This is useful when large arrays - actually contain only short strings. The default is off. - -`show print null-stop' - Show whether GDB stops printing an array on the first NULL - character. - -`set print pretty on' - Cause GDB to print structures in an indented format with one member - per line, like this: - - $1 = { - next = 0x0, - flags = { - sweet = 1, - sour = 1 - }, - meat = 0x54 "Pork" - } - -`set print pretty off' - Cause GDB to print structures in a compact format, like this: - - $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ - meat = 0x54 "Pork"} - - This is the default format. - -`show print pretty' - Show which format GDB is using to print structures. - -`set print sevenbit-strings on' - Print using only seven-bit characters; if this option is set, GDB - displays any eight-bit characters (in strings or character values) - using the notation `\'NNN. This setting is best if you are - working in English (ASCII) and you use the high-order bit of - characters as a marker or "meta" bit. - -`set print sevenbit-strings off' - Print full eight-bit characters. This allows the use of more - international character sets, and is the default. - -`show print sevenbit-strings' - Show whether or not GDB is printing only seven-bit characters. - -`set print union on' - Tell GDB to print unions which are contained in structures and - other unions. This is the default setting. - -`set print union off' - Tell GDB not to print unions which are contained in structures and - other unions. GDB will print `"{...}"' instead. - -`show print union' - Ask GDB whether or not it will print unions which are contained in - structures and other unions. - - For example, given the declarations - - typedef enum {Tree, Bug} Species; - typedef enum {Big_tree, Acorn, Seedling} Tree_forms; - typedef enum {Caterpillar, Cocoon, Butterfly} - Bug_forms; - - struct thing { - Species it; - union { - Tree_forms tree; - Bug_forms bug; - } form; - }; - - struct thing foo = {Tree, {Acorn}}; - - with `set print union on' in effect `p foo' would print - - $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} - - and with `set print union off' in effect it would print - - $1 = {it = Tree, form = {...}} - - `set print union' affects programs written in C-like languages and - in Pascal. - -These settings are of interest when debugging C++ programs: - -`set print demangle' -`set print demangle on' - Print C++ names in their source form rather than in the encoded - ("mangled") form passed to the assembler and linker for type-safe - linkage. The default is on. - -`show print demangle' - Show whether C++ names are printed in mangled or demangled form. - -`set print asm-demangle' -`set print asm-demangle on' - Print C++ names in their source form rather than their mangled - form, even in assembler code printouts such as instruction - disassemblies. The default is off. - -`show print asm-demangle' - Show whether C++ names in assembly listings are printed in mangled - or demangled form. - -`set demangle-style STYLE' - Choose among several encoding schemes used by different compilers - to represent C++ names. The choices for STYLE are currently: - - `auto' - Allow GDB to choose a decoding style by inspecting your - program. - - `gnu' - Decode based on the GNU C++ compiler (`g++') encoding - algorithm. This is the default. - - `hp' - Decode based on the HP ANSI C++ (`aCC') encoding algorithm. - - `lucid' - Decode based on the Lucid C++ compiler (`lcc') encoding - algorithm. - - `arm' - Decode using the algorithm in the `C++ Annotated Reference - Manual'. *Warning:* this setting alone is not sufficient to - allow debugging `cfront'-generated executables. GDB would - require further enhancement to permit that. - - If you omit STYLE, you will see a list of possible formats. - -`show demangle-style' - Display the encoding style currently in use for decoding C++ - symbols. - -`set print object' -`set print object on' - When displaying a pointer to an object, identify the _actual_ - (derived) type of the object rather than the _declared_ type, using - the virtual function table. - -`set print object off' - Display only the declared type of objects, without reference to the - virtual function table. This is the default setting. - -`show print object' - Show whether actual, or declared, object types are displayed. - -`set print static-members' -`set print static-members on' - Print static members when displaying a C++ object. The default is - on. - -`set print static-members off' - Do not print static members when displaying a C++ object. - -`show print static-members' - Show whether C++ static members are printed or not. - -`set print pascal_static-members' -`set print pascal_static-members on' - Print static members when displaying a Pascal object. The default - is on. - -`set print pascal_static-members off' - Do not print static members when displaying a Pascal object. - -`show print pascal_static-members' - Show whether Pascal static members are printed or not. - -`set print vtbl' -`set print vtbl on' - Pretty print C++ virtual function tables. The default is off. - (The `vtbl' commands do not work on programs compiled with the HP - ANSI C++ compiler (`aCC').) - -`set print vtbl off' - Do not pretty print C++ virtual function tables. - -`show print vtbl' - Show whether C++ virtual function tables are pretty printed, or - not. - - -File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data - -10.9 Pretty Printing -==================== - -GDB provides a mechanism to allow pretty-printing of values using -Python code. It greatly simplifies the display of complex objects. -This mechanism works for both MI and the CLI. - -* Menu: - -* Pretty-Printer Introduction:: Introduction to pretty-printers -* Pretty-Printer Example:: An example pretty-printer -* Pretty-Printer Commands:: Pretty-printer commands - - -File: gdb.info, Node: Pretty-Printer Introduction, Next: Pretty-Printer Example, Up: Pretty Printing - -10.9.1 Pretty-Printer Introduction ----------------------------------- - -When GDB prints a value, it first sees if there is a pretty-printer -registered for the value. If there is then GDB invokes the -pretty-printer to print the value. Otherwise the value is printed -normally. - - Pretty-printers are normally named. This makes them easy to manage. -The `info pretty-printer' command will list all the installed -pretty-printers with their names. If a pretty-printer can handle -multiple data types, then its "subprinters" are the printers for the -individual data types. Each such subprinter has its own name. The -format of the name is PRINTER-NAME;SUBPRINTER-NAME. - - Pretty-printers are installed by "registering" them with GDB. -Typically they are automatically loaded and registered when the -corresponding debug information is loaded, thus making them available -without having to do anything special. - - There are three places where a pretty-printer can be registered. - - * Pretty-printers registered globally are available when debugging - all inferiors. - - * Pretty-printers registered with a program space are available only - when debugging that program. *Note Progspaces In Python::, for - more details on program spaces in Python. - - * Pretty-printers registered with an objfile are loaded and unloaded - with the corresponding objfile (e.g., shared library). *Note - Objfiles In Python::, for more details on objfiles in Python. - - *Note Selecting Pretty-Printers::, for further information on how -pretty-printers are selected, - - *Note Writing a Pretty-Printer::, for implementing pretty printers -for new types. - - -File: gdb.info, Node: Pretty-Printer Example, Next: Pretty-Printer Commands, Prev: Pretty-Printer Introduction, Up: Pretty Printing - -10.9.2 Pretty-Printer Example ------------------------------ - -Here is how a C++ `std::string' looks without a pretty-printer: - - (gdb) print s - $1 = { - static npos = 4294967295, - _M_dataplus = { - <std::allocator<char>> = { - <__gnu_cxx::new_allocator<char>> = { - <No data fields>}, <No data fields> - }, - members of std::basic_string<char, std::char_traits<char>, - std::allocator<char> >::_Alloc_hider: - _M_p = 0x804a014 "abcd" - } - } - - With a pretty-printer for `std::string' only the contents are -printed: - - (gdb) print s - $2 = "abcd" - - -File: gdb.info, Node: Pretty-Printer Commands, Prev: Pretty-Printer Example, Up: Pretty Printing - -10.9.3 Pretty-Printer Commands ------------------------------- - -`info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' - Print the list of installed pretty-printers. This includes - disabled pretty-printers, which are marked as such. - - OBJECT-REGEXP is a regular expression matching the objects whose - pretty-printers to list. Objects can be `global', the program - space's file (*note Progspaces In Python::), and the object files - within that program space (*note Objfiles In Python::). *Note - Selecting Pretty-Printers::, for details on how GDB looks up a - printer from these three objects. - - NAME-REGEXP is a regular expression matching the name of the - printers to list. - -`disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' - Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. A - disabled pretty-printer is not forgotten, it may be enabled again - later. - -`enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' - Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. - - Example: - - Suppose we have three pretty-printers installed: one from library1.so -named `foo' that prints objects of type `foo', and another from -library2.so named `bar' that prints two types of objects, `bar1' and -`bar2'. - - (gdb) info pretty-printer - library1.so: - foo - library2.so: - bar - bar1 - bar2 - (gdb) info pretty-printer library2 - library2.so: - bar - bar1 - bar2 - (gdb) disable pretty-printer library1 - 1 printer disabled - 2 of 3 printers enabled - (gdb) info pretty-printer - library1.so: - foo [disabled] - library2.so: - bar - bar1 - bar2 - (gdb) disable pretty-printer library2 bar:bar1 - 1 printer disabled - 1 of 3 printers enabled - (gdb) info pretty-printer library2 - library1.so: - foo [disabled] - library2.so: - bar - bar1 [disabled] - bar2 - (gdb) disable pretty-printer library2 bar - 1 printer disabled - 0 of 3 printers enabled - (gdb) info pretty-printer library2 - library1.so: - foo [disabled] - library2.so: - bar [disabled] - bar1 [disabled] - bar2 - - Note that for `bar' the entire printer can be disabled, as can each -individual subprinter. - - -File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data - -10.10 Value History -=================== - -Values printed by the `print' command are saved in the GDB "value -history". This allows you to refer to them in other expressions. -Values are kept until the symbol table is re-read or discarded (for -example with the `file' or `symbol-file' commands). When the symbol -table changes, the value history is discarded, since the values may -contain pointers back to the types defined in the symbol table. - - The values printed are given "history numbers" by which you can -refer to them. These are successive integers starting with one. -`print' shows you the history number assigned to a value by printing -`$NUM = ' before the value; here NUM is the history number. - - To refer to any previous value, use `$' followed by the value's -history number. The way `print' labels its output is designed to -remind you of this. Just `$' refers to the most recent value in the -history, and `$$' refers to the value before that. `$$N' refers to the -Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is -equivalent to `$$', and `$$0' is equivalent to `$'. - - For example, suppose you have just printed a pointer to a structure -and want to see the contents of the structure. It suffices to type - - p *$ - - If you have a chain of structures where the component `next' points -to the next one, you can print the contents of the next one with this: - - p *$.next - -You can print successive links in the chain by repeating this -command--which you can do by just typing <RET>. - - Note that the history records values, not expressions. If the value -of `x' is 4 and you type these commands: - - print x - set x=5 - -then the value recorded in the value history by the `print' command -remains 4 even though the value of `x' has changed. - -`show values' - Print the last ten values in the value history, with their item - numbers. This is like `p $$9' repeated ten times, except that - `show values' does not change the history. - -`show values N' - Print ten history values centered on history item number N. - -`show values +' - Print ten history values just after the values last printed. If - no more values are available, `show values +' produces no display. - - Pressing <RET> to repeat `show values N' has exactly the same effect -as `show values +'. - - -File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data - -10.11 Convenience Variables -=========================== - -GDB provides "convenience variables" that you can use within GDB to -hold on to a value and refer to it later. These variables exist -entirely within GDB; they are not part of your program, and setting a -convenience variable has no direct effect on further execution of your -program. That is why you can use them freely. - - Convenience variables are prefixed with `$'. Any name preceded by -`$' can be used for a convenience variable, unless it is one of the -predefined machine-specific register names (*note Registers: -Registers.). (Value history references, in contrast, are _numbers_ -preceded by `$'. *Note Value History: Value History.) - - You can save a value in a convenience variable with an assignment -expression, just as you would set a variable in your program. For -example: - - set $foo = *object_ptr - -would save in `$foo' the value contained in the object pointed to by -`object_ptr'. - - Using a convenience variable for the first time creates it, but its -value is `void' until you assign a new value. You can alter the value -with another assignment at any time. - - Convenience variables have no fixed types. You can assign a -convenience variable any type of value, including structures and -arrays, even if that variable already has a value of a different type. -The convenience variable, when used as an expression, has the type of -its current value. - -`show convenience' - Print a list of convenience variables used so far, and their - values. Abbreviated `show conv'. - -`init-if-undefined $VARIABLE = EXPRESSION' - Set a convenience variable if it has not already been set. This - is useful for user-defined commands that keep some state. It is - similar, in concept, to using local static variables with - initializers in C (except that convenience variables are global). - It can also be used to allow users to override default values used - in a command script. - - If the variable is already defined then the expression is not - evaluated so any side-effects do not occur. - - One of the ways to use a convenience variable is as a counter to be -incremented or a pointer to be advanced. For example, to print a field -from successive elements of an array of structures: - - set $i = 0 - print bar[$i++]->contents - -Repeat that command by typing <RET>. - - Some convenience variables are created automatically by GDB and given -values likely to be useful. - -`$_' - The variable `$_' is automatically set by the `x' command to the - last address examined (*note Examining Memory: Memory.). Other - commands which provide a default address for `x' to examine also - set `$_' to that address; these commands include `info line' and - `info breakpoint'. The type of `$_' is `void *' except when set - by the `x' command, in which case it is a pointer to the type of - `$__'. - -`$__' - The variable `$__' is automatically set by the `x' command to the - value found in the last address examined. Its type is chosen to - match the format in which the data was printed. - -`$_exitcode' - The variable `$_exitcode' is automatically set to the exit code - when the program being debugged terminates. - -`$_sdata' - The variable `$_sdata' contains extra collected static tracepoint - data. *Note Tracepoint Action Lists: Tracepoint Actions. Note - that `$_sdata' could be empty, if not inspecting a trace buffer, or - if extra static tracepoint data has not been collected. - -`$_siginfo' - The variable `$_siginfo' contains extra signal information (*note - extra signal information::). Note that `$_siginfo' could be - empty, if the application has not yet received any signals. For - example, it will be empty before you execute the `run' command. - -`$_tlb' - The variable `$_tlb' is automatically set when debugging - applications running on MS-Windows in native mode or connected to - gdbserver that supports the `qGetTIBAddr' request. *Note General - Query Packets::. This variable contains the address of the thread - information block. - - - On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, GDB searches for a user or system name -first, before it searches for a convenience variable. - - GDB also supplies some "convenience functions". These have a syntax -similar to convenience variables. A convenience function can be used -in an expression just like an ordinary function; however, a convenience -function is implemented internally to GDB. - -`help function' - Print a list of all convenience functions. - - -File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data - -10.12 Registers -=============== - -You can refer to machine register contents, in expressions, as variables -with names starting with `$'. The names of registers are different for -each machine; use `info registers' to see the names used on your -machine. - -`info registers' - Print the names and values of all registers except floating-point - and vector registers (in the selected stack frame). - -`info all-registers' - Print the names and values of all registers, including - floating-point and vector registers (in the selected stack frame). - -`info registers REGNAME ...' - Print the "relativized" value of each specified register REGNAME. - As discussed in detail below, register values are normally - relative to the selected stack frame. REGNAME may be any register - name valid on the machine you are using, with or without the - initial `$'. - - GDB has four "standard" register names that are available (in -expressions) on most machines--whenever they do not conflict with an -architecture's canonical mnemonics for registers. The register names -`$pc' and `$sp' are used for the program counter register and the stack -pointer. `$fp' is used for a register that contains a pointer to the -current stack frame, and `$ps' is used for a register that contains the -processor status. For example, you could print the program counter in -hex with - - p/x $pc - -or print the instruction to be executed next with - - x/i $pc - -or add four to the stack pointer(1) with - - set $sp += 4 - - Whenever possible, these four standard register names are available -on your machine even though the machine has different canonical -mnemonics, so long as there is no conflict. The `info registers' -command shows the canonical names. For example, on the SPARC, `info -registers' displays the processor status register as `$psr' but you can -also refer to it as `$ps'; and on x86-based machines `$ps' is an alias -for the EFLAGS register. - - GDB always considers the contents of an ordinary register as an -integer when the register is examined in this way. Some machines have -special registers which can hold nothing but floating point; these -registers are considered to have floating point values. There is no way -to refer to the contents of an ordinary register as floating point value -(although you can _print_ it as a floating point value with `print/f -$REGNAME'). - - Some registers have distinct "raw" and "virtual" data formats. This -means that the data format in which the register contents are saved by -the operating system is not the same one that your program normally -sees. For example, the registers of the 68881 floating point -coprocessor are always saved in "extended" (raw) format, but all C -programs expect to work with "double" (virtual) format. In such cases, -GDB normally works with the virtual format only (the format that makes -sense for your program), but the `info registers' command prints the -data in both formats. - - Some machines have special registers whose contents can be -interpreted in several different ways. For example, modern x86-based -machines have SSE and MMX registers that can hold several values packed -together in several different formats. GDB refers to such registers in -`struct' notation: - - (gdb) print $xmm1 - $1 = { - v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, - v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, - v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", - v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, - v4_int32 = {0, 20657912, 11, 13}, - v2_int64 = {88725056443645952, 55834574859}, - uint128 = 0x0000000d0000000b013b36f800000000 - } - -To set values of such registers, you need to tell GDB which view of the -register you wish to change, as if you were assigning value to a -`struct' member: - - (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF - - Normally, register values are relative to the selected stack frame -(*note Selecting a Frame: Selection.). This means that you get the -value that the register would contain if all stack frames farther in -were exited and their saved registers restored. In order to see the -true contents of hardware registers, you must select the innermost -frame (with `frame 0'). - - However, GDB must deduce where registers are saved, from the machine -code generated by your compiler. If some registers are not saved, or if -GDB is unable to locate the saved registers, the selected stack frame -makes no difference. - - ---------- Footnotes ---------- - - (1) This is a way of removing one word from the stack, on machines -where stacks grow downward in memory (most machines, nowadays). This -assumes that the innermost stack frame is selected; setting `$sp' is -not allowed when other stack frames are selected. To pop entire frames -off the stack, regardless of machine architecture, use `return'; see -*note Returning from a Function: Returning. - - -File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data - -10.13 Floating Point Hardware -============================= - -Depending on the configuration, GDB may be able to give you more -information about the status of the floating point hardware. - -`info float' - Display hardware-dependent information about the floating point - unit. The exact contents and layout vary depending on the - floating point chip. Currently, `info float' is supported on the - ARM and x86 machines. - - -File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data - -10.14 Vector Unit -================= - -Depending on the configuration, GDB may be able to give you more -information about the status of the vector unit. - -`info vector' - Display information about the vector unit. The exact contents and - layout vary depending on the hardware. - - -File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data - -10.15 Operating System Auxiliary Information -============================================ - -GDB provides interfaces to useful OS facilities that can help you debug -your program. - - When GDB runs on a "Posix system" (such as GNU or Unix machines), it -interfaces with the inferior via the `ptrace' system call. The -operating system creates a special sata structure, called `struct -user', for this interface. You can use the command `info udot' to -display the contents of this data structure. - -`info udot' - Display the contents of the `struct user' maintained by the OS - kernel for the program being debugged. GDB displays the contents - of `struct user' as a list of hex numbers, similar to the - `examine' command. - - Some operating systems supply an "auxiliary vector" to programs at -startup. This is akin to the arguments and environment that you -specify for a program, but contains a system-dependent variety of -binary values that tell system libraries important details about the -hardware, operating system, and process. Each value's purpose is -identified by an integer tag; the meanings are well-known but -system-specific. Depending on the configuration and operating system -facilities, GDB may be able to show you this information. For remote -targets, this functionality may further depend on the remote stub's -support of the `qXfer:auxv:read' packet, see *note qXfer auxiliary -vector read::. - -`info auxv' - Display the auxiliary vector of the inferior, which can be either a - live process or a core dump file. GDB prints each tag value - numerically, and also shows names and text descriptions for - recognized tags. Some values in the vector are numbers, some bit - masks, and some pointers to strings or other data. GDB displays - each value in the most appropriate form for a recognized tag, and - in hexadecimal for an unrecognized tag. - - On some targets, GDB can access operating-system-specific information -and display it to user, without interpretation. For remote targets, -this functionality depends on the remote stub's support of the -`qXfer:osdata:read' packet, see *note qXfer osdata read::. - -`info os' - List the types of OS information available for the target. If the - target does not return a list of possible types, this command will - report an error. - -`info os processes' - Display the list of processes on the target. For each process, - GDB prints the process identifier, the name of the user, and the - command corresponding to the process. - - -File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data - -10.16 Memory Region Attributes -============================== - -"Memory region attributes" allow you to describe special handling -required by regions of your target's memory. GDB uses attributes to -determine whether to allow certain types of memory accesses; whether to -use specific width accesses; and whether to cache target memory. By -default the description of memory regions is fetched from the target -(if the current target supports this), but the user can override the -fetched regions. - - Defined memory regions can be individually enabled and disabled. -When a memory region is disabled, GDB uses the default attributes when -accessing memory in that region. Similarly, if no memory regions have -been defined, GDB uses the default attributes when accessing all memory. - - When a memory region is defined, it is given a number to identify it; -to enable, disable, or remove a memory region, you specify that number. - -`mem LOWER UPPER ATTRIBUTES...' - Define a memory region bounded by LOWER and UPPER with attributes - ATTRIBUTES..., and add it to the list of regions monitored by GDB. - Note that UPPER == 0 is a special case: it is treated as the - target's maximum memory address. (0xffff on 16 bit targets, - 0xffffffff on 32 bit targets, etc.) - -`mem auto' - Discard any user changes to the memory regions and use - target-supplied regions, if available, or no regions if the target - does not support. - -`delete mem NUMS...' - Remove memory regions NUMS... from the list of regions monitored - by GDB. - -`disable mem NUMS...' - Disable monitoring of memory regions NUMS.... A disabled memory - region is not forgotten. It may be enabled again later. - -`enable mem NUMS...' - Enable monitoring of memory regions NUMS.... - -`info mem' - Print a table of all defined memory regions, with the following - columns for each region: - - _Memory Region Number_ - - _Enabled or Disabled._ - Enabled memory regions are marked with `y'. Disabled memory - regions are marked with `n'. - - _Lo Address_ - The address defining the inclusive lower bound of the memory - region. - - _Hi Address_ - The address defining the exclusive upper bound of the memory - region. - - _Attributes_ - The list of attributes set for this memory region. - -10.16.1 Attributes ------------------- - -10.16.1.1 Memory Access Mode -............................ - -The access mode attributes set whether GDB may make read or write -accesses to a memory region. - - While these attributes prevent GDB from performing invalid memory -accesses, they do nothing to prevent the target system, I/O DMA, etc. -from accessing memory. - -`ro' - Memory is read only. - -`wo' - Memory is write only. - -`rw' - Memory is read/write. This is the default. - -10.16.1.2 Memory Access Size -............................ - -The access size attribute tells GDB to use specific sized accesses in -the memory region. Often memory mapped device registers require -specific sized accesses. If no access size attribute is specified, GDB -may use accesses of any size. - -`8' - Use 8 bit memory accesses. - -`16' - Use 16 bit memory accesses. - -`32' - Use 32 bit memory accesses. - -`64' - Use 64 bit memory accesses. - -10.16.1.3 Data Cache -.................... - -The data cache attributes set whether GDB will cache target memory. -While this generally improves performance by reducing debug protocol -overhead, it can lead to incorrect results because GDB does not know -about volatile variables or memory mapped device registers. - -`cache' - Enable GDB to cache target memory. - -`nocache' - Disable GDB from caching target memory. This is the default. - -10.16.2 Memory Access Checking ------------------------------- - -GDB can be instructed to refuse accesses to memory that is not -explicitly described. This can be useful if accessing such regions has -undesired effects for a specific target, or to provide better error -checking. The following commands control this behaviour. - -`set mem inaccessible-by-default [on|off]' - If `on' is specified, make GDB treat memory not explicitly - described by the memory ranges as non-existent and refuse accesses - to such memory. The checks are only performed if there's at least - one memory range defined. If `off' is specified, make GDB treat - the memory not explicitly described by the memory ranges as RAM. - The default value is `on'. - -`show mem inaccessible-by-default' - Show the current handling of accesses to unknown memory. - - -File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data - -10.17 Copy Between Memory and a File -==================================== - -You can use the commands `dump', `append', and `restore' to copy data -between target memory and a file. The `dump' and `append' commands -write data to a file, and the `restore' command reads data from a file -back into the inferior's memory. Files may be in binary, Motorola -S-record, Intel hex, or Tektronix Hex format; however, GDB can only -append to binary files. - -`dump [FORMAT] memory FILENAME START_ADDR END_ADDR' -`dump [FORMAT] value FILENAME EXPR' - Dump the contents of memory from START_ADDR to END_ADDR, or the - value of EXPR, to FILENAME in the given format. - - The FORMAT parameter may be any one of: - `binary' - Raw binary form. - - `ihex' - Intel hex format. - - `srec' - Motorola S-record format. - - `tekhex' - Tektronix Hex format. - - GDB uses the same definitions of these formats as the GNU binary - utilities, like `objdump' and `objcopy'. If FORMAT is omitted, - GDB dumps the data in raw binary form. - -`append [binary] memory FILENAME START_ADDR END_ADDR' -`append [binary] value FILENAME EXPR' - Append the contents of memory from START_ADDR to END_ADDR, or the - value of EXPR, to the file FILENAME, in raw binary form. (GDB can - only append data to files in raw binary form.) - -`restore FILENAME [binary] BIAS START END' - Restore the contents of file FILENAME into memory. The `restore' - command can automatically recognize any known BFD file format, - except for raw binary. To restore a raw binary file you must - specify the optional keyword `binary' after the filename. - - If BIAS is non-zero, its value will be added to the addresses - contained in the file. Binary files always start at address zero, - so they will be restored at address BIAS. Other bfd files have a - built-in location; they will be restored at offset BIAS from that - location. - - If START and/or END are non-zero, then only data between file - offset START and file offset END will be restored. These offsets - are relative to the addresses in the file, before the BIAS - argument is applied. - - - -File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data - -10.18 How to Produce a Core File from Your Program -================================================== - -A "core file" or "core dump" is a file that records the memory image of -a running process and its process status (register values etc.). Its -primary use is post-mortem debugging of a program that crashed while it -ran outside a debugger. A program that crashes automatically produces -a core file, unless this feature is disabled by the user. *Note -Files::, for information on invoking GDB in the post-mortem debugging -mode. - - Occasionally, you may wish to produce a core file of the program you -are debugging in order to preserve a snapshot of its state. GDB has a -special command for that. - -`generate-core-file [FILE]' -`gcore [FILE]' - Produce a core dump of the inferior process. The optional argument - FILE specifies the file name where to put the core dump. If not - specified, the file name defaults to `core.PID', where PID is the - inferior process ID. - - Note that this command is implemented only for some systems (as of - this writing, GNU/Linux, FreeBSD, Solaris, Unixware, and S390). - - -File: gdb.info, Node: Character Sets, Next: Caching Remote Data, Prev: Core File Generation, Up: Data - -10.19 Character Sets -==================== - -If the program you are debugging uses a different character set to -represent characters and strings than the one GDB uses itself, GDB can -automatically translate between the character sets for you. The -character set GDB uses we call the "host character set"; the one the -inferior program uses we call the "target character set". - - For example, if you are running GDB on a GNU/Linux system, which -uses the ISO Latin 1 character set, but you are using GDB's remote -protocol (*note Remote Debugging::) to debug a program running on an -IBM mainframe, which uses the EBCDIC character set, then the host -character set is Latin-1, and the target character set is EBCDIC. If -you give GDB the command `set target-charset EBCDIC-US', then GDB -translates between EBCDIC and Latin 1 as you print character or string -values, or use character and string literals in expressions. - - GDB has no way to automatically recognize which character set the -inferior program uses; you must tell it, using the `set target-charset' -command, described below. - - Here are the commands for controlling GDB's character set support: - -`set target-charset CHARSET' - Set the current target character set to CHARSET. To display the - list of supported target character sets, type - `set target-charset <TAB><TAB>'. - -`set host-charset CHARSET' - Set the current host character set to CHARSET. - - By default, GDB uses a host character set appropriate to the - system it is running on; you can override that default using the - `set host-charset' command. On some systems, GDB cannot - automatically determine the appropriate host character set. In - this case, GDB uses `UTF-8'. - - GDB can only use certain character sets as its host character set. - If you type `set host-charset <TAB><TAB>', GDB will list the host - character sets it supports. - -`set charset CHARSET' - Set the current host and target character sets to CHARSET. As - above, if you type `set charset <TAB><TAB>', GDB will list the - names of the character sets that can be used for both host and - target. - -`show charset' - Show the names of the current host and target character sets. - -`show host-charset' - Show the name of the current host character set. - -`show target-charset' - Show the name of the current target character set. - -`set target-wide-charset CHARSET' - Set the current target's wide character set to CHARSET. This is - the character set used by the target's `wchar_t' type. To display - the list of supported wide character sets, type - `set target-wide-charset <TAB><TAB>'. - -`show target-wide-charset' - Show the name of the current target's wide character set. - - Here is an example of GDB's character set support in action. Assume -that the following source code has been placed in the file -`charset-test.c': - - #include <stdio.h> - - char ascii_hello[] - = {72, 101, 108, 108, 111, 44, 32, 119, - 111, 114, 108, 100, 33, 10, 0}; - char ibm1047_hello[] - = {200, 133, 147, 147, 150, 107, 64, 166, - 150, 153, 147, 132, 90, 37, 0}; - - main () - { - printf ("Hello, world!\n"); - } - - In this program, `ascii_hello' and `ibm1047_hello' are arrays -containing the string `Hello, world!' followed by a newline, encoded in -the ASCII and IBM1047 character sets. - - We compile the program, and invoke the debugger on it: - - $ gcc -g charset-test.c -o charset-test - $ gdb -nw charset-test - GNU gdb 2001-12-19-cvs - Copyright 2001 Free Software Foundation, Inc. - ... - (gdb) - - We can use the `show charset' command to see what character sets GDB -is currently using to interpret and display characters and strings: - - (gdb) show charset - The current host and target character set is `ISO-8859-1'. - (gdb) - - For the sake of printing this manual, let's use ASCII as our initial -character set: - (gdb) set charset ASCII - (gdb) show charset - The current host and target character set is `ASCII'. - (gdb) - - Let's assume that ASCII is indeed the correct character set for our -host system -- in other words, let's assume that if GDB prints -characters using the ASCII character set, our terminal will display -them properly. Since our current target character set is also ASCII, -the contents of `ascii_hello' print legibly: - - (gdb) print ascii_hello - $1 = 0x401698 "Hello, world!\n" - (gdb) print ascii_hello[0] - $2 = 72 'H' - (gdb) - - GDB uses the target character set for character and string literals -you use in expressions: - - (gdb) print '+' - $3 = 43 '+' - (gdb) - - The ASCII character set uses the number 43 to encode the `+' -character. - - GDB relies on the user to tell it which character set the target -program uses. If we print `ibm1047_hello' while our target character -set is still ASCII, we get jibberish: - - (gdb) print ibm1047_hello - $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" - (gdb) print ibm1047_hello[0] - $5 = 200 '\310' - (gdb) - - If we invoke the `set target-charset' followed by <TAB><TAB>, GDB -tells us the character sets it supports: - - (gdb) set target-charset - ASCII EBCDIC-US IBM1047 ISO-8859-1 - (gdb) set target-charset - - We can select IBM1047 as our target character set, and examine the -program's strings again. Now the ASCII string is wrong, but GDB -translates the contents of `ibm1047_hello' from the target character -set, IBM1047, to the host character set, ASCII, and they display -correctly: - - (gdb) set target-charset IBM1047 - (gdb) show charset - The current host character set is `ASCII'. - The current target character set is `IBM1047'. - (gdb) print ascii_hello - $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" - (gdb) print ascii_hello[0] - $7 = 72 '\110' - (gdb) print ibm1047_hello - $8 = 0x4016a8 "Hello, world!\n" - (gdb) print ibm1047_hello[0] - $9 = 200 'H' - (gdb) - - As above, GDB uses the target character set for character and string -literals you use in expressions: - - (gdb) print '+' - $10 = 78 '+' - (gdb) - - The IBM1047 character set uses the number 78 to encode the `+' -character. - - -File: gdb.info, Node: Caching Remote Data, Next: Searching Memory, Prev: Character Sets, Up: Data - -10.20 Caching Data of Remote Targets -==================================== - -GDB caches data exchanged between the debugger and a remote target -(*note Remote Debugging::). Such caching generally improves -performance, because it reduces the overhead of the remote protocol by -bundling memory reads and writes into large chunks. Unfortunately, -simply caching everything would lead to incorrect results, since GDB -does not necessarily know anything about volatile values, memory-mapped -I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop -Mode::) memory can be changed _while_ a gdb command is executing. -Therefore, by default, GDB only caches data known to be on the stack(1). -Other regions of memory can be explicitly marked as cacheable; see -*note Memory Region Attributes::. - -`set remotecache on' -`set remotecache off' - This option no longer does anything; it exists for compatibility - with old scripts. - -`show remotecache' - Show the current state of the obsolete remotecache flag. - -`set stack-cache on' -`set stack-cache off' - Enable or disable caching of stack accesses. When `ON', use - caching. By default, this option is `ON'. - -`show stack-cache' - Show the current state of data caching for memory accesses. - -`info dcache [line]' - Print the information about the data cache performance. The - information displayed includes the dcache width and depth, and for - each cache line, its number, address, and how many times it was - referenced. This command is useful for debugging the data cache - operation. - - If a line number is specified, the contents of that line will be - printed in hex. - -`set dcache size SIZE' - Set maximum number of entries in dcache (dcache depth above). - -`set dcache line-size LINE-SIZE' - Set number of bytes each dcache entry caches (dcache width above). - Must be a power of 2. - -`show dcache size' - Show maximum number of dcache entries. See also *note info - dcache: Caching Remote Data. - -`show dcache line-size' - Show default size of dcache lines. See also *note info dcache: - Caching Remote Data. - - - ---------- Footnotes ---------- - - (1) In non-stop mode, it is moderately rare for a running thread to -modify the stack of a stopped thread in a way that would interfere with -a backtrace, and caching of stack reads provides a significant speed up -of remote backtraces. - - -File: gdb.info, Node: Searching Memory, Prev: Caching Remote Data, Up: Data - -10.21 Search Memory -=================== - -Memory can be searched for a particular sequence of bytes with the -`find' command. - -`find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]' -`find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]' - Search memory for the sequence of bytes specified by VAL1, VAL2, - etc. The search begins at address START_ADDR and continues for - either LEN bytes or through to END_ADDR inclusive. - - S and N are optional parameters. They may be specified in either -order, apart or together. - -S, search query size - The size of each search query value. - - `b' - bytes - - `h' - halfwords (two bytes) - - `w' - words (four bytes) - - `g' - giant words (eight bytes) - - All values are interpreted in the current language. This means, - for example, that if the current source language is C/C++ then - searching for the string "hello" includes the trailing '\0'. - - If the value size is not specified, it is taken from the value's - type in the current language. This is useful when one wants to - specify the search pattern as a mixture of types. Note that this - means, for example, that in the case of C-like languages a search - for an untyped 0x42 will search for `(int) 0x42' which is - typically four bytes. - -N, maximum number of finds - The maximum number of matches to print. The default is to print - all finds. - - You can use strings as search values. Quote them with double-quotes -(`"'). The string value is copied into the search pattern byte by byte, -regardless of the endianness of the target and the size specification. - - The address of each match found is printed as well as a count of the -number of matches found. - - The address of the last value found is stored in convenience variable -`$_'. A count of the number of matches is stored in `$numfound'. - - For example, if stopped at the `printf' in this function: - - void - hello () - { - static char hello[] = "hello-hello"; - static struct { char c; short s; int i; } - __attribute__ ((packed)) mixed - = { 'c', 0x1234, 0x87654321 }; - printf ("%s\n", hello); - } - -you get during debugging: - - (gdb) find &hello[0], +sizeof(hello), "hello" - 0x804956d <hello.1620+6> - 1 pattern found - (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' - 0x8049567 <hello.1620> - 0x804956d <hello.1620+6> - 2 patterns found - (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' - 0x8049567 <hello.1620> - 1 pattern found - (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 - 0x8049560 <mixed.1625> - 1 pattern found - (gdb) print $numfound - $1 = 1 - (gdb) print $_ - $2 = (void *) 0x8049560 - - -File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top - -11 Debugging Optimized Code -*************************** - -Almost all compilers support optimization. With optimization disabled, -the compiler generates assembly code that corresponds directly to your -source code, in a simplistic way. As the compiler applies more -powerful optimizations, the generated assembly code diverges from your -original source code. With help from debugging information generated -by the compiler, GDB can map from the running program back to -constructs from your original source. - - GDB is more accurate with optimization disabled. If you can -recompile without optimization, it is easier to follow the progress of -your program during debugging. But, there are many cases where you may -need to debug an optimized version. - - When you debug a program compiled with `-g -O', remember that the -optimizer has rearranged your code; the debugger shows you what is -really there. Do not be too surprised when the execution path does not -exactly match your source file! An extreme example: if you define a -variable, but never use it, GDB never sees that variable--because the -compiler optimizes it out of existence. - - Some things do not work as well with `-g -O' as with just `-g', -particularly on machines with instruction scheduling. If in doubt, -recompile with `-g' alone, and if this fixes the problem, please report -it to us as a bug (including a test case!). *Note Variables::, for -more information about debugging optimized code. - -* Menu: - -* Inline Functions:: How GDB presents inlining - - -File: gdb.info, Node: Inline Functions, Up: Optimized Code - -11.1 Inline Functions -===================== - -"Inlining" is an optimization that inserts a copy of the function body -directly at each call site, instead of jumping to a shared routine. -GDB displays inlined functions just like non-inlined functions. They -appear in backtraces. You can view their arguments and local -variables, step into them with `step', skip them with `next', and -escape from them with `finish'. You can check whether a function was -inlined by using the `info frame' command. - - For GDB to support inlined functions, the compiler must record -information about inlining in the debug information -- GCC using the -DWARF 2 format does this, and several other compilers do also. GDB -only supports inlined functions when using DWARF 2. Versions of GCC -before 4.1 do not emit two required attributes (`DW_AT_call_file' and -`DW_AT_call_line'); GDB does not display inlined function calls with -earlier versions of GCC. It instead displays the arguments and local -variables of inlined functions as local variables in the caller. - - The body of an inlined function is directly included at its call -site; unlike a non-inlined function, there are no instructions devoted -to the call. GDB still pretends that the call site and the start of -the inlined function are different instructions. Stepping to the call -site shows the call site, and then stepping again shows the first line -of the inlined function, even though no additional instructions are -executed. - - This makes source-level debugging much clearer; you can see both the -context of the call and then the effect of the call. Only stepping by -a single instruction using `stepi' or `nexti' does not do this; single -instruction steps always show the inlined body. - - There are some ways that GDB does not pretend that inlined function -calls are the same as normal calls: - - * You cannot set breakpoints on inlined functions. GDB either - reports that there is no symbol with that name, or else sets the - breakpoint only on non-inlined copies of the function. This - limitation will be removed in a future version of GDB; until then, - set a breakpoint by line number on the first line of the inlined - function instead. - - * Setting breakpoints at the call site of an inlined function may not - work, because the call site does not contain any code. GDB may - incorrectly move the breakpoint to the next line of the enclosing - function, after the call. This limitation will be removed in a - future version of GDB; until then, set a breakpoint on an earlier - line or inside the inlined function instead. - - * GDB cannot locate the return value of inlined calls after using - the `finish' command. This is a limitation of compiler-generated - debugging information; after `finish', you can step to the next - line and print a variable where your program stored the return - value. - - - -File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top - -12 C Preprocessor Macros -************************ - -Some languages, such as C and C++, provide a way to define and invoke -"preprocessor macros" which expand into strings of tokens. GDB can -evaluate expressions containing macro invocations, show the result of -macro expansion, and show a macro's definition, including where it was -defined. - - You may need to compile your program specially to provide GDB with -information about preprocessor macros. Most compilers do not include -macros in their debugging information, even when you compile with the -`-g' flag. *Note Compilation::. - - A program may define a macro at one point, remove that definition -later, and then provide a different definition after that. Thus, at -different points in the program, a macro may have different -definitions, or have no definition at all. If there is a current stack -frame, GDB uses the macros in scope at that frame's source code line. -Otherwise, GDB uses the macros in scope at the current listing location; -see *note List::. - - Whenever GDB evaluates an expression, it always expands any macro -invocations present in the expression. GDB also provides the following -commands for working with macros explicitly. - -`macro expand EXPRESSION' -`macro exp EXPRESSION' - Show the results of expanding all preprocessor macro invocations in - EXPRESSION. Since GDB simply expands macros, but does not parse - the result, EXPRESSION need not be a valid expression; it can be - any string of tokens. - -`macro expand-once EXPRESSION' -`macro exp1 EXPRESSION' - (This command is not yet implemented.) Show the results of - expanding those preprocessor macro invocations that appear - explicitly in EXPRESSION. Macro invocations appearing in that - expansion are left unchanged. This command allows you to see the - effect of a particular macro more clearly, without being confused - by further expansions. Since GDB simply expands macros, but does - not parse the result, EXPRESSION need not be a valid expression; it - can be any string of tokens. - -`info macro MACRO' - Show the definition of the macro named MACRO, and describe the - source location or compiler command-line where that definition was - established. - -`macro define MACRO REPLACEMENT-LIST' -`macro define MACRO(ARGLIST) REPLACEMENT-LIST' - Introduce a definition for a preprocessor macro named MACRO, - invocations of which are replaced by the tokens given in - REPLACEMENT-LIST. The first form of this command defines an - "object-like" macro, which takes no arguments; the second form - defines a "function-like" macro, which takes the arguments given in - ARGLIST. - - A definition introduced by this command is in scope in every - expression evaluated in GDB, until it is removed with the `macro - undef' command, described below. The definition overrides all - definitions for MACRO present in the program being debugged, as - well as any previous user-supplied definition. - -`macro undef MACRO' - Remove any user-supplied definition for the macro named MACRO. - This command only affects definitions provided with the `macro - define' command, described above; it cannot remove definitions - present in the program being debugged. - -`macro list' - List all the macros defined using the `macro define' command. - - Here is a transcript showing the above commands in action. First, we -show our source files: - - $ cat sample.c - #include <stdio.h> - #include "sample.h" - - #define M 42 - #define ADD(x) (M + x) - - main () - { - #define N 28 - printf ("Hello, world!\n"); - #undef N - printf ("We're so creative.\n"); - #define N 1729 - printf ("Goodbye, world!\n"); - } - $ cat sample.h - #define Q < - $ - - Now, we compile the program using the GNU C compiler, GCC. We pass -the `-gdwarf-2' and `-g3' flags to ensure the compiler includes -information about preprocessor macros in the debugging information. - - $ gcc -gdwarf-2 -g3 sample.c -o sample - $ - - Now, we start GDB on our sample program: - - $ gdb -nw sample - GNU gdb 2002-05-06-cvs - Copyright 2002 Free Software Foundation, Inc. - GDB is free software, ... - (gdb) - - We can expand macros and examine their definitions, even when the -program is not running. GDB uses the current listing position to -decide which macro definitions are in scope: - - (gdb) list main - 3 - 4 #define M 42 - 5 #define ADD(x) (M + x) - 6 - 7 main () - 8 { - 9 #define N 28 - 10 printf ("Hello, world!\n"); - 11 #undef N - 12 printf ("We're so creative.\n"); - (gdb) info macro ADD - Defined at /home/jimb/gdb/macros/play/sample.c:5 - #define ADD(x) (M + x) - (gdb) info macro Q - Defined at /home/jimb/gdb/macros/play/sample.h:1 - included at /home/jimb/gdb/macros/play/sample.c:2 - #define Q < - (gdb) macro expand ADD(1) - expands to: (42 + 1) - (gdb) macro expand-once ADD(1) - expands to: once (M + 1) - (gdb) - - In the example above, note that `macro expand-once' expands only the -macro invocation explicit in the original text -- the invocation of -`ADD' -- but does not expand the invocation of the macro `M', which was -introduced by `ADD'. - - Once the program is running, GDB uses the macro definitions in force -at the source line of the current stack frame: - - (gdb) break main - Breakpoint 1 at 0x8048370: file sample.c, line 10. - (gdb) run - Starting program: /home/jimb/gdb/macros/play/sample - - Breakpoint 1, main () at sample.c:10 - 10 printf ("Hello, world!\n"); - (gdb) - - At line 10, the definition of the macro `N' at line 9 is in force: - - (gdb) info macro N - Defined at /home/jimb/gdb/macros/play/sample.c:9 - #define N 28 - (gdb) macro expand N Q M - expands to: 28 < 42 - (gdb) print N Q M - $1 = 1 - (gdb) - - As we step over directives that remove `N''s definition, and then -give it a new definition, GDB finds the definition (or lack thereof) in -force at each point: - - (gdb) next - Hello, world! - 12 printf ("We're so creative.\n"); - (gdb) info macro N - The symbol `N' has no definition as a C/C++ preprocessor macro - at /home/jimb/gdb/macros/play/sample.c:12 - (gdb) next - We're so creative. - 14 printf ("Goodbye, world!\n"); - (gdb) info macro N - Defined at /home/jimb/gdb/macros/play/sample.c:13 - #define N 1729 - (gdb) macro expand N Q M - expands to: 1729 < 42 - (gdb) print N Q M - $2 = 0 - (gdb) - - In addition to source files, macros can be defined on the -compilation command line using the `-DNAME=VALUE' syntax. For macros -defined in such a way, GDB displays the location of their definition as -line zero of the source file submitted to the compiler. - - (gdb) info macro __STDC__ - Defined at /home/jimb/gdb/macros/play/sample.c:0 - -D__STDC__=1 - (gdb) - - -File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top - -13 Tracepoints -************** - -In some applications, it is not feasible for the debugger to interrupt -the program's execution long enough for the developer to learn anything -helpful about its behavior. If the program's correctness depends on -its real-time behavior, delays introduced by a debugger might cause the -program to change its behavior drastically, or perhaps fail, even when -the code itself is correct. It is useful to be able to observe the -program's behavior without interrupting it. - - Using GDB's `trace' and `collect' commands, you can specify -locations in the program, called "tracepoints", and arbitrary -expressions to evaluate when those tracepoints are reached. Later, -using the `tfind' command, you can examine the values those expressions -had when the program hit the tracepoints. The expressions may also -denote objects in memory--structures or arrays, for example--whose -values GDB should record; while visiting a particular tracepoint, you -may inspect those objects as if they were in memory at that moment. -However, because GDB records these values without interacting with you, -it can do so quickly and unobtrusively, hopefully not disturbing the -program's behavior. - - The tracepoint facility is currently available only for remote -targets. *Note Targets::. In addition, your remote target must know -how to collect trace data. This functionality is implemented in the -remote stub; however, none of the stubs distributed with GDB support -tracepoints as of this writing. The format of the remote packets used -to implement tracepoints are described in *note Tracepoint Packets::. - - It is also possible to get trace data from a file, in a manner -reminiscent of corefiles; you specify the filename, and use `tfind' to -search through the file. *Note Trace Files::, for more details. - - This chapter describes the tracepoint commands and features. - -* Menu: - -* Set Tracepoints:: -* Analyze Collected Data:: -* Tracepoint Variables:: -* Trace Files:: - - -File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints - -13.1 Commands to Set Tracepoints -================================ - -Before running such a "trace experiment", an arbitrary number of -tracepoints can be set. A tracepoint is actually a special type of -breakpoint (*note Set Breaks::), so you can manipulate it using -standard breakpoint commands. For instance, as with breakpoints, -tracepoint numbers are successive integers starting from one, and many -of the commands associated with tracepoints take the tracepoint number -as their argument, to identify which tracepoint to work on. - - For each tracepoint, you can specify, in advance, some arbitrary set -of data that you want the target to collect in the trace buffer when it -hits that tracepoint. The collected data can include registers, local -variables, or global data. Later, you can use GDB commands to examine -the values these data had at the time the tracepoint was hit. - - Tracepoints do not support every breakpoint feature. Ignore counts -on tracepoints have no effect, and tracepoints cannot run GDB commands -when they are hit. Tracepoints may not be thread-specific either. - - Some targets may support "fast tracepoints", which are inserted in a -different way (such as with a jump instead of a trap), that is faster -but possibly restricted in where they may be installed. - - Regular and fast tracepoints are dynamic tracing facilities, meaning -that they can be used to insert tracepoints at (almost) any location in -the target. Some targets may also support controlling "static -tracepoints" from GDB. With static tracing, a set of instrumentation -points, also known as "markers", are embedded in the target program, -and can be activated or deactivated by name or address. These are -usually placed at locations which facilitate investigating what the -target is actually doing. GDB's support for static tracing includes -being able to list instrumentation points, and attach them with GDB -defined high level tracepoints that expose the whole range of -convenience of GDB's tracepoints support. Namely, support for -collecting registers values and values of global or local (to the -instrumentation point) variables; tracepoint conditions and trace state -variables. The act of installing a GDB static tracepoint on an -instrumentation point, or marker, is referred to as "probing" a static -tracepoint marker. - - `gdbserver' supports tracepoints on some target systems. *Note -Tracepoints support in `gdbserver': Server. - - This section describes commands to set tracepoints and associated -conditions and actions. - -* Menu: - -* Create and Delete Tracepoints:: -* Enable and Disable Tracepoints:: -* Tracepoint Passcounts:: -* Tracepoint Conditions:: -* Trace State Variables:: -* Tracepoint Actions:: -* Listing Tracepoints:: -* Listing Static Tracepoint Markers:: -* Starting and Stopping Trace Experiments:: -* Tracepoint Restrictions:: - - -File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints - -13.1.1 Create and Delete Tracepoints ------------------------------------- - -`trace LOCATION' - The `trace' command is very similar to the `break' command. Its - argument LOCATION can be a source line, a function name, or an - address in the target program. *Note Specify Location::. The - `trace' command defines a tracepoint, which is a point in the - target program where the debugger will briefly stop, collect some - data, and then allow the program to continue. Setting a - tracepoint or changing its actions doesn't take effect until the - next `tstart' command, and once a trace experiment is running, - further changes will not have any effect until the next trace - experiment starts. - - Here are some examples of using the `trace' command: - - (gdb) trace foo.c:121 // a source file and line number - - (gdb) trace +2 // 2 lines forward - - (gdb) trace my_function // first source line of function - - (gdb) trace *my_function // EXACT start address of function - - (gdb) trace *0x2117c4 // an address - - You can abbreviate `trace' as `tr'. - -`trace LOCATION if COND' - Set a tracepoint with condition COND; evaluate the expression COND - each time the tracepoint is reached, and collect data only if the - value is nonzero--that is, if COND evaluates as true. *Note - Tracepoint Conditions: Tracepoint Conditions, for more information - on tracepoint conditions. - -`ftrace LOCATION [ if COND ]' - The `ftrace' command sets a fast tracepoint. For targets that - support them, fast tracepoints will use a more efficient but - possibly less general technique to trigger data collection, such - as a jump instruction instead of a trap, or some sort of hardware - support. It may not be possible to create a fast tracepoint at - the desired location, in which case the command will exit with an - explanatory message. - - GDB handles arguments to `ftrace' exactly as for `trace'. - -`strace LOCATION [ if COND ]' - The `strace' command sets a static tracepoint. For targets that - support it, setting a static tracepoint probes a static - instrumentation point, or marker, found at LOCATION. It may not - be possible to set a static tracepoint at the desired location, in - which case the command will exit with an explanatory message. - - GDB handles arguments to `strace' exactly as for `trace', with the - addition that the user can also specify `-m MARKER' as LOCATION. - This probes the marker identified by the MARKER string identifier. - This identifier depends on the static tracepoint backend library - your program is using. You can find all the marker identifiers in - the `ID' field of the `info static-tracepoint-markers' command - output. *Note Listing Static Tracepoint Markers: Listing Static - Tracepoint Markers. For example, in the following small program - using the UST tracing engine: - - main () - { - trace_mark(ust, bar33, "str %s", "FOOBAZ"); - } - - the marker id is composed of joining the first two arguments to the - `trace_mark' call with a slash, which translates to: - - (gdb) info static-tracepoint-markers - Cnt Enb ID Address What - 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 - Data: "str %s" - [etc...] - - so you may probe the marker above with: - - (gdb) strace -m ust/bar33 - - Static tracepoints accept an extra collect action -- `collect - $_sdata'. This collects arbitrary user data passed in the probe - point call to the tracing library. In the UST example above, - you'll see that the third argument to `trace_mark' is a - printf-like format string. The user data is then the result of - running that formating string against the following arguments. - Note that `info static-tracepoint-markers' command output lists - that format string in the `Data:' field. - - You can inspect this data when analyzing the trace buffer, by - printing the $_sdata variable like any other variable available to - GDB. *Note Tracepoint Action Lists: Tracepoint Actions. - - The convenience variable `$tpnum' records the tracepoint number of - the most recently set tracepoint. - -`delete tracepoint [NUM]' - Permanently delete one or more tracepoints. With no argument, the - default is to delete all tracepoints. Note that the regular - `delete' command can remove tracepoints also. - - Examples: - - (gdb) delete trace 1 2 3 // remove three tracepoints - - (gdb) delete trace // remove all tracepoints - - You can abbreviate this command as `del tr'. - - -File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints - -13.1.2 Enable and Disable Tracepoints -------------------------------------- - -These commands are deprecated; they are equivalent to plain `disable' -and `enable'. - -`disable tracepoint [NUM]' - Disable tracepoint NUM, or all tracepoints if no argument NUM is - given. A disabled tracepoint will have no effect during the next - trace experiment, but it is not forgotten. You can re-enable a - disabled tracepoint using the `enable tracepoint' command. - -`enable tracepoint [NUM]' - Enable tracepoint NUM, or all tracepoints. The enabled - tracepoints will become effective the next time a trace experiment - is run. - - -File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints - -13.1.3 Tracepoint Passcounts ----------------------------- - -`passcount [N [NUM]]' - Set the "passcount" of a tracepoint. The passcount is a way to - automatically stop a trace experiment. If a tracepoint's - passcount is N, then the trace experiment will be automatically - stopped on the N'th time that tracepoint is hit. If the - tracepoint number NUM is not specified, the `passcount' command - sets the passcount of the most recently defined tracepoint. If no - passcount is given, the trace experiment will run until stopped - explicitly by the user. - - Examples: - - (gdb) passcount 5 2 // Stop on the 5th execution of - `// tracepoint 2' - - (gdb) passcount 12 // Stop on the 12th execution of the - `// most recently defined tracepoint.' - (gdb) trace foo - (gdb) pass 3 - (gdb) trace bar - (gdb) pass 2 - (gdb) trace baz - (gdb) pass 1 // Stop tracing when foo has been - `// executed 3 times OR when bar has' - `// been executed 2 times' - `// OR when baz has been executed 1 time.' - - - -File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints - -13.1.4 Tracepoint Conditions ----------------------------- - -The simplest sort of tracepoint collects data every time your program -reaches a specified place. You can also specify a "condition" for a -tracepoint. A condition is just a Boolean expression in your -programming language (*note Expressions: Expressions.). A tracepoint -with a condition evaluates the expression each time your program -reaches it, and data collection happens only if the condition is true. - - Tracepoint conditions can be specified when a tracepoint is set, by -using `if' in the arguments to the `trace' command. *Note Setting -Tracepoints: Create and Delete Tracepoints. They can also be set or -changed at any time with the `condition' command, just as with -breakpoints. - - Unlike breakpoint conditions, GDB does not actually evaluate the -conditional expression itself. Instead, 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. - - For instance, suppose you have a function that is usually called -frequently, but should not be called after an error has occurred. You -could use the following tracepoint command to collect data about calls -of that function that happen while the error code is propagating -through the program; an unconditional tracepoint could end up -collecting thousands of useless trace frames that you would have to -search through. - - (gdb) trace normal_operation if errcode > 0 - - -File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints - -13.1.5 Trace State Variables ----------------------------- - -A "trace state variable" is a special type of variable that is created -and managed by target-side code. The syntax is the same as that for -GDB's convenience variables (a string prefixed with "$"), but they are -stored on the target. They must be created explicitly, using a -`tvariable' command. They are always 64-bit signed integers. - - Trace state variables are remembered by GDB, and downloaded to the -target along with tracepoint information when the trace experiment -starts. There are no intrinsic limits on the number of trace state -variables, beyond memory limitations of the target. - - Although trace state variables are managed by the target, you can use -them in print commands and expressions as if they were convenience -variables; GDB will get the current value from the target while the -trace experiment is running. Trace state variables share the same -namespace as other "$" variables, which means that you cannot have -trace state variables with names like `$23' or `$pc', nor can you have -a trace state variable and a convenience variable with the same name. - -`tvariable $NAME [ = EXPRESSION ]' - The `tvariable' command creates a new trace state variable named - `$NAME', and optionally gives it an initial value of EXPRESSION. - EXPRESSION is evaluated when this command is entered; the result - will be converted to an integer if possible, otherwise GDB will - report an error. A subsequent `tvariable' command specifying the - same name does not create a variable, but instead assigns the - supplied initial value to the existing variable of that name, - overwriting any previous initial value. The default initial value - is 0. - -`info tvariables' - List all the trace state variables along with their initial values. - Their current values may also be displayed, if the trace - experiment is currently running. - -`delete tvariable [ $NAME ... ]' - Delete the given trace state variables, or all of them if no - arguments are specified. - - - -File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints - -13.1.6 Tracepoint Action Lists ------------------------------- - -`actions [NUM]' - This command will prompt for a list of actions to be taken when the - tracepoint is hit. If the tracepoint number NUM is not specified, - this command sets the actions for the one that was most recently - defined (so that you can define a tracepoint and then say - `actions' without bothering about its number). You specify the - actions themselves on the following lines, one action at a time, - and terminate the actions list with a line containing just `end'. - So far, the only defined actions are `collect', `teval', and - `while-stepping'. - - `actions' is actually equivalent to `commands' (*note Breakpoint - Command Lists: Break Commands.), except that only the defined - actions are allowed; any other GDB command is rejected. - - To remove all actions from a tracepoint, type `actions NUM' and - follow it immediately with `end'. - - (gdb) collect DATA // collect some data - - (gdb) while-stepping 5 // single-step 5 times, collect data - - (gdb) end // signals the end of actions. - - In the following example, the action list begins with `collect' - commands indicating the things to be collected when the tracepoint - is hit. Then, in order to single-step and collect additional data - following the tracepoint, a `while-stepping' command is used, - followed by the list of things to be collected after each step in a - sequence of single steps. The `while-stepping' command is - terminated by its own separate `end' command. Lastly, the action - list is terminated by an `end' command. - - (gdb) trace foo - (gdb) actions - Enter actions for tracepoint 1, one per line: - > collect bar,baz - > collect $regs - > while-stepping 12 - > collect $pc, arr[i] - > end - end - -`collect EXPR1, EXPR2, ...' - Collect values of the given expressions when the tracepoint is hit. - This command accepts a comma-separated list of any valid - expressions. In addition to global, static, or local variables, - the following special arguments are supported: - - `$regs' - Collect all registers. - - `$args' - Collect all function arguments. - - `$locals' - Collect all local variables. - - `$_sdata' - Collect static tracepoint marker specific data. Only - available for static tracepoints. *Note Tracepoint Action - Lists: Tracepoint Actions. On the UST static tracepoints - library backend, an instrumentation point resembles a - `printf' function call. The tracing library is able to - collect user specified data formatted to a character string - using the format provided by the programmer that instrumented - the program. Other backends have similar mechanisms. Here's - an example of a UST marker call: - - const char master_name[] = "$your_name"; - trace_mark(channel1, marker1, "hello %s", master_name) - - In this case, collecting `$_sdata' collects the string `hello - $yourname'. When analyzing the trace buffer, you can inspect - `$_sdata' like any other variable available to GDB. - - You can give several consecutive `collect' commands, each one with - a single argument, or one `collect' command with several arguments - separated by commas; the effect is the same. - - The command `info scope' (*note info scope: Symbols.) is - particularly useful for figuring out what data to collect. - -`teval EXPR1, EXPR2, ...' - Evaluate the given expressions when the tracepoint is hit. This - command accepts a comma-separated list of expressions. The results - are discarded, so this is mainly useful for assigning values to - trace state variables (*note Trace State Variables::) without - adding those values to the trace buffer, as would be the case if - the `collect' action were used. - -`while-stepping N' - Perform N single-step instruction traces after the tracepoint, - collecting new data after each step. The `while-stepping' command - is followed by the list of what to collect while stepping - (followed by its own `end' command): - - > while-stepping 12 - > collect $regs, myglobal - > end - > - - Note that `$pc' is not automatically collected by - `while-stepping'; you need to explicitly collect that register if - you need it. You may abbreviate `while-stepping' as `ws' or - `stepping'. - -`set default-collect EXPR1, EXPR2, ...' - This variable is a list of expressions to collect at each - tracepoint hit. It is effectively an additional `collect' action - prepended to every tracepoint action list. The expressions are - parsed individually for each tracepoint, so for instance a - variable named `xyz' may be interpreted as a global for one - tracepoint, and a local for another, as appropriate to the - tracepoint's location. - -`show default-collect' - Show the list of expressions that are collected by default at each - tracepoint hit. - - - -File: gdb.info, Node: Listing Tracepoints, Next: Listing Static Tracepoint Markers, Prev: Tracepoint Actions, Up: Set Tracepoints - -13.1.7 Listing Tracepoints --------------------------- - -`info tracepoints [NUM...]' - Display information about the tracepoint NUM. If you don't - specify a tracepoint number, displays information about all the - tracepoints defined so far. The format is similar to that used for - `info breakpoints'; in fact, `info tracepoints' is the same - command, simply restricting itself to tracepoints. - - A tracepoint's listing may include additional information specific - to tracing: - - * its passcount as given by the `passcount N' command - - (gdb) info trace - Num Type Disp Enb Address What - 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 - while-stepping 20 - collect globfoo, $regs - end - collect globfoo2 - end - pass count 1200 - (gdb) - - This command can be abbreviated `info tp'. - - -File: gdb.info, Node: Listing Static Tracepoint Markers, Next: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints - -13.1.8 Listing Static Tracepoint Markers ----------------------------------------- - -`info static-tracepoint-markers' - Display information about all static tracepoint markers defined in - the program. - - For each marker, the following columns are printed: - - _Count_ - An incrementing counter, output to help readability. This is - not a stable identifier. - - _ID_ - The marker ID, as reported by the target. - - _Enabled or Disabled_ - Probed markers are tagged with `y'. `n' identifies marks - that are not enabled. - - _Address_ - Where the marker is in your program, as a memory address. - - _What_ - Where the marker is in the source for your program, as a file - and line number. If the debug information included in the - program does not allow GDB to locate the source of the - marker, this column will be left blank. - - In addition, the following information may be printed for each - marker: - - _Data_ - User data passed to the tracing library by the marker call. - In the UST backend, this is the format string passed as - argument to the marker call. - - _Static tracepoints probing the marker_ - The list of static tracepoints attached to the marker. - - (gdb) info static-tracepoint-markers - Cnt ID Enb Address What - 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 - Data: number1 %d number2 %d - Probed by static tracepoints: #2 - 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 - Data: str %s - (gdb) - - -File: gdb.info, Node: Starting and Stopping Trace Experiments, Next: Tracepoint Restrictions, Prev: Listing Static Tracepoint Markers, Up: Set Tracepoints - -13.1.9 Starting and Stopping Trace Experiments ----------------------------------------------- - -`tstart' - This command takes no arguments. It starts the trace experiment, - and begins collecting data. This has the side effect of - discarding all the data collected in the trace buffer during the - previous trace experiment. - -`tstop' - This command takes no arguments. It ends the trace experiment, and - stops collecting data. - - *Note*: a trace experiment and data collection may stop - automatically if any tracepoint's passcount is reached (*note - Tracepoint Passcounts::), or if the trace buffer becomes full. - -`tstatus' - This command displays the status of the current trace data - collection. - - Here is an example of the commands we described so far: - - (gdb) trace gdb_c_test - (gdb) actions - Enter actions for tracepoint #1, one per line. - > collect $regs,$locals,$args - > while-stepping 11 - > collect $regs - > end - > end - (gdb) tstart - [time passes ...] - (gdb) tstop - - You can choose to continue running the trace experiment even if GDB -disconnects from the target, voluntarily or involuntarily. For -commands such as `detach', the debugger will ask what you want to do -with the trace. But for unexpected terminations (GDB crash, network -outage), it would be unfortunate to lose hard-won trace data, so the -variable `disconnected-tracing' lets you decide whether the trace should -continue running without GDB. - -`set disconnected-tracing on' -`set disconnected-tracing off' - Choose whether a tracing run should continue to run if GDB has - disconnected from the target. Note that `detach' or `quit' will - ask you directly what to do about a running trace no matter what - this variable's setting, so the variable is mainly useful for - handling unexpected situations, such as loss of the network. - -`show disconnected-tracing' - Show the current choice for disconnected tracing. - - - When you reconnect to the target, the trace experiment may or may not -still be running; it might have filled the trace buffer in the -meantime, or stopped for one of the other reasons. If it is running, -it will continue after reconnection. - - Upon reconnection, the target will upload information about the -tracepoints in effect. GDB will then compare that information to the -set of tracepoints currently defined, and attempt to match them up, -allowing for the possibility that the numbers may have changed due to -creation and deletion in the meantime. If one of the target's -tracepoints does not match any in GDB, the debugger will create a new -tracepoint, so that you have a number with which to specify that -tracepoint. This matching-up process is necessarily heuristic, and it -may result in useless tracepoints being created; you may simply delete -them if they are of no use. - - If your target agent supports a "circular trace buffer", then you -can run a trace experiment indefinitely without filling the trace -buffer; when space runs out, the agent deletes already-collected trace -frames, oldest first, until there is enough room to continue -collecting. This is especially useful if your tracepoints are being -hit too often, and your trace gets terminated prematurely because the -buffer is full. To ask for a circular trace buffer, simply set -`circular-trace-buffer' to on. You can set this at any time, including -during tracing; if the agent can do it, it will change buffer handling -on the fly, otherwise it will not take effect until the next run. - -`set circular-trace-buffer on' -`set circular-trace-buffer off' - Choose whether a tracing run should use a linear or circular buffer - for trace data. A linear buffer will not lose any trace data, but - may fill up prematurely, while a circular buffer will discard old - trace data, but it will have always room for the latest tracepoint - hits. - -`show circular-trace-buffer' - Show the current choice for the trace buffer. Note that this may - not match the agent's current buffer handling, nor is it - guaranteed to match the setting that might have been in effect - during a past run, for instance if you are looking at frames from - a trace file. - - - -File: gdb.info, Node: Tracepoint Restrictions, Prev: Starting and Stopping Trace Experiments, Up: Set Tracepoints - -13.1.10 Tracepoint Restrictions -------------------------------- - -There are a number of restrictions on the use of tracepoints. As -described above, tracepoint data gathering occurs on the target without -interaction from GDB. Thus the full capabilities of the debugger are -not available during data gathering, and then at data examination time, -you will be limited by only having what was collected. The following -items describe some common problems, but it is not exhaustive, and you -may run into additional difficulties not mentioned here. - - * Tracepoint expressions are intended to gather objects (lvalues). - Thus the full flexibility of GDB's expression evaluator is not - available. You cannot call functions, cast objects to aggregate - types, access convenience variables or modify values (except by - assignment to trace state variables). Some language features may - implicitly call functions (for instance Objective-C fields with - accessors), and therefore cannot be collected either. - - * Collection of local variables, either individually or in bulk with - `$locals' or `$args', during `while-stepping' may behave - erratically. The stepping action may enter a new scope (for - instance by stepping into a function), or the location of the - variable may change (for instance it is loaded into a register). - The tracepoint data recorded uses the location information for the - variables that is correct for the tracepoint location. When the - tracepoint is created, it is not possible, in general, to determine - where the steps of a `while-stepping' sequence will advance the - program--particularly if a conditional branch is stepped. - - * Collection of an incompletely-initialized or partially-destroyed - object may result in something that GDB cannot display, or displays - in a misleading way. - - * When GDB displays a pointer to character it automatically - dereferences the pointer to also display characters of the string - being pointed to. However, collecting the pointer during tracing - does not automatically collect the string. You need to explicitly - dereference the pointer and provide size information if you want to - collect not only the pointer, but the memory pointed to. For - example, `*ptr@50' can be used to collect the 50 element array - pointed to by `ptr'. - - * It is not possible to collect a complete stack backtrace at a - tracepoint. Instead, you may collect the registers and a few - hundred bytes from the stack pointer with something like - `*$esp@300' (adjust to use the name of the actual stack pointer - register on your target architecture, and the amount of stack you - wish to capture). Then the `backtrace' command will show a - partial backtrace when using a trace frame. The number of stack - frames that can be examined depends on the sizes of the frames in - the collected stack. Note that if you ask for a block so large - that it goes past the bottom of the stack, the target agent may - report an error trying to read from an invalid address. - - * If you do not collect registers at a tracepoint, GDB can infer - that the value of `$pc' must be the same as the address of the - tracepoint and use that when you are looking at a trace frame for - that tracepoint. However, this cannot work if the tracepoint has - multiple locations (for instance if it was set in a function that - was inlined), or if it has a `while-stepping' loop. In those cases - GDB will warn you that it can't infer `$pc', and default it to - zero. - - - -File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints - -13.2 Using the Collected Data -============================= - -After the tracepoint experiment ends, you use GDB commands for -examining the trace data. The basic idea is that each tracepoint -collects a trace "snapshot" every time it is hit and another snapshot -every time it single-steps. All these snapshots are consecutively -numbered from zero and go into a buffer, and you can examine them -later. The way you examine them is to "focus" on a specific trace -snapshot. When the remote stub is focused on a trace snapshot, it will -respond to all GDB requests for memory and registers by reading from -the buffer which belongs to that snapshot, rather than from _real_ -memory or registers of the program being debugged. This means that -*all* GDB commands (`print', `info registers', `backtrace', etc.) will -behave as if we were currently debugging the program state as it was -when the tracepoint occurred. Any requests for data that are not in -the buffer will fail. - -* Menu: - -* tfind:: How to select a trace snapshot -* tdump:: How to display all data for a snapshot -* save tracepoints:: How to save tracepoints for a future run - - -File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data - -13.2.1 `tfind N' ----------------- - -The basic command for selecting a trace snapshot from the buffer is -`tfind N', which finds trace snapshot number N, counting from zero. If -no argument N is given, the next snapshot is selected. - - Here are the various forms of using the `tfind' command. - -`tfind start' - Find the first snapshot in the buffer. This is a synonym for - `tfind 0' (since 0 is the number of the first snapshot). - -`tfind none' - Stop debugging trace snapshots, resume _live_ debugging. - -`tfind end' - Same as `tfind none'. - -`tfind' - No argument means find the next trace snapshot. - -`tfind -' - Find the previous trace snapshot before the current one. This - permits retracing earlier steps. - -`tfind tracepoint NUM' - Find the next snapshot associated with tracepoint NUM. Search - proceeds forward from the last examined trace snapshot. If no - argument NUM is given, it means find the next snapshot collected - for the same tracepoint as the current snapshot. - -`tfind pc ADDR' - Find the next snapshot associated with the value ADDR of the - program counter. Search proceeds forward from the last examined - trace snapshot. If no argument ADDR is given, it means find the - next snapshot with the same value of PC as the current snapshot. - -`tfind outside ADDR1, ADDR2' - Find the next snapshot whose PC is outside the given range of - addresses (exclusive). - -`tfind range ADDR1, ADDR2' - Find the next snapshot whose PC is between ADDR1 and ADDR2 - (inclusive). - -`tfind line [FILE:]N' - Find the next snapshot associated with the source line N. If the - optional argument FILE is given, refer to line N in that source - file. Search proceeds forward from the last examined trace - snapshot. If no argument N is given, it means find the next line - other than the one currently being examined; thus saying `tfind - line' repeatedly can appear to have the same effect as stepping - from line to line in a _live_ debugging session. - - The default arguments for the `tfind' commands are specifically -designed to make it easy to scan through the trace buffer. For -instance, `tfind' with no argument selects the next trace snapshot, and -`tfind -' with no argument selects the previous trace snapshot. So, by -giving one `tfind' command, and then simply hitting <RET> repeatedly -you can examine all the trace snapshots in order. Or, by saying `tfind --' and then hitting <RET> repeatedly you can examine the snapshots in -reverse order. The `tfind line' command with no argument selects the -snapshot for the next source line executed. The `tfind pc' command with -no argument selects the next snapshot with the same program counter -(PC) as the current frame. The `tfind tracepoint' command with no -argument selects the next trace snapshot collected by the same -tracepoint as the current one. - - In addition to letting you scan through the trace buffer manually, -these commands make it easy to construct GDB scripts that scan through -the trace buffer and print out whatever collected data you are -interested in. Thus, if we want to examine the PC, FP, and SP -registers from each trace frame in the buffer, we can say this: - - (gdb) tfind start - (gdb) while ($trace_frame != -1) - > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ - $trace_frame, $pc, $sp, $fp - > tfind - > end - - Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 - Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 - Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 - Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 - Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 - Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 - Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 - Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 - Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 - Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 - Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 - - Or, if we want to examine the variable `X' at each source line in -the buffer: - - (gdb) tfind start - (gdb) while ($trace_frame != -1) - > printf "Frame %d, X == %d\n", $trace_frame, X - > tfind line - > end - - Frame 0, X = 1 - Frame 7, X = 2 - Frame 13, X = 255 - - -File: gdb.info, Node: tdump, Next: save tracepoints, Prev: tfind, Up: Analyze Collected Data - -13.2.2 `tdump' --------------- - -This command takes no arguments. It prints all the data collected at -the current trace snapshot. - - (gdb) trace 444 - (gdb) actions - Enter actions for tracepoint #2, one per line: - > collect $regs, $locals, $args, gdb_long_test - > end - - (gdb) tstart - - (gdb) tfind line 444 - #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) - at gdb_test.c:444 - 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) - - (gdb) tdump - Data collected at tracepoint 2, trace frame 1: - d0 0xc4aa0085 -995491707 - d1 0x18 24 - d2 0x80 128 - d3 0x33 51 - d4 0x71aea3d 119204413 - d5 0x22 34 - d6 0xe0 224 - d7 0x380035 3670069 - a0 0x19e24a 1696330 - a1 0x3000668 50333288 - a2 0x100 256 - a3 0x322000 3284992 - a4 0x3000698 50333336 - a5 0x1ad3cc 1758156 - fp 0x30bf3c 0x30bf3c - sp 0x30bf34 0x30bf34 - ps 0x0 0 - pc 0x20b2c8 0x20b2c8 - fpcontrol 0x0 0 - fpstatus 0x0 0 - fpiaddr 0x0 0 - p = 0x20e5b4 "gdb-test" - p1 = (void *) 0x11 - p2 = (void *) 0x22 - p3 = (void *) 0x33 - p4 = (void *) 0x44 - p5 = (void *) 0x55 - p6 = (void *) 0x66 - gdb_long_test = 17 '\021' - - (gdb) - - `tdump' works by scanning the tracepoint's current collection -actions and printing the value of each expression listed. So `tdump' -can fail, if after a run, you change the tracepoint's actions to -mention variables that were not collected during the run. - - Also, for tracepoints with `while-stepping' loops, `tdump' uses the -collected value of `$pc' to distinguish between trace frames that were -collected at the tracepoint hit, and frames that were collected while -stepping. This allows it to correctly choose whether to display the -basic list of collections, or the collections from the body of the -while-stepping loop. However, if `$pc' was not collected, then `tdump' -will always attempt to dump using the basic collection list, and may -fail if a while-stepping frame does not include all the same data that -is collected at the tracepoint hit. - - -File: gdb.info, Node: save tracepoints, Prev: tdump, Up: Analyze Collected Data - -13.2.3 `save tracepoints FILENAME' ----------------------------------- - -This command saves all current tracepoint definitions together with -their actions and passcounts, into a file `FILENAME' suitable for use -in a later debugging session. To read the saved tracepoint -definitions, use the `source' command (*note Command Files::). The -`save-tracepoints' command is a deprecated alias for `save tracepoints' - - -File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints - -13.3 Convenience Variables for Tracepoints -========================================== - -`(int) $trace_frame' - The current trace snapshot (a.k.a. "frame") number, or -1 if no - snapshot is selected. - -`(int) $tracepoint' - The tracepoint for the current trace snapshot. - -`(int) $trace_line' - The line number for the current trace snapshot. - -`(char []) $trace_file' - The source file for the current trace snapshot. - -`(char []) $trace_func' - The name of the function containing `$tracepoint'. - - Note: `$trace_file' is not suitable for use in `printf', use -`output' instead. - - Here's a simple example of using these convenience variables for -stepping through all the trace snapshots and printing some of their -data. Note that these are not the same as trace state variables, which -are managed by the target. - - (gdb) tfind start - - (gdb) while $trace_frame != -1 - > output $trace_file - > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint - > tfind - > end - - -File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints - -13.4 Using Trace Files -====================== - -In some situations, the target running a trace experiment may no longer -be available; perhaps it crashed, or the hardware was needed for a -different activity. To handle these cases, you can arrange to dump the -trace data into a file, and later use that file as a source of trace -data, via the `target tfile' command. - -`tsave [ -r ] FILENAME' - Save the trace data to FILENAME. By default, this command assumes - that FILENAME refers to the host filesystem, so if necessary GDB - will copy raw trace data up from the target and then save it. If - the target supports it, you can also supply the optional argument - `-r' ("remote") to direct the target to save the data directly - into FILENAME in its own filesystem, which may be more efficient - if the trace buffer is very large. (Note, however, that `target - tfile' can only read from files accessible to the host.) - -`target tfile FILENAME' - Use the file named FILENAME as a source of trace data. Commands - that examine data work as they do with a live target, but it is not - possible to run any new trace experiments. `tstatus' will report - the state of the trace run at the moment the data was saved, as - well as the current trace frame you are examining. FILENAME must - be on a filesystem accessible to the host. - - - -File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top - -14 Debugging Programs That Use Overlays -*************************************** - -If your program is too large to fit completely in your target system's -memory, you can sometimes use "overlays" to work around this problem. -GDB provides some support for debugging programs that use overlays. - -* Menu: - -* How Overlays Work:: A general explanation of overlays. -* Overlay Commands:: Managing overlays in GDB. -* Automatic Overlay Debugging:: GDB can find out which overlays are - mapped by asking the inferior. -* Overlay Sample Program:: A sample program using overlays. - - -File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays - -14.1 How Overlays Work -====================== - -Suppose you have a computer whose instruction address space is only 64 -kilobytes long, but which has much more memory which can be accessed by -other means: special instructions, segment registers, or memory -management hardware, for example. Suppose further that you want to -adapt a program which is larger than 64 kilobytes to run on this system. - - One solution is to identify modules of your program which are -relatively independent, and need not call each other directly; call -these modules "overlays". Separate the overlays from the main program, -and place their machine code in the larger memory. Place your main -program in instruction memory, but leave at least enough space there to -hold the largest overlay as well. - - Now, to call a function located in an overlay, you must first copy -that overlay's machine code from the large memory into the space set -aside for it in the instruction memory, and then jump to its entry point -there. - - Data Instruction Larger - Address Space Address Space Address Space - +-----------+ +-----------+ +-----------+ - | | | | | | - +-----------+ +-----------+ +-----------+<-- overlay 1 - | program | | main | .----| overlay 1 | load address - | variables | | program | | +-----------+ - | and heap | | | | | | - +-----------+ | | | +-----------+<-- overlay 2 - | | +-----------+ | | | load address - +-----------+ | | | .-| overlay 2 | - | | | | | | - mapped --->+-----------+ | | +-----------+ - address | | | | | | - | overlay | <-' | | | - | area | <---' +-----------+<-- overlay 3 - | | <---. | | load address - +-----------+ `--| overlay 3 | - | | | | - +-----------+ | | - +-----------+ - | | - +-----------+ - - A code overlay - - The diagram (*note A code overlay::) shows a system with separate -data and instruction address spaces. To map an overlay, the program -copies its code from the larger address space to the instruction -address space. Since the overlays shown here all use the same mapped -address, only one may be mapped at a time. For a system with a single -address space for data and instructions, the diagram would be similar, -except that the program variables and heap would share an address space -with the main program and the overlay area. - - An overlay loaded into instruction memory and ready for use is -called a "mapped" overlay; its "mapped address" is its address in the -instruction memory. An overlay not present (or only partially present) -in instruction memory is called "unmapped"; its "load address" is its -address in the larger memory. The mapped address is also called the -"virtual memory address", or "VMA"; the load address is also called the -"load memory address", or "LMA". - - Unfortunately, overlays are not a completely transparent way to -adapt a program to limited instruction memory. They introduce a new -set of global constraints you must keep in mind as you design your -program: - - * Before calling or returning to a function in an overlay, your - program must make sure that overlay is actually mapped. - Otherwise, the call or return will transfer control to the right - address, but in the wrong overlay, and your program will probably - crash. - - * If the process of mapping an overlay is expensive on your system, - you will need to choose your overlays carefully to minimize their - effect on your program's performance. - - * The executable file you load onto your system must contain each - overlay's instructions, appearing at the overlay's load address, - not its mapped address. However, each overlay's instructions must - be relocated and its symbols defined as if the overlay were at its - mapped address. You can use GNU linker scripts to specify - different load and relocation addresses for pieces of your - program; see *note Overlay Description: (ld.info)Overlay - Description. - - * The procedure for loading executable files onto your system must - be able to load their contents into the larger address space as - well as the instruction and data spaces. - - - The overlay system described above is rather simple, and could be -improved in many ways: - - * If your system has suitable bank switch registers or memory - management hardware, you could use those facilities to make an - overlay's load area contents simply appear at their mapped address - in instruction space. This would probably be faster than copying - the overlay to its mapped area in the usual way. - - * If your overlays are small enough, you could set aside more than - one overlay area, and have more than one overlay mapped at a time. - - * You can use overlays to manage data, as well as instructions. In - general, data overlays are even less transparent to your design - than code overlays: whereas code overlays only require care when - you call or return to functions, data overlays require care every - time you access the data. Also, if you change the contents of a - data overlay, you must copy its contents back out to its load - address before you can copy a different data overlay into the same - mapped area. - - - -File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays - -14.2 Overlay Commands -===================== - -To use GDB's overlay support, each overlay in your program must -correspond to a separate section of the executable file. The section's -virtual memory address and load memory address must be the overlay's -mapped and load addresses. Identifying overlays with sections allows -GDB to determine the appropriate address of a function or variable, -depending on whether the overlay is mapped or not. - - GDB's overlay commands all start with the word `overlay'; you can -abbreviate this as `ov' or `ovly'. The commands are: - -`overlay off' - Disable GDB's overlay support. When overlay support is disabled, - GDB assumes that all functions and variables are always present at - their mapped addresses. By default, GDB's overlay support is - disabled. - -`overlay manual' - Enable "manual" overlay debugging. In this mode, GDB relies on - you to tell it which overlays are mapped, and which are not, using - the `overlay map-overlay' and `overlay unmap-overlay' commands - described below. - -`overlay map-overlay OVERLAY' -`overlay map OVERLAY' - Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of - the object file section containing the overlay. When an overlay - is mapped, GDB assumes it can find the overlay's functions and - variables at their mapped addresses. GDB assumes that any other - overlays whose mapped ranges overlap that of OVERLAY are now - unmapped. - -`overlay unmap-overlay OVERLAY' -`overlay unmap OVERLAY' - Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the - name of the object file section containing the overlay. When an - overlay is unmapped, GDB assumes it can find the overlay's - functions and variables at their load addresses. - -`overlay auto' - Enable "automatic" overlay debugging. In this mode, GDB consults - a data structure the overlay manager maintains in the inferior to - see which overlays are mapped. For details, see *note Automatic - Overlay Debugging::. - -`overlay load-target' -`overlay load' - Re-read the overlay table from the inferior. Normally, GDB - re-reads the table GDB automatically each time the inferior stops, - so this command should only be necessary if you have changed the - overlay mapping yourself using GDB. This command is only useful - when using automatic overlay debugging. - -`overlay list-overlays' -`overlay list' - Display a list of the overlays currently mapped, along with their - mapped addresses, load addresses, and sizes. - - - Normally, when GDB prints a code address, it includes the name of -the function the address falls in: - - (gdb) print main - $3 = {int ()} 0x11a0 <main> - When overlay debugging is enabled, GDB recognizes code in unmapped -overlays, and prints the names of unmapped functions with asterisks -around them. For example, if `foo' is a function in an unmapped -overlay, GDB prints it this way: - - (gdb) overlay list - No sections are mapped. - (gdb) print foo - $5 = {int (int)} 0x100000 <*foo*> - When `foo''s overlay is mapped, GDB prints the function's name -normally: - - (gdb) overlay list - Section .ov.foo.text, loaded at 0x100000 - 0x100034, - mapped at 0x1016 - 0x104a - (gdb) print foo - $6 = {int (int)} 0x1016 <foo> - - When overlay debugging is enabled, GDB can find the correct address -for functions and variables in an overlay, whether or not the overlay -is mapped. This allows most GDB commands, like `break' and -`disassemble', to work normally, even on unmapped code. However, GDB's -breakpoint support has some limitations: - - * You can set breakpoints in functions in unmapped overlays, as long - as GDB can write to the overlay at its load address. - - * GDB can not set hardware or simulator-based breakpoints in - unmapped overlays. However, if you set a breakpoint at the end of - your overlay manager (and tell GDB which overlays are now mapped, - if you are using manual overlay management), GDB will re-set its - breakpoints properly. - - -File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays - -14.3 Automatic Overlay Debugging -================================ - -GDB can automatically track which overlays are mapped and which are -not, given some simple co-operation from the overlay manager in the -inferior. If you enable automatic overlay debugging with the `overlay -auto' command (*note Overlay Commands::), GDB looks in the inferior's -memory for certain variables describing the current state of the -overlays. - - Here are the variables your overlay manager must define to support -GDB's automatic overlay debugging: - -`_ovly_table': - This variable must be an array of the following structures: - - struct - { - /* The overlay's mapped address. */ - unsigned long vma; - - /* The size of the overlay, in bytes. */ - unsigned long size; - - /* The overlay's load address. */ - unsigned long lma; - - /* Non-zero if the overlay is currently mapped; - zero otherwise. */ - unsigned long mapped; - } - -`_novlys': - This variable must be a four-byte signed integer, holding the total - number of elements in `_ovly_table'. - - - To decide whether a particular overlay is mapped or not, GDB looks -for an entry in `_ovly_table' whose `vma' and `lma' members equal the -VMA and LMA of the overlay's section in the executable file. When GDB -finds a matching entry, it consults the entry's `mapped' member to -determine whether the overlay is currently mapped. - - In addition, your overlay manager may define a function called -`_ovly_debug_event'. If this function is defined, GDB will silently -set a breakpoint there. If the overlay manager then calls this -function whenever it has changed the overlay table, this will enable -GDB to accurately keep track of which overlays are in program memory, -and update any breakpoints that may be set in overlays. This will -allow breakpoints to work even if the overlays are kept in ROM or other -non-writable memory while they are not being executed. - - -File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays - -14.4 Overlay Sample Program -=========================== - -When linking a program which uses overlays, you must place the overlays -at their load addresses, while relocating them to run at their mapped -addresses. To do this, you must write a linker script (*note Overlay -Description: (ld.info)Overlay Description.). Unfortunately, since -linker scripts are specific to a particular host system, target -architecture, and target memory layout, this manual cannot provide -portable sample code demonstrating GDB's overlay support. - - However, the GDB source distribution does contain an overlaid -program, with linker scripts for a few systems, as part of its test -suite. The program consists of the following files from -`gdb/testsuite/gdb.base': - -`overlays.c' - The main program file. - -`ovlymgr.c' - A simple overlay manager, used by `overlays.c'. - -`foo.c' -`bar.c' -`baz.c' -`grbx.c' - Overlay modules, loaded and used by `overlays.c'. - -`d10v.ld' -`m32r.ld' - Linker scripts for linking the test program on the `d10v-elf' and - `m32r-elf' targets. - - You can build the test program using the `d10v-elf' GCC -cross-compiler like this: - - $ d10v-elf-gcc -g -c overlays.c - $ d10v-elf-gcc -g -c ovlymgr.c - $ d10v-elf-gcc -g -c foo.c - $ d10v-elf-gcc -g -c bar.c - $ d10v-elf-gcc -g -c baz.c - $ d10v-elf-gcc -g -c grbx.c - $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ - baz.o grbx.o -Wl,-Td10v.ld -o overlays - - The build process is identical for any other architecture, except -that you must substitute the appropriate compiler and linker script for -the target system for `d10v-elf-gcc' and `d10v.ld'. - - -File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top - -15 Using GDB with Different Languages -************************************* - -Although programming languages generally have common aspects, they are -rarely expressed in the same manner. For instance, in ANSI C, -dereferencing a pointer `p' is accomplished by `*p', but in Modula-2, -it is accomplished by `p^'. Values can also be represented (and -displayed) differently. Hex numbers in C appear as `0x1ae', while in -Modula-2 they appear as `1AEH'. - - Language-specific information is built into GDB for some languages, -allowing you to express operations like the above in your program's -native language, and allowing GDB to output values in a manner -consistent with the syntax of your program's native language. The -language you use to build expressions is called the "working language". - -* Menu: - -* Setting:: Switching between source languages -* Show:: Displaying the language -* Checks:: Type and range checks -* Supported Languages:: Supported languages -* Unsupported Languages:: Unsupported languages - - -File: gdb.info, Node: Setting, Next: Show, Up: Languages - -15.1 Switching Between Source Languages -======================================= - -There are two ways to control the working language--either have GDB set -it automatically, or select it manually yourself. You can use the `set -language' command for either purpose. On startup, GDB defaults to -setting the language automatically. The working language is used to -determine how expressions you type are interpreted, how values are -printed, etc. - - In addition to the working language, every source file that GDB -knows about has its own working language. For some object file -formats, the compiler might indicate which language a particular source -file is in. However, most of the time GDB infers the language from the -name of the file. The language of a source file controls whether C++ -names are demangled--this way `backtrace' can show each frame -appropriately for its own language. There is no way to set the -language of a source file from within GDB, but you can set the language -associated with a filename extension. *Note Displaying the Language: -Show. - - This is most commonly a problem when you use a program, such as -`cfront' or `f2c', that generates C but is written in another language. -In that case, make the program use `#line' directives in its C output; -that way GDB will know the correct language of the source code of the -original program, and will display that source code, not the generated -C code. - -* Menu: - -* Filenames:: Filename extensions and languages. -* Manually:: Setting the working language manually -* Automatically:: Having GDB infer the source language - - -File: gdb.info, Node: Filenames, Next: Manually, Up: Setting - -15.1.1 List of Filename Extensions and Languages ------------------------------------------------- - -If a source file name ends in one of the following extensions, then GDB -infers that its language is the one indicated. - -`.ada' -`.ads' -`.adb' -`.a' - Ada source file. - -`.c' - C source file - -`.C' -`.cc' -`.cp' -`.cpp' -`.cxx' -`.c++' - C++ source file - -`.d' - D source file - -`.m' - Objective-C source file - -`.f' -`.F' - Fortran source file - -`.mod' - Modula-2 source file - -`.s' -`.S' - Assembler source file. This actually behaves almost like C, but - GDB does not skip over function prologues when stepping. - - In addition, you may set the language associated with a filename -extension. *Note Displaying the Language: Show. - - -File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting - -15.1.2 Setting the Working Language ------------------------------------ - -If you allow GDB to set the language automatically, expressions are -interpreted the same way in your debugging session and your program. - - If you wish, you may set the language manually. To do this, issue -the command `set language LANG', where LANG is the name of a language, -such as `c' or `modula-2'. For a list of the supported languages, type -`set language'. - - Setting the language manually prevents GDB from updating the working -language automatically. This can lead to confusion if you try to debug -a program when the working language is not the same as the source -language, when an expression is acceptable to both languages--but means -different things. For instance, if the current source file were -written in C, and GDB was parsing Modula-2, a command such as: - - print a = b + c - -might not have the effect you intended. In C, this means to add `b' -and `c' and place the result in `a'. The result printed would be the -value of `a'. In Modula-2, this means to compare `a' to the result of -`b+c', yielding a `BOOLEAN' value. - - -File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting - -15.1.3 Having GDB Infer the Source Language -------------------------------------------- - -To have GDB set the working language automatically, use `set language -local' or `set language auto'. GDB then infers the working language. -That is, when your program stops in a frame (usually by encountering a -breakpoint), GDB sets the working language to the language recorded for -the function in that frame. If the language for a frame is unknown -(that is, if the function or block corresponding to the frame was -defined in a source file that does not have a recognized extension), -the current working language is not changed, and GDB issues a warning. - - This may not seem necessary for most programs, which are written -entirely in one source language. However, program modules and libraries -written in one source language can be used by a main program written in -a different source language. Using `set language auto' in this case -frees you from having to set the working language manually. - - -File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages - -15.2 Displaying the Language -============================ - -The following commands help you find out which language is the working -language, and also what language source files were written in. - -`show language' - Display the current working language. This is the language you - can use with commands such as `print' to build and compute - expressions that may involve variables in your program. - -`info frame' - Display the source language for this frame. This language becomes - the working language if you use an identifier from this frame. - *Note Information about a Frame: Frame Info, to identify the other - information listed here. - -`info source' - Display the source language of this source file. *Note Examining - the Symbol Table: Symbols, to identify the other information - listed here. - - In unusual circumstances, you may have source files with extensions -not in the standard list. You can then set the extension associated -with a language explicitly: - -`set extension-language EXT LANGUAGE' - Tell GDB that source files with extension EXT are to be assumed as - written in the source language LANGUAGE. - -`info extensions' - List all the filename extensions and the associated languages. - - -File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages - -15.3 Type and Range Checking -============================ - - _Warning:_ In this release, the GDB commands for type and range - checking are included, but they do not yet have any effect. This - section documents the intended facilities. - - Some languages are designed to guard you against making seemingly -common errors through a series of compile- and run-time checks. These -include checking the type of arguments to functions and operators, and -making sure mathematical overflows are caught at run time. Checks such -as these help to ensure a program's correctness once it has been -compiled by eliminating type mismatches, and providing active checks -for range errors when your program is running. - - GDB can check for conditions like the above if you wish. Although -GDB does not check the statements in your program, it can check -expressions entered directly into GDB for evaluation via the `print' -command, for example. As with the working language, GDB can also -decide whether or not to check automatically based on your program's -source language. *Note Supported Languages: Supported Languages, for -the default settings of supported languages. - -* Menu: - -* Type Checking:: An overview of type checking -* Range Checking:: An overview of range checking - - -File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks - -15.3.1 An Overview of Type Checking ------------------------------------ - -Some languages, such as Modula-2, are strongly typed, meaning that the -arguments to operators and functions have to be of the correct type, -otherwise an error occurs. These checks prevent type mismatch errors -from ever causing any run-time problems. For example, - - 1 + 2 => 3 -but - error--> 1 + 2.3 - - The second example fails because the `CARDINAL' 1 is not -type-compatible with the `REAL' 2.3. - - For the expressions you use in GDB commands, you can tell the GDB -type checker to skip checking; to treat any mismatches as errors and -abandon the expression; or to only issue warnings when type mismatches -occur, but evaluate the expression anyway. When you choose the last of -these, GDB evaluates expressions like the second example above, but -also issues a warning. - - Even if you turn type checking off, there may be other reasons -related to type that prevent GDB from evaluating an expression. For -instance, GDB does not know how to add an `int' and a `struct foo'. -These particular type errors have nothing to do with the language in -use, and usually arise from expressions, such as the one described -above, which make little sense to evaluate anyway. - - Each language defines to what degree it is strict about type. For -instance, both Modula-2 and C require the arguments to arithmetical -operators to be numbers. In C, enumerated types and pointers can be -represented as numbers, so that they are valid arguments to mathematical -operators. *Note Supported Languages: Supported Languages, for further -details on specific languages. - - GDB provides some additional commands for controlling the type -checker: - -`set check type auto' - Set type checking on or off based on the current working language. - *Note Supported Languages: Supported Languages, for the default - settings for each language. - -`set check type on' -`set check type off' - Set type checking on or off, overriding the default setting for the - current working language. Issue a warning if the setting does not - match the language default. If any type mismatches occur in - evaluating an expression while type checking is on, GDB prints a - message and aborts evaluation of the expression. - -`set check type warn' - Cause the type checker to issue warnings, but to always attempt to - evaluate the expression. Evaluating the expression may still be - impossible for other reasons. For example, GDB cannot add numbers - and structures. - -`show type' - Show the current setting of the type checker, and whether or not - GDB is setting it automatically. - - -File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks - -15.3.2 An Overview of Range Checking ------------------------------------- - -In some languages (such as Modula-2), it is an error to exceed the -bounds of a type; this is enforced with run-time checks. Such range -checking is meant to ensure program correctness by making sure -computations do not overflow, or indices on an array element access do -not exceed the bounds of the array. - - For expressions you use in GDB commands, you can tell GDB to treat -range errors in one of three ways: ignore them, always treat them as -errors and abandon the expression, or issue warnings but evaluate the -expression anyway. - - A range error can result from numerical overflow, from exceeding an -array index bound, or when you type a constant that is not a member of -any type. Some languages, however, do not treat overflows as an error. -In many implementations of C, mathematical overflow causes the result -to "wrap around" to lower values--for example, if M is the largest -integer value, and S is the smallest, then - - M + 1 => S - - This, too, is specific to individual languages, and in some cases -specific to individual compilers or machines. *Note Supported -Languages: Supported Languages, for further details on specific -languages. - - GDB provides some additional commands for controlling the range -checker: - -`set check range auto' - Set range checking on or off based on the current working language. - *Note Supported Languages: Supported Languages, for the default - settings for each language. - -`set check range on' -`set check range off' - Set range checking on or off, overriding the default setting for - the current working language. A warning is issued if the setting - does not match the language default. If a range error occurs and - range checking is on, then a message is printed and evaluation of - the expression is aborted. - -`set check range warn' - Output messages when the GDB range checker detects a range error, - but attempt to evaluate the expression anyway. Evaluating the - expression may still be impossible for other reasons, such as - accessing memory that the process does not own (a typical example - from many Unix systems). - -`show range' - Show the current setting of the range checker, and whether or not - it is being set automatically by GDB. - - -File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages - -15.4 Supported Languages -======================== - -GDB supports C, C++, D, Objective-C, Fortran, Java, OpenCL C, Pascal, -assembly, Modula-2, and Ada. Some GDB features may be used in -expressions regardless of the language you use: the GDB `@' and `::' -operators, and the `{type}addr' construct (*note Expressions: -Expressions.) can be used with the constructs of any supported language. - - The following sections detail to what degree each source language is -supported by GDB. These sections are not meant to be language -tutorials or references, but serve only as a reference guide to what the -GDB expression parser accepts, and what input and output formats should -look like for different languages. There are many good books written -on each of these languages; please look to these for a language -reference or tutorial. - -* Menu: - -* C:: C and C++ -* D:: D -* Objective-C:: Objective-C -* OpenCL C:: OpenCL C -* Fortran:: Fortran -* Pascal:: Pascal -* Modula-2:: Modula-2 -* Ada:: Ada - - -File: gdb.info, Node: C, Next: D, Up: Supported Languages - -15.4.1 C and C++ ----------------- - -Since C and C++ are so closely related, many features of GDB apply to -both languages. Whenever this is the case, we discuss those languages -together. - - The C++ debugging facilities are jointly implemented by the C++ -compiler and GDB. Therefore, to debug your C++ code effectively, you -must compile your C++ programs with a supported C++ compiler, such as -GNU `g++', or the HP ANSI C++ compiler (`aCC'). - - For best results when using GNU C++, use the DWARF 2 debugging -format; if it doesn't work on your system, try the stabs+ debugging -format. You can select those formats explicitly with the `g++' -command-line options `-gdwarf-2' and `-gstabs+'. *Note Options for -Debugging Your Program or GCC: (gcc.info)Debugging Options. - -* Menu: - -* C Operators:: C and C++ operators -* C Constants:: C and C++ constants -* C Plus Plus Expressions:: C++ expressions -* C Defaults:: Default settings for C and C++ -* C Checks:: C and C++ type and range checks -* Debugging C:: GDB and C -* Debugging C Plus Plus:: GDB features for C++ -* Decimal Floating Point:: Numbers in Decimal Floating Point format - - -File: gdb.info, Node: C Operators, Next: C Constants, Up: C - -15.4.1.1 C and C++ Operators -............................ - -Operators must be defined on values of specific types. For instance, -`+' is defined on numbers, but not on structures. Operators are often -defined on groups of types. - - For the purposes of C and C++, the following definitions hold: - - * _Integral types_ include `int' with any of its storage-class - specifiers; `char'; `enum'; and, for C++, `bool'. - - * _Floating-point types_ include `float', `double', and `long - double' (if supported by the target platform). - - * _Pointer types_ include all types defined as `(TYPE *)'. - - * _Scalar types_ include all of the above. - - -The following operators are supported. They are listed here in order -of increasing precedence: - -`,' - The comma or sequencing operator. Expressions in a - comma-separated list are evaluated from left to right, with the - result of the entire expression being the last expression - evaluated. - -`=' - Assignment. The value of an assignment expression is the value - assigned. Defined on scalar types. - -`OP=' - Used in an expression of the form `A OP= B', and translated to - `A = A OP B'. `OP=' and `=' have the same precedence. OP is any - one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', - `/', `%'. - -`?:' - The ternary operator. `A ? B : C' can be thought of as: if A - then B else C. A should be of an integral type. - -`||' - Logical OR. Defined on integral types. - -`&&' - Logical AND. Defined on integral types. - -`|' - Bitwise OR. Defined on integral types. - -`^' - Bitwise exclusive-OR. Defined on integral types. - -`&' - Bitwise AND. Defined on integral types. - -`==, !=' - Equality and inequality. Defined on scalar types. The value of - these expressions is 0 for false and non-zero for true. - -`<, >, <=, >=' - Less than, greater than, less than or equal, greater than or equal. - Defined on scalar types. The value of these expressions is 0 for - false and non-zero for true. - -`<<, >>' - left shift, and right shift. Defined on integral types. - -`@' - The GDB "artificial array" operator (*note Expressions: - Expressions.). - -`+, -' - Addition and subtraction. Defined on integral types, - floating-point types and pointer types. - -`*, /, %' - Multiplication, division, and modulus. Multiplication and - division are defined on integral and floating-point types. - Modulus is defined on integral types. - -`++, --' - Increment and decrement. When appearing before a variable, the - operation is performed before the variable is used in an - expression; when appearing after it, the variable's value is used - before the operation takes place. - -`*' - Pointer dereferencing. Defined on pointer types. Same precedence - as `++'. - -`&' - Address operator. Defined on variables. Same precedence as `++'. - - For debugging C++, GDB implements a use of `&' beyond what is - allowed in the C++ language itself: you can use `&(&REF)' to - examine the address where a C++ reference variable (declared with - `&REF') is stored. - -`-' - Negative. Defined on integral and floating-point types. Same - precedence as `++'. - -`!' - Logical negation. Defined on integral types. Same precedence as - `++'. - -`~' - Bitwise complement operator. Defined on integral types. Same - precedence as `++'. - -`., ->' - Structure member, and pointer-to-structure member. For - convenience, GDB regards the two as equivalent, choosing whether - to dereference a pointer based on the stored type information. - Defined on `struct' and `union' data. - -`.*, ->*' - Dereferences of pointers to members. - -`[]' - Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence - as `->'. - -`()' - Function parameter list. Same precedence as `->'. - -`::' - C++ scope resolution operator. Defined on `struct', `union', and - `class' types. - -`::' - Doubled colons also represent the GDB scope operator (*note - Expressions: Expressions.). Same precedence as `::', above. - - If an operator is redefined in the user code, GDB usually attempts -to invoke the redefined version instead of using the operator's -predefined meaning. - - -File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C - -15.4.1.2 C and C++ Constants -............................ - -GDB allows you to express the constants of C and C++ in the following -ways: - - * Integer constants are a sequence of digits. Octal constants are - specified by a leading `0' (i.e. zero), and hexadecimal constants - by a leading `0x' or `0X'. Constants may also end with a letter - `l', specifying that the constant should be treated as a `long' - value. - - * Floating point constants are a sequence of digits, followed by a - decimal point, followed by a sequence of digits, and optionally - followed by an exponent. An exponent is of the form: - `e[[+]|-]NNN', where NNN is another sequence of digits. The `+' - is optional for positive exponents. A floating-point constant may - also end with a letter `f' or `F', specifying that the constant - should be treated as being of the `float' (as opposed to the - default `double') type; or with a letter `l' or `L', which - specifies a `long double' constant. - - * Enumerated constants consist of enumerated identifiers, or their - integral equivalents. - - * Character constants are a single character surrounded by single - quotes (`''), or a number--the ordinal value of the corresponding - character (usually its ASCII value). Within quotes, the single - character may be represented by a letter or by "escape sequences", - which are of the form `\NNN', where NNN is the octal representation - of the character's ordinal value; or of the form `\X', where `X' - is a predefined special character--for example, `\n' for newline. - - * String constants are a sequence of character constants surrounded - by double quotes (`"'). Any valid character constant (as described - above) may appear. Double quotes within the string must be - preceded by a backslash, so for instance `"a\"b'c"' is a string of - five characters. - - * Pointer constants are an integral value. You can also write - pointers to constants using the C operator `&'. - - * Array constants are comma-separated lists surrounded by braces `{' - and `}'; for example, `{1,2,3}' is a three-element array of - integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and - `{&"hi", &"there", &"fred"}' is a three-element array of pointers. - - -File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C - -15.4.1.3 C++ Expressions -........................ - -GDB expression handling can interpret most C++ expressions. - - _Warning:_ GDB can only debug C++ code if you use the proper - compiler and the proper debug format. Currently, GDB works best - when debugging C++ code that is compiled with GCC 2.95.3 or with - GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'. - DWARF 2 is preferred over stabs+. Most configurations of GCC emit - either DWARF 2 or stabs+ as their default debug format, so you - usually don't need to specify a debug format explicitly. Other - compilers and/or debug formats are likely to work badly or not at - all when using GDB to debug C++ code. - - 1. Member function calls are allowed; you can use expressions like - - count = aml->GetOriginal(x, y) - - 2. While a member function is active (in the selected stack frame), - your expressions have the same namespace available as the member - function; that is, GDB allows implicit references to the class - instance pointer `this' following the same rules as C++. - - 3. You can call overloaded functions; GDB resolves the function call - to the right definition, with some restrictions. GDB does not - perform overload resolution involving user-defined type - conversions, calls to constructors, or instantiations of templates - that do not exist in the program. It also cannot handle ellipsis - argument lists or default arguments. - - It does perform integral conversions and promotions, floating-point - promotions, arithmetic conversions, pointer conversions, - conversions of class objects to base classes, and standard - conversions such as those of functions or arrays to pointers; it - requires an exact match on the number of function arguments. - - Overload resolution is always performed, unless you have specified - `set overload-resolution off'. *Note GDB Features for C++: - Debugging C Plus Plus. - - You must specify `set overload-resolution off' in order to use an - explicit function signature to call an overloaded function, as in - p 'foo(char,int)'('x', 13) - - The GDB command-completion facility can simplify this; see *note - Command Completion: Completion. - - 4. GDB understands variables declared as C++ references; you can use - them in expressions just as you do in C++ source--they are - automatically dereferenced. - - In the parameter list shown when GDB displays a frame, the values - of reference variables are not displayed (unlike other variables); - this avoids clutter, since references are often used for large - structures. The _address_ of a reference variable is always - shown, unless you have specified `set print address off'. - - 5. GDB supports the C++ name resolution operator `::'--your - expressions can use it just as expressions in your program do. - Since one scope may be defined in another, you can use `::' - repeatedly if necessary, for example in an expression like - `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by - reference to source files, in both C and C++ debugging (*note - Program Variables: Variables.). - - In addition, when used with HP's C++ compiler, GDB supports calling -virtual functions correctly, printing out virtual bases of objects, -calling functions in a base subobject, casting objects, and invoking -user-defined operators. - - -File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C - -15.4.1.4 C and C++ Defaults -........................... - -If you allow GDB to set type and range checking automatically, they -both default to `off' whenever the working language changes to C or -C++. This happens regardless of whether you or GDB selects the working -language. - - If you allow GDB to set the language automatically, it recognizes -source files whose names end with `.c', `.C', or `.cc', etc, and when -GDB enters code compiled from one of these files, it sets the working -language to C or C++. *Note Having GDB Infer the Source Language: -Automatically, for further details. - - -File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C - -15.4.1.5 C and C++ Type and Range Checks -........................................ - -By default, when GDB parses C or C++ expressions, type checking is not -used. However, if you turn type checking on, GDB considers two -variables type equivalent if: - - * The two variables are structured and have the same structure, - union, or enumerated tag. - - * The two variables have the same type name, or types that have been - declared equivalent through `typedef'. - - - Range checking, if turned on, is done on mathematical operations. -Array indices are not checked, since they are often used to index a -pointer that is not itself an array. - - -File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C - -15.4.1.6 GDB and C -.................. - -The `set print union' and `show print union' commands apply to the -`union' type. When set to `on', any `union' that is inside a `struct' -or `class' is also printed. Otherwise, it appears as `{...}'. - - The `@' operator aids in the debugging of dynamic arrays, formed -with pointers and a memory allocation function. *Note Expressions: -Expressions. - - -File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C - -15.4.1.7 GDB Features for C++ -............................. - -Some GDB commands are particularly useful with C++, and some are -designed specifically for use with C++. Here is a summary: - -`breakpoint menus' - When you want a breakpoint in a function whose name is overloaded, - GDB has the capability to display a menu of possible breakpoint - locations to help you specify which function definition you want. - *Note Ambiguous Expressions: Ambiguous Expressions. - -`rbreak REGEX' - Setting breakpoints using regular expressions is helpful for - setting breakpoints on overloaded functions that are not members - of any special classes. *Note Setting Breakpoints: Set Breaks. - -`catch throw' -`catch catch' - Debug C++ exception handling using these commands. *Note Setting - Catchpoints: Set Catchpoints. - -`ptype TYPENAME' - Print inheritance relationships as well as other information for - type TYPENAME. *Note Examining the Symbol Table: Symbols. - -`set print demangle' -`show print demangle' -`set print asm-demangle' -`show print asm-demangle' - Control whether C++ symbols display in their source form, both when - displaying code as C++ source and when displaying disassemblies. - *Note Print Settings: Print Settings. - -`set print object' -`show print object' - Choose whether to print derived (actual) or declared types of - objects. *Note Print Settings: Print Settings. - -`set print vtbl' -`show print vtbl' - Control the format for printing virtual function tables. *Note - Print Settings: Print Settings. (The `vtbl' commands do not work - on programs compiled with the HP ANSI C++ compiler (`aCC').) - -`set overload-resolution on' - Enable overload resolution for C++ expression evaluation. The - default is on. For overloaded functions, GDB evaluates the - arguments and searches for a function whose signature matches the - argument types, using the standard C++ conversion rules (see *note - C++ Expressions: C Plus Plus Expressions, for details). If it - cannot find a match, it emits a message. - -`set overload-resolution off' - Disable overload resolution for C++ expression evaluation. For - overloaded functions that are not class member functions, GDB - chooses the first function of the specified name that it finds in - the symbol table, whether or not its arguments are of the correct - type. For overloaded functions that are class member functions, - GDB searches for a function whose signature _exactly_ matches the - argument types. - -`show overload-resolution' - Show the current setting of overload resolution. - -`Overloaded symbol names' - You can specify a particular definition of an overloaded symbol, - using the same notation that is used to declare such symbols in - C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also - use the GDB command-line word completion facilities to list the - available choices, or to finish the type list for you. *Note - Command Completion: Completion, for details on how to do this. - - -File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C - -15.4.1.8 Decimal Floating Point format -...................................... - -GDB can examine, set and perform computations with numbers in decimal -floating point format, which in the C language correspond to the -`_Decimal32', `_Decimal64' and `_Decimal128' types as specified by the -extension to support decimal floating-point arithmetic. - - There are two encodings in use, depending on the architecture: BID -(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed -Decimal) for PowerPC. GDB will use the appropriate encoding for the -configured target. - - Because of a limitation in `libdecnumber', the library used by GDB -to manipulate decimal floating point numbers, it is not possible to -convert (using a cast, for example) integers wider than 32-bit to -decimal float. - - In addition, in order to imitate GDB's behaviour with binary floating -point computations, error checking in decimal float operations ignores -underflow, overflow and divide by zero exceptions. - - In the PowerPC architecture, GDB provides a set of pseudo-registers -to inspect `_Decimal128' values stored in floating point registers. -See *note PowerPC: PowerPC. for more details. - - -File: gdb.info, Node: D, Next: Objective-C, Prev: C, Up: Supported Languages - -15.4.2 D --------- - -GDB can be used to debug programs written in D and compiled with GDC, -LDC or DMD compilers. Currently GDB supports only one D specific -feature -- dynamic arrays. - - -File: gdb.info, Node: Objective-C, Next: OpenCL C, Prev: D, Up: Supported Languages - -15.4.3 Objective-C ------------------- - -This section provides information about some commands and command -options that are useful for debugging Objective-C code. See also *note -info classes: Symbols, and *note info selectors: Symbols, for a few -more commands specific to Objective-C support. - -* Menu: - -* Method Names in Commands:: -* The Print Command with Objective-C:: - - -File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C - -15.4.3.1 Method Names in Commands -................................. - -The following commands have been extended to accept Objective-C method -names as line specifications: - - * `clear' - - * `break' - - * `info line' - - * `jump' - - * `list' - - A fully qualified Objective-C method name is specified as - - -[CLASS METHODNAME] - - where the minus sign is used to indicate an instance method and a -plus sign (not shown) is used to indicate a class method. The class -name CLASS and method name METHODNAME are enclosed in brackets, similar -to the way messages are specified in Objective-C source code. For -example, to set a breakpoint at the `create' instance method of class -`Fruit' in the program currently being debugged, enter: - - break -[Fruit create] - - To list ten program lines around the `initialize' class method, -enter: - - list +[NSText initialize] - - In the current version of GDB, the plus or minus sign is required. -In future versions of GDB, the plus or minus sign will be optional, but -you can use it to narrow the search. It is also possible to specify -just a method name: - - break create - - You must specify the complete method name, including any colons. If -your program's source files contain more than one `create' method, -you'll be presented with a numbered list of classes that implement that -method. Indicate your choice by number, or type `0' to exit if none -apply. - - As another example, to clear a breakpoint established at the -`makeKeyAndOrderFront:' method of the `NSWindow' class, enter: - - clear -[NSWindow makeKeyAndOrderFront:] - - -File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C - -15.4.3.2 The Print Command With Objective-C -........................................... - -The print command has also been extended to accept methods. For -example: - - print -[OBJECT hash] - -will tell GDB to send the `hash' message to OBJECT and print the -result. Also, an additional command has been added, `print-object' or -`po' for short, which is meant to print the description of an object. -However, this command may only work with certain Objective-C libraries -that have a particular hook function, `_NSPrintForDebugger', defined. - - -File: gdb.info, Node: OpenCL C, Next: Fortran, Prev: Objective-C, Up: Supported Languages - -15.4.4 OpenCL C ---------------- - -This section provides information about GDBs OpenCL C support. - -* Menu: - -* OpenCL C Datatypes:: -* OpenCL C Expressions:: -* OpenCL C Operators:: - - -File: gdb.info, Node: OpenCL C Datatypes, Next: OpenCL C Expressions, Up: OpenCL C - -15.4.4.1 OpenCL C Datatypes -........................... - -GDB supports the builtin scalar and vector datatypes specified by -OpenCL 1.1. In addition the half- and double-precision floating point -data types of the `cl_khr_fp16' and `cl_khr_fp64' OpenCL extensions are -also known to GDB. - - -File: gdb.info, Node: OpenCL C Expressions, Next: OpenCL C Operators, Prev: OpenCL C Datatypes, Up: OpenCL C - -15.4.4.2 OpenCL C Expressions -............................. - -GDB supports accesses to vector components including the access as -lvalue where possible. Since OpenCL C is based on C99 most C -expressions supported by GDB can be used as well. - - -File: gdb.info, Node: OpenCL C Operators, Prev: OpenCL C Expressions, Up: OpenCL C - -15.4.4.3 OpenCL C Operators -........................... - -GDB supports the operators specified by OpenCL 1.1 for scalar and -vector data types. - - -File: gdb.info, Node: Fortran, Next: Pascal, Prev: OpenCL C, Up: Supported Languages - -15.4.5 Fortran --------------- - -GDB can be used to debug programs written in Fortran, but it currently -supports only the features of Fortran 77 language. - - Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers -among them) append an underscore to the names of variables and -functions. When you debug programs compiled by those compilers, you -will need to refer to variables and functions with a trailing -underscore. - -* Menu: - -* Fortran Operators:: Fortran operators and expressions -* Fortran Defaults:: Default settings for Fortran -* Special Fortran Commands:: Special GDB commands for Fortran - - -File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran - -15.4.5.1 Fortran Operators and Expressions -.......................................... - -Operators must be defined on values of specific types. For instance, -`+' is defined on numbers, but not on characters or other non- -arithmetic types. Operators are often defined on groups of types. - -`**' - The exponentiation operator. It raises the first operand to the - power of the second one. - -`:' - The range operator. Normally used in the form of array(low:high) - to represent a section of array. - -`%' - The access component operator. Normally used to access elements - in derived types. Also suitable for unions. As unions aren't - part of regular Fortran, this can only happen when accessing a - register that uses a gdbarch-defined union type. - - -File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran - -15.4.5.2 Fortran Defaults -......................... - -Fortran symbols are usually case-insensitive, so GDB by default uses -case-insensitive matches for Fortran symbols. You can change that with -the `set case-insensitive' command, see *note Symbols::, for the -details. - - -File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran - -15.4.5.3 Special Fortran Commands -................................. - -GDB has some commands to support Fortran-specific features, such as -displaying common blocks. - -`info common [COMMON-NAME]' - This command prints the values contained in the Fortran `COMMON' - block whose name is COMMON-NAME. With no argument, the names of - all `COMMON' blocks visible at the current program location are - printed. - - -File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages - -15.4.6 Pascal -------------- - -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. - - The Pascal-specific command `set print pascal_static-members' -controls whether static members of Pascal objects are displayed. *Note -pascal_static-members: Print Settings. - - -File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages - -15.4.7 Modula-2 ---------------- - -The extensions made to GDB to support Modula-2 only support output from -the GNU Modula-2 compiler (which is currently being developed). Other -Modula-2 compilers are not currently supported, and attempting to debug -executables produced by them is most likely to give an error as GDB -reads in the executable's symbol table. - -* Menu: - -* M2 Operators:: Built-in operators -* Built-In Func/Proc:: Built-in functions and procedures -* M2 Constants:: Modula-2 constants -* M2 Types:: Modula-2 types -* M2 Defaults:: Default settings for Modula-2 -* Deviations:: Deviations from standard Modula-2 -* M2 Checks:: Modula-2 type and range checks -* M2 Scope:: The scope operators `::' and `.' -* GDB/M2:: GDB and Modula-2 - - -File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 - -15.4.7.1 Operators -.................. - -Operators must be defined on values of specific types. For instance, -`+' is defined on numbers, but not on structures. Operators are often -defined on groups of types. For the purposes of Modula-2, the -following definitions hold: - - * _Integral types_ consist of `INTEGER', `CARDINAL', and their - subranges. - - * _Character types_ consist of `CHAR' and its subranges. - - * _Floating-point types_ consist of `REAL'. - - * _Pointer types_ consist of anything declared as `POINTER TO TYPE'. - - * _Scalar types_ consist of all of the above. - - * _Set types_ consist of `SET' and `BITSET' types. - - * _Boolean types_ consist of `BOOLEAN'. - -The following operators are supported, and appear in order of -increasing precedence: - -`,' - Function argument or array index separator. - -`:=' - Assignment. The value of VAR `:=' VALUE is VALUE. - -`<, >' - Less than, greater than on integral, floating-point, or enumerated - types. - -`<=, >=' - Less than or equal to, greater than or equal to on integral, - floating-point and enumerated types, or set inclusion on set - types. Same precedence as `<'. - -`=, <>, #' - Equality and two ways of expressing inequality, valid on scalar - types. Same precedence as `<'. In GDB scripts, only `<>' is - available for inequality, since `#' conflicts with the script - comment character. - -`IN' - Set membership. Defined on set types and the types of their - members. Same precedence as `<'. - -`OR' - Boolean disjunction. Defined on boolean types. - -`AND, &' - Boolean conjunction. Defined on boolean types. - -`@' - The GDB "artificial array" operator (*note Expressions: - Expressions.). - -`+, -' - Addition and subtraction on integral and floating-point types, or - union and difference on set types. - -`*' - Multiplication on integral and floating-point types, or set - intersection on set types. - -`/' - Division on floating-point types, or symmetric set difference on - set types. Same precedence as `*'. - -`DIV, MOD' - Integer division and remainder. Defined on integral types. Same - precedence as `*'. - -`-' - Negative. Defined on `INTEGER' and `REAL' data. - -`^' - Pointer dereferencing. Defined on pointer types. - -`NOT' - Boolean negation. Defined on boolean types. Same precedence as - `^'. - -`.' - `RECORD' field selector. Defined on `RECORD' data. Same - precedence as `^'. - -`[]' - Array indexing. Defined on `ARRAY' data. Same precedence as `^'. - -`()' - Procedure argument list. Defined on `PROCEDURE' objects. Same - precedence as `^'. - -`::, .' - GDB and Modula-2 scope operators. - - _Warning:_ Set expressions and their operations are not yet - supported, so GDB treats the use of the operator `IN', or the use - of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>=' - on sets as an error. - - -File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 - -15.4.7.2 Built-in Functions and Procedures -.......................................... - -Modula-2 also makes available several built-in procedures and functions. -In describing these, the following metavariables are used: - -A - represents an `ARRAY' variable. - -C - represents a `CHAR' constant or variable. - -I - represents a variable or constant of integral type. - -M - represents an identifier that belongs to a set. Generally used in - the same function with the metavariable S. The type of S should - be `SET OF MTYPE' (where MTYPE is the type of M). - -N - represents a variable or constant of integral or floating-point - type. - -R - represents a variable or constant of floating-point type. - -T - represents a type. - -V - represents a variable. - -X - represents a variable or constant of one of many types. See the - explanation of the function for details. - - All Modula-2 built-in procedures also return a result, described -below. - -`ABS(N)' - Returns the absolute value of N. - -`CAP(C)' - If C is a lower case letter, it returns its upper case equivalent, - otherwise it returns its argument. - -`CHR(I)' - Returns the character whose ordinal value is I. - -`DEC(V)' - Decrements the value in the variable V by one. Returns the new - value. - -`DEC(V,I)' - Decrements the value in the variable V by I. Returns the new - value. - -`EXCL(M,S)' - Removes the element M from the set S. Returns the new set. - -`FLOAT(I)' - Returns the floating point equivalent of the integer I. - -`HIGH(A)' - Returns the index of the last member of A. - -`INC(V)' - Increments the value in the variable V by one. Returns the new - value. - -`INC(V,I)' - Increments the value in the variable V by I. Returns the new - value. - -`INCL(M,S)' - Adds the element M to the set S if it is not already there. - Returns the new set. - -`MAX(T)' - Returns the maximum value of the type T. - -`MIN(T)' - Returns the minimum value of the type T. - -`ODD(I)' - Returns boolean TRUE if I is an odd number. - -`ORD(X)' - Returns the ordinal value of its argument. For example, the - ordinal value of a character is its ASCII value (on machines - supporting the ASCII character set). X must be of an ordered - type, which include integral, character and enumerated types. - -`SIZE(X)' - Returns the size of its argument. X can be a variable or a type. - -`TRUNC(R)' - Returns the integral part of R. - -`TSIZE(X)' - Returns the size of its argument. X can be a variable or a type. - -`VAL(T,I)' - Returns the member of the type T whose ordinal value is I. - - _Warning:_ Sets and their operations are not yet supported, so - GDB treats the use of procedures `INCL' and `EXCL' as an error. - - -File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 - -15.4.7.3 Constants -.................. - -GDB allows you to express the constants of Modula-2 in the following -ways: - - * Integer constants are simply a sequence of digits. When used in an - expression, a constant is interpreted to be type-compatible with - the rest of the expression. Hexadecimal integers are specified by - a trailing `H', and octal integers by a trailing `B'. - - * Floating point constants appear as a sequence of digits, followed - by a decimal point and another sequence of digits. An optional - exponent can then be specified, in the form `E[+|-]NNN', where - `[+|-]NNN' is the desired exponent. All of the digits of the - floating point constant must be valid decimal (base 10) digits. - - * Character constants consist of a single character enclosed by a - pair of like quotes, either single (`'') or double (`"'). They may - also be expressed by their ordinal value (their ASCII value, - usually) followed by a `C'. - - * String constants consist of a sequence of characters enclosed by a - pair of like quotes, either single (`'') or double (`"'). Escape - sequences in the style of C are also allowed. *Note C and C++ - Constants: C Constants, for a brief explanation of escape - sequences. - - * Enumerated constants consist of an enumerated identifier. - - * Boolean constants consist of the identifiers `TRUE' and `FALSE'. - - * Pointer constants consist of integral values only. - - * Set constants are not yet supported. - - -File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 - -15.4.7.4 Modula-2 Types -....................... - -Currently GDB can print the following data types in Modula-2 syntax: -array types, record types, set types, pointer types, procedure types, -enumerated types, subrange types and base types. You can also print -the contents of variables declared using these type. This section -gives a number of simple source code examples together with sample GDB -sessions. - - The first example contains the following section of code: - - VAR - s: SET OF CHAR ; - r: [20..40] ; - -and you can request GDB to interrogate the type and value of `r' and -`s'. - - (gdb) print s - {'A'..'C', 'Z'} - (gdb) ptype s - SET OF CHAR - (gdb) print r - 21 - (gdb) ptype r - [20..40] - -Likewise if your source code declares `s' as: - - VAR - s: SET ['A'..'Z'] ; - -then you may query the type of `s' by: - - (gdb) ptype s - type = SET ['A'..'Z'] - -Note that at present you cannot interactively manipulate set -expressions using the debugger. - - The following example shows how you might declare an array in -Modula-2 and how you can interact with GDB to print its type and -contents: - - VAR - s: ARRAY [-10..10] OF CHAR ; - - (gdb) ptype s - ARRAY [-10..10] OF CHAR - - Note that the array handling is not yet complete and although the -type is printed correctly, expression handling still assumes that all -arrays have a lower bound of zero and not `-10' as in the example above. - - Here are some more type related Modula-2 examples: - - TYPE - colour = (blue, red, yellow, green) ; - t = [blue..yellow] ; - VAR - s: t ; - BEGIN - s := blue ; - -The GDB interaction shows how you can query the data type and value of -a variable. - - (gdb) print s - $1 = blue - (gdb) ptype t - type = [blue..yellow] - -In this example a Modula-2 array is declared and its contents -displayed. Observe that the contents are written in the same way as -their `C' counterparts. - - VAR - s: ARRAY [1..5] OF CARDINAL ; - BEGIN - s[1] := 1 ; - - (gdb) print s - $1 = {1, 0, 0, 0, 0} - (gdb) ptype s - type = ARRAY [1..5] OF CARDINAL - - The Modula-2 language interface to GDB also understands pointer -types as shown in this example: - - VAR - s: POINTER TO ARRAY [1..5] OF CARDINAL ; - BEGIN - NEW(s) ; - s^[1] := 1 ; - -and you can request that GDB describes the type of `s'. - - (gdb) ptype s - type = POINTER TO ARRAY [1..5] OF CARDINAL - - GDB handles compound types as we can see in this example. Here we -combine array types, record types, pointer types and subrange types: - - TYPE - foo = RECORD - f1: CARDINAL ; - f2: CHAR ; - f3: myarray ; - END ; - - myarray = ARRAY myrange OF CARDINAL ; - myrange = [-2..2] ; - VAR - s: POINTER TO ARRAY myrange OF foo ; - -and you can ask GDB to describe the type of `s' as shown below. - - (gdb) ptype s - type = POINTER TO ARRAY [-2..2] OF foo = RECORD - f1 : CARDINAL; - f2 : CHAR; - f3 : ARRAY [-2..2] OF CARDINAL; - END - - -File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 - -15.4.7.5 Modula-2 Defaults -.......................... - -If type and range checking are set automatically by GDB, they both -default to `on' whenever the working language changes to Modula-2. -This happens regardless of whether you or GDB selected the working -language. - - If you allow GDB to set the language automatically, then entering -code compiled from a file whose name ends with `.mod' sets the working -language to Modula-2. *Note Having GDB Infer the Source Language: -Automatically, for further details. - - -File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 - -15.4.7.6 Deviations from Standard Modula-2 -.......................................... - -A few changes have been made to make Modula-2 programs easier to debug. -This is done primarily via loosening its type strictness: - - * Unlike in standard Modula-2, pointer constants can be formed by - integers. This allows you to modify pointer variables during - debugging. (In standard Modula-2, the actual address contained in - a pointer variable is hidden from you; it can only be modified - through direct assignment to another pointer variable or - expression that returned a pointer.) - - * C escape sequences can be used in strings and characters to - represent non-printable characters. GDB prints out strings with - these escape sequences embedded. Single non-printable characters - are printed using the `CHR(NNN)' format. - - * The assignment operator (`:=') returns the value of its right-hand - argument. - - * All built-in procedures both modify _and_ return their argument. - - -File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 - -15.4.7.7 Modula-2 Type and Range Checks -....................................... - - _Warning:_ in this release, GDB does not yet perform type or range - checking. - - GDB considers two Modula-2 variables type equivalent if: - - * They are of types that have been declared equivalent via a `TYPE - T1 = T2' statement - - * They have been declared on the same line. (Note: This is true of - the GNU Modula-2 compiler, but it may not be true of other - compilers.) - - As long as type checking is enabled, any attempt to combine variables -whose types are not equivalent is an error. - - Range checking is done on all mathematical operations, assignment, -array index bounds, and all built-in functions and procedures. - - -File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 - -15.4.7.8 The Scope Operators `::' and `.' -......................................... - -There are a few subtle differences between the Modula-2 scope operator -(`.') and the GDB scope operator (`::'). The two have similar syntax: - - - MODULE . ID - SCOPE :: ID - -where SCOPE is the name of a module or a procedure, MODULE the name of -a module, and ID is any declared identifier within your program, except -another module. - - Using the `::' operator makes GDB search the scope specified by -SCOPE for the identifier ID. If it is not found in the specified -scope, then GDB searches all scopes enclosing the one specified by -SCOPE. - - Using the `.' operator makes GDB search the current scope for the -identifier specified by ID that was imported from the definition module -specified by MODULE. With this operator, it is an error if the -identifier ID was not imported from definition module MODULE, or if ID -is not an identifier in MODULE. - - -File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 - -15.4.7.9 GDB and Modula-2 -......................... - -Some GDB commands have little use when debugging Modula-2 programs. -Five subcommands of `set print' and `show print' apply specifically to -C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. -The first four apply to C++, and the last to the C `union' type, which -has no direct analogue in Modula-2. - - The `@' operator (*note Expressions: Expressions.), while available -with any language, is not useful with Modula-2. Its intent is to aid -the debugging of "dynamic arrays", which cannot be created in Modula-2 -as they can in C or C++. However, because an address can be specified -by an integral constant, the construct `{TYPE}ADREXP' is still useful. - - In GDB scripts, the Modula-2 inequality operator `#' is interpreted -as the beginning of a comment. Use `<>' instead. - - -File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages - -15.4.8 Ada ----------- - -The extensions made to GDB for Ada only support output from the GNU Ada -(GNAT) compiler. Other Ada compilers are not currently supported, and -attempting to debug executables produced by them is most likely to be -difficult. - -* Menu: - -* Ada Mode Intro:: General remarks on the Ada syntax - and semantics supported by Ada mode - in GDB. -* Omissions from Ada:: Restrictions on the Ada expression syntax. -* Additions to Ada:: Extensions of the Ada expression syntax. -* Stopping Before Main Program:: Debugging the program during elaboration. -* Ada Tasks:: Listing and setting breakpoints in tasks. -* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files -* Ravenscar Profile:: Tasking Support when using the Ravenscar - Profile -* Ada Glitches:: Known peculiarities of Ada mode. - - -File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada - -15.4.8.1 Introduction -..................... - -The Ada mode of GDB supports a fairly large subset of Ada expression -syntax, with some extensions. The philosophy behind the design of this -subset is - - * That GDB should provide basic literals and access to operations for - arithmetic, dereferencing, field selection, indexing, and - subprogram calls, leaving more sophisticated computations to - subprograms written into the program (which therefore may be - called from GDB). - - * That type safety and strict adherence to Ada language restrictions - are not particularly important to the GDB user. - - * That brevity is important to the GDB user. - - Thus, for brevity, the debugger acts as if all names declared in -user-written packages are directly visible, even if they are not visible -according to Ada rules, thus making it unnecessary to fully qualify most -names with their packages, regardless of context. Where this causes -ambiguity, GDB asks the user's intent. - - The debugger will start in Ada mode if it detects an Ada main -program. As for other languages, it will enter Ada mode when stopped -in a program that was translated from an Ada source file. - - While in Ada mode, you may use `-' for comments. This is useful -mostly for documenting command files. The standard GDB comment (`#') -still works at the beginning of a line in Ada mode, but not in the -middle (to allow based literals). - - The debugger supports limited overloading. Given a subprogram call -in which the function symbol has multiple definitions, it will use the -number of actual parameters and some information about their types to -attempt to narrow the set of definitions. It also makes very limited -use of context, preferring procedures to functions in the context of -the `call' command, and functions to procedures elsewhere. - - -File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada - -15.4.8.2 Omissions from Ada -........................... - -Here are the notable omissions from the subset: - - * Only a subset of the attributes are supported: - - - 'First, 'Last, and 'Length on array objects (not on types - and subtypes). - - - 'Min and 'Max. - - - 'Pos and 'Val. - - - 'Tag. - - - 'Range on array objects (not subtypes), but only as the right - operand of the membership (`in') operator. - - - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT - extension). - - - 'Address. - - * The names in `Characters.Latin_1' are not available and - concatenation is not implemented. Thus, escape characters in - strings are not currently available. - - * Equality tests (`=' and `/=') on arrays test for bitwise equality - of representations. They will generally work correctly for - strings and arrays whose elements have integer or enumeration - types. They may not work correctly for arrays whose element types - have user-defined equality, for arrays of real values (in - particular, IEEE-conformant floating point, because of negative - zeroes and NaNs), and for arrays whose elements contain unused - bits with indeterminate values. - - * The other component-by-component array operations (`and', `or', - `xor', `not', and relational tests other than equality) are not - implemented. - - * There is limited support for array and record aggregates. They are - permitted only on the right sides of assignments, as in these - examples: - - (gdb) set An_Array := (1, 2, 3, 4, 5, 6) - (gdb) set An_Array := (1, others => 0) - (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) - (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) - (gdb) set A_Record := (1, "Peter", True); - (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) - - Changing a discriminant's value by assigning an aggregate has an - undefined effect if that discriminant is used within the record. - However, you can first modify discriminants by directly assigning - to them (which normally would not be allowed in Ada), and then - performing an aggregate assignment. For example, given a variable - `A_Rec' declared to have a type such as: - - type Rec (Len : Small_Integer := 0) is record - Id : Integer; - Vals : IntArray (1 .. Len); - end record; - - you can assign a value with a different size of `Vals' with two - assignments: - - (gdb) set A_Rec.Len := 4 - (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) - - As this example also illustrates, GDB is very loose about the usual - rules concerning aggregates. You may leave out some of the - components of an array or record aggregate (such as the `Len' - component in the assignment to `A_Rec' above); they will retain - their original values upon assignment. You may freely use dynamic - values as indices in component associations. You may even use - overlapping or redundant component associations, although which - component values are assigned in such cases is not defined. - - * Calls to dispatching subprograms are not implemented. - - * The overloading algorithm is much more limited (i.e., less - selective) than that of real Ada. It makes only limited use of - the context in which a subexpression appears to resolve its - meaning, and it is much looser in its rules for allowing type - matches. As a result, some function calls will be ambiguous, and - the user will be asked to choose the proper resolution. - - * The `new' operator is not implemented. - - * Entry calls are not implemented. - - * Aside from printing, arithmetic operations on the native VAX - floating-point formats are not supported. - - * It is not possible to slice a packed array. - - * The names `True' and `False', when not part of a qualified name, - are interpreted as if implicitly prefixed by `Standard', - regardless of context. Should your program redefine these names - in a package or procedure (at best a dubious practice), you will - have to use fully qualified names to access their new definitions. - - -File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada - -15.4.8.3 Additions to Ada -......................... - -As it does for other languages, GDB makes certain generic extensions to -Ada (*note Expressions::): - - * If the expression E is a variable residing in memory (typically a - local variable or array element) and N is a positive integer, then - `E@N' displays the values of E and the N-1 adjacent variables - following it in memory as an array. In Ada, this operator is - generally not necessary, since its prime use is in displaying - parts of an array, and slicing will usually do this in Ada. - However, there are occasional uses when debugging programs in - which certain debugging information has been optimized away. - - * `B::VAR' means "the variable named VAR that appears in function or - file B." When B is a file name, you must typically surround it in - single quotes. - - * The expression `{TYPE} ADDR' means "the variable of type TYPE that - appears at address ADDR." - - * A name starting with `$' is a convenience variable (*note - Convenience Vars::) or a machine register (*note Registers::). - - In addition, GDB provides a few other shortcuts and outright -additions specific to Ada: - - * The assignment statement is allowed as an expression, returning - its right-hand operand as its value. Thus, you may enter - - (gdb) set x := y + 3 - (gdb) print A(tmp := y + 1) - - * The semicolon is allowed as an "operator," returning as its value - the value of its right-hand operand. This allows, for example, - complex conditional breaks: - - (gdb) break f - (gdb) condition 1 (report(i); k += 1; A(k) > 100) - - * Rather than use catenation and symbolic character names to - introduce special characters into strings, one may instead use a - special bracket notation, which is also used to print strings. A - sequence of characters of the form `["XX"]' within a string or - character literal denotes the (single) character whose numeric - encoding is XX in hexadecimal. The sequence of characters `["""]' - also denotes a single quotation mark in strings. For example, - "One line.["0a"]Next line.["0a"]" - contains an ASCII newline character (`Ada.Characters.Latin_1.LF') - after each period. - - * The subtype used as a prefix for the attributes 'Pos, 'Min, and - 'Max is optional (and is ignored in any case). For example, it is - valid to write - - (gdb) print 'max(x, y) - - * When printing arrays, GDB uses positional notation when the array - has a lower bound of 1, and uses a modified named notation - otherwise. For example, a one-dimensional array of three integers - with a lower bound of 3 might print as - - (3 => 10, 17, 1) - - That is, in contrast to valid Ada, only the first component has a - `=>' clause. - - * You may abbreviate attributes in expressions with any unique, - multi-character subsequence of their names (an exact match gets - preference). For example, you may use a'len, a'gth, or a'lh in - place of a'length. - - * Since Ada is case-insensitive, the debugger normally maps - identifiers you type to lower case. The GNAT compiler uses - upper-case characters for some of its internal identifiers, which - are normally of no interest to users. For the rare occasions when - you actually have to look at them, enclose them in angle brackets - to avoid the lower-case mapping. For example, - (gdb) print <JMPBUF_SAVE>[0] - - * Printing an object of class-wide type or dereferencing an - access-to-class-wide value will display all the components of the - object's specific type (as indicated by its run-time tag). - Likewise, component selection on such a value will operate on the - specific type of the object. - - - -File: gdb.info, Node: Stopping Before Main Program, Next: Ada Tasks, Prev: Additions to Ada, Up: Ada - -15.4.8.4 Stopping at the Very Beginning -....................................... - -It is sometimes necessary to debug the program during elaboration, and -before reaching the main procedure. As defined in the Ada Reference -Manual, the elaboration code is invoked from a procedure called -`adainit'. To run your program up to the beginning of elaboration, -simply use the following two commands: `tbreak adainit' and `run'. - - -File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Stopping Before Main Program, Up: Ada - -15.4.8.5 Extensions for Ada Tasks -................................. - -Support for Ada tasks is analogous to that for threads (*note -Threads::). GDB provides the following task-related commands: - -`info tasks' - This command shows a list of current Ada tasks, as in the - following example: - - (gdb) info tasks - ID TID P-ID Pri State Name - 1 8088000 0 15 Child Activation Wait main_task - 2 80a4000 1 15 Accept Statement b - 3 809a800 1 15 Child Activation Wait a - * 4 80ae800 3 15 Runnable c - - In this listing, the asterisk before the last task indicates it to - be the task currently being inspected. - - ID - Represents GDB's internal task number. - - TID - The Ada task ID. - - P-ID - The parent's task ID (GDB's internal task number). - - Pri - The base priority of the task. - - State - Current state of the task. - - `Unactivated' - The task has been created but has not been activated. - It cannot be executing. - - `Runnable' - The task is not blocked for any reason known to Ada. - (It may be waiting for a mutex, though.) It is - conceptually "executing" in normal mode. - - `Terminated' - The task is terminated, in the sense of ARM 9.3 (5). - Any dependents that were waiting on terminate - alternatives have been awakened and have terminated - themselves. - - `Child Activation Wait' - The task is waiting for created tasks to complete - activation. - - `Accept Statement' - The task is waiting on an accept or selective wait - statement. - - `Waiting on entry call' - The task is waiting on an entry call. - - `Async Select Wait' - The task is waiting to start the abortable part of an - asynchronous select statement. - - `Delay Sleep' - The task is waiting on a select statement with only a - delay alternative open. - - `Child Termination Wait' - The task is sleeping having completed a master within - itself, and is waiting for the tasks dependent on that - master to become terminated or waiting on a terminate - Phase. - - `Wait Child in Term Alt' - The task is sleeping waiting for tasks on terminate - alternatives to finish terminating. - - `Accepting RV with TASKNO' - The task is accepting a rendez-vous with the task TASKNO. - - Name - Name of the task in the program. - - -`info task TASKNO' - This command shows detailled informations on the specified task, - as in the following example: - (gdb) info tasks - ID TID P-ID Pri State Name - 1 8077880 0 15 Child Activation Wait main_task - * 2 807c468 1 15 Runnable task_1 - (gdb) info task 2 - Ada Task: 0x807c468 - Name: task_1 - Thread: 0x807f378 - Parent: 1 (main_task) - Base Priority: 15 - State: Runnable - -`task' - This command prints the ID of the current task. - - (gdb) info tasks - ID TID P-ID Pri State Name - 1 8077870 0 15 Child Activation Wait main_task - * 2 807c458 1 15 Runnable t - (gdb) task - [Current task is 2] - -`task TASKNO' - This command is like the `thread THREADNO' command (*note - Threads::). It switches the context of debugging from the current - task to the given task. - - (gdb) info tasks - ID TID P-ID Pri State Name - 1 8077870 0 15 Child Activation Wait main_task - * 2 807c458 1 15 Runnable t - (gdb) task 1 - [Switching to task 1] - #0 0x8067726 in pthread_cond_wait () - (gdb) bt - #0 0x8067726 in pthread_cond_wait () - #1 0x8056714 in system.os_interface.pthread_cond_wait () - #2 0x805cb63 in system.task_primitives.operations.sleep () - #3 0x806153e in system.tasking.stages.activate_tasks () - #4 0x804aacc in un () at un.adb:5 - -`break LINESPEC task TASKNO' -`break LINESPEC task TASKNO if ...' - These commands are like the `break ... thread ...' command (*note - Thread Stops::). LINESPEC specifies source lines, as described in - *note Specify Location::. - - Use the qualifier `task TASKNO' with a breakpoint command to - specify that you only want GDB to stop the program when a - particular Ada task reaches this breakpoint. TASKNO is one of the - numeric task identifiers assigned by GDB, shown in the first - column of the `info tasks' display. - - If you do not specify `task TASKNO' when you set a breakpoint, the - breakpoint applies to _all_ tasks of your program. - - You can use the `task' qualifier on conditional breakpoints as - well; in this case, place `task TASKNO' before the breakpoint - condition (before the `if'). - - For example, - - (gdb) info tasks - ID TID P-ID Pri State Name - 1 140022020 0 15 Child Activation Wait main_task - 2 140045060 1 15 Accept/Select Wait t2 - 3 140044840 1 15 Runnable t1 - * 4 140056040 1 15 Runnable t3 - (gdb) b 15 task 2 - Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. - (gdb) cont - Continuing. - task # 1 running - task # 2 running - - Breakpoint 5, test_task_debug () at test_task_debug.adb:15 - 15 flush; - (gdb) info tasks - ID TID P-ID Pri State Name - 1 140022020 0 15 Child Activation Wait main_task - * 2 140045060 1 15 Runnable t2 - 3 140044840 1 15 Runnable t1 - 4 140056040 1 15 Delay Sleep t3 - - -File: gdb.info, Node: Ada Tasks and Core Files, Next: Ravenscar Profile, Prev: Ada Tasks, Up: Ada - -15.4.8.6 Tasking Support when Debugging Core Files -.................................................. - -When inspecting a core file, as opposed to debugging a live program, -tasking support may be limited or even unavailable, depending on the -platform being used. For instance, on x86-linux, the list of tasks is -available, but task switching is not supported. On Tru64, however, -task switching will work as usual. - - On certain platforms, including Tru64, the debugger needs to perform -some memory writes in order to provide Ada tasking support. When -inspecting a core file, this means that the core file must be opened -with read-write privileges, using the command `"set write on"' (*note -Patching::). Under these circumstances, you should make a backup copy -of the core file before inspecting it with GDB. - - -File: gdb.info, Node: Ravenscar Profile, Next: Ada Glitches, Prev: Ada Tasks and Core Files, Up: Ada - -15.4.8.7 Tasking Support when using the Ravenscar Profile -......................................................... - -The "Ravenscar Profile" is a subset of the Ada tasking features, -specifically designed for systems with safety-critical real-time -requirements. - -`set ravenscar task-switching on' - Allows task switching when debugging a program that uses the - Ravenscar Profile. This is the default. - -`set ravenscar task-switching off' - Turn off task switching when debugging a program that uses the - Ravenscar Profile. This is mostly intended to disable the code - that adds support for the Ravenscar Profile, in case a bug in - either GDB or in the Ravenscar runtime is preventing GDB from - working properly. To be effective, this command should be run - before the program is started. - -`show ravenscar task-switching' - Show whether it is possible to switch from task to task in a - program using the Ravenscar Profile. - - - -File: gdb.info, Node: Ada Glitches, Prev: Ravenscar Profile, Up: Ada - -15.4.8.8 Known Peculiarities of Ada Mode -........................................ - -Besides the omissions listed previously (*note Omissions from Ada::), -we know of several problems with and limitations of Ada mode in GDB, -some of which will be fixed with planned future releases of the debugger -and the GNU Ada compiler. - - * Static constants that the compiler chooses not to materialize as - objects in storage are invisible to the debugger. - - * Named parameter associations in function argument lists are - ignored (the argument lists are treated as positional). - - * Many useful library packages are currently invisible to the - debugger. - - * Fixed-point arithmetic, conversions, input, and output is carried - out using floating-point arithmetic, and may give results that - only approximate those on the host machine. - - * The GNAT compiler never generates the prefix `Standard' for any of - the standard symbols defined by the Ada language. GDB knows about - this: it will strip the prefix from names when you use it, and - will never look for a name you have so qualified among local - symbols, nor match against symbols in other packages or - subprograms. If you have defined entities anywhere in your - program other than parameters and local variables whose simple - names match names in `Standard', GNAT's lack of qualification here - can cause confusion. When this happens, you can usually resolve - the confusion by qualifying the problematic names with package - `Standard' explicitly. - - Older versions of the compiler sometimes generate erroneous debugging -information, resulting in the debugger incorrectly printing the value -of affected entities. In some cases, the debugger is able to work -around an issue automatically. In other cases, the debugger is able to -work around the issue, but the work-around has to be specifically -enabled. - -`set ada trust-PAD-over-XVS on' - Configure GDB to strictly follow the GNAT encoding when computing - the value of Ada entities, particularly when `PAD' and `PAD___XVS' - types are involved (see `ada/exp_dbug.ads' in the GCC sources for - a complete description of the encoding used by the GNAT compiler). - This is the default. - -`set ada trust-PAD-over-XVS off' - This is related to the encoding using by the GNAT compiler. If - GDB sometimes prints the wrong value for certain entities, - changing `ada trust-PAD-over-XVS' to `off' activates a work-around - which may fix the issue. It is always safe to set `ada - trust-PAD-over-XVS' to `off', but this incurs a slight performance - penalty, so it is recommended to leave this setting to `on' unless - necessary. - - - -File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages - -15.5 Unsupported Languages -========================== - -In addition to the other fully-supported programming languages, GDB -also provides a pseudo-language, called `minimal'. It does not -represent a real programming language, but provides a set of -capabilities close to what the C or assembly languages provide. This -should allow most simple operations to be performed while debugging an -application that uses a language currently not supported by GDB. - - If the language is set to `auto', GDB will automatically select this -language if the current frame corresponds to an unsupported language. - - -File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top - -16 Examining the Symbol Table -***************************** - -The commands described in this chapter allow you to inquire about the -symbols (names of variables, functions and types) defined in your -program. This information is inherent in the text of your program and -does not change as your program executes. GDB finds it in your -program's symbol table, in the file indicated when you started GDB -(*note Choosing Files: File Options.), or by one of the file-management -commands (*note Commands to Specify Files: Files.). - - Occasionally, you may need to refer to symbols that contain unusual -characters, which GDB ordinarily treats as word delimiters. The most -frequent case is in referring to static variables in other source files -(*note Program Variables: Variables.). File names are recorded in -object files as debugging symbols, but GDB would ordinarily parse a -typical file name, like `foo.c', as the three words `foo' `.' `c'. To -allow GDB to recognize `foo.c' as a single symbol, enclose it in single -quotes; for example, - - p 'foo.c'::x - -looks up the value of `x' in the scope of the file `foo.c'. - -`set case-sensitive on' -`set case-sensitive off' -`set case-sensitive auto' - Normally, when GDB looks up symbols, it matches their names with - case sensitivity determined by the current source language. - Occasionally, you may wish to control that. The command `set - case-sensitive' lets you do that by specifying `on' for - case-sensitive matches or `off' for case-insensitive ones. If you - specify `auto', case sensitivity is reset to the default suitable - for the source language. The default is case-sensitive matches - for all languages except for Fortran, for which the default is - case-insensitive matches. - -`show case-sensitive' - This command shows the current setting of case sensitivity for - symbols lookups. - -`info address SYMBOL' - Describe where the data for SYMBOL is stored. For a register - variable, this says which register it is kept in. For a - non-register local variable, this prints the stack-frame offset at - which the variable is always stored. - - Note the contrast with `print &SYMBOL', which does not work at all - for a register variable, and for a stack local variable prints the - exact address of the current instantiation of the variable. - -`info symbol ADDR' - Print the name of a symbol which is stored at the address ADDR. - If no symbol is stored exactly at ADDR, GDB prints the nearest - symbol and an offset from it: - - (gdb) info symbol 0x54320 - _initialize_vx + 396 in section .text - - This is the opposite of the `info address' command. You can use - it to find out the name of a variable or a function given its - address. - - For dynamically linked executables, the name of executable or - shared library containing the symbol is also printed: - - (gdb) info symbol 0x400225 - _start + 5 in section .text of /tmp/a.out - (gdb) info symbol 0x2aaaac2811cf - __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 - -`whatis [ARG]' - Print the data type of ARG, which can be either an expression or a - data type. With no argument, print the data type of `$', the last - value in the value history. If ARG is an expression, it is not - actually evaluated, and any side-effecting operations (such as - assignments or function calls) inside it do not take place. If - ARG is a type name, it may be the name of a type or typedef, or - for C code it may have the form `class CLASS-NAME', `struct - STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'. *Note - Expressions: Expressions. - -`ptype [ARG]' - `ptype' accepts the same arguments as `whatis', but prints a - detailed description of the type, instead of just the name of the - type. *Note Expressions: Expressions. - - For example, for this variable declaration: - - struct complex {double real; double imag;} v; - - the two commands give this output: - - (gdb) whatis v - type = struct complex - (gdb) ptype v - type = struct complex { - double real; - double imag; - } - - As with `whatis', using `ptype' without an argument refers to the - type of `$', the last value in the value history. - - Sometimes, programs use opaque data types or incomplete - specifications of complex data structure. If the debug - information included in the program does not allow GDB to display - a full declaration of the data type, it will say `<incomplete - type>'. For example, given these declarations: - - struct foo; - struct foo *fooptr; - - but no definition for `struct foo' itself, GDB will say: - - (gdb) ptype foo - $1 = <incomplete type> - - "Incomplete type" is C terminology for data types that are not - completely specified. - -`info types REGEXP' -`info types' - Print a brief description of all types whose names match the - regular expression REGEXP (or all types in your program, if you - supply no argument). Each complete typename is matched as though - it were a complete line; thus, `i type value' gives information on - all types in your program whose names include the string `value', - but `i type ^value$' gives information only on types whose complete - name is `value'. - - This command differs from `ptype' in two ways: first, like - `whatis', it does not print a detailed description; second, it - lists all source files where a type is defined. - -`info scope LOCATION' - List all the variables local to a particular scope. This command - accepts a LOCATION argument--a function name, a source line, or an - address preceded by a `*', and prints all the variables local to - the scope defined by that location. (*Note Specify Location::, for - details about supported forms of LOCATION.) For example: - - (gdb) info scope command_line_handler - Scope for command_line_handler: - Symbol rl is an argument at stack/frame offset 8, length 4. - Symbol linebuffer is in static storage at address 0x150a18, length 4. - Symbol linelength is in static storage at address 0x150a1c, length 4. - Symbol p is a local variable in register $esi, length 4. - Symbol p1 is a local variable in register $ebx, length 4. - Symbol nline is a local variable in register $edx, length 4. - Symbol repeat is a local variable at frame offset -8, length 4. - - This command is especially useful for determining what data to - collect during a "trace experiment", see *note collect: Tracepoint - Actions. - -`info source' - Show information about the current source file--that is, the - source file for the function containing the current point of - execution: - * the name of the source file, and the directory containing it, - - * the directory it was compiled in, - - * its length, in lines, - - * which programming language it is written in, - - * whether the executable includes debugging information for - that file, and if so, what format the information is in - (e.g., STABS, Dwarf 2, etc.), and - - * whether the debugging information includes information about - preprocessor macros. - -`info sources' - Print the names of all source files in your program for which - there is debugging information, organized into two lists: files - whose symbols have already been read, and files whose symbols will - be read when needed. - -`info functions' - Print the names and data types of all defined functions. - -`info functions REGEXP' - Print the names and data types of all defined functions whose - names contain a match for regular expression REGEXP. Thus, `info - fun step' finds all functions whose names include `step'; `info - fun ^step' finds those whose names start with `step'. If a - function name contains characters that conflict with the regular - expression language (e.g. `operator*()'), they may be quoted with - a backslash. - -`info variables' - Print the names and data types of all variables that are defined - outside of functions (i.e. excluding local variables). - -`info variables REGEXP' - Print the names and data types of all variables (except for local - variables) whose names contain a match for regular expression - REGEXP. - -`info classes' -`info classes REGEXP' - Display all Objective-C classes in your program, or (with the - REGEXP argument) all those matching a particular regular - expression. - -`info selectors' -`info selectors REGEXP' - Display all Objective-C selectors in your program, or (with the - REGEXP argument) all those matching a particular regular - expression. - - Some systems allow individual object files that make up your - program to be replaced without stopping and restarting your - program. For example, in VxWorks you can simply recompile a - defective object file and keep on running. If you are running on - one of these systems, you can allow GDB to reload the symbols for - automatically relinked modules: - - `set symbol-reloading on' - Replace symbol definitions for the corresponding source file - when an object file with a particular name is seen again. - - `set symbol-reloading off' - Do not replace symbol definitions when encountering object - files of the same name more than once. This is the default - state; if you are not running on a system that permits - automatic relinking of modules, you should leave - `symbol-reloading' off, since otherwise GDB may discard - symbols when linking large programs, that may contain several - modules (from different directories or libraries) with the - same name. - - `show symbol-reloading' - Show the current `on' or `off' setting. - -`set opaque-type-resolution on' - Tell GDB to resolve opaque types. An opaque type is a type - declared as a pointer to a `struct', `class', or `union'--for - example, `struct MyType *'--that is used in one source file - although the full declaration of `struct MyType' is in another - source file. The default is on. - - A change in the setting of this subcommand will not take effect - until the next time symbols for a file are loaded. - -`set opaque-type-resolution off' - Tell GDB not to resolve opaque types. In this case, the type is - printed as follows: - {<no data fields>} - -`show opaque-type-resolution' - Show whether opaque types are resolved or not. - -`set print symbol-loading' -`set print symbol-loading on' -`set print symbol-loading off' - The `set print symbol-loading' command allows you to enable or - disable printing of messages when GDB loads symbols. By default, - these messages will be printed, and normally this is what you - want. Disabling these messages is useful when debugging - applications with lots of shared libraries where the quantity of - output can be more annoying than useful. - -`show print symbol-loading' - Show whether messages will be printed when GDB loads symbols. - -`maint print symbols FILENAME' -`maint print psymbols FILENAME' -`maint print msymbols FILENAME' - Write a dump of debugging symbol data into the file FILENAME. - These commands are used to debug the GDB symbol-reading code. Only - symbols with debugging data are included. If you use `maint print - symbols', GDB includes all the symbols for which it has already - collected full details: that is, FILENAME reflects symbols for - only those files whose symbols GDB has read. You can use the - command `info sources' to find out which files these are. If you - use `maint print psymbols' instead, the dump shows information - about symbols that GDB only knows partially--that is, symbols - defined in files that GDB has skimmed, but not yet read - completely. Finally, `maint print msymbols' dumps just the - minimal symbol information required for each object file from - which GDB has read some symbols. *Note Commands to Specify Files: - Files, for a discussion of how GDB reads symbols (in the - description of `symbol-file'). - -`maint info symtabs [ REGEXP ]' -`maint info psymtabs [ REGEXP ]' - List the `struct symtab' or `struct partial_symtab' structures - whose names match REGEXP. If REGEXP is not given, list them all. - The output includes expressions which you can copy into a GDB - debugging this one to examine a particular structure in more - detail. For example: - - (gdb) maint info psymtabs dwarf2read - { objfile /home/gnu/build/gdb/gdb - ((struct objfile *) 0x82e69d0) - { psymtab /home/gnu/src/gdb/dwarf2read.c - ((struct partial_symtab *) 0x8474b10) - readin no - fullname (null) - text addresses 0x814d3c8 -- 0x8158074 - globals (* (struct partial_symbol **) 0x8507a08 @ 9) - statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) - dependencies (none) - } - } - (gdb) maint info symtabs - (gdb) - We see that there is one partial symbol table whose filename - contains the string `dwarf2read', belonging to the `gdb' - executable; and we see that GDB has not read in any symtabs yet at - all. If we set a breakpoint on a function, that will cause GDB to - read the symtab for the compilation unit containing that function: - - (gdb) break dwarf2_psymtab_to_symtab - Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, - line 1574. - (gdb) maint info symtabs - { objfile /home/gnu/build/gdb/gdb - ((struct objfile *) 0x82e69d0) - { symtab /home/gnu/src/gdb/dwarf2read.c - ((struct symtab *) 0x86c1f38) - dirname (null) - fullname (null) - blockvector ((struct blockvector *) 0x86c1bd0) (primary) - linetable ((struct linetable *) 0x8370fa0) - debugformat DWARF 2 - } - } - (gdb) - - -File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top - -17 Altering Execution -********************* - -Once you think you have found an error in your program, you might want -to find out for certain whether correcting the apparent error would -lead to correct results in the rest of the run. You can find the -answer by experiment, using the GDB features for altering execution of -the program. - - For example, you can store new values into variables or memory -locations, give your program a signal, restart it at a different -address, or even return prematurely from a function. - -* Menu: - -* Assignment:: Assignment to variables -* Jumping:: Continuing at a different address -* Signaling:: Giving your program a signal -* Returning:: Returning from a function -* Calling:: Calling your program's functions -* Patching:: Patching your program - - -File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering - -17.1 Assignment to Variables -============================ - -To alter the value of a variable, evaluate an assignment expression. -*Note Expressions: Expressions. For example, - - print x=4 - -stores the value 4 into the variable `x', and then prints the value of -the assignment expression (which is 4). *Note Using GDB with Different -Languages: Languages, for more information on operators in supported -languages. - - If you are not interested in seeing the value of the assignment, use -the `set' command instead of the `print' command. `set' is really the -same as `print' except that the expression's value is not printed and -is not put in the value history (*note Value History: Value History.). -The expression is evaluated only for its effects. - - If the beginning of the argument string of the `set' command appears -identical to a `set' subcommand, use the `set variable' command instead -of just `set'. This command is identical to `set' except for its lack -of subcommands. For example, if your program has a variable `width', -you get an error if you try to set a new value with just `set -width=13', because GDB has the command `set width': - - (gdb) whatis width - type = double - (gdb) p width - $4 = 13 - (gdb) set width=47 - Invalid syntax in expression. - -The invalid expression, of course, is `=47'. In order to actually set -the program's variable `width', use - - (gdb) set var width=47 - - Because the `set' command has many subcommands that can conflict -with the names of program variables, it is a good idea to use the `set -variable' command instead of just `set'. For example, if your program -has a variable `g', you run into problems if you try to set a new value -with just `set g=4', because GDB has the command `set gnutarget', -abbreviated `set g': - - (gdb) whatis g - type = double - (gdb) p g - $1 = 1 - (gdb) set g=4 - (gdb) p g - $2 = 1 - (gdb) r - The program being debugged has been started already. - Start it from the beginning? (y or n) y - Starting program: /home/smith/cc_progs/a.out - "/home/smith/cc_progs/a.out": can't open to read symbols: - Invalid bfd target. - (gdb) show g - The current BFD target is "=4". - -The program variable `g' did not change, and you silently set the -`gnutarget' to an invalid value. In order to set the variable `g', use - - (gdb) set var g=4 - - GDB allows more implicit conversions in assignments than C; you can -freely store an integer value into a pointer variable or vice versa, -and you can convert any structure to any other structure that is the -same length or shorter. - - To store values into arbitrary places in memory, use the `{...}' -construct to generate a value of specified type at a specified address -(*note Expressions: Expressions.). For example, `{int}0x83040' refers -to memory location `0x83040' as an integer (which implies a certain size -and representation in memory), and - - set {int}0x83040 = 4 - -stores the value 4 into that memory location. - - -File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering - -17.2 Continuing at a Different Address -====================================== - -Ordinarily, when you continue your program, you do so at the place where -it stopped, with the `continue' command. You can instead continue at -an address of your own choosing, with the following commands: - -`jump LINESPEC' -`jump LOCATION' - Resume execution at line LINESPEC or at address given by LOCATION. - Execution stops again immediately if there is a breakpoint there. - *Note Specify Location::, for a description of the different forms - of LINESPEC and LOCATION. It is common practice to use the - `tbreak' command in conjunction with `jump'. *Note Setting - Breakpoints: Set Breaks. - - The `jump' command does not change the current stack frame, or the - stack pointer, or the contents of any memory location or any - register other than the program counter. If line LINESPEC is in a - different function from the one currently executing, the results - may be bizarre if the two functions expect different patterns of - arguments or of local variables. For this reason, the `jump' - command requests confirmation if the specified line is not in the - function currently executing. However, even bizarre results are - predictable if you are well acquainted with the machine-language - code of your program. - - On many systems, you can get much the same effect as the `jump' -command by storing a new value into the register `$pc'. The difference -is that this does not start your program running; it only changes the -address of where it _will_ run when you continue. For example, - - set $pc = 0x485 - -makes the next `continue' command or stepping command execute at -address `0x485', rather than at the address where your program stopped. -*Note Continuing and Stepping: Continuing and Stepping. - - The most common occasion to use the `jump' command is to back -up--perhaps with more breakpoints set--over a portion of a program that -has already executed, in order to examine its execution in more detail. - - -File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering - -17.3 Giving your Program a Signal -================================= - -`signal SIGNAL' - Resume execution where your program stopped, but immediately give - it the signal SIGNAL. SIGNAL can be the name or the number of a - signal. For example, on many systems `signal 2' and `signal - SIGINT' are both ways of sending an interrupt signal. - - Alternatively, if SIGNAL is zero, continue execution without - giving a signal. This is useful when your program stopped on - account of a signal and would ordinary see the signal when resumed - with the `continue' command; `signal 0' causes it to resume - without a signal. - - `signal' does not repeat when you press <RET> a second time after - executing the command. - - Invoking the `signal' command is not the same as invoking the `kill' -utility from the shell. Sending a signal with `kill' causes GDB to -decide what to do with the signal depending on the signal handling -tables (*note Signals::). The `signal' command passes the signal -directly to your program. - - -File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering - -17.4 Returning from a Function -============================== - -`return' -`return EXPRESSION' - You can cancel execution of a function call with the `return' - command. If you give an EXPRESSION argument, its value is used as - the function's return value. - - When you use `return', GDB discards the selected stack frame (and -all frames within it). You can think of this as making the discarded -frame return prematurely. If you wish to specify a value to be -returned, give that value as the argument to `return'. - - This pops the selected stack frame (*note Selecting a Frame: -Selection.), and any other frames inside of it, leaving its caller as -the innermost remaining frame. That frame becomes selected. The -specified value is stored in the registers used for returning values of -functions. - - The `return' command does not resume execution; it leaves the -program stopped in the state that would exist if the function had just -returned. In contrast, the `finish' command (*note Continuing and -Stepping: Continuing and Stepping.) resumes execution until the -selected stack frame returns naturally. - - GDB needs to know how the EXPRESSION argument should be set for the -inferior. The concrete registers assignment depends on the OS ABI and -the type being returned by the selected stack frame. For example it is -common for OS ABI to return floating point values in FPU registers -while integer values in CPU registers. Still some ABIs return even -floating point values in CPU registers. Larger integer widths (such as -`long long int') also have specific placement rules. GDB already knows -the OS ABI from its current target so it needs to find out also the -type being returned to make the assignment into the right register(s). - - Normally, the selected stack frame has debug info. GDB will always -use the debug info instead of the implicit type of EXPRESSION when the -debug info is available. For example, if you type `return -1', and the -function in the current stack frame is declared to return a `long long -int', GDB transparently converts the implicit `int' value of -1 into a -`long long int': - - Breakpoint 1, func () at gdb.base/return-nodebug.c:29 - 29 return 31; - (gdb) return -1 - Make func return now? (y or n) y - #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 - 43 printf ("result=%lld\n", func ()); - (gdb) - - However, if the selected stack frame does not have a debug info, -e.g., if the function was compiled without debug info, GDB has to find -out the type to return from user. Specifying a different type by -mistake may set the value in different inferior registers than the -caller code expects. For example, typing `return -1' with its implicit -type `int' would set only a part of a `long long int' result for a -debug info less function (on 32-bit architectures). Therefore the user -is required to specify the return type by an appropriate cast -explicitly: - - Breakpoint 2, 0x0040050b in func () - (gdb) return -1 - Return value type not available for selected stack frame. - Please use an explicit cast of the value to return. - (gdb) return (long long int) -1 - Make selected stack frame return now? (y or n) y - #0 0x00400526 in main () - (gdb) - - -File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering - -17.5 Calling Program Functions -============================== - -`print EXPR' - Evaluate the expression EXPR and display the resulting value. - EXPR may include calls to functions in the program being debugged. - -`call EXPR' - Evaluate the expression EXPR without displaying `void' returned - values. - - You can use this variant of the `print' command if you want to - execute a function from your program that does not return anything - (a.k.a. "a void function"), but without cluttering the output with - `void' returned values that GDB will otherwise print. If the - result is not void, it is printed and saved in the value history. - - It is possible for the function you call via the `print' or `call' -command to generate a signal (e.g., if there's a bug in the function, -or if you passed it incorrect arguments). What happens in that case is -controlled by the `set unwindonsignal' command. - - Similarly, with a C++ program it is possible for the function you -call via the `print' or `call' command to generate an exception that is -not handled due to the constraints of the dummy frame. In this case, -any exception that is raised in the frame, but has an out-of-frame -exception handler will not be found. GDB builds a dummy-frame for the -inferior function call, and the unwinder cannot seek for exception -handlers outside of this dummy-frame. What happens in that case is -controlled by the `set unwind-on-terminating-exception' command. - -`set unwindonsignal' - Set unwinding of the stack if a signal is received while in a - function that GDB called in the program being debugged. If set to - on, GDB unwinds the stack it created for the call and restores the - context to what it was before the call. If set to off (the - default), GDB stops in the frame where the signal was received. - -`show unwindonsignal' - Show the current setting of stack unwinding in the functions - called by GDB. - -`set unwind-on-terminating-exception' - Set unwinding of the stack if a C++ exception is raised, but left - unhandled while in a function that GDB called in the program being - debugged. If set to on (the default), GDB unwinds the stack it - created for the call and restores the context to what it was before - the call. If set to off, GDB the exception is delivered to the - default C++ exception handler and the inferior terminated. - -`show unwind-on-terminating-exception' - Show the current setting of stack unwinding in the functions - called by GDB. - - - Sometimes, a function you wish to call is actually a "weak alias" -for another function. In such case, GDB might not pick up the type -information, including the types of the function arguments, which -causes GDB to call the inferior function incorrectly. As a result, the -called function will function erroneously and may even crash. A -solution to that is to use the name of the aliased function instead. - - -File: gdb.info, Node: Patching, Prev: Calling, Up: Altering - -17.6 Patching Programs -====================== - -By default, GDB opens the file containing your program's executable -code (or the corefile) read-only. This prevents accidental alterations -to machine code; but it also prevents you from intentionally patching -your program's binary. - - If you'd like to be able to patch the binary, you can specify that -explicitly with the `set write' command. For example, you might want -to turn on internal debugging flags, or even to make emergency repairs. - -`set write on' -`set write off' - If you specify `set write on', GDB opens executable and core files - for both reading and writing; if you specify `set write off' (the - default), GDB opens them read-only. - - If you have already loaded a file, you must load it again (using - the `exec-file' or `core-file' command) after changing `set - write', for your new setting to take effect. - -`show write' - Display whether executable files and core files are opened for - writing as well as reading. - - -File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top - -18 GDB Files -************ - -GDB needs to know the file name of the program to be debugged, both in -order to read its symbol table and in order to start your program. To -debug a core dump of a previous run, you must also tell GDB the name of -the core dump file. - -* Menu: - -* Files:: Commands to specify files -* Separate Debug Files:: Debugging information in separate files -* Index Files:: Index files speed up GDB -* Symbol Errors:: Errors reading symbol files -* Data Files:: GDB data files - - -File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files - -18.1 Commands to Specify Files -============================== - -You may want to specify executable and core dump file names. The usual -way to do this is at start-up time, using the arguments to GDB's -start-up commands (*note Getting In and Out of GDB: Invocation.). - - Occasionally it is necessary to change to a different file during a -GDB session. Or you may run GDB and forget to specify a file you want -to use. Or you are debugging a remote target via `gdbserver' (*note -file: Server.). In these situations the GDB commands to specify new -files are useful. - -`file FILENAME' - Use FILENAME as the program to be debugged. It is read for its - symbols and for the contents of pure memory. It is also the - program executed when you use the `run' command. If you do not - specify a directory and the file is not found in the GDB working - directory, GDB uses the environment variable `PATH' as a list of - directories to search, just as the shell does when looking for a - program to run. You can change the value of this variable, for - both GDB and your program, using the `path' command. - - You can load unlinked object `.o' files into GDB using the `file' - command. You will not be able to "run" an object file, but you - can disassemble functions and inspect variables. Also, if the - underlying BFD functionality supports it, you could use `gdb - -write' to patch object files using this technique. Note that GDB - can neither interpret nor modify relocations in this case, so - branches and some initialized variables will appear to go to the - wrong place. But this feature is still handy from time to time. - -`file' - `file' with no argument makes GDB discard any information it has - on both executable file and the symbol table. - -`exec-file [ FILENAME ]' - Specify that the program to be run (but not the symbol table) is - found in FILENAME. GDB searches the environment variable `PATH' - if necessary to locate your program. Omitting FILENAME means to - discard information on the executable file. - -`symbol-file [ FILENAME ]' - Read symbol table information from file FILENAME. `PATH' is - searched when necessary. Use the `file' command to get both symbol - table and program to run from the same file. - - `symbol-file' with no argument clears out GDB information on your - program's symbol table. - - The `symbol-file' command causes GDB to forget the contents of - some breakpoints and auto-display expressions. This is because - they may contain pointers to the internal data recording symbols - and data types, which are part of the old symbol table data being - discarded inside GDB. - - `symbol-file' does not repeat if you press <RET> again after - executing it once. - - When GDB is configured for a particular environment, it - understands debugging information in whatever format is the - standard generated for that environment; you may use either a GNU - compiler, or other compilers that adhere to the local conventions. - Best results are usually obtained from GNU compilers; for example, - using `GCC' you can generate debugging information for optimized - code. - - For most kinds of object files, with the exception of old SVR3 - systems using COFF, the `symbol-file' command does not normally - read the symbol table in full right away. Instead, it scans the - symbol table quickly to find which source files and which symbols - are present. The details are read later, one source file at a - time, as they are needed. - - The purpose of this two-stage reading strategy is to make GDB - start up faster. For the most part, it is invisible except for - occasional pauses while the symbol table details for a particular - source file are being read. (The `set verbose' command can turn - these pauses into messages if desired. *Note Optional Warnings - and Messages: Messages/Warnings.) - - We have not implemented the two-stage strategy for COFF yet. When - the symbol table is stored in COFF format, `symbol-file' reads the - symbol table data in full right away. Note that "stabs-in-COFF" - still does the two-stage strategy, since the debug info is actually - in stabs format. - -`symbol-file [ -readnow ] FILENAME' -`file [ -readnow ] FILENAME' - You can override the GDB two-stage strategy for reading symbol - tables by using the `-readnow' option with any of the commands that - load symbol table information, if you want to be sure GDB has the - entire symbol table available. - -`core-file [FILENAME]' -`core' - Specify the whereabouts of a core dump file to be used as the - "contents of memory". Traditionally, core files contain only some - parts of the address space of the process that generated them; GDB - can access the executable file itself for other parts. - - `core-file' with no argument specifies that no core file is to be - used. - - Note that the core file is ignored when your program is actually - running under GDB. So, if you have been running your program and - you wish to debug a core file instead, you must kill the - subprocess in which the program is running. To do this, use the - `kill' command (*note Killing the Child Process: Kill Process.). - -`add-symbol-file FILENAME ADDRESS' -`add-symbol-file FILENAME ADDRESS [ -readnow ]' -`add-symbol-file FILENAME -sSECTION ADDRESS ...' - The `add-symbol-file' command reads additional symbol table - information from the file FILENAME. You would use this command - when FILENAME has been dynamically loaded (by some other means) - into the program that is running. ADDRESS should be the memory - address at which the file has been loaded; GDB cannot figure this - out for itself. You can additionally specify an arbitrary number - of `-sSECTION ADDRESS' pairs, to give an explicit section name and - base address for that section. You can specify any ADDRESS as an - expression. - - The symbol table of the file FILENAME is added to the symbol table - originally read with the `symbol-file' command. You can use the - `add-symbol-file' command any number of times; the new symbol data - thus read keeps adding to the old. To discard all old symbol data - instead, use the `symbol-file' command without any arguments. - - Although FILENAME is typically a shared library file, an - executable file, or some other object file which has been fully - relocated for loading into a process, you can also load symbolic - information from relocatable `.o' files, as long as: - - * the file's symbolic information refers only to linker symbols - defined in that file, not to symbols defined by other object - files, - - * every section the file's symbolic information refers to has - actually been loaded into the inferior, as it appears in the - file, and - - * you can determine the address at which every section was - loaded, and provide these to the `add-symbol-file' command. - - Some embedded operating systems, like Sun Chorus and VxWorks, can - load relocatable files into an already running program; such - systems typically make the requirements above easy to meet. - However, it's important to recognize that many native systems use - complex link procedures (`.linkonce' section factoring and C++ - constructor table assembly, for example) that make the - requirements difficult to meet. In general, one cannot assume - that using `add-symbol-file' to read a relocatable object file's - symbolic information will have the same effect as linking the - relocatable object file into the program in the normal way. - - `add-symbol-file' does not repeat if you press <RET> after using - it. - -`add-symbol-file-from-memory ADDRESS' - Load symbols from the given ADDRESS in a dynamically loaded object - file whose image is mapped directly into the inferior's memory. - For example, the Linux kernel maps a `syscall DSO' into each - process's address space; this DSO provides kernel-specific code for - some system calls. The argument can be any expression whose - evaluation yields the address of the file's shared object file - header. For this command to work, you must have used - `symbol-file' or `exec-file' commands in advance. - -`add-shared-symbol-files LIBRARY-FILE' -`assf LIBRARY-FILE' - The `add-shared-symbol-files' command can currently be used only - in the Cygwin build of GDB on MS-Windows OS, where it is an alias - for the `dll-symbols' command (*note Cygwin Native::). GDB - automatically looks for shared libraries, however if GDB does not - find yours, you can invoke `add-shared-symbol-files'. It takes - one argument: the shared library's file name. `assf' is a - shorthand alias for `add-shared-symbol-files'. - -`section SECTION ADDR' - The `section' command changes the base address of the named - SECTION of the exec file to ADDR. This can be used if the exec - file does not contain section addresses, (such as in the `a.out' - format), or when the addresses specified in the file itself are - wrong. Each section must be changed separately. The `info files' - command, described below, lists all the sections and their - addresses. - -`info files' -`info target' - `info files' and `info target' are synonymous; both print the - current target (*note Specifying a Debugging Target: Targets.), - including the names of the executable and core dump files - currently in use by GDB, and the files from which symbols were - loaded. The command `help target' lists all possible targets - rather than current ones. - -`maint info sections' - Another command that can give you extra information about program - sections is `maint info sections'. In addition to the section - information displayed by `info files', this command displays the - flags and file offset of each section in the executable and core - dump files. In addition, `maint info sections' provides the - following command options (which may be arbitrarily combined): - - `ALLOBJ' - Display sections for all loaded object files, including - shared libraries. - - `SECTIONS' - Display info only for named SECTIONS. - - `SECTION-FLAGS' - Display info only for sections for which SECTION-FLAGS are - true. The section flags that GDB currently knows about are: - `ALLOC' - Section will have space allocated in the process when - loaded. Set for all sections except those containing - debug information. - - `LOAD' - Section will be loaded from the file into the child - process memory. Set for pre-initialized code and data, - clear for `.bss' sections. - - `RELOC' - Section needs to be relocated before loading. - - `READONLY' - Section cannot be modified by the child process. - - `CODE' - Section contains executable code only. - - `DATA' - Section contains data only (no executable code). - - `ROM' - Section will reside in ROM. - - `CONSTRUCTOR' - Section contains data for constructor/destructor lists. - - `HAS_CONTENTS' - Section is not empty. - - `NEVER_LOAD' - An instruction to the linker to not output the section. - - `COFF_SHARED_LIBRARY' - A notification to the linker that the section contains - COFF shared library information. - - `IS_COMMON' - Section contains common symbols. - -`set trust-readonly-sections on' - Tell GDB that readonly sections in your object file really are - read-only (i.e. that their contents will not change). In that - case, GDB can fetch values from these sections out of the object - file, rather than from the target program. For some targets - (notably embedded ones), this can be a significant enhancement to - debugging performance. - - The default is off. - -`set trust-readonly-sections off' - Tell GDB not to trust readonly sections. This means that the - contents of the section might change while the program is running, - and must therefore be fetched from the target when needed. - -`show trust-readonly-sections' - Show the current setting of trusting readonly sections. - - All file-specifying commands allow both absolute and relative file -names as arguments. GDB always converts the file name to an absolute -file name and remembers it that way. - - GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and -IBM RS/6000 AIX shared libraries. - - On MS-Windows GDB must be linked with the Expat library to support -shared libraries. *Note Expat::. - - GDB automatically loads symbol definitions from shared libraries -when you use the `run' command, or when you examine a core file. -(Before you issue the `run' command, GDB does not understand references -to a function in a shared library, however--unless you are debugging a -core file). - - On HP-UX, if the program loads a library explicitly, GDB -automatically loads the symbols at the time of the `shl_load' call. - - There are times, however, when you may wish to not automatically load -symbol definitions from shared libraries, such as when they are -particularly large or there are many of them. - - To control the automatic loading of shared library symbols, use the -commands: - -`set auto-solib-add MODE' - If MODE is `on', symbols from all shared object libraries will be - loaded automatically when the inferior begins execution, you - attach to an independently started inferior, or when the dynamic - linker informs GDB that a new library has been loaded. If MODE is - `off', symbols must be loaded manually, using the `sharedlibrary' - command. The default value is `on'. - - If your program uses lots of shared libraries with debug info that - takes large amounts of memory, you can decrease the GDB memory - footprint by preventing it from automatically loading the symbols - from shared libraries. To that end, type `set auto-solib-add off' - before running the inferior, then load each library whose debug - symbols you do need with `sharedlibrary REGEXP', where REGEXP is a - regular expression that matches the libraries whose symbols you - want to be loaded. - -`show auto-solib-add' - Display the current autoloading mode. - - To explicitly load shared library symbols, use the `sharedlibrary' -command: - -`info share REGEX' -`info sharedlibrary REGEX' - Print the names of the shared libraries which are currently loaded - that match REGEX. If REGEX is omitted then print all shared - libraries that are loaded. - -`sharedlibrary REGEX' -`share REGEX' - Load shared object library symbols for files matching a Unix - regular expression. As with files loaded automatically, it only - loads shared libraries required by your program for a core file or - after typing `run'. If REGEX is omitted all shared libraries - required by your program are loaded. - -`nosharedlibrary' - Unload all shared object library symbols. This discards all - symbols that have been loaded from all shared libraries. Symbols - from shared libraries that were loaded by explicit user requests - are not discarded. - - Sometimes you may wish that GDB stops and gives you control when any -of shared library events happen. Use the `set stop-on-solib-events' -command for this: - -`set stop-on-solib-events' - This command controls whether GDB should give you control when the - dynamic linker notifies it about some shared library event. The - most common event of interest is loading or unloading of a new - shared library. - -`show stop-on-solib-events' - Show whether GDB stops and gives you control when shared library - events happen. - - Shared libraries are also supported in many cross or remote debugging -configurations. GDB needs to have access to the target's libraries; -this can be accomplished either by providing copies of the libraries on -the host system, or by asking GDB to automatically retrieve the -libraries from the target. If copies of the target libraries are -provided, they need to be the same as the target libraries, although the -copies on the target can be stripped as long as the copies on the host -are not. - - For remote debugging, you need to tell GDB where the target -libraries are, so that it can load the correct copies--otherwise, it -may try to load the host's libraries. GDB has two variables to specify -the search directories for target libraries. - -`set sysroot PATH' - Use PATH as the system root for the program being debugged. Any - absolute shared library paths will be prefixed with PATH; many - runtime loaders store the absolute paths to the shared library in - the target program's memory. If you use `set sysroot' to find - shared libraries, they need to be laid out in the same way that - they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy - under PATH. - - If PATH starts with the sequence `remote:', GDB will retrieve the - target libraries from the remote system. This is only supported - when using a remote target that supports the `remote get' command - (*note Sending files to a remote system: File Transfer.). The - part of PATH following the initial `remote:' (if present) is used - as system root prefix on the remote file system. (1) - - For targets with an MS-DOS based filesystem, such as MS-Windows and - SymbianOS, GDB tries prefixing a few variants of the target - absolute file name with PATH. But first, on Unix hosts, GDB - converts all backslash directory separators into forward slashes, - because the backslash is not a directory separator on Unix: - - c:\foo\bar.dll => c:/foo/bar.dll - - Then, GDB attempts prefixing the target file name with PATH, and - looks for the resulting file name in the host file system: - - c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll - - If that does not find the shared library, GDB tries removing the - `:' character from the drive spec, both for convenience, and, for - the case of the host file system not supporting file names with - colons: - - c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll - - This makes it possible to have a system root that mirrors a target - with more than one drive. E.g., you may want to setup your local - copies of the target system shared libraries like so (note `c' vs - `z'): - - `/path/to/sysroot/c/sys/bin/foo.dll' - `/path/to/sysroot/c/sys/bin/bar.dll' - `/path/to/sysroot/z/sys/bin/bar.dll' - - and point the system root at `/path/to/sysroot', so that GDB can - find the correct copies of both `c:\sys\bin\foo.dll', and - `z:\sys\bin\bar.dll'. - - If that still does not find the shared library, GDB tries removing - the whole drive spec from the target file name: - - c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll - - This last lookup makes it possible to not care about the drive - name, if you don't want or need to. - - The `set solib-absolute-prefix' command is an alias for `set - sysroot'. - - You can set the default system root by using the configure-time - `--with-sysroot' option. If the system root is inside GDB's - configured binary prefix (set with `--prefix' or `--exec-prefix'), - then the default system root will be updated automatically if the - installed GDB is moved to a new location. - -`show sysroot' - Display the current shared library prefix. - -`set solib-search-path PATH' - If this variable is set, PATH is a colon-separated list of - directories to search for shared libraries. `solib-search-path' - is used after `sysroot' fails to locate the library, or if the - path to the library is relative instead of absolute. If you want - to use `solib-search-path' instead of `sysroot', be sure to set - `sysroot' to a nonexistent directory to prevent GDB from finding - your host's libraries. `sysroot' is preferred; setting it to a - nonexistent directory may interfere with automatic loading of - shared library symbols. - -`show solib-search-path' - Display the current shared library search path. - -`set target-file-system-kind KIND' - Set assumed file system kind for target reported file names. - - Shared library file names as reported by the target system may not - make sense as is on the system GDB is running on. For example, - when remote debugging a target that has MS-DOS based file system - semantics, from a Unix host, the target may be reporting to GDB a - list of loaded shared libraries with file names such as - `c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of - drive letters, so the `c:\' prefix is not normally understood as - indicating an absolute file name, and neither is the backslash - normally considered a directory separator character. In that case, - the native file system would interpret this whole absolute file - name as a relative file name with no directory components. This - would make it impossible to point GDB at a copy of the remote - target's shared libraries on the host using `set sysroot', and - impractical with `set solib-search-path'. Setting - `target-file-system-kind' to `dos-based' tells GDB to interpret - such file names similarly to how the target would, and to map them - to file names valid on GDB's native file system semantics. The - value of KIND can be `"auto"', in addition to one of the supported - file system kinds. In that case, GDB tries to determine the - appropriate file system variant based on the current target's - operating system (*note Configuring the Current ABI: ABI.). The - supported file system settings are: - - `unix' - Instruct GDB to assume the target file system is of Unix - kind. Only file names starting the forward slash (`/') - character are considered absolute, and the directory - separator character is also the forward slash. - - `dos-based' - Instruct GDB to assume the target file system is DOS based. - File names starting with either a forward slash, or a drive - letter followed by a colon (e.g., `c:'), are considered - absolute, and both the slash (`/') and the backslash (`\\') - characters are considered directory separators. - - `auto' - Instruct GDB to use the file system kind associated with the - target operating system (*note Configuring the Current ABI: - ABI.). This is the default. - - When processing file names provided by the user, GDB frequently -needs to compare them to the file names recorded in the program's debug -info. Normally, GDB compares just the "base names" of the files as -strings, which is reasonably fast even for very large programs. (The -base name of a file is the last portion of its name, after stripping -all the leading directories.) This shortcut in comparison is based -upon the assumption that files cannot have more than one base name. -This is usually true, but references to files that use symlinks or -similar filesystem facilities violate that assumption. If your program -records files using such facilities, or if you provide file names to -GDB using symlinks etc., you can set `basenames-may-differ' to `true' -to instruct GDB to completely canonicalize each pair of file names it -needs to compare. This will make file-name comparisons accurate, but -at a price of a significant slowdown. - -`set basenames-may-differ' - Set whether a source file may have multiple base names. - -`show basenames-may-differ' - Show whether a source file may have multiple base names. - - ---------- Footnotes ---------- - - (1) If you want to specify a local system root using a directory -that happens to be named `remote:', you need to use some equivalent -variant of the name like `./remote:'. - - -File: gdb.info, Node: Separate Debug Files, Next: Index Files, Prev: Files, Up: GDB Files - -18.2 Debugging Information in Separate Files -============================================ - -GDB allows you to put a program's debugging information in a file -separate from the executable itself, in a way that allows GDB to find -and load the debugging information automatically. Since debugging -information can be very large--sometimes larger than the executable -code itself--some systems distribute debugging information for their -executables in separate files, which users can install only when they -need to debug a problem. - - GDB supports two ways of specifying the separate debug info file: - - * The executable contains a "debug link" that specifies the name of - the separate debug info file. The separate debug file's name is - usually `EXECUTABLE.debug', where EXECUTABLE is the name of the - corresponding executable file without leading directories (e.g., - `ls.debug' for `/usr/bin/ls'). In addition, the debug link - specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for - the debug file, which GDB uses to validate that the executable and - the debug file came from the same build. - - * The executable contains a "build ID", a unique bit string that is - also present in the corresponding debug info file. (This is - supported only on some operating systems, notably those which use - the ELF format for binary files and the GNU Binutils.) For more - details about this feature, see the description of the `--build-id' - command-line option in *note Command Line Options: - (ld.info)Options. The debug info file's name is not specified - explicitly by the build ID, but can be computed from the build ID, - see below. - - Depending on the way the debug info file is specified, GDB uses two -different methods of looking for the debug file: - - * For the "debug link" method, GDB looks up the named file in the - directory of the executable file, then in a subdirectory of that - directory named `.debug', and finally under the global debug - directory, in a subdirectory whose name is identical to the leading - directories of the executable's absolute file name. - - * For the "build ID" method, GDB looks in the `.build-id' - subdirectory of the global debug directory for a file named - `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of - the build ID bit string, and NNNNNNNN are the rest of the bit - string. (Real build ID strings are 32 or more hex characters, not - 10.) - - So, for example, suppose you ask GDB to debug `/usr/bin/ls', which -has a debug link that specifies the file `ls.debug', and a build ID -whose value in hex is `abcdef1234'. If the global debug directory is -`/usr/lib/debug', then GDB will look for the following debug -information files, in the indicated order: - - - `/usr/lib/debug/.build-id/ab/cdef1234.debug' - - - `/usr/bin/ls.debug' - - - `/usr/bin/.debug/ls.debug' - - - `/usr/lib/debug/usr/bin/ls.debug'. - - You can set the global debugging info directory's name, and view the -name GDB is currently using. - -`set debug-file-directory DIRECTORIES' - Set the directories which GDB searches for separate debugging - information files to DIRECTORY. Multiple directory components can - be set concatenating them by a directory separator. - -`show debug-file-directory' - Show the directories GDB searches for separate debugging - information files. - - - A debug link is a special section of the executable file named -`.gnu_debuglink'. The section must contain: - - * A filename, with any leading directory components removed, - followed by a zero byte, - - * zero to three bytes of padding, as needed to reach the next - four-byte boundary within the section, and - - * a four-byte CRC checksum, stored in the same endianness used for - the executable file itself. The checksum is computed on the - debugging information file's full contents by the function given - below, passing zero as the CRC argument. - - Any executable file format can carry a debug link, as long as it can -contain a section named `.gnu_debuglink' with the contents described -above. - - The build ID is a special section in the executable file (and in -other ELF binary files that GDB may consider). This section is often -named `.note.gnu.build-id', but that name is not mandatory. It -contains unique identification for the built files--the ID remains the -same across multiple builds of the same build tree. The default -algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the -content for the build ID string. The same section with an identical -value is present in the original built binary with symbols, in its -stripped variant, and in the separate debugging information file. - - The debugging information file itself should be an ordinary -executable, containing a full set of linker symbols, sections, and -debugging information. The sections of the debugging information file -should have the same names, addresses, and sizes as the original file, -but they need not contain any data--much like a `.bss' section in an -ordinary executable. - - The GNU binary utilities (Binutils) package includes the `objcopy' -utility that can produce the separated executable / debugging -information file pairs using the following commands: - - objcopy --only-keep-debug foo foo.debug - strip -g foo - -These commands remove the debugging information from the executable -file `foo' and place it in the file `foo.debug'. You can use the -first, second or both methods to link the two files: - - * The debug link method needs the following additional command to - also leave behind a debug link in `foo': - - objcopy --add-gnu-debuglink=foo.debug foo - - Ulrich Drepper's `elfutils' package, starting with version 0.53, - contains a version of the `strip' command such that the command - `strip foo -f foo.debug' has the same functionality as the two - `objcopy' commands and the `ln -s' command above, together. - - * Build ID gets embedded into the main executable using `ld - --build-id' or the GCC counterpart `gcc -Wl,--build-id'. Build ID - support plus compatibility fixes for debug files separation are - present in GNU binary utilities (Binutils) package since version - 2.18. - -The CRC used in `.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 -using the polynomial: - - x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 - + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 - - The function is computed byte at a time, taking the least -significant bit of each byte first. The initial pattern `0xffffffff' -is used, to ensure leading zeros affect the CRC and the final result is -inverted to ensure trailing zeros also affect the CRC. - - _Note:_ This is the same CRC polynomial as used in handling the -"Remote Serial Protocol" `qCRC' packet (*note GDB Remote Serial -Protocol: Remote Protocol.). However in the case of the Remote Serial -Protocol, the CRC is computed _most_ significant bit first, and the -result is not inverted, so trailing zeros have no effect on the CRC -value. - - To complete the description, we show below the code of the function -which produces the CRC used in `.gnu_debuglink'. Inverting the -initially supplied `crc' argument means that an initial call to this -function passing in zero will start computing the CRC using -`0xffffffff'. - - unsigned long - gnu_debuglink_crc32 (unsigned long crc, - unsigned char *buf, size_t len) - { - static const unsigned long crc32_table[256] = - { - 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, - 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, - 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, - 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, - 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, - 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, - 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, - 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, - 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, - 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, - 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, - 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, - 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, - 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, - 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, - 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, - 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, - 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, - 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, - 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, - 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, - 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, - 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, - 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, - 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, - 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, - 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, - 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, - 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, - 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, - 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, - 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, - 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, - 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, - 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, - 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, - 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, - 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, - 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, - 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, - 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, - 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, - 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, - 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, - 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, - 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, - 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, - 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, - 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, - 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, - 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, - 0x2d02ef8d - }; - unsigned char *end; - - crc = ~crc & 0xffffffff; - for (end = buf + len; buf < end; ++buf) - crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); - return ~crc & 0xffffffff; - } - -This computation does not apply to the "build ID" method. - - -File: gdb.info, Node: Index Files, Next: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files - -18.3 Index Files Speed Up GDB -============================= - -When GDB finds a symbol file, it scans the symbols in the file in order -to construct an internal symbol table. This lets most GDB operations -work quickly--at the cost of a delay early on. For large programs, -this delay can be quite lengthy, so GDB provides a way to build an -index, which speeds up startup. - - The index is stored as a section in the symbol file. GDB can write -the index to a file, then you can put it into the symbol file using -`objcopy'. - - To create an index file, use the `save gdb-index' command: - -`save gdb-index DIRECTORY' - Create an index file for each symbol file currently known by GDB. - Each file is named after its corresponding symbol file, with - `.gdb-index' appended, and is written into the given DIRECTORY. - - Once you have created an index file you can merge it into your symbol -file, here named `symfile', using `objcopy': - - $ objcopy --add-section .gdb_index=symfile.gdb-index \ - --set-section-flags .gdb_index=readonly symfile symfile - - There are currently some limitation on indices. They only work when -for DWARF debugging information, not stabs. And, they do not currently -work for programs using Ada. - - -File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Index Files, Up: GDB Files - -18.4 Errors Reading Symbol Files -================================ - -While reading a symbol file, GDB occasionally encounters problems, such -as symbol types it does not recognize, or known bugs in compiler -output. By default, GDB does not notify you of such problems, since -they are relatively common and primarily of interest to people -debugging compilers. If you are interested in seeing information about -ill-constructed symbol tables, you can either ask GDB to print only one -message about each such type of problem, no matter how many times the -problem occurs; or you can ask GDB to print more messages, to see how -many times the problems occur, with the `set complaints' command (*note -Optional Warnings and Messages: Messages/Warnings.). - - The messages currently printed, and their meanings, include: - -`inner block not inside outer block in SYMBOL' - The symbol information shows where symbol scopes begin and end - (such as at the start of a function or a block of statements). - This error indicates that an inner scope block is not fully - contained in its outer scope blocks. - - GDB circumvents the problem by treating the inner block as if it - had the same scope as the outer block. In the error message, - SYMBOL may be shown as "`(don't know)'" if the outer block is not a - function. - -`block at ADDRESS out of order' - The symbol information for symbol scope blocks should occur in - order of increasing addresses. This error indicates that it does - not do so. - - GDB does not circumvent this problem, and has trouble locating - symbols in the source file whose symbols it is reading. (You can - often determine what source file is affected by specifying `set - verbose on'. *Note Optional Warnings and Messages: - Messages/Warnings.) - -`bad block start address patched' - The symbol information for a symbol scope block has a start address - smaller than the address of the preceding source line. This is - known to occur in the SunOS 4.1.1 (and earlier) C compiler. - - GDB circumvents the problem by treating the symbol scope block as - starting on the previous source line. - -`bad string table offset in symbol N' - Symbol number N contains a pointer into the string table which is - larger than the size of the string table. - - GDB circumvents the problem by considering the symbol to have the - name `foo', which may cause other problems if many symbols end up - with this name. - -`unknown symbol type `0xNN'' - The symbol information contains new data types that GDB does not - yet know how to read. `0xNN' is the symbol type of the - uncomprehended information, in hexadecimal. - - GDB circumvents the error by ignoring this symbol information. - This usually allows you to debug your program, though certain - symbols are not accessible. If you encounter such a problem and - feel like debugging it, you can debug `gdb' with itself, breakpoint - on `complain', then go up to the function `read_dbx_symtab' and - examine `*bufp' to see the symbol. - -`stub type has NULL name' - GDB could not find the full definition for a struct or class. - -`const/volatile indicator missing (ok if using g++ v1.x), got...' - The symbol information for a C++ member function is missing some - information that recent versions of the compiler should have - output for it. - -`info mismatch between compiler and debugger' - GDB could not parse a type specification output by the compiler. - - - -File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files - -18.5 GDB Data Files -=================== - -GDB will sometimes read an auxiliary data file. These files are kept -in a directory known as the "data directory". - - You can set the data directory's name, and view the name GDB is -currently using. - -`set data-directory DIRECTORY' - Set the directory which GDB searches for auxiliary data files to - DIRECTORY. - -`show data-directory' - Show the directory GDB searches for auxiliary data files. - - You can set the default data directory by using the configure-time -`--with-gdb-datadir' option. If the data directory is inside GDB's -configured binary prefix (set with `--prefix' or `--exec-prefix'), then -the default data directory will be updated automatically if the -installed GDB is moved to a new location. - - The data directory may also be specified with the `--data-directory' -command line option. *Note Mode Options::. - - -File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top - -19 Specifying a Debugging Target -******************************** - -A "target" is the execution environment occupied by your program. - - Often, GDB runs in the same host environment as your program; in -that case, the debugging target is specified as a side effect when you -use the `file' or `core' commands. When you need more flexibility--for -example, running GDB on a physically separate host, or controlling a -standalone system over a serial port or a realtime system over a TCP/IP -connection--you can use the `target' command to specify one of the -target types configured for GDB (*note Commands for Managing Targets: -Target Commands.). - - It is possible to build GDB for several different "target -architectures". When GDB is built like that, you can choose one of the -available architectures with the `set architecture' command. - -`set architecture ARCH' - This command sets the current target architecture to ARCH. The - value of ARCH can be `"auto"', in addition to one of the supported - architectures. - -`show architecture' - Show the current target architecture. - -`set processor' -`processor' - These are alias commands for, respectively, `set architecture' and - `show architecture'. - -* Menu: - -* Active Targets:: Active targets -* Target Commands:: Commands for managing targets -* Byte Order:: Choosing target byte order - - -File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets - -19.1 Active Targets -=================== - -There are multiple classes of targets such as: processes, executable -files or recording sessions. Core files belong to the process class, -making core file and process mutually exclusive. Otherwise, GDB can -work concurrently on multiple active targets, one in each class. This -allows you to (for example) start a process and inspect its activity, -while still having access to the executable file after the process -finishes. Or if you start process recording (*note Reverse -Execution::) and `reverse-step' there, you are presented a virtual -layer of the recording target, while the process target remains stopped -at the chronologically last point of the process execution. - - Use the `core-file' and `exec-file' commands to select a new core -file or executable target (*note Commands to Specify Files: Files.). To -specify as a target a process that is already running, use the `attach' -command (*note Debugging an Already-running Process: Attach.). - - -File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets - -19.2 Commands for Managing Targets -================================== - -`target TYPE PARAMETERS' - Connects the GDB host environment to a target machine or process. - A target is typically a protocol for talking to debugging - facilities. You use the argument TYPE to specify the type or - protocol of the target machine. - - Further PARAMETERS are interpreted by the target protocol, but - typically include things like device names or host names to connect - with, process numbers, and baud rates. - - The `target' command does not repeat if you press <RET> again - after executing the command. - -`help target' - Displays the names of all targets available. To display targets - currently selected, use either `info target' or `info files' - (*note Commands to Specify Files: Files.). - -`help target NAME' - Describe a particular target, including any parameters necessary to - select it. - -`set gnutarget ARGS' - GDB uses its own library BFD to read your files. GDB knows - whether it is reading an "executable", a "core", or a ".o" file; - however, you can specify the file format with the `set gnutarget' - command. Unlike most `target' commands, with `gnutarget' the - `target' refers to a program, not a machine. - - _Warning:_ To specify a file format with `set gnutarget', you - must know the actual BFD name. - - *Note Commands to Specify Files: Files. - -`show gnutarget' - Use the `show gnutarget' command to display what file format - `gnutarget' is set to read. If you have not set `gnutarget', GDB - will determine the file format for each file automatically, and - `show gnutarget' displays `The current BDF target is "auto"'. - - Here are some common targets (available, or not, depending on the GDB -configuration): - -`target exec PROGRAM' - An executable file. `target exec PROGRAM' is the same as - `exec-file PROGRAM'. - -`target core FILENAME' - A core dump file. `target core FILENAME' is the same as - `core-file FILENAME'. - -`target remote MEDIUM' - A remote system connected to GDB via a serial line or network - connection. This command tells GDB to use its own remote protocol - over MEDIUM for debugging. *Note Remote Debugging::. - - For example, if you have a board connected to `/dev/ttya' on the - machine running GDB, you could say: - - target remote /dev/ttya - - `target remote' supports the `load' command. This is only useful - if you have some other way of getting the stub to the target - system, and you can put it somewhere in memory where it won't get - clobbered by the download. - -`target sim [SIMARGS] ...' - Builtin CPU simulator. GDB includes simulators for most - architectures. In general, - target sim - load - run - works; however, you cannot assume that a specific memory map, - device drivers, or even basic I/O is available, although some - simulators do provide these. For info about any - processor-specific simulator details, see the appropriate section - in *note Embedded Processors: Embedded Processors. - - - Some configurations may include these targets as well: - -`target nrom DEV' - NetROM ROM emulator. This target only supports downloading. - - - Different targets are available on different configurations of GDB; -your configuration may have more or fewer targets. - - Many remote targets require you to download the executable's code -once you've successfully established a connection. You may wish to -control various aspects of this process. - -`set hash' - This command controls whether a hash mark `#' is displayed while - downloading a file to the remote monitor. If on, a hash mark is - displayed after each S-record is successfully downloaded to the - monitor. - -`show hash' - Show the current status of displaying the hash mark. - -`set debug monitor' - Enable or disable display of communications messages between GDB - and the remote monitor. - -`show debug monitor' - Show the current status of displaying communications between GDB - and the remote monitor. - -`load FILENAME' - Depending on what remote debugging facilities are configured into - GDB, the `load' command may be available. Where it exists, it is - meant to make FILENAME (an executable) available for debugging on - the remote system--by downloading, or dynamic linking, for example. - `load' also records the FILENAME symbol table in GDB, like the - `add-symbol-file' command. - - If your GDB does not have a `load' command, attempting to execute - it gets the error message "`You can't do that when your target is - ...'" - - The file is loaded at whatever address is specified in the - executable. For some object file formats, you can specify the - load address when you link the program; for other formats, like - a.out, the object file format specifies a fixed address. - - Depending on the remote side capabilities, GDB may be able to load - programs into flash memory. - - `load' does not repeat if you press <RET> again after using it. - - -File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets - -19.3 Choosing Target Byte Order -=============================== - -Some types of processors, such as the MIPS, PowerPC, and Renesas SH, -offer the ability to run either big-endian or little-endian byte -orders. Usually the executable or symbol will include a bit to -designate the endian-ness, and you will not need to worry about which -to use. However, you may still find it useful to adjust GDB's idea of -processor endian-ness manually. - -`set endian big' - Instruct GDB to assume the target is big-endian. - -`set endian little' - Instruct GDB to assume the target is little-endian. - -`set endian auto' - Instruct GDB to use the byte order associated with the executable. - -`show endian' - Display GDB's current idea of the target byte order. - - - Note that these commands merely adjust interpretation of symbolic -data on the host, and that they have absolutely no effect on the target -system. - - -File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top - -20 Debugging Remote Programs -**************************** - -If you are trying to debug a program running on a machine that cannot -run GDB in the usual way, it is often useful to use remote debugging. -For example, you might use remote debugging on an operating system -kernel, or on a small system which does not have a general purpose -operating system powerful enough to run a full-featured debugger. - - Some configurations of GDB have special serial or TCP/IP interfaces -to make this work with particular debugging targets. In addition, GDB -comes with a generic serial protocol (specific to GDB, but not specific -to any particular target system) which you can use if you write the -remote stubs--the code that runs on the remote system to communicate -with GDB. - - Other remote targets may be available in your configuration of GDB; -use `help target' to list them. - -* Menu: - -* Connecting:: Connecting to a remote target -* File Transfer:: Sending files to a remote system -* Server:: Using the gdbserver program -* Remote Configuration:: Remote configuration -* Remote Stub:: Implementing a remote stub - - -File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging - -20.1 Connecting to a Remote Target -================================== - -On the GDB host machine, you will need an unstripped copy of your -program, since GDB needs symbol and debugging information. Start up -GDB as usual, using the name of the local copy of your program as the -first argument. - - GDB can communicate with the target over a serial line, or over an -IP network using TCP or UDP. In each case, GDB uses the same protocol -for debugging your program; only the medium carrying the debugging -packets varies. The `target remote' command establishes a connection -to the target. Its arguments indicate which medium to use: - -`target remote SERIAL-DEVICE' - Use SERIAL-DEVICE to communicate with the target. For example, to - use a serial line connected to the device named `/dev/ttyb': - - target remote /dev/ttyb - - If you're using a serial line, you may want to give GDB the - `--baud' option, or use the `set remotebaud' command (*note set - remotebaud: Remote Configuration.) before the `target' command. - -`target remote `HOST:PORT'' -`target remote `tcp:HOST:PORT'' - Debug using a TCP connection to PORT on HOST. The HOST may be - either a host name or a numeric IP address; PORT must be a decimal - number. The HOST could be the target machine itself, if it is - directly connected to the net, or it might be a terminal server - which in turn has a serial line to the target. - - For example, to connect to port 2828 on a terminal server named - `manyfarms': - - target remote manyfarms:2828 - - If your remote target is actually running on the same machine as - your debugger session (e.g. a simulator for your target running on - the same host), you can omit the hostname. For example, to - connect to port 1234 on your local machine: - - target remote :1234 - Note that the colon is still required here. - -`target remote `udp:HOST:PORT'' - Debug using UDP packets to PORT on HOST. For example, to connect - to UDP port 2828 on a terminal server named `manyfarms': - - target remote udp:manyfarms:2828 - - When using a UDP connection for remote debugging, you should keep - in mind that the `U' stands for "Unreliable". UDP can silently - drop packets on busy or unreliable networks, which will cause - havoc with your debugging session. - -`target remote | COMMAND' - Run COMMAND in the background and communicate with it using a - pipe. The COMMAND is a shell command, to be parsed and expanded - by the system's command shell, `/bin/sh'; it should expect remote - protocol packets on its standard input, and send replies on its - standard output. You could use this to run a stand-alone simulator - that speaks the remote debugging protocol, to make net connections - using programs like `ssh', or for other similar tricks. - - If COMMAND closes its standard output (perhaps by exiting), GDB - will try to send it a `SIGTERM' signal. (If the program has - already exited, this will have no effect.) - - - Once the connection has been established, you can use all the usual -commands to examine and change data. The remote program is already -running; you can use `step' and `continue', and you do not need to use -`run'. - - Whenever GDB is waiting for the remote program, if you type the -interrupt character (often `Ctrl-c'), GDB attempts to stop the program. -This may or may not succeed, depending in part on the hardware and the -serial drivers the remote system uses. If you type the interrupt -character once again, GDB displays this prompt: - - Interrupted while waiting for the program. - Give up (and stop debugging it)? (y or n) - - If you type `y', GDB abandons the remote debugging session. (If you -decide you want to try again later, you can use `target remote' again -to connect once more.) If you type `n', GDB goes back to waiting. - -`detach' - When you have finished debugging the remote program, you can use - the `detach' command to release it from GDB control. Detaching - from the target normally resumes its execution, but the results - will depend on your particular remote stub. After the `detach' - command, GDB is free to connect to another target. - -`disconnect' - The `disconnect' command behaves like `detach', except that the - target is generally not resumed. It will wait for GDB (this - instance or another one) to connect and continue debugging. After - the `disconnect' command, GDB is again free to connect to another - target. - -`monitor CMD' - This command allows you to send arbitrary commands directly to the - remote monitor. Since GDB doesn't care about the commands it - sends like this, this command is the way to extend GDB--you can - add new commands that only the external monitor will understand - and implement. - - -File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging - -20.2 Sending files to a remote system -===================================== - -Some remote targets offer the ability to transfer files over the same -connection used to communicate with GDB. This is convenient for -targets accessible through other means, e.g. GNU/Linux systems running -`gdbserver' over a network interface. For other targets, e.g. embedded -devices with only a single serial port, this may be the only way to -upload or download files. - - Not all remote targets support these commands. - -`remote put HOSTFILE TARGETFILE' - Copy file HOSTFILE from the host system (the machine running GDB) - to TARGETFILE on the target system. - -`remote get TARGETFILE HOSTFILE' - Copy file TARGETFILE from the target system to HOSTFILE on the - host system. - -`remote delete TARGETFILE' - Delete TARGETFILE from the target system. - - - -File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging - -20.3 Using the `gdbserver' Program -================================== - -`gdbserver' is a control program for Unix-like systems, which allows -you to connect your program with a remote GDB via `target remote'--but -without linking in the usual debugging stub. - - `gdbserver' is not a complete replacement for the debugging stubs, -because it requires essentially the same operating-system facilities -that GDB itself does. In fact, a system that can run `gdbserver' to -connect to a remote GDB could also run GDB locally! `gdbserver' is -sometimes useful nevertheless, because it is a much smaller program -than GDB itself. It is also easier to port than all of GDB, so you may -be able to get started more quickly on a new system by using -`gdbserver'. Finally, if you develop code for real-time systems, you -may find that the tradeoffs involved in real-time operation make it -more convenient to do as much development work as possible on another -system, for example by cross-compiling. You can use `gdbserver' to -make a similar choice for debugging. - - GDB and `gdbserver' communicate via either a serial line or a TCP -connection, using the standard GDB remote serial protocol. - - _Warning:_ `gdbserver' does not have any built-in security. Do - not run `gdbserver' connected to any public network; a GDB - connection to `gdbserver' provides access to the target system - with the same privileges as the user running `gdbserver'. - -20.3.1 Running `gdbserver' --------------------------- - -Run `gdbserver' on the target system. You need a copy of the program -you want to debug, including any libraries it requires. `gdbserver' -does not need your program's symbol table, so you can strip the program -if necessary to save space. GDB on the host system does all the symbol -handling. - - To use the server, you must tell it how to communicate with GDB; the -name of your program; and the arguments for your program. The usual -syntax is: - - target> gdbserver COMM PROGRAM [ ARGS ... ] - - COMM is either a device name (to use a serial line) or a TCP -hostname and portnumber. For example, to debug Emacs with the argument -`foo.txt' and communicate with GDB over the serial port `/dev/com1': - - target> gdbserver /dev/com1 emacs foo.txt - - `gdbserver' waits passively for the host GDB to communicate with it. - - To use a TCP connection instead of a serial line: - - target> gdbserver host:2345 emacs foo.txt - - The only difference from the previous example is the first argument, -specifying that you are communicating with the host GDB via TCP. The -`host:2345' argument means that `gdbserver' is to expect a TCP -connection from machine `host' to local TCP port 2345. (Currently, the -`host' part is ignored.) You can choose any number you want for the -port number as long as it does not conflict with any TCP ports already -in use on the target system (for example, `23' is reserved for -`telnet').(1) You must use the same port number with the host GDB -`target remote' command. - -20.3.1.1 Attaching to a Running Program -....................................... - -On some targets, `gdbserver' can also attach to running programs. This -is accomplished via the `--attach' argument. The syntax is: - - target> gdbserver --attach COMM PID - - PID is the process ID of a currently running process. It isn't -necessary to point `gdbserver' at a binary for the running process. - - You can debug processes by name instead of process ID if your target -has the `pidof' utility: - - target> gdbserver --attach COMM `pidof PROGRAM` - - In case more than one copy of PROGRAM is running, or PROGRAM has -multiple threads, most versions of `pidof' support the `-s' option to -only return the first process ID. - -20.3.1.2 Multi-Process Mode for `gdbserver' -........................................... - -When you connect to `gdbserver' using `target remote', `gdbserver' -debugs the specified program only once. When the program exits, or you -detach from it, GDB closes the connection and `gdbserver' exits. - - If you connect using `target extended-remote', `gdbserver' enters -multi-process mode. When the debugged program exits, or you detach -from it, GDB stays connected to `gdbserver' even though no program is -running. The `run' and `attach' commands instruct `gdbserver' to run -or attach to a new program. The `run' command uses `set remote -exec-file' (*note set remote exec-file::) to select the program to run. -Command line arguments are supported, except for wildcard expansion and -I/O redirection (*note Arguments::). - - To start `gdbserver' without supplying an initial command to run or -process ID to attach, use the `--multi' command line option. Then you -can connect using `target extended-remote' and start the program you -want to debug. - - `gdbserver' does not automatically exit in multi-process mode. You -can terminate it by using `monitor exit' (*note Monitor Commands for -gdbserver::). - -20.3.1.3 Other Command-Line Arguments for `gdbserver' -..................................................... - -The `--debug' option tells `gdbserver' to display extra status -information about the debugging process. The `--remote-debug' option -tells `gdbserver' to display remote protocol debug output. These -options are intended for `gdbserver' development and for bug reports to -the developers. - - The `--wrapper' option specifies a wrapper to launch programs for -debugging. The option should be followed by the name of the wrapper, -then any command-line arguments to pass to the wrapper, then `--' -indicating the end of the wrapper arguments. - - `gdbserver' runs the specified wrapper program with a combined -command line including the wrapper arguments, then the name of the -program to debug, then any arguments to the program. The wrapper runs -until it executes your program, and then GDB gains 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 `gdbserver''s -environment: - - $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog - -20.3.2 Connecting to `gdbserver' --------------------------------- - -Run GDB on the host system. - - First make sure you have the necessary symbol files. Load symbols -for your application using the `file' command before you connect. Use -`set sysroot' to locate target libraries (unless your GDB was compiled -with the correct sysroot using `--with-sysroot'). - - The symbol file and target libraries must exactly match the -executable and libraries on the target, with one exception: the files -on the host system should not be stripped, even if the files on the -target system are. Mismatched or missing files will lead to confusing -results during debugging. On GNU/Linux targets, mismatched or missing -files may also prevent `gdbserver' from debugging multi-threaded -programs. - - Connect to your target (*note Connecting to a Remote Target: -Connecting.). For TCP connections, you must start up `gdbserver' prior -to using the `target remote' command. Otherwise you may get an error -whose text depends on the host system, but which usually looks -something like `Connection refused'. Don't use the `load' command in -GDB when using `gdbserver', since the program is already on the target. - -20.3.3 Monitor Commands for `gdbserver' ---------------------------------------- - -During a GDB session using `gdbserver', you can use the `monitor' -command to send special requests to `gdbserver'. Here are the -available commands. - -`monitor help' - List the available monitor commands. - -`monitor set debug 0' -`monitor set debug 1' - Disable or enable general debugging messages. - -`monitor set remote-debug 0' -`monitor set remote-debug 1' - Disable or enable specific debugging messages associated with the - remote protocol (*note Remote Protocol::). - -`monitor set libthread-db-search-path [PATH]' - When this command is issued, PATH is a colon-separated list of - directories to search for `libthread_db' (*note set - libthread-db-search-path: Threads.). If you omit PATH, - `libthread-db-search-path' will be reset to its default value. - - The special entry `$pdir' for `libthread-db-search-path' is not - supported in `gdbserver'. - -`monitor exit' - Tell gdbserver to exit immediately. This command should be - followed by `disconnect' to close the debugging session. - `gdbserver' will detach from any attached processes and kill any - processes it created. Use `monitor exit' to terminate `gdbserver' - at the end of a multi-process mode debug session. - - -20.3.4 Tracepoints support in `gdbserver' ------------------------------------------ - -On some targets, `gdbserver' supports tracepoints, fast tracepoints and -static tracepoints. - - For fast or static tracepoints to work, a special library called the -"in-process agent" (IPA), must be loaded in the inferior process. This -library is built and distributed as an integral part of `gdbserver'. -In addition, support for static tracepoints requires building the -in-process agent library with static tracepoints support. At present, -the UST (LTTng Userspace Tracer, `http://lttng.org/ust') tracing engine -is supported. This support is automatically available if UST -development headers are found in the standard include path when -`gdbserver' is built, or if `gdbserver' was explicitly configured using -`--with-ust' to point at such headers. You can explicitly disable the -support using `--with-ust=no'. - - There are several ways to load the in-process agent in your program: - -`Specifying it as dependency at link time' - You can link your program dynamically with the in-process agent - library. On most systems, this is accomplished by adding - `-linproctrace' to the link command. - -`Using the system's preloading mechanisms' - You can force loading the in-process agent at startup time by using - your system's support for preloading shared libraries. Many Unixes - support the concept of preloading user defined libraries. In most - cases, you do that by specifying `LD_PRELOAD=libinproctrace.so' in - the environment. See also the description of `gdbserver''s - `--wrapper' command line option. - -`Using GDB to force loading the agent at run time' - On some systems, you can force the inferior to load a shared - library, by calling a dynamic loader function in the inferior that - takes care of dynamically looking up and loading a shared library. - On most Unix systems, the function is `dlopen'. You'll use the - `call' command for that. For example: - - (gdb) call dlopen ("libinproctrace.so", ...) - - Note that on most Unix systems, for the `dlopen' function to be - available, the program needs to be linked with `-ldl'. - - On systems that have a userspace dynamic loader, like most Unix -systems, when you connect to `gdbserver' using `target remote', you'll -find that the program is stopped at the dynamic loader's entry point, -and no shared library has been loaded in the program's address space -yet, including the in-process agent. In that case, before being able -to use any of the fast or static tracepoints features, you need to let -the loader run and load the shared libraries. The simplest way to do -that is to run the program to the main procedure. E.g., if debugging a -C or C++ program, start `gdbserver' like so: - - $ gdbserver :9999 myprogram - - Start GDB and connect to `gdbserver' like so, and run to main: - - $ gdb myprogram - (gdb) target remote myhost:9999 - 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 - (gdb) b main - (gdb) continue - - The in-process tracing agent library should now be loaded into the -process; you can confirm it with the `info sharedlibrary' command, -which will list `libinproctrace.so' as loaded in the process. You are -now ready to install fast tracepoints, list static tracepoint markers, -probe static tracepoints markers, and start tracing. - - ---------- Footnotes ---------- - - (1) If you choose a port number that conflicts with another service, -`gdbserver' prints an error message and exits. - - -File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging - -20.4 Remote Configuration -========================= - -This section documents the configuration options available when -debugging remote programs. For the options related to the File I/O -extensions of the remote protocol, see *note system-call-allowed: -system. - -`set remoteaddresssize BITS' - Set the maximum size of address in a memory packet to the specified - number of bits. GDB will mask off the address bits above that - number, when it passes addresses to the remote target. The - default value is the number of bits in the target's address. - -`show remoteaddresssize' - Show the current value of remote address size in bits. - -`set remotebaud N' - Set the baud rate for the remote serial I/O to N baud. The value - is used to set the speed of the serial port used for debugging - remote targets. - -`show remotebaud' - Show the current speed of the remote connection. - -`set remotebreak' - If set to on, GDB sends a `BREAK' signal to the remote when you - type `Ctrl-c' to interrupt the program running on the remote. If - set to off, GDB sends the `Ctrl-C' character instead. The default - is off, since most remote systems expect to see `Ctrl-C' as the - interrupt signal. - -`show remotebreak' - Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote - program. - -`set remoteflow on' -`set remoteflow off' - Enable or disable hardware flow control (`RTS'/`CTS') on the - serial port used to communicate to the remote target. - -`show remoteflow' - Show the current setting of hardware flow control. - -`set remotelogbase BASE' - Set the base (a.k.a. radix) of logging serial protocol - communications to BASE. Supported values of BASE are: `ascii', - `octal', and `hex'. The default is `ascii'. - -`show remotelogbase' - Show the current setting of the radix for logging remote serial - protocol. - -`set remotelogfile FILE' - Record remote serial communications on the named FILE. The - default is not to record at all. - -`show remotelogfile.' - Show the current setting of the file name on which to record the - serial communications. - -`set remotetimeout NUM' - Set the timeout limit to wait for the remote target to respond to - NUM seconds. The default is 2 seconds. - -`show remotetimeout' - Show the current number of seconds to wait for the remote target - responses. - -`set remote hardware-watchpoint-limit LIMIT' -`set remote hardware-breakpoint-limit LIMIT' - Restrict GDB to using LIMIT remote hardware breakpoint or - watchpoints. A limit of -1, the default, is treated as unlimited. - -`set remote exec-file FILENAME' -`show remote exec-file' - Select the file used for `run' with `target extended-remote'. - This should be set to a filename valid on the target system. If - it is not set, the target will use a default filename (e.g. the - last program run). - -`set remote interrupt-sequence' - Allow the user to select one of `Ctrl-C', a `BREAK' or `BREAK-g' - as the sequence to the remote target in order to interrupt the - execution. `Ctrl-C' is a default. Some system prefers `BREAK' - which is high level of serial line for some certain time. Linux - kernel prefers `BREAK-g', a.k.a Magic SysRq g. It is `BREAK' - signal followed by character `g'. - -`show interrupt-sequence' - Show which of `Ctrl-C', `BREAK' or `BREAK-g' is sent by GDB to - interrupt the remote program. `BREAK-g' is BREAK signal followed - by `g' and also known as Magic SysRq g. - -`set remote interrupt-on-connect' - Specify whether interrupt-sequence is sent to remote target when - GDB connects to it. This is mostly needed when you debug Linux - kernel. Linux kernel expects `BREAK' followed by `g' which is - known as Magic SysRq g in order to connect GDB. - -`show interrupt-on-connect' - Show whether interrupt-sequence is sent to remote target when GDB - connects to it. - -`set tcp auto-retry on' - Enable auto-retry for remote TCP connections. This is useful if - the remote debugging agent is launched in parallel with GDB; there - is a race condition because the agent may not become ready to - accept the connection before GDB attempts to connect. When - auto-retry is enabled, if the initial attempt to connect fails, - GDB reattempts to establish the connection using the timeout - specified by `set tcp connect-timeout'. - -`set tcp auto-retry off' - Do not auto-retry failed TCP connections. - -`show tcp auto-retry' - Show the current auto-retry setting. - -`set tcp connect-timeout SECONDS' - Set the timeout for establishing a TCP connection to the remote - target to SECONDS. The timeout affects both polling to retry - failed connections (enabled by `set tcp auto-retry on') and - waiting for connections that are merely slow to complete, and - represents an approximate cumulative value. - -`show tcp connect-timeout' - Show the current connection timeout setting. - - The GDB remote protocol autodetects the packets supported by your -debugging stub. If you need to override the autodetection, you can use -these commands to enable or disable individual packets. Each packet -can be set to `on' (the remote target supports this packet), `off' (the -remote target does not support this packet), or `auto' (detect remote -target support for this packet). They all default to `auto'. For more -information about each packet, see *note Remote Protocol::. - - During normal use, you should not have to use any of these commands. -If you do, that may be a bug in your remote debugging stub, or a bug in -GDB. You may want to report the problem to the GDB developers. - - For each packet NAME, the command to enable or disable the packet is -`set remote NAME-packet'. The available settings are: - -Command Name Remote Packet Related Features -`fetch-register' `p' `info registers' -`set-register' `P' `set' -`binary-download' `X' `load', `set' -`read-aux-vector' `qXfer:auxv:read' `info auxv' -`symbol-lookup' `qSymbol' Detecting - multiple threads -`attach' `vAttach' `attach' -`verbose-resume' `vCont' Stepping or - resuming multiple - threads -`run' `vRun' `run' -`software-breakpoint'`Z0' `break' -`hardware-breakpoint'`Z1' `hbreak' -`write-watchpoint' `Z2' `watch' -`read-watchpoint' `Z3' `rwatch' -`access-watchpoint' `Z4' `awatch' -`target-features' `qXfer:features:read' `set architecture' -`library-info' `qXfer:libraries:read' `info - sharedlibrary' -`memory-map' `qXfer:memory-map:read' `info mem' -`read-sdata-object' `qXfer:sdata:read' `print $_sdata' -`read-spu-object' `qXfer:spu:read' `info spu' -`write-spu-object' `qXfer:spu:write' `info spu' -`read-siginfo-object'`qXfer:siginfo:read' `print $_siginfo' -`write-siginfo-object'`qXfer:siginfo:write' `set $_siginfo' -`threads' `qXfer:threads:read' `info threads' -`get-thread-local- `qGetTLSAddr' Displaying -storage-address' `__thread' - variables -`get-thread-information-block-address'`qGetTIBAddr' Display - MS-Windows Thread - Information Block. -`search-memory' `qSearch:memory' `find' -`supported-packets' `qSupported' Remote - communications - parameters -`pass-signals' `QPassSignals' `handle SIGNAL' -`hostio-close-packet'`vFile:close' `remote get', - `remote put' -`hostio-open-packet' `vFile:open' `remote get', - `remote put' -`hostio-pread-packet'`vFile:pread' `remote get', - `remote put' -`hostio-pwrite-packet'`vFile:pwrite' `remote get', - `remote put' -`hostio-unlink-packet'`vFile:unlink' `remote delete' -`noack-packet' `QStartNoAckMode' Packet - acknowledgment -`osdata' `qXfer:osdata:read' `info os' -`query-attached' `qAttached' Querying remote - process attach - state. -`traceframe-info' `qXfer:traceframe-info:read'Traceframe info - - -File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging - -20.5 Implementing a Remote Stub -=============================== - -The stub files provided with GDB implement the target side of the -communication protocol, and the GDB side is implemented in the GDB -source file `remote.c'. Normally, you can simply allow these -subroutines to communicate, and ignore the details. (If you're -implementing your own stub file, you can still ignore the details: start -with one of the existing stub files. `sparc-stub.c' is the best -organized, and therefore the easiest to read.) - - To debug a program running on another machine (the debugging -"target" machine), you must first arrange for all the usual -prerequisites for the program to run by itself. For example, for a C -program, you need: - - 1. A startup routine to set up the C runtime environment; these - usually have a name like `crt0'. The startup routine may be - supplied by your hardware supplier, or you may have to write your - own. - - 2. A C subroutine library to support your program's subroutine calls, - notably managing input and output. - - 3. A way of getting your program to the other machine--for example, a - download program. These are often supplied by the hardware - manufacturer, but you may have to write your own from hardware - documentation. - - The next step is to arrange for your program to use a serial port to -communicate with the machine where GDB is running (the "host" machine). -In general terms, the scheme looks like this: - -_On the host,_ - GDB already understands how to use this protocol; when everything - else is set up, you can simply use the `target remote' command - (*note Specifying a Debugging Target: Targets.). - -_On the target,_ - you must link with your program a few special-purpose subroutines - that implement the GDB remote serial protocol. The file - containing these subroutines is called a "debugging stub". - - On certain remote targets, you can use an auxiliary program - `gdbserver' instead of linking a stub into your program. *Note - Using the `gdbserver' Program: Server, for details. - - The debugging stub is specific to the architecture of the remote -machine; for example, use `sparc-stub.c' to debug programs on SPARC -boards. - - These working remote stubs are distributed with GDB: - -`i386-stub.c' - For Intel 386 and compatible architectures. - -`m68k-stub.c' - For Motorola 680x0 architectures. - -`sh-stub.c' - For Renesas SH architectures. - -`sparc-stub.c' - For SPARC architectures. - -`sparcl-stub.c' - For Fujitsu SPARCLITE architectures. - - - The `README' file in the GDB distribution may list other recently -added stubs. - -* Menu: - -* Stub Contents:: What the stub can do for you -* Bootstrapping:: What you must do for the stub -* Debug Session:: Putting it all together - - -File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub - -20.5.1 What the Stub Can Do for You ------------------------------------ - -The debugging stub for your architecture supplies these three -subroutines: - -`set_debug_traps' - This routine arranges for `handle_exception' to run when your - program stops. You must call this subroutine explicitly near the - beginning of your program. - -`handle_exception' - This is the central workhorse, but your program never calls it - explicitly--the setup code arranges for `handle_exception' to run - when a trap is triggered. - - `handle_exception' takes control when your program stops during - execution (for example, on a breakpoint), and mediates - communications with GDB on the host machine. This is where the - communications protocol is implemented; `handle_exception' acts as - the GDB representative on the target machine. It begins by - sending summary information on the state of your program, then - continues to execute, retrieving and transmitting any information - GDB needs, until you execute a GDB command that makes your program - resume; at that point, `handle_exception' returns control to your - own code on the target machine. - -`breakpoint' - Use this auxiliary subroutine to make your program contain a - breakpoint. Depending on the particular situation, this may be - the only way for GDB to get control. For instance, if your target - machine has some sort of interrupt button, you won't need to call - this; pressing the interrupt button transfers control to - `handle_exception'--in effect, to GDB. On some machines, simply - receiving characters on the serial port may also trigger a trap; - again, in that situation, you don't need to call `breakpoint' from - your own program--simply running `target remote' from the host GDB - session gets control. - - Call `breakpoint' if none of these is true, or if you simply want - to make certain your program stops at a predetermined point for the - start of your debugging session. - - -File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub - -20.5.2 What You Must Do for the Stub ------------------------------------- - -The debugging stubs that come with GDB are set up for a particular chip -architecture, but they have no information about the rest of your -debugging target machine. - - First of all you need to tell the stub how to communicate with the -serial port. - -`int getDebugChar()' - Write this subroutine to read a single character from the serial - port. It may be identical to `getchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - -`void putDebugChar(int)' - Write this subroutine to write a single character to the serial - port. It may be identical to `putchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - - If you want GDB to be able to stop your program while it is running, -you need to use an interrupt-driven serial driver, and arrange for it -to stop when it receives a `^C' (`\003', the control-C character). -That is the character which GDB uses to tell the remote system to stop. - - Getting the debugging target to return the proper status to GDB -probably requires changes to the standard stub; one quick and dirty way -is to just execute a breakpoint instruction (the "dirty" part is that -GDB reports a `SIGTRAP' instead of a `SIGINT'). - - Other routines you need to supply are: - -`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' - Write this function to install EXCEPTION_ADDRESS in the exception - handling tables. You need to do this because the stub does not - have any way of knowing what the exception handling tables on your - target system are like (for example, the processor's table might - be in ROM, containing entries which point to a table in RAM). - EXCEPTION_NUMBER is the exception number which should be changed; - its meaning is architecture-dependent (for example, different - numbers might represent divide by zero, misaligned access, etc). - When this exception occurs, control should be transferred directly - to EXCEPTION_ADDRESS, and the processor state (stack, registers, - and so on) should be just as it is when a processor exception - occurs. So if you want to use a jump instruction to reach - EXCEPTION_ADDRESS, it should be a simple jump, not a jump to - subroutine. - - For the 386, EXCEPTION_ADDRESS should be installed as an interrupt - gate so that interrupts are masked while the handler runs. The - gate should be at privilege level 0 (the most privileged level). - The SPARC and 68k stubs are able to mask interrupts themselves - without help from `exceptionHandler'. - -`void flush_i_cache()' - On SPARC and SPARCLITE only, write this subroutine to flush the - instruction cache, if any, on your target machine. If there is no - instruction cache, this subroutine may be a no-op. - - On target machines that have instruction caches, GDB requires this - function to make certain that the state of your program is stable. - -You must also make sure this library routine is available: - -`void *memset(void *, int, int)' - This is the standard library function `memset' that sets an area of - memory to a known value. If you have one of the free versions of - `libc.a', `memset' can be found there; otherwise, you must either - obtain it from your hardware manufacturer, or write your own. - - If you do not use the GNU C compiler, you may need other standard -library subroutines as well; this varies from one stub to another, but -in general the stubs are likely to use any of the common library -subroutines which `GCC' generates as inline code. - - -File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub - -20.5.3 Putting it All Together ------------------------------- - -In summary, when your program is ready to debug, you must follow these -steps. - - 1. Make sure you have defined the supporting low-level routines - (*note What You Must Do for the Stub: Bootstrapping.): - `getDebugChar', `putDebugChar', - `flush_i_cache', `memset', `exceptionHandler'. - - 2. Insert these lines near the top of your program: - - set_debug_traps(); - breakpoint(); - - 3. For the 680x0 stub only, you need to provide a variable called - `exceptionHook'. Normally you just use: - - void (*exceptionHook)() = 0; - - but if before calling `set_debug_traps', you set it to point to a - function in your program, that function is called when `GDB' - continues after stopping on a trap (for example, bus error). The - function indicated by `exceptionHook' is called with one - parameter: an `int' which is the exception number. - - 4. Compile and link together: your program, the GDB debugging stub for - your target architecture, and the supporting subroutines. - - 5. Make sure you have a serial connection between your target machine - and the GDB host, and identify the serial port on the host. - - 6. Download your program to your target machine (or get it there by - whatever means the manufacturer provides), and start it. - - 7. Start GDB on the host, and connect to the target (*note Connecting - to a Remote Target: Connecting.). - - - -File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top - -21 Configuration-Specific Information -************************************* - -While nearly all GDB commands are available for all native and cross -versions of the debugger, there are some exceptions. This chapter -describes things that are only available in certain configurations. - - There are three major categories of configurations: native -configurations, where the host and target are the same, embedded -operating system configurations, which are usually the same for several -different processor architectures, and bare embedded processors, which -are quite different from each other. - -* Menu: - -* Native:: -* Embedded OS:: -* Embedded Processors:: -* Architectures:: - - -File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations - -21.1 Native -=========== - -This section describes details specific to particular native -configurations. - -* Menu: - -* HP-UX:: HP-UX -* BSD libkvm Interface:: Debugging BSD kernel memory images -* SVR4 Process Information:: SVR4 process information -* DJGPP Native:: Features specific to the DJGPP port -* Cygwin Native:: Features specific to the Cygwin port -* Hurd Native:: Features specific to GNU Hurd -* Neutrino:: Features specific to QNX Neutrino -* Darwin:: Features specific to Darwin - - -File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native - -21.1.1 HP-UX ------------- - -On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, GDB searches for a user or system name -first, before it searches for a convenience variable. - - -File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native - -21.1.2 BSD libkvm Interface ---------------------------- - -BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory -interface that provides a uniform interface for accessing kernel virtual -memory images, including live systems and crash dumps. GDB uses this -interface to allow you to debug live kernels and kernel crash dumps on -many native BSD configurations. This is implemented as a special `kvm' -debugging target. For debugging a live system, load the currently -running kernel into GDB and connect to the `kvm' target: - - (gdb) target kvm - - For debugging crash dumps, provide the file name of the crash dump -as an argument: - - (gdb) target kvm /var/crash/bsd.0 - - Once connected to the `kvm' target, the following commands are -available: - -`kvm pcb' - Set current context from the "Process Control Block" (PCB) address. - -`kvm proc' - Set current context from proc address. This command isn't - available on modern FreeBSD systems. - - -File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native - -21.1.3 SVR4 Process Information -------------------------------- - -Many versions of SVR4 and compatible systems provide a facility called -`/proc' that can be used to examine the image of a running process -using file-system subroutines. If GDB is configured for an operating -system with this facility, the command `info proc' is available to -report information about the process running your program, or about any -process running on your system. `info proc' works only on SVR4 systems -that include the `procfs' code. This includes, as of this writing, -GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not -HP-UX, for example. - -`info proc' -`info proc PROCESS-ID' - Summarize available information about any running process. If a - process ID is specified by PROCESS-ID, display information about - that process; otherwise display information about the program being - debugged. The summary includes the debugged process ID, the - command line used to invoke it, its current working directory, and - its executable file's absolute file name. - - On some systems, PROCESS-ID can be of the form `[PID]/TID' which - specifies a certain thread ID within a process. If the optional - PID part is missing, it means a thread from the process being - debugged (the leading `/' still needs to be present, or else GDB - will interpret the number as a process ID rather than a thread ID). - -`info proc mappings' - Report the memory address space ranges accessible in the program, - with information on whether the process has read, write, or - execute access rights to each range. On GNU/Linux systems, each - memory range includes the object file which is mapped to that - range, instead of the memory access rights to that range. - -`info proc stat' -`info proc status' - These subcommands are specific to GNU/Linux systems. They show - the process-related information, including the user ID and group - ID; how many threads are there in the process; its virtual memory - usage; the signals that are pending, blocked, and ignored; its - TTY; its consumption of system and user time; its stack size; its - `nice' value; etc. For more information, see the `proc' man page - (type `man 5 proc' from your shell prompt). - -`info proc all' - Show all the information about the process described under all of - the above `info proc' subcommands. - -`set procfs-trace' - This command enables and disables tracing of `procfs' API calls. - -`show procfs-trace' - Show the current state of `procfs' API call tracing. - -`set procfs-file FILE' - Tell GDB to write `procfs' API trace to the named FILE. GDB - appends the trace info to the previous contents of the file. The - default is to display the trace on the standard output. - -`show procfs-file' - Show the file to which `procfs' API trace is written. - -`proc-trace-entry' -`proc-trace-exit' -`proc-untrace-entry' -`proc-untrace-exit' - These commands enable and disable tracing of entries into and exits - from the `syscall' interface. - -`info pidlist' - For QNX Neutrino only, this command displays the list of all the - processes and all the threads within each process. - -`info meminfo' - For QNX Neutrino only, this command displays the list of all - mapinfos. - - -File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native - -21.1.4 Features for Debugging DJGPP Programs --------------------------------------------- - -DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. -DJGPP programs are 32-bit protected-mode programs that use the "DPMI" -(DOS Protected-Mode Interface) API to run on top of real-mode DOS -systems and their emulations. - - GDB supports native debugging of DJGPP programs, and defines a few -commands specific to the DJGPP port. This subsection describes those -commands. - -`info dos' - This is a prefix of DJGPP-specific commands which print - information about the target system and important OS structures. - -`info dos sysinfo' - This command displays assorted information about the underlying - platform: the CPU type and features, the OS version and flavor, the - DPMI version, and the available conventional and DPMI memory. - -`info dos gdt' -`info dos ldt' -`info dos idt' - These 3 commands display entries from, respectively, Global, Local, - and Interrupt Descriptor Tables (GDT, LDT, and IDT). The - descriptor tables are data structures which store a descriptor for - each segment that is currently in use. The segment's selector is - an index into a descriptor table; the table entry for that index - holds the descriptor's base address and limit, and its attributes - and access rights. - - A typical DJGPP program uses 3 segments: a code segment, a data - segment (used for both data and the stack), and a DOS segment - (which allows access to DOS/BIOS data structures and absolute - addresses in conventional memory). However, the DPMI host will - usually define additional segments in order to support the DPMI - environment. - - These commands allow to display entries from the descriptor tables. - Without an argument, all entries from the specified table are - displayed. An argument, which should be an integer expression, - means display a single entry whose index is given by the argument. - For example, here's a convenient way to display information about - the debugged program's data segment: - - `(gdb) info dos ldt $ds' - `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' - - - This comes in handy when you want to see whether a pointer is - outside the data segment's limit (i.e. "garbled"). - -`info dos pde' -`info dos pte' - These two commands display entries from, respectively, the Page - Directory and the Page Tables. Page Directories and Page Tables - are data structures which control how virtual memory addresses are - mapped into physical addresses. A Page Table includes an entry - for every page of memory that is mapped into the program's address - space; there may be several Page Tables, each one holding up to - 4096 entries. A Page Directory has up to 4096 entries, one each - for every Page Table that is currently in use. - - Without an argument, `info dos pde' displays the entire Page - Directory, and `info dos pte' displays all the entries in all of - the Page Tables. An argument, an integer expression, given to the - `info dos pde' command means display only that entry from the Page - Directory table. An argument given to the `info dos pte' command - means display entries from a single Page Table, the one pointed to - by the specified entry in the Page Directory. - - These commands are useful when your program uses "DMA" (Direct - Memory Access), which needs physical addresses to program the DMA - controller. - - These commands are supported only with some DPMI servers. - -`info dos address-pte ADDR' - This command displays the Page Table entry for a specified linear - address. The argument ADDR is a linear address which should - already have the appropriate segment's base address added to it, - because this command accepts addresses which may belong to _any_ - segment. For example, here's how to display the Page Table entry - for the page where a variable `i' is stored: - - `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' - `Page Table entry for address 0x11a00d30:' - `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' - - - This says that `i' is stored at offset `0xd30' from the page whose - physical base address is `0x02698000', and shows all the - attributes of that page. - - Note that you must cast the addresses of variables to a `char *', - since otherwise the value of `__djgpp_base_address', the base - address of all variables and functions in a DJGPP program, will be - added using the rules of C pointer arithmetics: if `i' is declared - an `int', GDB will add 4 times the value of `__djgpp_base_address' - to the address of `i'. - - Here's another example, it displays the Page Table entry for the - transfer buffer: - - `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' - `Page Table entry for address 0x29110:' - `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' - - - (The `+ 3' offset is because the transfer buffer's address is the - 3rd member of the `_go32_info_block' structure.) The output - clearly shows that this DPMI server maps the addresses in - conventional memory 1:1, i.e. the physical (`0x00029000' + - `0x110') and linear (`0x29110') addresses are identical. - - This command is supported only with some DPMI servers. - - In addition to native debugging, the DJGPP port supports remote -debugging via a serial data link. The following commands are specific -to remote serial debugging in the DJGPP port of GDB. - -`set com1base ADDR' - This command sets the base I/O port address of the `COM1' serial - port. - -`set com1irq IRQ' - This command sets the "Interrupt Request" (`IRQ') line to use for - the `COM1' serial port. - - There are similar commands `set com2base', `set com3irq', etc. for - setting the port address and the `IRQ' lines for the other 3 COM - ports. - - The related commands `show com1base', `show com1irq' etc. display - the current settings of the base address and the `IRQ' lines used - by the COM ports. - -`info serial' - This command prints the status of the 4 DOS serial ports. For each - port, it prints whether it's active or not, its I/O base address - and IRQ number, whether it uses a 16550-style FIFO, its baudrate, - and the counts of various errors encountered so far. - - -File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native - -21.1.5 Features for Debugging MS Windows PE Executables -------------------------------------------------------- - -GDB supports native debugging of MS Windows programs, including DLLs -with and without symbolic debugging information. - - MS-Windows programs that call `SetConsoleMode' to switch off the -special meaning of the `Ctrl-C' keystroke cannot be interrupted by -typing `C-c'. For this reason, GDB on MS-Windows supports `C-<BREAK>' -as an alternative interrupt key sequence, which can be used to -interrupt the debuggee even if it ignores `C-c'. - - There are various additional Cygwin-specific commands, described in -this section. Working with DLLs that have no debugging symbols is -described in *note Non-debug DLL Symbols::. - -`info w32' - This is a prefix of MS Windows-specific commands which print - information about the target system and important OS structures. - -`info w32 selector' - This command displays information returned by the Win32 API - `GetThreadSelectorEntry' function. It takes an optional argument - that is evaluated to a long value to give the information about - this given selector. Without argument, this command displays - information about the six segment registers. - -`info w32 thread-information-block' - This command displays thread specific information stored in the - Thread Information Block (readable on the X86 CPU family using - `$fs' selector for 32-bit programs and `$gs' for 64-bit programs). - -`info dll' - This is a Cygwin-specific alias of `info shared'. - -`dll-symbols' - This command loads symbols from a dll similarly to add-sym command - but without the need to specify a base address. - -`set cygwin-exceptions MODE' - If MODE is `on', GDB will break on exceptions that happen inside - the Cygwin DLL. If MODE is `off', GDB will delay recognition of - exceptions, and may ignore some exceptions which seem to be caused - by internal Cygwin DLL "bookkeeping". This option is meant - primarily for debugging the Cygwin DLL itself; the default value - is `off' to avoid annoying GDB users with false `SIGSEGV' signals. - -`show cygwin-exceptions' - Displays whether GDB will break on exceptions that happen inside - the Cygwin DLL itself. - -`set new-console MODE' - If MODE is `on' the debuggee will be started in a new console on - next start. If MODE is `off', the debuggee will be started in the - same console as the debugger. - -`show new-console' - Displays whether a new console is used when the debuggee is - started. - -`set new-group MODE' - This boolean value controls whether the debuggee should start a - new group or stay in the same group as the debugger. This affects - the way the Windows OS handles `Ctrl-C'. - -`show new-group' - Displays current value of new-group boolean. - -`set debugevents' - This boolean value adds debug output concerning kernel events - related to the debuggee seen by the debugger. This includes - events that signal thread and process creation and exit, DLL - loading and unloading, console interrupts, and debugging messages - produced by the Windows `OutputDebugString' API call. - -`set debugexec' - This boolean value adds debug output concerning execute events - (such as resume thread) seen by the debugger. - -`set debugexceptions' - This boolean value adds debug output concerning exceptions in the - debuggee seen by the debugger. - -`set debugmemory' - This boolean value adds debug output concerning debuggee memory - reads and writes by the debugger. - -`set shell' - This boolean values specifies whether the debuggee is called via a - shell or directly (default value is on). - -`show shell' - Displays if the debuggee will be started with a shell. - - -* Menu: - -* Non-debug DLL Symbols:: Support for DLLs without debugging symbols - - -File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native - -21.1.5.1 Support for DLLs without Debugging Symbols -................................................... - -Very often on windows, some of the DLLs that your program relies on do -not include symbolic debugging information (for example, -`kernel32.dll'). When GDB doesn't recognize any debugging symbols in a -DLL, it relies on the minimal amount of symbolic information contained -in the DLL's export table. This section describes working with such -symbols, known internally to GDB as "minimal symbols". - - Note that before the debugged program has started execution, no DLLs -will have been loaded. The easiest way around this problem is simply to -start the program -- either by setting a breakpoint or letting the -program run once to completion. It is also possible to force GDB to -load a particular DLL before starting the executable -- see the shared -library information in *note Files::, or the `dll-symbols' command in -*note Cygwin Native::. Currently, explicitly loading symbols from a -DLL with no debugging information will cause the symbol names to be -duplicated in GDB's lookup table, which may adversely affect symbol -lookup performance. - -21.1.5.2 DLL Name Prefixes -.......................... - -In keeping with the naming conventions used by the Microsoft debugging -tools, DLL export symbols are made available with a prefix based on the -DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also -entered into the symbol table, so `CreateFileA' is often sufficient. -In some cases there will be name clashes within a program (particularly -if the executable itself includes full debugging symbols) necessitating -the use of the fully qualified name when referring to the contents of -the DLL. Use single-quotes around the name to avoid the exclamation -mark ("!") being interpreted as a language operator. - - Note that the internal name of the DLL may be all upper-case, even -though the file name of the DLL is lower-case, or vice-versa. Since -symbols within GDB are _case-sensitive_ this may cause some confusion. -If in doubt, try the `info functions' and `info variables' commands or -even `maint print msymbols' (*note Symbols::). Here's an example: - - (gdb) info function CreateFileA - All functions matching regular expression "CreateFileA": - - Non-debugging symbols: - 0x77e885f4 CreateFileA - 0x77e885f4 KERNEL32!CreateFileA - - (gdb) info function ! - All functions matching regular expression "!": - - Non-debugging symbols: - 0x6100114c cygwin1!__assert - 0x61004034 cygwin1!_dll_crt0@0 - 0x61004240 cygwin1!dll_crt0(per_process *) - [etc...] - -21.1.5.3 Working with Minimal Symbols -..................................... - -Symbols extracted from a DLL's export table do not contain very much -type information. All that GDB can do is guess whether a symbol refers -to a function or variable depending on the linker section that contains -the symbol. Also note that the actual contents of the memory contained -in a DLL are not available unless the program is running. This means -that you cannot examine the contents of a variable or disassemble a -function within a DLL without a running program. - - Variables are generally treated as pointers and dereferenced -automatically. For this reason, it is often necessary to prefix a -variable name with the address-of operator ("&") and provide explicit -type information in the command. Here's an example of the type of -problem: - - (gdb) print 'cygwin1!__argv' - $1 = 268572168 - - (gdb) x 'cygwin1!__argv' - 0x10021610: "\230y\"" - - And two possible solutions: - - (gdb) print ((char **)'cygwin1!__argv')[0] - $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" - - (gdb) x/2x &'cygwin1!__argv' - 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 - (gdb) x/x 0x10021608 - 0x10021608: 0x0022fd98 - (gdb) x/s 0x0022fd98 - 0x22fd98: "/cygdrive/c/mydirectory/myprogram" - - Setting a break point within a DLL is possible even before the -program starts execution. However, under these circumstances, GDB can't -examine the initial instructions of the function in order to skip the -function's frame set-up code. You can work around this by using "*&" to -set the breakpoint at a raw memory address: - - (gdb) break *&'python22!PyOS_Readline' - Breakpoint 1 at 0x1e04eff0 - - The author of these extensions is not entirely convinced that -setting a break point within a shared DLL like `kernel32.dll' is -completely safe. - - -File: gdb.info, Node: Hurd Native, Next: Neutrino, Prev: Cygwin Native, Up: Native - -21.1.6 Commands Specific to GNU Hurd Systems --------------------------------------------- - -This subsection describes GDB commands specific to the GNU Hurd native -debugging. - -`set signals' -`set sigs' - This command toggles the state of inferior signal interception by - GDB. Mach exceptions, such as breakpoint traps, are not affected - by this command. `sigs' is a shorthand alias for `signals'. - -`show signals' -`show sigs' - Show the current state of intercepting inferior's signals. - -`set signal-thread' -`set sigthread' - This command tells GDB which thread is the `libc' signal thread. - That thread is run when a signal is delivered to a running - process. `set sigthread' is the shorthand alias of `set - signal-thread'. - -`show signal-thread' -`show sigthread' - These two commands show which thread will run when the inferior is - delivered a signal. - -`set stopped' - This commands tells GDB that the inferior process is stopped, as - with the `SIGSTOP' signal. The stopped process can be continued - by delivering a signal to it. - -`show stopped' - This command shows whether GDB thinks the debuggee is stopped. - -`set exceptions' - Use this command to turn off trapping of exceptions in the - inferior. When exception trapping is off, neither breakpoints nor - single-stepping will work. To restore the default, set exception - trapping on. - -`show exceptions' - Show the current state of trapping exceptions in the inferior. - -`set task pause' - This command toggles task suspension when GDB has control. - Setting it to on takes effect immediately, and the task is - suspended whenever GDB gets control. Setting it to off will take - effect the next time the inferior is continued. If this option is - set to off, you can use `set thread default pause on' or `set - thread pause on' (see below) to pause individual threads. - -`show task pause' - Show the current state of task suspension. - -`set task detach-suspend-count' - This command sets the suspend count the task will be left with when - GDB detaches from it. - -`show task detach-suspend-count' - Show the suspend count the task will be left with when detaching. - -`set task exception-port' -`set task excp' - This command sets the task exception port to which GDB will - forward exceptions. The argument should be the value of the "send - rights" of the task. `set task excp' is a shorthand alias. - -`set noninvasive' - This command switches GDB to a mode that is the least invasive as - far as interfering with the inferior is concerned. This is the - same as using `set task pause', `set exceptions', and `set - signals' to values opposite to the defaults. - -`info send-rights' -`info receive-rights' -`info port-rights' -`info port-sets' -`info dead-names' -`info ports' -`info psets' - These commands display information about, respectively, send - rights, receive rights, port rights, port sets, and dead names of - a task. There are also shorthand aliases: `info ports' for `info - port-rights' and `info psets' for `info port-sets'. - -`set thread pause' - This command toggles current thread suspension when GDB has - control. Setting it to on takes effect immediately, and the - current thread is suspended whenever GDB gets control. Setting it - to off will take effect the next time the inferior is continued. - Normally, this command has no effect, since when GDB has control, - the whole task is suspended. However, if you used `set task pause - off' (see above), this command comes in handy to suspend only the - current thread. - -`show thread pause' - This command shows the state of current thread suspension. - -`set thread run' - This command sets whether the current thread is allowed to run. - -`show thread run' - Show whether the current thread is allowed to run. - -`set thread detach-suspend-count' - This command sets the suspend count GDB will leave on a thread - when detaching. This number is relative to the suspend count - found by GDB when it notices the thread; use `set thread - takeover-suspend-count' to force it to an absolute value. - -`show thread detach-suspend-count' - Show the suspend count GDB will leave on the thread when detaching. - -`set thread exception-port' -`set thread excp' - Set the thread exception port to which to forward exceptions. This - overrides the port set by `set task exception-port' (see above). - `set thread excp' is the shorthand alias. - -`set thread takeover-suspend-count' - Normally, GDB's thread suspend counts are relative to the value - GDB finds when it notices each thread. This command changes the - suspend counts to be absolute instead. - -`set thread default' -`show thread default' - Each of the above `set thread' commands has a `set thread default' - counterpart (e.g., `set thread default pause', `set thread default - exception-port', etc.). The `thread default' variety of commands - sets the default thread properties for all threads; you can then - change the properties of individual threads with the non-default - commands. - - -File: gdb.info, Node: Neutrino, Next: Darwin, Prev: Hurd Native, Up: Native - -21.1.7 QNX Neutrino -------------------- - -GDB provides the following commands specific to the QNX Neutrino target: - -`set debug nto-debug' - When set to on, enables debugging messages specific to the QNX - Neutrino support. - -`show debug nto-debug' - Show the current state of QNX Neutrino messages. - - -File: gdb.info, Node: Darwin, Prev: Neutrino, Up: Native - -21.1.8 Darwin -------------- - -GDB provides the following commands specific to the Darwin target: - -`set debug darwin NUM' - When set to a non zero value, enables debugging messages specific - to the Darwin support. Higher values produce more verbose output. - -`show debug darwin' - Show the current state of Darwin messages. - -`set debug mach-o NUM' - When set to a non zero value, enables debugging messages while GDB - is reading Darwin object files. ("Mach-O" is the file format used - on Darwin for object and executable files.) Higher values produce - more verbose output. This is a command to diagnose problems - internal to GDB and should not be needed in normal usage. - -`show debug mach-o' - Show the current state of Mach-O file messages. - -`set mach-exceptions on' -`set mach-exceptions off' - On Darwin, faults are first reported as a Mach exception and are - then mapped to a Posix signal. Use this command to turn on - trapping of Mach exceptions in the inferior. This might be - sometimes useful to better understand the cause of a fault. The - default is off. - -`show mach-exceptions' - Show the current state of exceptions trapping. - - -File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations - -21.2 Embedded Operating Systems -=============================== - -This section describes configurations involving the debugging of -embedded operating systems that are available for several different -architectures. - -* Menu: - -* VxWorks:: Using GDB with VxWorks - - GDB includes the ability to debug programs running on various -real-time operating systems. - - -File: gdb.info, Node: VxWorks, Up: Embedded OS - -21.2.1 Using GDB with VxWorks ------------------------------ - -`target vxworks MACHINENAME' - A VxWorks system, attached via TCP/IP. The argument MACHINENAME - is the target system's machine name or IP address. - - - On VxWorks, `load' links FILENAME dynamically on the current target -system as well as adding its symbols in GDB. - - GDB enables developers to spawn and debug tasks running on networked -VxWorks targets from a Unix host. Already-running tasks spawned from -the VxWorks shell can also be debugged. GDB uses code that runs on -both the Unix host and on the VxWorks target. The program `gdb' is -installed and executed on the Unix host. (It may be installed with the -name `vxgdb', to distinguish it from a GDB for debugging programs on -the host itself.) - -`VxWorks-timeout ARGS' - All VxWorks-based targets now support the option `vxworks-timeout'. - This option is set by the user, and ARGS represents the number of - seconds GDB waits for responses to rpc's. You might use this if - your VxWorks target is a slow software simulator or is on the far - side of a thin network line. - - The following information on connecting to VxWorks was current when -this manual was produced; newer releases of VxWorks may use revised -procedures. - - To use GDB with VxWorks, you must rebuild your VxWorks kernel to -include the remote debugging interface routines in the VxWorks library -`rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration -file `configAll.h' and rebuild your VxWorks kernel. The resulting -kernel contains `rdb.a', and spawns the source debugging task -`tRdbTask' when VxWorks is booted. For more information on configuring -and remaking VxWorks, see the manufacturer's manual. - - Once you have included `rdb.a' in your VxWorks system image and set -your Unix execution search path to find GDB, you are ready to run GDB. -From your Unix host, run `gdb' (or `vxgdb', depending on your -installation). - - GDB comes up showing the prompt: - - (vxgdb) - -* Menu: - -* VxWorks Connection:: Connecting to VxWorks -* VxWorks Download:: VxWorks download -* VxWorks Attach:: Running tasks - - -File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks - -21.2.1.1 Connecting to VxWorks -.............................. - -The GDB command `target' lets you connect to a VxWorks target on the -network. To connect to a target whose host name is "`tt'", type: - - (vxgdb) target vxworks tt - - GDB displays messages like these: - - Attaching remote machine across net... - Connected to tt. - - GDB then attempts to read the symbol tables of any object modules -loaded into the VxWorks target since it was last booted. GDB locates -these files by searching the directories listed in the command search -path (*note Your Program's Environment: Environment.); if it fails to -find an object file, it displays a message such as: - - prog.o: No such file or directory. - - When this happens, add the appropriate directory to the search path -with the GDB command `path', and execute the `target' command again. - - -File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks - -21.2.1.2 VxWorks Download -......................... - -If you have connected to the VxWorks target and you want to debug an -object that has not yet been loaded, you can use the GDB `load' command -to download a file from Unix to VxWorks incrementally. The object file -given as an argument to the `load' command is actually opened twice: -first by the VxWorks target in order to download the code, then by GDB -in order to read the symbol table. This can lead to problems if the -current working directories on the two systems differ. If both systems -have NFS mounted the same filesystems, you can avoid these problems by -using absolute paths. Otherwise, it is simplest to set the working -directory on both systems to the directory in which the object file -resides, and then to reference the file by its name, without any path. -For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in -VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this -program, type this on VxWorks: - - -> cd "VXPATH/vw/demo/rdb" - -Then, in GDB, type: - - (vxgdb) cd HOSTPATH/vw/demo/rdb - (vxgdb) load prog.o - - GDB displays a response similar to this: - - Reading symbol data from wherever/vw/demo/rdb/prog.o... done. - - You can also use the `load' command to reload an object module after -editing and recompiling the corresponding source file. Note that this -makes GDB delete all currently-defined breakpoints, auto-displays, and -convenience variables, and to clear the value history. (This is -necessary in order to preserve the integrity of debugger's data -structures that reference the target system's symbol table.) - - -File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks - -21.2.1.3 Running Tasks -...................... - -You can also attach to an existing task using the `attach' command as -follows: - - (vxgdb) attach TASK - -where TASK is the VxWorks hexadecimal task ID. The task can be running -or suspended when you attach to it. Running tasks are suspended at the -time of attachment. - - -File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations - -21.3 Embedded Processors -======================== - -This section goes into details specific to particular embedded -configurations. - - Whenever a specific embedded processor has a simulator, GDB allows -to send an arbitrary command to the simulator. - -`sim COMMAND' - Send an arbitrary COMMAND string to the simulator. Consult the - documentation for the specific simulator in use for information - about acceptable commands. - -* Menu: - -* ARM:: ARM RDI -* M32R/D:: Renesas M32R/D -* M68K:: Motorola M68K -* MicroBlaze:: Xilinx MicroBlaze -* MIPS Embedded:: MIPS Embedded -* OpenRISC 1000:: OpenRisc 1000 -* PA:: HP PA Embedded -* PowerPC Embedded:: PowerPC Embedded -* Sparclet:: Tsqware Sparclet -* Sparclite:: Fujitsu Sparclite -* Z8000:: Zilog Z8000 -* AVR:: Atmel AVR -* CRIS:: CRIS -* Super-H:: Renesas Super-H - - -File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors - -21.3.1 ARM ----------- - -`target rdi DEV' - ARM Angel monitor, via RDI library interface to ADP protocol. You - may use this target to communicate with both boards running the - Angel monitor, or with the EmbeddedICE JTAG debug device. - -`target rdp DEV' - ARM Demon monitor. - - - GDB provides the following ARM-specific commands: - -`set arm disassembler' - This commands selects from a list of disassembly styles. The - `"std"' style is the standard style. - -`show arm disassembler' - Show the current disassembly style. - -`set arm apcs32' - This command toggles ARM operation mode between 32-bit and 26-bit. - -`show arm apcs32' - Display the current usage of the ARM 32-bit mode. - -`set arm fpu FPUTYPE' - This command sets the ARM floating-point unit (FPU) type. The - argument FPUTYPE can be one of these: - - `auto' - Determine the FPU type by querying the OS ABI. - - `softfpa' - Software FPU, with mixed-endian doubles on little-endian ARM - processors. - - `fpa' - GCC-compiled FPA co-processor. - - `softvfp' - Software FPU with pure-endian doubles. - - `vfp' - VFP co-processor. - -`show arm fpu' - Show the current type of the FPU. - -`set arm abi' - This command forces GDB to use the specified ABI. - -`show arm abi' - Show the currently used ABI. - -`set arm fallback-mode (arm|thumb|auto)' - GDB uses the symbol table, when available, to determine whether - instructions are ARM or Thumb. This command controls GDB's - default behavior when the symbol table is not available. The - default is `auto', which causes GDB to use the current execution - mode (from the `T' bit in the `CPSR' register). - -`show arm fallback-mode' - Show the current fallback instruction mode. - -`set arm force-mode (arm|thumb|auto)' - This command overrides use of the symbol table to determine whether - instructions are ARM or Thumb. The default is `auto', which - causes GDB to use the symbol table and then the setting of `set - arm fallback-mode'. - -`show arm force-mode' - Show the current forced instruction mode. - -`set debug arm' - Toggle whether to display ARM-specific debugging messages from the - ARM target support subsystem. - -`show debug arm' - Show whether ARM-specific debugging messages are enabled. - - The following commands are available when an ARM target is debugged -using the RDI interface: - -`rdilogfile [FILE]' - Set the filename for the ADP (Angel Debugger Protocol) packet log. - With an argument, sets the log file to the specified FILE. With - no argument, show the current log file name. The default log file - is `rdi.log'. - -`rdilogenable [ARG]' - Control logging of ADP packets. With an argument of 1 or `"yes"' - enables logging, with an argument 0 or `"no"' disables it. With - no arguments displays the current setting. When logging is - enabled, ADP packets exchanged between GDB and the RDI target - device are logged to a file. - -`set rdiromatzero' - Tell GDB whether the target has ROM at address 0. If on, vector - catching is disabled, so that zero address can be used. If off - (the default), vector catching is enabled. For this command to - take effect, it needs to be invoked prior to the `target rdi' - command. - -`show rdiromatzero' - Show the current setting of ROM at zero address. - -`set rdiheartbeat' - Enable or disable RDI heartbeat packets. It is not recommended to - turn on this option, since it confuses ARM and EPI JTAG interface, - as well as the Angel monitor. - -`show rdiheartbeat' - Show the setting of RDI heartbeat packets. - -`target sim [SIMARGS] ...' - The GDB ARM simulator accepts the following optional arguments. - - `--swi-support=TYPE' - Tell the simulator which SWI interfaces to support. TYPE may - be a comma separated list of the following values. The - default value is `all'. - - `none' - - `demon' - - `angel' - - `redboot' - - `all' - - -File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors - -21.3.2 Renesas M32R/D and M32R/SDI ----------------------------------- - -`target m32r DEV' - Renesas M32R/D ROM monitor. - -`target m32rsdi DEV' - Renesas M32R SDI server, connected via parallel port to the board. - - The following GDB commands are specific to the M32R monitor: - -`set download-path PATH' - Set the default path for finding downloadable SREC files. - -`show download-path' - Show the default path for downloadable SREC files. - -`set board-address ADDR' - Set the IP address for the M32R-EVA target board. - -`show board-address' - Show the current IP address of the target board. - -`set server-address ADDR' - Set the IP address for the download server, which is the GDB's - host machine. - -`show server-address' - Display the IP address of the download server. - -`upload [FILE]' - Upload the specified SREC FILE via the monitor's Ethernet upload - capability. If no FILE argument is given, the current executable - file is uploaded. - -`tload [FILE]' - Test the `upload' command. - - The following commands are available for M32R/SDI: - -`sdireset' - This command resets the SDI connection. - -`sdistatus' - This command shows the SDI connection status. - -`debug_chaos' - Instructs the remote that M32R/Chaos debugging is to be used. - -`use_debug_dma' - Instructs the remote to use the DEBUG_DMA method of accessing - memory. - -`use_mon_code' - Instructs the remote to use the MON_CODE method of accessing - memory. - -`use_ib_break' - Instructs the remote to set breakpoints by IB break. - -`use_dbt_break' - Instructs the remote to set breakpoints by DBT. - - -File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: M32R/D, Up: Embedded Processors - -21.3.3 M68k ------------ - -The Motorola m68k configuration includes ColdFire support, and a target -command for the following ROM monitor. - -`target dbug DEV' - dBUG ROM monitor for Motorola ColdFire. - - - -File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors - -21.3.4 MicroBlaze ------------------ - -The MicroBlaze is a soft-core processor supported on various Xilinx -FPGAs, such as Spartan or Virtex series. Boards with these processors -usually have JTAG ports which connect to a host system running the -Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). -This host system is used to download the configuration bitstream to the -target FPGA. The Xilinx Microprocessor Debugger (XMD) program -communicates with the target board using the JTAG interface and -presents a `gdbserver' interface to the board. By default `xmd' uses -port `1234'. (While it is possible to change this default port, it -requires the use of undocumented `xmd' commands. Contact Xilinx -support if you need to do this.) - - Use these GDB commands to connect to the MicroBlaze target processor. - -`target remote :1234' - Use this command to connect to the target if you are running GDB - on the same system as `xmd'. - -`target remote XMD-HOST:1234' - Use this command to connect to the target if it is connected to - `xmd' running on a different system named XMD-HOST. - -`load' - Use this command to download a program to the MicroBlaze target. - -`set debug microblaze N' - Enable MicroBlaze-specific debugging messages if non-zero. - -`show debug microblaze N' - Show MicroBlaze-specific debugging level. - - -File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors - -21.3.5 MIPS Embedded --------------------- - -GDB can use the MIPS remote debugging protocol to talk to a MIPS board -attached to a serial line. This is available when you configure GDB -with `--target=mips-idt-ecoff'. - - Use these GDB commands to specify the connection to your target -board: - -`target mips PORT' - To run a program on the board, start up `gdb' with the name of - your program as the argument. To connect to the board, use the - command `target mips PORT', where PORT is the name of the serial - port connected to the board. If the program has not already been - downloaded to the board, you may use the `load' command to - download it. You can then use all the usual GDB commands. - - For example, this sequence connects to the target board through a - serial port, and loads and runs a program called PROG through the - debugger: - - host$ gdb PROG - GDB is free software and ... - (gdb) target mips /dev/ttyb - (gdb) load PROG - (gdb) run - -`target mips HOSTNAME:PORTNUMBER' - On some GDB host configurations, you can specify a TCP connection - (for instance, to a serial line managed by a terminal - concentrator) instead of a serial port, using the syntax - `HOSTNAME:PORTNUMBER'. - -`target pmon PORT' - PMON ROM monitor. - -`target ddb PORT' - NEC's DDB variant of PMON for Vr4300. - -`target lsi PORT' - LSI variant of PMON. - -`target r3900 DEV' - Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. - -`target array DEV' - Array Tech LSI33K RAID controller board. - - -GDB also supports these special commands for MIPS targets: - -`set mipsfpu double' -`set mipsfpu single' -`set mipsfpu none' -`set mipsfpu auto' -`show mipsfpu' - If your target board does not support the MIPS floating point - coprocessor, you should use the command `set mipsfpu none' (if you - need this, you may wish to put the command in your GDB init file). - This tells GDB how to find the return value of functions which - return floating point values. It also allows GDB to avoid saving - the floating point registers when calling functions on the board. - If you are using a floating point coprocessor with only single - precision floating point support, as on the R4650 processor, use - the command `set mipsfpu single'. The default double precision - floating point coprocessor may be selected using `set mipsfpu - double'. - - In previous versions the only choices were double precision or no - floating point, so `set mipsfpu on' will select double precision - and `set mipsfpu off' will select no floating point. - - As usual, you can inquire about the `mipsfpu' variable with `show - mipsfpu'. - -`set timeout SECONDS' -`set retransmit-timeout SECONDS' -`show timeout' -`show retransmit-timeout' - You can control the timeout used while waiting for a packet, in - the MIPS remote protocol, with the `set timeout SECONDS' command. - The default is 5 seconds. Similarly, you can control the timeout - used while waiting for an acknowledgment of a packet with the `set - retransmit-timeout SECONDS' command. The default is 3 seconds. - You can inspect both values with `show timeout' and `show - retransmit-timeout'. (These commands are _only_ available when - GDB is configured for `--target=mips-idt-ecoff'.) - - The timeout set by `set timeout' does not apply when GDB is - waiting for your program to stop. In that case, GDB waits forever - because it has no way of knowing how long the program is going to - run before stopping. - -`set syn-garbage-limit NUM' - Limit the maximum number of characters GDB should ignore when it - tries to synchronize with the remote target. The default is 10 - characters. Setting the limit to -1 means there's no limit. - -`show syn-garbage-limit' - Show the current limit on the number of characters to ignore when - trying to synchronize with the remote system. - -`set monitor-prompt PROMPT' - Tell GDB to expect the specified PROMPT string from the remote - monitor. The default depends on the target: - pmon target - `PMON' - - ddb target - `NEC010' - - lsi target - `PMON>' - -`show monitor-prompt' - Show the current strings GDB expects as the prompt from the remote - monitor. - -`set monitor-warnings' - Enable or disable monitor warnings about hardware breakpoints. - This has effect only for the `lsi' target. When on, GDB will - display warning messages whose codes are returned by the `lsi' - PMON monitor for breakpoint commands. - -`show monitor-warnings' - Show the current setting of printing monitor warnings. - -`pmon COMMAND' - This command allows sending an arbitrary COMMAND string to the - monitor. The monitor must be in debug mode for this to work. - - -File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors - -21.3.6 OpenRISC 1000 --------------------- - -See OR1k Architecture document (`www.opencores.org') for more -information about platform and commands. - -`target jtag jtag://HOST:PORT' - Connects to remote JTAG server. JTAG remote server can be either - an or1ksim or JTAG server, connected via parallel port to the - board. - - Example: `target jtag jtag://localhost:9999' - -`or1ksim COMMAND' - If connected to `or1ksim' OpenRISC 1000 Architectural Simulator, - proprietary commands can be executed. - -`info or1k spr' - Displays spr groups. - -`info or1k spr GROUP' -`info or1k spr GROUPNO' - Displays register names in selected group. - -`info or1k spr GROUP REGISTER' -`info or1k spr REGISTER' -`info or1k spr GROUPNO REGISTERNO' -`info or1k spr REGISTERNO' - Shows information about specified spr register. - -`spr GROUP REGISTER VALUE' -`spr REGISTER VALUE' -`spr GROUPNO REGISTERNO VALUE' -`spr REGISTERNO VALUE' - Writes VALUE to specified spr register. - - Some implementations of OpenRISC 1000 Architecture also have -hardware trace. It is very similar to GDB trace, except it does not -interfere with normal program execution and is thus much faster. -Hardware breakpoints/watchpoint triggers can be set using: -`$LEA/$LDATA' - Load effective address/data - -`$SEA/$SDATA' - Store effective address/data - -`$AEA/$ADATA' - Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) - -`$FETCH' - Fetch data - - When triggered, it can capture low level data, like: `PC', `LSEA', -`LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'. - - `htrace' commands: -`hwatch CONDITIONAL' - Set hardware watchpoint on combination of Load/Store Effective - Address(es) or Data. For example: - - `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && - ($SDATA >= 50)' - - `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && - ($SDATA >= 50)' - -`htrace info' - Display information about current HW trace configuration. - -`htrace trigger CONDITIONAL' - Set starting criteria for HW trace. - -`htrace qualifier CONDITIONAL' - Set acquisition qualifier for HW trace. - -`htrace stop CONDITIONAL' - Set HW trace stopping criteria. - -`htrace record [DATA]*' - Selects the data to be recorded, when qualifier is met and HW - trace was triggered. - -`htrace enable' -`htrace disable' - Enables/disables the HW trace. - -`htrace rewind [FILENAME]' - Clears currently recorded trace data. - - If filename is specified, new trace file is made and any newly - collected data will be written there. - -`htrace print [START [LEN]]' - Prints trace buffer, using current record configuration. - -`htrace mode continuous' - Set continuous trace mode. - -`htrace mode suspend' - Set suspend trace mode. - - - -File: gdb.info, Node: PowerPC Embedded, Next: Sparclet, Prev: PA, Up: Embedded Processors - -21.3.7 PowerPC Embedded ------------------------ - -GDB supports using the DVC (Data Value Compare) register to implement -in hardware simple hardware watchpoint conditions of the form: - - (gdb) watch ADDRESS|VARIABLE \ - if ADDRESS|VARIABLE == CONSTANT EXPRESSION - - The DVC register will be automatically used when GDB detects such -pattern in a condition expression, and the created watchpoint uses one -debug register (either the `exact-watchpoints' option is on and the -variable is scalar, or the variable has a length of one byte). This -feature is available in native GDB running on a Linux kernel version -2.6.34 or newer. - - When running on PowerPC embedded processors, GDB automatically uses -ranged hardware watchpoints, unless the `exact-watchpoints' option is -on, in which case watchpoints using only one debug register are created -when watching variables of scalar types. - - You can create an artificial array to watch an arbitrary memory -region using one of the following commands (*note Expressions::): - - (gdb) watch *((char *) ADDRESS)@LENGTH - (gdb) watch {char[LENGTH]} ADDRESS - - PowerPC embedded processors support hardware accelerated "ranged -breakpoints". A ranged breakpoint stops execution of the inferior -whenever it executes an instruction at any address within the range it -specifies. To set a ranged breakpoint in GDB, use the `break-range' -command. - - GDB provides the following PowerPC-specific commands: - -`break-range START-LOCATION, END-LOCATION' - Set a breakpoint for an address range. START-LOCATION and - END-LOCATION can specify a function name, a line number, an offset - of lines from the current line or from the start location, or an - address of an instruction (see *note Specify Location::, for a - list of all the possible ways to specify a LOCATION.) The - breakpoint will stop execution of the inferior whenever it - executes an instruction at any address within the specified range, - (including START-LOCATION and END-LOCATION.) - -`set powerpc soft-float' -`show powerpc soft-float' - Force GDB to use (or not use) a software floating point calling - convention. By default, GDB selects the calling convention based - on the selected architecture and the provided executable file. - -`set powerpc vector-abi' -`show powerpc vector-abi' - Force GDB to use the specified calling convention for vector - arguments and return values. The valid options are `auto'; - `generic', to avoid vector registers even if they are present; - `altivec', to use AltiVec registers; and `spe' to use SPE - registers. By default, GDB selects the calling convention based - on the selected architecture and the provided executable file. - -`set powerpc exact-watchpoints' -`show powerpc exact-watchpoints' - Allow GDB to use only one debug register when watching a variable - of scalar type, thus assuming that the variable is accessed - through the address of its first byte. - -`target dink32 DEV' - DINK32 ROM monitor. - -`target ppcbug DEV' - -`target ppcbug1 DEV' - PPCBUG ROM monitor for PowerPC. - -`target sds DEV' - SDS monitor, running on a PowerPC board (such as Motorola's ADS). - - The following commands specific to the SDS protocol are supported by -GDB: - -`set sdstimeout NSEC' - Set the timeout for SDS protocol reads to be NSEC seconds. The - default is 2 seconds. - -`show sdstimeout' - Show the current value of the SDS timeout. - -`sds COMMAND' - Send the specified COMMAND string to the SDS monitor. - - -File: gdb.info, Node: PA, Next: PowerPC Embedded, Prev: OpenRISC 1000, Up: Embedded Processors - -21.3.8 HP PA Embedded ---------------------- - -`target op50n DEV' - OP50N monitor, running on an OKI HPPA board. - -`target w89k DEV' - W89K monitor, running on a Winbond HPPA board. - - - -File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PowerPC Embedded, Up: Embedded Processors - -21.3.9 Tsqware Sparclet ------------------------ - -GDB enables developers to debug tasks running on Sparclet targets from -a Unix host. GDB uses code that runs on both the Unix host and on the -Sparclet target. The program `gdb' is installed and executed on the -Unix host. - -`remotetimeout ARGS' - GDB supports the option `remotetimeout'. This option is set by - the user, and ARGS represents the number of seconds GDB waits for - responses. - - When compiling for debugging, include the options `-g' to get debug -information and `-Ttext' to relocate the program to where you wish to -load it on the target. You may also want to add the options `-n' or -`-N' in order to reduce the size of the sections. Example: - - sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N - - You can use `objdump' to verify that the addresses are what you -intended: - - sparclet-aout-objdump --headers --syms prog - - Once you have set your Unix execution search path to find GDB, you -are ready to run GDB. From your Unix host, run `gdb' (or -`sparclet-aout-gdb', depending on your installation). - - GDB comes up showing the prompt: - - (gdbslet) - -* Menu: - -* Sparclet File:: Setting the file to debug -* Sparclet Connection:: Connecting to Sparclet -* Sparclet Download:: Sparclet download -* Sparclet Execution:: Running and debugging - - -File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet - -21.3.9.1 Setting File to Debug -.............................. - -The GDB command `file' lets you choose with program to debug. - - (gdbslet) file prog - - GDB then attempts to read the symbol table of `prog'. GDB locates -the file by searching the directories listed in the command search path. -If the file was compiled with debug information (option `-g'), source -files will be searched as well. GDB locates the source files by -searching the directories listed in the directory search path (*note -Your Program's Environment: Environment.). If it fails to find a file, -it displays a message such as: - - prog: No such file or directory. - - When this happens, add the appropriate directories to the search -paths with the GDB commands `path' and `dir', and execute the `target' -command again. - - -File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet - -21.3.9.2 Connecting to Sparclet -............................... - -The GDB command `target' lets you connect to a Sparclet target. To -connect to a target on serial port "`ttya'", type: - - (gdbslet) target sparclet /dev/ttya - Remote target sparclet connected to /dev/ttya - main () at ../prog.c:3 - - GDB displays messages like these: - - Connected to ttya. - - -File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet - -21.3.9.3 Sparclet Download -.......................... - -Once connected to the Sparclet target, you can use the GDB `load' -command to download the file from the host to the target. The file -name and load offset should be given as arguments to the `load' command. -Since the file format is aout, the program must be loaded to the -starting address. You can use `objdump' to find out what this value -is. The load offset is an offset which is added to the VMA (virtual -memory address) of each of the file's sections. For instance, if the -program `prog' was linked to text address 0x1201000, with data at -0x12010160 and bss at 0x12010170, in GDB, type: - - (gdbslet) load prog 0x12010000 - Loading section .text, size 0xdb0 vma 0x12010000 - - If the code is loaded at a different address then what the program -was linked to, you may need to use the `section' and `add-symbol-file' -commands to tell GDB where to map the symbol table. - - -File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet - -21.3.9.4 Running and Debugging -.............................. - -You can now begin debugging the task using GDB's execution control -commands, `b', `step', `run', etc. See the GDB manual for the list of -commands. - - (gdbslet) b main - Breakpoint 1 at 0x12010000: file prog.c, line 3. - (gdbslet) run - Starting program: prog - Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 - 3 char *symarg = 0; - (gdbslet) step - 4 char *execarg = "hello!"; - (gdbslet) - - -File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors - -21.3.10 Fujitsu Sparclite -------------------------- - -`target sparclite DEV' - Fujitsu sparclite boards, used only for the purpose of loading. - You must use an additional command to debug the program. For - example: target remote DEV using GDB standard remote protocol. - - - -File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors - -21.3.11 Zilog Z8000 -------------------- - -When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 -simulator. - - For the Z8000 family, `target sim' simulates either the Z8002 (the -unsegmented variant of the Z8000 architecture) or the Z8001 (the -segmented variant). The simulator recognizes which architecture is -appropriate by inspecting the object code. - -`target sim ARGS' - Debug programs on a simulated CPU. If the simulator supports setup - options, specify them via ARGS. - -After specifying this target, you can debug programs for the simulated -CPU in the same style as programs for your host computer; use the -`file' command to load a new program image, the `run' command to run -your program, and so on. - - As well as making available all the usual machine registers (*note -Registers: Registers.), the Z8000 simulator provides three additional -items of information as specially named registers: - -`cycles' - Counts clock-ticks in the simulator. - -`insts' - Counts instructions run in the simulator. - -`time' - Execution time in 60ths of a second. - - - You can refer to these values in GDB expressions with the usual -conventions; for example, `b fputc if $cycles>5000' sets a conditional -breakpoint that suspends only after at least 5000 simulated clock ticks. - - -File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors - -21.3.12 Atmel AVR ------------------ - -When configured for debugging the Atmel AVR, GDB supports the following -AVR-specific commands: - -`info io_registers' - This command displays information about the AVR I/O registers. For - each register, GDB prints its number and value. - - -File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors - -21.3.13 CRIS ------------- - -When configured for debugging CRIS, GDB provides the following -CRIS-specific commands: - -`set cris-version VER' - Set the current CRIS version to VER, either `10' or `32'. The - CRIS version affects register names and sizes. This command is - useful in case autodetection of the CRIS version fails. - -`show cris-version' - Show the current CRIS version. - -`set cris-dwarf2-cfi' - Set the usage of DWARF-2 CFI for CRIS debugging. The default is - `on'. Change to `off' when using `gcc-cris' whose version is below - `R59'. - -`show cris-dwarf2-cfi' - Show the current state of using DWARF-2 CFI. - -`set cris-mode MODE' - Set the current CRIS mode to MODE. It should only be changed when - debugging in guru mode, in which case it should be set to `guru' - (the default is `normal'). - -`show cris-mode' - Show the current CRIS mode. - - -File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors - -21.3.14 Renesas Super-H ------------------------ - -For the Renesas Super-H processor, GDB provides these commands: - -`regs' - Show the values of all Super-H registers. - -`set sh calling-convention CONVENTION' - Set the calling-convention used when calling functions from GDB. - Allowed values are `gcc', which is the default setting, and - `renesas'. With the `gcc' setting, functions are called using the - GCC calling convention. If the DWARF-2 information of the called - function specifies that the function follows the Renesas calling - convention, the function is called using the Renesas calling - convention. If the calling convention is set to `renesas', the - Renesas calling convention is always used, regardless of the - DWARF-2 information. This can be used to override the default of - `gcc' if debug information is missing, or the compiler does not - emit the DWARF-2 calling convention entry for a function. - -`show sh calling-convention' - Show the current calling convention setting. - - - -File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations - -21.4 Architectures -================== - -This section describes characteristics of architectures that affect all -uses of GDB with the architecture, both native and cross. - -* Menu: - -* i386:: -* A29K:: -* Alpha:: -* MIPS:: -* HPPA:: HP PA architecture -* SPU:: Cell Broadband Engine SPU architecture -* PowerPC:: - - -File: gdb.info, Node: i386, Next: A29K, Up: Architectures - -21.4.1 x86 Architecture-specific Issues ---------------------------------------- - -`set struct-convention MODE' - Set the convention used by the inferior to return `struct's and - `union's from functions to MODE. Possible values of MODE are - `"pcc"', `"reg"', and `"default"' (the default). `"default"' or - `"pcc"' means that `struct's are returned on the stack, while - `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, - or 8 bytes will be returned in a register. - -`show struct-convention' - Show the current setting of the convention to return `struct's - from functions. - - -File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures - -21.4.2 A29K ------------ - -`set rstack_high_address ADDRESS' - On AMD 29000 family processors, registers are saved in a separate - "register stack". There is no way for GDB to determine the extent - of this stack. Normally, GDB just assumes that the stack is - "large enough". This may result in GDB referencing memory - locations that do not exist. If necessary, you can get around - this problem by specifying the ending address of the register - stack with the `set rstack_high_address' command. The argument - should be an address, which you probably want to precede with `0x' - to specify in hexadecimal. - -`show rstack_high_address' - Display the current limit of the register stack, on AMD 29000 - family processors. - - - -File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures - -21.4.3 Alpha ------------- - -See the following section. - - -File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures - -21.4.4 MIPS ------------ - -Alpha- and MIPS-based computers use an unusual stack frame, which -sometimes requires GDB to search backward in the object code to find -the beginning of a function. - - To improve response time (especially for embedded applications, where -GDB may be restricted to a slow serial line for this search) you may -want to limit the size of this search, using one of these commands: - -`set heuristic-fence-post LIMIT' - Restrict GDB to examining at most LIMIT bytes in its search for - the beginning of a function. A value of 0 (the default) means - there is no limit. However, except for 0, the larger the limit - the more bytes `heuristic-fence-post' must search and therefore - the longer it takes to run. You should only need to use this - command when debugging a stripped executable. - -`show heuristic-fence-post' - Display the current limit. - -These commands are available _only_ when GDB is configured for -debugging programs on Alpha or MIPS processors. - - Several MIPS-specific commands are available when debugging MIPS -programs: - -`set mips abi ARG' - Tell GDB which MIPS ABI is used by the inferior. Possible values - of ARG are: - - `auto' - The default ABI associated with the current binary (this is - the default). - - `o32' - - `o64' - - `n32' - - `n64' - - `eabi32' - - `eabi64' - - `auto' - -`show mips abi' - Show the MIPS ABI used by GDB to debug the inferior. - -`set mipsfpu' -`show mipsfpu' - *Note set mipsfpu: MIPS Embedded. - -`set mips mask-address ARG' - This command determines whether the most-significant 32 bits of - 64-bit MIPS addresses are masked off. The argument ARG can be - `on', `off', or `auto'. The latter is the default setting, which - lets GDB determine the correct value. - -`show mips mask-address' - Show whether the upper 32 bits of MIPS addresses are masked off or - not. - -`set remote-mips64-transfers-32bit-regs' - This command controls compatibility with 64-bit MIPS targets that - transfer data in 32-bit quantities. If you have an old MIPS 64 - target that transfers 32 bits for some registers, like SR and FSR, - and 64 bits for other registers, set this option to `on'. - -`show remote-mips64-transfers-32bit-regs' - Show the current setting of compatibility with older MIPS 64 - targets. - -`set debug mips' - This command turns on and off debugging messages for the - MIPS-specific target code in GDB. - -`show debug mips' - Show the current setting of MIPS debugging messages. - - -File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures - -21.4.5 HPPA ------------ - -When GDB is debugging the HP PA architecture, it provides the following -special commands: - -`set debug hppa' - This command determines whether HPPA architecture-specific - debugging messages are to be displayed. - -`show debug hppa' - Show whether HPPA debugging messages are displayed. - -`maint print unwind ADDRESS' - This command displays the contents of the unwind table entry at the - given ADDRESS. - - - -File: gdb.info, Node: SPU, Next: PowerPC, Prev: HPPA, Up: Architectures - -21.4.6 Cell Broadband Engine SPU architecture ---------------------------------------------- - -When GDB is debugging the Cell Broadband Engine SPU architecture, it -provides the following special commands: - -`info spu event' - Display SPU event facility status. Shows current event mask and - pending event status. - -`info spu signal' - Display SPU signal notification facility status. Shows pending - signal-control word and signal notification mode of both signal - notification channels. - -`info spu mailbox' - Display SPU mailbox facility status. Shows all pending entries, - in order of processing, in each of the SPU Write Outbound, SPU - Write Outbound Interrupt, and SPU Read Inbound mailboxes. - -`info spu dma' - Display MFC DMA status. Shows all pending commands in the MFC DMA - queue. For each entry, opcode, tag, class IDs, effective and - local store addresses and transfer size are shown. - -`info spu proxydma' - Display MFC Proxy-DMA status. Shows all pending commands in the - MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs, - effective and local store addresses and transfer size are shown. - - - When GDB is debugging a combined PowerPC/SPU application on the Cell -Broadband Engine, it provides in addition the following special -commands: - -`set spu stop-on-load ARG' - Set whether to stop for new SPE threads. When set to `on', GDB - will give control to the user when a new SPE thread enters its - `main' function. The default is `off'. - -`show spu stop-on-load' - Show whether to stop for new SPE threads. - -`set spu auto-flush-cache ARG' - Set whether to automatically flush the software-managed cache. - When set to `on', GDB will automatically cause the SPE - software-managed cache to be flushed whenever SPE execution stops. - This provides a consistent view of PowerPC memory that is accessed - via the cache. If an application does not use the - software-managed cache, this option has no effect. - -`show spu auto-flush-cache' - Show whether to automatically flush the software-managed cache. - - - -File: gdb.info, Node: PowerPC, Prev: SPU, Up: Architectures - -21.4.7 PowerPC --------------- - -When GDB is debugging the PowerPC architecture, it provides a set of -pseudo-registers to enable inspection of 128-bit wide Decimal Floating -Point numbers stored in the floating point registers. These values must -be stored in two consecutive registers, always starting at an even -register like `f0' or `f2'. - - The pseudo-registers go from `$dl0' through `$dl15', and are formed -by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2' -and `f3' for `$dl1' and so on. - - For POWER7 processors, GDB provides a set of pseudo-registers, the -64-bit wide Extended Floating Point Registers (`f32' through `f63'). - - -File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top - -22 Controlling GDB -****************** - -You can alter the way GDB interacts with you by using the `set' -command. For commands controlling how GDB displays data, see *note -Print Settings: Print Settings. Other settings are described here. - -* Menu: - -* Prompt:: Prompt -* Editing:: Command editing -* Command History:: Command history -* Screen Size:: Screen size -* Numbers:: Numbers -* ABI:: Configuring the current ABI -* Messages/Warnings:: Optional warnings and messages -* Debugging Output:: Optional messages about internal happenings -* Other Misc Settings:: Other Miscellaneous Settings - - -File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB - -22.1 Prompt -=========== - -GDB indicates its readiness to read a command by printing a string -called the "prompt". This string is normally `(gdb)'. You can change -the prompt string with the `set prompt' command. For instance, when -debugging GDB with GDB, it is useful to change the prompt in one of the -GDB sessions so that you can always tell which one you are talking to. - - _Note:_ `set prompt' does not add a space for you after the prompt -you set. This allows you to set a prompt which ends in a space or a -prompt that does not. - -`set prompt NEWPROMPT' - Directs GDB to use NEWPROMPT as its prompt string henceforth. - -`show prompt' - Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' - - -File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB - -22.2 Command Editing -==================== - -GDB reads its input commands via the "Readline" interface. This GNU -library provides consistent behavior for programs which provide a -command line interface to the user. Advantages are GNU Emacs-style or -"vi"-style inline editing of commands, `csh'-like history substitution, -and a storage and recall of command history across debugging sessions. - - You may control the behavior of command line editing in GDB with the -command `set'. - -`set editing' -`set editing on' - Enable command line editing (enabled by default). - -`set editing off' - Disable command line editing. - -`show editing' - Show whether command line editing is enabled. - - *Note Command Line Editing::, for more details about the Readline -interface. Users unfamiliar with GNU Emacs or `vi' are encouraged to -read that chapter. - - -File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB - -22.3 Command History -==================== - -GDB can keep track of the commands you type during your debugging -sessions, so that you can be certain of precisely what happened. Use -these commands to manage the GDB command history facility. - - GDB uses the GNU History library, a part of the Readline package, to -provide the history facility. *Note Using History Interactively::, for -the detailed description of the History library. - - To issue a command to GDB without affecting certain aspects of the -state which is seen by users, prefix it with `server ' (*note Server -Prefix::). This means that this command will not affect the command -history, nor will it affect GDB's notion of which command to repeat if -<RET> is pressed on a line by itself. - - The server prefix does not affect the recording of values into the -value history; to print a value without recording it into the value -history, use the `output' command instead of the `print' command. - - Here is the description of GDB commands related to command history. - -`set history filename FNAME' - Set the name of the GDB command history file to FNAME. This is - the file where GDB reads an initial command history list, and - where it writes the command history from this session when it - exits. You can access this list through history expansion or - through the history command editing characters listed below. This - file defaults to the value of the environment variable - `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS) - if this variable is not set. - -`set history save' -`set history save on' - Record command history in a file, whose name may be specified with - the `set history filename' command. By default, this option is - disabled. - -`set history save off' - Stop recording command history in a file. - -`set history size SIZE' - Set the number of commands which GDB keeps in its history list. - This defaults to the value of the environment variable `HISTSIZE', - or to 256 if this variable is not set. - - History expansion assigns special meaning to the character `!'. -*Note Event Designators::, for more details. - - Since `!' is also the logical not operator in C, history expansion -is off by default. If you decide to enable history expansion with the -`set history expansion on' command, you may sometimes need to follow -`!' (when it is used as logical not, in an expression) with a space or -a tab to prevent it from being expanded. The readline history -facilities do not attempt substitution on the strings `!=' and `!(', -even when history expansion is enabled. - - The commands to control history expansion are: - -`set history expansion on' -`set history expansion' - Enable history expansion. History expansion is off by default. - -`set history expansion off' - Disable history expansion. - -`show history' -`show history filename' -`show history save' -`show history size' -`show history expansion' - These commands display the state of the GDB history parameters. - `show history' by itself displays all four states. - -`show commands' - Display the last ten commands in the command history. - -`show commands N' - Print ten commands centered on command number N. - -`show commands +' - Print ten commands just after the commands last printed. - - -File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB - -22.4 Screen Size -================ - -Certain commands to GDB may produce large amounts of information output -to the screen. To help you read all of it, GDB pauses and asks you for -input at the end of each page of output. Type <RET> when you want to -continue the output, or `q' to discard the remaining output. Also, the -screen width setting determines when to wrap lines of output. -Depending on what is being printed, GDB tries to break the line at a -readable place, rather than simply letting it overflow onto the -following line. - - Normally GDB knows the size of the screen from the terminal driver -software. For example, on Unix GDB uses the termcap data base together -with the value of the `TERM' environment variable and the `stty rows' -and `stty cols' settings. If this is not correct, you can override it -with the `set height' and `set width' commands: - -`set height LPP' -`show height' -`set width CPL' -`show width' - These `set' commands specify a screen height of LPP lines and a - screen width of CPL characters. The associated `show' commands - display the current settings. - - If you specify a height of zero lines, GDB does not pause during - output no matter how long the output is. This is useful if output - is to a file or to an editor buffer. - - Likewise, you can specify `set width 0' to prevent GDB from - wrapping its output. - -`set pagination on' -`set pagination off' - Turn the output pagination on or off; the default is on. Turning - pagination off is the alternative to `set height 0'. Note that - running GDB with the `--batch' option (*note -batch: Mode - Options.) also automatically disables pagination. - -`show pagination' - Show the current pagination mode. - - -File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB - -22.5 Numbers -============ - -You can always enter numbers in octal, decimal, or hexadecimal in GDB -by the usual conventions: octal numbers begin with `0', decimal numbers -end with `.', and hexadecimal numbers begin with `0x'. Numbers that -neither begin with `0' or `0x', nor end with a `.' are, by default, -entered in base 10; likewise, the default display for numbers--when no -particular format is specified--is base 10. You can change the default -base for both input and output with the commands described below. - -`set input-radix BASE' - Set the default base for numeric input. Supported choices for - BASE are decimal 8, 10, or 16. BASE must itself be specified - either unambiguously or using the current input radix; for - example, any of - - set input-radix 012 - set input-radix 10. - set input-radix 0xa - - sets the input base to decimal. On the other hand, `set - input-radix 10' leaves the input radix unchanged, no matter what - it was, since `10', being without any leading or trailing signs of - its base, is interpreted in the current radix. Thus, if the - current radix is 16, `10' is interpreted in hex, i.e. as 16 - decimal, which doesn't change the radix. - -`set output-radix BASE' - Set the default base for numeric display. Supported choices for - BASE are decimal 8, 10, or 16. BASE must itself be specified - either unambiguously or using the current input radix. - -`show input-radix' - Display the current default base for numeric input. - -`show output-radix' - Display the current default base for numeric display. - -`set radix [BASE]' -`show radix' - These commands set and show the default base for both input and - output of numbers. `set radix' sets the radix of input and output - to the same base; without an argument, it resets the radix back to - its default value of 10. - - - -File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB - -22.6 Configuring the Current ABI -================================ - -GDB can determine the "ABI" (Application Binary Interface) of your -application automatically. However, sometimes you need to override its -conclusions. Use these commands to manage GDB's view of the current -ABI. - - One GDB configuration can debug binaries for multiple operating -system targets, either via remote debugging or native emulation. GDB -will autodetect the "OS ABI" (Operating System ABI) in use, but you can -override its conclusion using the `set osabi' command. One example -where this is useful is in debugging of binaries which use an alternate -C library (e.g. UCLIBC for GNU/Linux) which does not have the same -identifying marks that the standard C library for your platform -provides. - -`show osabi' - Show the OS ABI currently in use. - -`set osabi' - With no argument, show the list of registered available OS ABI's. - -`set osabi ABI' - Set the current OS ABI to ABI. - - Generally, the way that an argument of type `float' is passed to a -function depends on whether the function is prototyped. For a -prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed -unchanged, according to the architecture's convention for `float'. For -unprototyped (i.e. K&R style) functions, `float' arguments are first -promoted to type `double' and then passed. - - Unfortunately, some forms of debug information do not reliably -indicate whether a function is prototyped. If GDB calls a function -that is not marked as prototyped, it consults `set -coerce-float-to-double'. - -`set coerce-float-to-double' -`set coerce-float-to-double on' - Arguments of type `float' will be promoted to `double' when passed - to an unprototyped function. This is the default setting. - -`set coerce-float-to-double off' - Arguments of type `float' will be passed directly to unprototyped - functions. - -`show coerce-float-to-double' - Show the current setting of promoting `float' to `double'. - - GDB needs to know the ABI used for your program's C++ objects. The -correct C++ ABI depends on which C++ compiler was used to build your -application. GDB only fully supports programs with a single C++ ABI; -if your program contains code using multiple C++ ABI's or if GDB can -not identify your program's ABI correctly, you can tell GDB which ABI -to use. Currently supported ABI's include "gnu-v2", for `g++' versions -before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for -the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or -"gnu-v3" ABI's as well. The default setting is "auto". - -`show cp-abi' - Show the C++ ABI currently in use. - -`set cp-abi' - With no argument, show the list of supported C++ ABI's. - -`set cp-abi ABI' -`set cp-abi auto' - Set the current C++ ABI to ABI, or return to automatic detection. - - -File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB - -22.7 Optional Warnings and Messages -=================================== - -By default, GDB is silent about its inner workings. If you are running -on a slow machine, you may want to use the `set verbose' command. This -makes GDB tell you when it does a lengthy internal operation, so you -will not think it has crashed. - - Currently, the messages controlled by `set verbose' are those which -announce that the symbol table for a source file is being read; see -`symbol-file' in *note Commands to Specify Files: Files. - -`set verbose on' - Enables GDB output of certain informational messages. - -`set verbose off' - Disables GDB output of certain informational messages. - -`show verbose' - Displays whether `set verbose' is on or off. - - By default, if GDB encounters bugs in the symbol table of an object -file, it is silent; but if you are debugging a compiler, you may find -this information useful (*note Errors Reading Symbol Files: Symbol -Errors.). - -`set complaints LIMIT' - Permits GDB to output LIMIT complaints about each type of unusual - symbols before becoming silent about the problem. Set LIMIT to - zero to suppress all complaints; set it to a large number to - prevent complaints from being suppressed. - -`show complaints' - Displays how many symbol complaints GDB is permitted to produce. - - - By default, GDB is cautious, and asks what sometimes seems to be a -lot of stupid questions to confirm certain commands. For example, if -you try to run a program which is already running: - - (gdb) run - The program being debugged has been started already. - Start it from the beginning? (y or n) - - If you are willing to unflinchingly face the consequences of your own -commands, you can disable this "feature": - -`set confirm off' - Disables confirmation requests. Note that running GDB with the - `--batch' option (*note -batch: Mode Options.) also automatically - disables confirmation requests. - -`set confirm on' - Enables confirmation requests (the default). - -`show confirm' - Displays state of confirmation requests. - - - If you need to debug user-defined commands or sourced files you may -find it useful to enable "command tracing". In this mode each command -will be printed as it is executed, prefixed with one or more `+' -symbols, the quantity denoting the call depth of each command. - -`set trace-commands on' - Enable command tracing. - -`set trace-commands off' - Disable command tracing. - -`show trace-commands' - Display the current state of command tracing. - - -File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB - -22.8 Optional Messages about Internal Happenings -================================================ - -GDB has commands that enable optional debugging messages from various -GDB subsystems; normally these commands are of interest to GDB -maintainers, or when reporting a bug. This section documents those -commands. - -`set exec-done-display' - Turns on or off the notification of asynchronous commands' - completion. When on, GDB will print a message when an - asynchronous command finishes its execution. The default is off. - -`show exec-done-display' - Displays the current setting of asynchronous command completion - notification. - -`set debug arch' - Turns on or off display of gdbarch debugging info. The default is - off - -`show debug arch' - Displays the current state of displaying gdbarch debugging info. - -`set debug aix-thread' - Display debugging messages about inner workings of the AIX thread - module. - -`show debug aix-thread' - Show the current state of AIX thread debugging info display. - -`set debug check-physname' - Check the results of the "physname" computation. When reading - DWARF debugging information for C++, GDB attempts to compute each - entity's name. GDB can do this computation in two different ways, - depending on exactly what information is present. When enabled, - this setting causes GDB to compute the names both ways and display - any discrepancies. - -`show debug check-physname' - Show the current state of "physname" checking. - -`set debug dwarf2-die' - Dump DWARF2 DIEs after they are read in. The value is the number - of nesting levels to print. A value of zero turns off the display. - -`show debug dwarf2-die' - Show the current state of DWARF2 DIE debugging. - -`set debug displaced' - Turns on or off display of GDB debugging info for the displaced - stepping support. The default is off. - -`show debug displaced' - Displays the current state of displaying GDB debugging info - related to displaced stepping. - -`set debug event' - Turns on or off display of GDB event debugging info. The default - is off. - -`show debug event' - Displays the current state of displaying GDB event debugging info. - -`set debug expression' - Turns on or off display of debugging info about GDB expression - parsing. The default is off. - -`show debug expression' - Displays the current state of displaying debugging info about GDB - expression parsing. - -`set debug frame' - Turns on or off display of GDB frame debugging info. The default - is off. - -`show debug frame' - Displays the current state of displaying GDB frame debugging info. - -`set debug gnu-nat' - Turns on or off debugging messages from the GNU/Hurd debug support. - -`show debug gnu-nat' - Show the current state of GNU/Hurd debugging messages. - -`set debug infrun' - Turns on or off display of GDB debugging info for running the - inferior. The default is off. `infrun.c' contains GDB's runtime - state machine used for implementing operations such as - single-stepping the inferior. - -`show debug infrun' - Displays the current state of GDB inferior debugging. - -`set debug jit' - Turns on or off debugging messages from JIT debug support. - -`show debug jit' - Displays the current state of GDB JIT debugging. - -`set debug lin-lwp' - Turns on or off debugging messages from the Linux LWP debug - support. - -`show debug lin-lwp' - Show the current state of Linux LWP debugging messages. - -`set debug lin-lwp-async' - Turns on or off debugging messages from the Linux LWP async debug - support. - -`show debug lin-lwp-async' - Show the current state of Linux LWP async debugging messages. - -`set debug observer' - Turns on or off display of GDB observer debugging. This includes - info such as the notification of observable events. - -`show debug observer' - Displays the current state of observer debugging. - -`set debug overload' - Turns on or off display of GDB C++ overload debugging info. This - includes info such as ranking of functions, etc. The default is - off. - -`show debug overload' - Displays the current state of displaying GDB C++ overload - debugging info. - -`set debug parser' - Turns on or off the display of expression parser debugging output. - Internally, this sets the `yydebug' variable in the expression - parser. *Note Tracing Your Parser: (bison)Tracing, for details. - The default is off. - -`show debug parser' - Show the current state of expression parser debugging. - -`set debug remote' - Turns on or off display of reports on all packets sent back and - forth across the serial line to the remote machine. The info is - printed on the GDB standard output stream. The default is off. - -`show debug remote' - Displays the state of display of remote packets. - -`set debug serial' - Turns on or off display of GDB serial debugging info. The default - is off. - -`show debug serial' - Displays the current state of displaying GDB serial debugging info. - -`set debug solib-frv' - Turns on or off debugging messages for FR-V shared-library code. - -`show debug solib-frv' - Display the current state of FR-V shared-library code debugging - messages. - -`set debug target' - Turns on or off display of GDB target debugging info. This info - includes what is going on at the target level of GDB, as it - happens. The default is 0. Set it to 1 to track events, and to 2 - to also track the value of large memory transfers. Changes to - this flag do not take effect until the next time you connect to a - target or use the `run' command. - -`show debug target' - Displays the current state of displaying GDB target debugging info. - -`set debug timestamp' - Turns on or off display of timestamps with GDB debugging info. - When enabled, seconds and microseconds are displayed before each - debugging message. - -`show debug timestamp' - Displays the current state of displaying timestamps with GDB - debugging info. - -`set debugvarobj' - Turns on or off display of GDB variable object debugging info. The - default is off. - -`show debugvarobj' - Displays the current state of displaying GDB variable object - debugging info. - -`set debug xml' - Turns on or off debugging messages for built-in XML parsers. - -`show debug xml' - Displays the current state of XML debugging messages. - - -File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB - -22.9 Other Miscellaneous Settings -================================= - -`set interactive-mode' - If `on', forces GDB to assume that GDB was started in a terminal. - In practice, this means that GDB should wait for the user to - answer queries generated by commands entered at the command - prompt. If `off', forces GDB to operate in the opposite mode, and - it uses the default answers to all queries. If `auto' (the - default), GDB tries to determine whether its standard input is a - terminal, and works in interactive-mode if it is, - non-interactively otherwise. - - In the vast majority of cases, the debugger should be able to guess - correctly which mode should be used. But this setting can be - useful in certain specific cases, such as running a MinGW GDB - inside a cygwin window. - -`show interactive-mode' - Displays whether the debugger is operating in interactive mode or - not. - - -File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top - -23 Extending GDB -**************** - -GDB provides two mechanisms for extension. The first is based on -composition of GDB commands, and the second is based on the Python -scripting language. - - To facilitate the use of these extensions, GDB is capable of -evaluating the contents of a file. When doing so, GDB can recognize -which scripting language is being used by looking at the filename -extension. Files with an unrecognized filename extension are always -treated as a GDB Command Files. *Note Command files: Command Files. - - You can control how GDB evaluates these files with the following -setting: - -`set script-extension off' - All scripts are always evaluated as GDB Command Files. - -`set script-extension soft' - The debugger determines the scripting language based on filename - extension. If this scripting language is supported, GDB evaluates - the script using that language. Otherwise, it evaluates the file - as a GDB Command File. - -`set script-extension strict' - The debugger determines the scripting language based on filename - extension, and evaluates the script using that language. If the - language is not supported, then the evaluation fails. - -`show script-extension' - Display the current value of the `script-extension' option. - - -* Menu: - -* Sequences:: Canned Sequences of Commands -* Python:: Scripting GDB using Python - - -File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB - -23.1 Canned Sequences of Commands -================================= - -Aside from breakpoint commands (*note Breakpoint Command Lists: Break -Commands.), GDB provides two ways to store sequences of commands for -execution as a unit: user-defined commands and command files. - -* Menu: - -* Define:: How to define your own commands -* Hooks:: Hooks for user-defined commands -* Command Files:: How to write scripts of commands to be stored in a file -* Output:: Commands for controlled output - - -File: gdb.info, Node: Define, Next: Hooks, Up: Sequences - -23.1.1 User-defined Commands ----------------------------- - -A "user-defined command" is a sequence of GDB commands to which you -assign a new name as a command. This is done with the `define' -command. User commands may accept up to 10 arguments separated by -whitespace. Arguments are accessed within the user command via -`$arg0...$arg9'. A trivial example: - - define adder - print $arg0 + $arg1 + $arg2 - end - -To execute the command use: - - adder 1 2 3 - -This defines the command `adder', which prints the sum of its three -arguments. Note the arguments are text substitutions, so they may -reference variables, use complex expressions, or even perform inferior -functions calls. - - In addition, `$argc' may be used to find out how many arguments have -been passed. This expands to a number in the range 0...10. - - define adder - if $argc == 2 - print $arg0 + $arg1 - end - if $argc == 3 - print $arg0 + $arg1 + $arg2 - end - end - -`define COMMANDNAME' - Define a command named COMMANDNAME. If there is already a command - by that name, you are asked to confirm that you want to redefine - it. COMMANDNAME may be a bare command name consisting of letters, - numbers, dashes, and underscores. It may also start with any - predefined prefix command. For example, `define target my-target' - creates a user-defined `target my-target' command. - - The definition of the command is made up of other GDB command - lines, which are given following the `define' command. The end of - these commands is marked by a line containing `end'. - -`document COMMANDNAME' - Document the user-defined command COMMANDNAME, so that it can be - accessed by `help'. The command COMMANDNAME must already be - defined. This command reads lines of documentation just as - `define' reads the lines of the command definition, ending with - `end'. After the `document' command is finished, `help' on command - COMMANDNAME displays the documentation you have written. - - You may use the `document' command again to change the - documentation of a command. Redefining the command with `define' - does not change the documentation. - -`dont-repeat' - Used inside a user-defined command, this tells GDB that this - command should not be repeated when the user hits <RET> (*note - repeat last command: Command Syntax.). - -`help user-defined' - List all user-defined commands, with the first line of the - documentation (if any) for each. - -`show user' -`show user COMMANDNAME' - Display the GDB commands used to define COMMANDNAME (but not its - documentation). If no COMMANDNAME is given, display the - definitions for all user-defined commands. - -`show max-user-call-depth' -`set max-user-call-depth' - The value of `max-user-call-depth' controls how many recursion - levels are allowed in user-defined commands before GDB suspects an - infinite recursion and aborts the command. - - In addition to the above commands, user-defined commands frequently -use control flow commands, described in *note Command Files::. - - When user-defined commands are executed, the commands of the -definition are not printed. An error in any command stops execution of -the user-defined command. - - If used interactively, commands that would ask for confirmation -proceed without asking when used inside a user-defined command. Many -GDB commands that normally print messages to say what they are doing -omit the messages when used in a user-defined command. - - -File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences - -23.1.2 User-defined Command Hooks ---------------------------------- - -You may define "hooks", which are a special kind of user-defined -command. Whenever you run the command `foo', if the user-defined -command `hook-foo' exists, it is executed (with no arguments) before -that command. - - A hook may also be defined which is run after the command you -executed. Whenever you run the command `foo', if the user-defined -command `hookpost-foo' exists, it is executed (with no arguments) after -that command. Post-execution hooks may exist simultaneously with -pre-execution hooks, for the same command. - - It is valid for a hook to call the command which it hooks. If this -occurs, the hook is not re-executed, thereby avoiding infinite -recursion. - - In addition, a pseudo-command, `stop' exists. Defining -(`hook-stop') makes the associated commands execute every time -execution stops in your program: before breakpoint commands are run, -displays are printed, or the stack frame is printed. - - For example, to ignore `SIGALRM' signals while single-stepping, but -treat them normally during normal execution, you could define: - - define hook-stop - handle SIGALRM nopass - end - - define hook-run - handle SIGALRM pass - end - - define hook-continue - handle SIGALRM pass - end - - As a further example, to hook at the beginning and end of the `echo' -command, and to add extra text to the beginning and end of the message, -you could define: - - define hook-echo - echo <<<--- - end - - define hookpost-echo - echo --->>>\n - end - - (gdb) echo Hello World - <<<---Hello World--->>> - (gdb) - - You can define a hook for any single-word command in GDB, but not -for command aliases; you should define a hook for the basic command -name, e.g. `backtrace' rather than `bt'. You can hook a multi-word -command by adding `hook-' or `hookpost-' to the last word of the -command, e.g. `define target hook-remote' to add a hook to `target -remote'. - - If an error occurs during the execution of your hook, execution of -GDB commands stops and GDB issues a prompt (before the command that you -actually typed had a chance to run). - - If you try to define a hook which does not match any known command, -you get a warning from the `define' command. - - -File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences - -23.1.3 Command Files --------------------- - -A command file for GDB is a text file made of lines that are GDB -commands. Comments (lines starting with `#') may also be included. An -empty line in a command file does nothing; it does not mean to repeat -the last command, as it would from the terminal. - - You can request the execution of a command file with the `source' -command. Note that the `source' command is also used to evaluate -scripts that are not Command Files. The exact behavior can be -configured using the `script-extension' setting. *Note Extending GDB: -Extending GDB. - -`source [-s] [-v] FILENAME' - Execute the command file FILENAME. - - The lines in a command file are generally executed sequentially, -unless the order of execution is changed by one of the _flow-control -commands_ described below. The commands are not printed as they are -executed. An error in any command terminates execution of the command -file and control is returned to the console. - - GDB first searches for FILENAME in the current directory. If the -file is not found there, and FILENAME does not specify a directory, -then GDB also looks for the file on the source search path (specified -with the `directory' command); except that `$cdir' is not searched -because the compilation directory is not relevant to scripts. - - If `-s' is specified, then GDB searches for FILENAME on the search -path even if FILENAME specifies a directory. The search is done by -appending FILENAME to each element of the search path. So, for -example, if FILENAME is `mylib/myscript' and the search path contains -`/home/user' then GDB will look for the script -`/home/user/mylib/myscript'. The search is also done if FILENAME is an -absolute path. For example, if FILENAME is `/tmp/myscript' and the -search path contains `/home/user' then GDB will look for the script -`/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains -a drive specification, it is stripped before concatenation. For -example, if FILENAME is `d:myscript' and the search path contains -`c:/tmp' then GDB will look for the script `c:/tmp/myscript'. - - If `-v', for verbose mode, is given then GDB displays each command -as it is executed. The option must be given before FILENAME, and is -interpreted as part of the filename anywhere else. - - Commands that would ask for confirmation if used interactively -proceed without asking when used in a command file. Many GDB commands -that normally print messages to say what they are doing omit the -messages when called from command files. - - GDB also accepts command input from standard input. In this mode, -normal output goes to standard output and error output goes to standard -error. Errors in a command file supplied on standard input do not -terminate execution of the command file--execution continues with the -next command. - - gdb < cmds > log 2>&1 - - (The syntax above will vary depending on the shell used.) This -example will execute commands from the file `cmds'. All output and -errors would be directed to `log'. - - Since commands stored on command files tend to be more general than -commands typed interactively, they frequently need to deal with -complicated situations, such as different or unexpected values of -variables and symbols, changes in how the program being debugged is -built, etc. GDB provides a set of flow-control commands to deal with -these complexities. Using these commands, you can write complex -scripts that loop over data structures, execute commands conditionally, -etc. - -`if' -`else' - This command allows to include in your script conditionally - executed commands. The `if' command takes a single argument, which - is an expression to evaluate. It is followed by a series of - commands that are executed only if the expression is true (its - value is nonzero). There can then optionally be an `else' line, - followed by a series of commands that are only executed if the - expression was false. The end of the list is marked by a line - containing `end'. - -`while' - This command allows to write loops. Its syntax is similar to - `if': the command takes a single argument, which is an expression - to evaluate, and must be followed by the commands to execute, one - per line, terminated by an `end'. These commands are called the - "body" of the loop. The commands in the body of `while' are - executed repeatedly as long as the expression evaluates to true. - -`loop_break' - This command exits the `while' loop in whose body it is included. - Execution of the script continues after that `while's `end' line. - -`loop_continue' - This command skips the execution of the rest of the body of - commands in the `while' loop in whose body it is included. - Execution branches to the beginning of the `while' loop, where it - evaluates the controlling expression. - -`end' - Terminate the block of commands that are the body of `if', `else', - or `while' flow-control commands. - - -File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences - -23.1.4 Commands for Controlled Output -------------------------------------- - -During the execution of a command file or a user-defined command, normal -GDB output is suppressed; the only output that appears is what is -explicitly printed by the commands in the definition. This section -describes three commands useful for generating exactly the output you -want. - -`echo TEXT' - Print TEXT. Nonprinting characters can be included in TEXT using - C escape sequences, such as `\n' to print a newline. *No newline - is printed unless you specify one.* In addition to the standard C - escape sequences, a backslash followed by a space stands for a - space. This is useful for displaying a string with spaces at the - beginning or the end, since leading and trailing spaces are - otherwise trimmed from all arguments. To print ` and foo = ', use - the command `echo \ and foo = \ '. - - A backslash at the end of TEXT can be used, as in C, to continue - the command onto subsequent lines. For example, - - echo This is some text\n\ - which is continued\n\ - onto several lines.\n - - produces the same output as - - echo This is some text\n - echo which is continued\n - echo onto several lines.\n - -`output EXPRESSION' - Print the value of EXPRESSION and nothing but that value: no - newlines, no `$NN = '. The value is not entered in the value - history either. *Note Expressions: Expressions, for more - information on expressions. - -`output/FMT EXPRESSION' - Print the value of EXPRESSION in format FMT. You can use the same - formats as for `print'. *Note Output Formats: Output Formats, for - more information. - -`printf TEMPLATE, EXPRESSIONS...' - Print the values of one or more EXPRESSIONS under the control of - the string TEMPLATE. To print several values, make EXPRESSIONS be - a comma-separated list of individual expressions, which may be - either numbers or pointers. Their values are printed as specified - by TEMPLATE, exactly as a C program would do by executing the code - below: - - printf (TEMPLATE, EXPRESSIONS...); - - As in `C' `printf', ordinary characters in TEMPLATE are printed - verbatim, while "conversion specification" introduced by the `%' - character cause subsequent EXPRESSIONS to be evaluated, their - values converted and formatted according to type and style - information encoded in the conversion specifications, and then - printed. - - For example, you can print two values in hex like this: - - printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo - - `printf' supports all the standard `C' conversion specifications, - including the flags and modifiers between the `%' character and - the conversion letter, with the following exceptions: - - * The argument-ordering modifiers, such as `2$', are not - supported. - - * The modifier `*' is not supported for specifying precision or - width. - - * The `'' flag (for separation of digits into groups according - to `LC_NUMERIC'') is not supported. - - * The type modifiers `hh', `j', `t', and `z' are not supported. - - * The conversion letter `n' (as in `%n') is not supported. - - * The conversion letters `a' and `A' are not supported. - - Note that the `ll' type modifier is supported only if the - underlying `C' implementation used to build GDB supports the `long - long int' type, and the `L' type modifier is supported only if - `long double' type is available. - - As in `C', `printf' supports simple backslash-escape sequences, - such as `\n', `\t', `\\', `\"', `\a', and `\f', that consist of - backslash followed by a single character. Octal and hexadecimal - escape sequences are not supported. - - Additionally, `printf' supports conversion specifications for DFP - ("Decimal Floating Point") types using the following length - modifiers together with a floating point specifier. letters: - - * `H' for printing `Decimal32' types. - - * `D' for printing `Decimal64' types. - - * `DD' for printing `Decimal128' types. - - If the underlying `C' implementation used to build GDB has support - for the three length modifiers for DFP types, other modifiers such - as width and precision will also be available for GDB to use. - - In case there is no such `C' support, no additional modifiers will - be available and the value will be printed in the standard way. - - Here's an example of printing DFP types using the above conversion - letters: - printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl - -`eval TEMPLATE, EXPRESSIONS...' - Convert the values of one or more EXPRESSIONS under the control of - the string TEMPLATE to a command line, and call it. - - - -File: gdb.info, Node: Python, Prev: Sequences, Up: Extending GDB - -23.2 Scripting GDB using Python -=============================== - -You can script GDB using the Python programming language -(http://www.python.org/). This feature is available only if GDB was -configured using `--with-python'. - - Python scripts used by GDB should be installed in -`DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as -determined at GDB startup (*note Data Files::). This directory, known -as the "python directory", is automatically added to the Python Search -Path in order to allow the Python interpreter to locate all scripts -installed at this location. - -* Menu: - -* Python Commands:: Accessing Python from GDB. -* Python API:: Accessing GDB from Python. -* Auto-loading:: Automatically loading Python code. -* Python modules:: Python modules provided by GDB. - - -File: gdb.info, Node: Python Commands, Next: Python API, Up: Python - -23.2.1 Python Commands ----------------------- - -GDB provides one command for accessing the Python interpreter, and one -related setting: - -`python [CODE]' - The `python' command can be used to evaluate Python code. - - If given an argument, the `python' command will evaluate the - argument as a Python command. For example: - - (gdb) python print 23 - 23 - - If you do not provide an argument to `python', it will act as a - multi-line command, like `define'. In this case, the Python - script is made up of subsequent command lines, given after the - `python' command. This command list is terminated using a line - containing `end'. For example: - - (gdb) python - Type python script - End with a line saying just "end". - >print 23 - >end - 23 - -`maint set python print-stack' - By default, GDB will print a stack trace when an error occurs in a - Python script. This can be controlled using `maint set python - print-stack': if `on', the default, then Python stack printing is - enabled; if `off', then Python stack printing is disabled. - - It is also possible to execute a Python script from the GDB -interpreter: - -`source `script-name'' - The script name must end with `.py' and GDB must be configured to - recognize the script language based on filename extension using - the `script-extension' setting. *Note Extending GDB: Extending - GDB. - -`python execfile ("script-name")' - This method is based on the `execfile' Python built-in function, - and thus is always available. - - -File: gdb.info, Node: Python API, Next: Auto-loading, Prev: Python Commands, Up: Python - -23.2.2 Python API ------------------ - -At startup, GDB overrides Python's `sys.stdout' and `sys.stderr' to -print using GDB's output-paging streams. A Python program which -outputs to one of these streams may have its output interrupted by the -user (*note Screen Size::). In this situation, a Python -`KeyboardInterrupt' exception is thrown. - -* Menu: - -* Basic Python:: Basic Python Functions. -* Exception Handling:: How Python exceptions are translated. -* Values From Inferior:: Python representation of values. -* Types In Python:: Python representation of types. -* Pretty Printing API:: Pretty-printing values. -* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. -* Writing a Pretty-Printer:: Writing a Pretty-Printer. -* Inferiors In Python:: Python representation of inferiors (processes) -* Events In Python:: Listening for events from GDB. -* Threads In Python:: Accessing inferior threads from Python. -* Commands In Python:: Implementing new commands in Python. -* Parameters In Python:: Adding new GDB parameters. -* Functions In Python:: Writing new convenience functions. -* Progspaces In Python:: Program spaces. -* Objfiles In Python:: Object files. -* Frames In Python:: Accessing inferior stack frames from Python. -* Blocks In Python:: Accessing frame blocks from Python. -* Symbols In Python:: Python representation of symbols. -* Symbol Tables In Python:: Python representation of symbol tables. -* Lazy Strings In Python:: Python representation of lazy strings. -* Breakpoints In Python:: Manipulating breakpoints using Python. - - -File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API - -23.2.2.1 Basic Python -..................... - -GDB introduces a new Python module, named `gdb'. All methods and -classes added by GDB are placed in this module. GDB automatically -`import's the `gdb' module for use in all scripts evaluated by the -`python' command. - - -- Variable: PYTHONDIR - A string containing the python directory (*note Python::). - - -- Function: execute command [from_tty] [to_string] - Evaluate COMMAND, a string, as a GDB CLI command. If a GDB - exception happens while COMMAND runs, it is translated as - described in *note Exception Handling: Exception Handling. - - FROM_TTY specifies whether GDB ought to consider this command as - having originated from the user invoking it interactively. It - must be a boolean value. If omitted, it defaults to `False'. - - By default, any output produced by COMMAND is sent to GDB's - standard output. If the TO_STRING parameter is `True', then - output will be collected by `gdb.execute' and returned as a - string. The default is `False', in which case the return value is - `None'. If TO_STRING is `True', the GDB virtual terminal will be - temporarily set to unlimited width and height, and its pagination - will be disabled; *note Screen Size::. - - -- Function: breakpoints - Return a sequence holding all of GDB's breakpoints. *Note - Breakpoints In Python::, for more information. - - -- Function: parameter parameter - Return the value of a GDB parameter. PARAMETER is a string naming - the parameter to look up; PARAMETER may contain spaces if the - parameter has a multi-part name. For example, `print object' is a - valid parameter name. - - If the named parameter does not exist, this function throws a - `gdb.error' (*note Exception Handling::). Otherwise, the - parameter's value is converted to a Python value of the appropriate - type, and returned. - - -- Function: history number - Return a value from GDB's value history (*note Value History::). - NUMBER indicates which history element to return. If NUMBER is - negative, then GDB will take its absolute value and count backward - from the last element (i.e., the most recent element) to find the - value to return. If NUMBER is zero, then GDB will return the most - recent element. If the element specified by NUMBER doesn't exist - in the value history, a `gdb.error' exception will be raised. - - If no exception is raised, the return value is always an instance - of `gdb.Value' (*note Values From Inferior::). - - -- Function: parse_and_eval expression - Parse EXPRESSION as an expression in the current language, - evaluate it, and return the result as a `gdb.Value'. EXPRESSION - must be a string. - - This function can be useful when implementing a new command (*note - Commands In Python::), as it provides a way to parse the command's - argument as an expression. It is also useful simply to compute - values, for example, it is the only way to get the value of a - convenience variable (*note Convenience Vars::) as a `gdb.Value'. - - -- Function: post_event event - Put EVENT, a callable object taking no arguments, into GDB's - internal event queue. This callable will be invoked at some later - point, during GDB's event processing. Events posted using - `post_event' will be run in the order in which they were posted; - however, there is no way to know when they will be processed - relative to other events inside GDB. - - GDB is not thread-safe. If your Python program uses multiple - threads, you must be careful to only call GDB-specific functions - in the main GDB thread. `post_event' ensures this. For example: - - (gdb) python - >import threading - > - >class Writer(): - > def __init__(self, message): - > self.message = message; - > def __call__(self): - > gdb.write(self.message) - > - >class MyThread1 (threading.Thread): - > def run (self): - > gdb.post_event(Writer("Hello ")) - > - >class MyThread2 (threading.Thread): - > def run (self): - > gdb.post_event(Writer("World\n")) - > - >MyThread1().start() - >MyThread2().start() - >end - (gdb) Hello World - - -- Function: write string [stream] - Print a string to GDB's paginated output stream. The optional - STREAM determines the stream to print to. The default stream is - GDB's standard output stream. Possible stream values are: - - `STDOUT' - GDB's standard output stream. - - `STDERR' - GDB's standard error stream. - - `STDLOG' - GDB's log stream (*note Logging Output::). - - Writing to `sys.stdout' or `sys.stderr' will automatically call - this function and will automatically direct the output to the - relevant stream. - - -- Function: flush - Flush the buffer of a GDB paginated stream so that the contents - are displayed immediately. GDB will flush the contents of a - stream automatically when it encounters a newline in the buffer. - The optional STREAM determines the stream to flush. The default - stream is GDB's standard output stream. Possible stream values - are: - - `STDOUT' - GDB's standard output stream. - - `STDERR' - GDB's standard error stream. - - `STDLOG' - GDB's log stream (*note Logging Output::). - - - Flushing `sys.stdout' or `sys.stderr' will automatically call this - function for the relevant stream. - - -- Function: target_charset - Return the name of the current target character set (*note - Character Sets::). This differs from - `gdb.parameter('target-charset')' in that `auto' is never returned. - - -- Function: target_wide_charset - Return the name of the current target wide character set (*note - Character Sets::). This differs from - `gdb.parameter('target-wide-charset')' in that `auto' is never - returned. - - -- Function: solib_name address - Return the name of the shared library holding the given ADDRESS as - a string, or `None'. - - -- Function: decode_line [expression] - Return locations of the line specified by EXPRESSION, or of the - current line if no argument was given. This function returns a - Python tuple containing two elements. The first element contains - a string holding any unparsed section of EXPRESSION (or `None' if - the expression has been fully parsed). The second element contains - either `None' or another tuple that contains all the locations - that match the expression represented as `gdb.Symtab_and_line' - objects (*note Symbol Tables In Python::). If EXPRESSION is - provided, it is decoded the way that GDB's inbuilt `break' or - `edit' commands do (*note Specify Location::). - - -File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Basic Python, Up: Python API - -23.2.2.2 Exception Handling -........................... - -When executing the `python' command, Python exceptions uncaught within -the Python code are translated to calls to GDB error-reporting -mechanism. If the command that called `python' does not handle the -error, GDB will terminate it and print an error message containing the -Python exception name, the associated value, and the Python call stack -backtrace at the point where the exception was raised. Example: - - (gdb) python print foo - Traceback (most recent call last): - File "<string>", line 1, in <module> - NameError: name 'foo' is not defined - - GDB errors that happen in GDB commands invoked by Python code are -converted to Python exceptions. The type of the Python exception -depends on the error. - -`gdb.error' - This is the base class for most exceptions generated by GDB. It - is derived from `RuntimeError', for compatibility with earlier - versions of GDB. - - If an error occurring in GDB does not fit into some more specific - category, then the generated exception will have this type. - -`gdb.MemoryError' - This is a subclass of `gdb.error' which is thrown when an - operation tried to access invalid memory in the inferior. - -`KeyboardInterrupt' - User interrupt (via `C-c' or by typing `q' at a pagination prompt) - is translated to a Python `KeyboardInterrupt' exception. - - In all cases, your exception handler will see the GDB error message -as its value and the Python call stack backtrace at the Python -statement closest to where the GDB error occured as the traceback. - - When implementing GDB commands in Python via `gdb.Command', it is -useful to be able to throw an exception that doesn't cause a traceback -to be printed. For example, the user may have invoked the command -incorrectly. Use the `gdb.GdbError' exception to handle this case. -Example: - - (gdb) python - >class HelloWorld (gdb.Command): - > """Greet the whole world.""" - > def __init__ (self): - > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) - > def invoke (self, args, from_tty): - > argv = gdb.string_to_argv (args) - > if len (argv) != 0: - > raise gdb.GdbError ("hello-world takes no arguments") - > print "Hello, World!" - >HelloWorld () - >end - (gdb) hello-world 42 - hello-world takes no arguments - - -File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API - -23.2.2.3 Values From Inferior -............................. - -GDB provides values it obtains from the inferior program in an object -of type `gdb.Value'. GDB uses this object for its internal bookkeeping -of the inferior's values, and for fetching values when necessary. - - Inferior values that are simple scalars can be used directly in -Python expressions that are valid for the value's data type. Here's an -example for an integer or floating-point value `some_val': - - bar = some_val + 2 - -As result of this, `bar' will also be a `gdb.Value' object whose values -are of the same type as those of `some_val'. - - Inferior values that are structures or instances of some class can -be accessed using the Python "dictionary syntax". For example, if -`some_val' is a `gdb.Value' instance holding a structure, you can -access its `foo' element with: - - bar = some_val['foo'] - - Again, `bar' will also be a `gdb.Value' object. - - A `gdb.Value' that represents a function can be executed via -inferior function call. Any arguments provided to the call must match -the function's prototype, and must be provided in the order specified -by that prototype. - - For example, `some_val' is a `gdb.Value' instance representing a -function that takes two integers as arguments. To execute this -function, call it like so: - - result = some_val (10,20) - - Any values returned from a function call will be stored as a -`gdb.Value'. - - The following attributes are provided: - - -- Instance Variable of Value: address - If this object is addressable, this read-only attribute holds - a `gdb.Value' object representing the address. Otherwise, - this attribute holds `None'. - - -- Instance Variable of Value: is_optimized_out - This read-only boolean attribute is true if the compiler - optimized out this value, thus it is not available for - fetching from the inferior. - - -- Instance Variable of Value: type - The type of this `gdb.Value'. The value of this attribute is - a `gdb.Type' object (*note Types In Python::). - - -- Instance Variable of Value: dynamic_type - The dynamic type of this `gdb.Value'. This uses C++ run-time - type information (RTTI) to determine the dynamic type of the - value. If this value is of class type, it will return the - class in which the value is embedded, if any. If this value - is of pointer or reference to a class type, it will compute - the dynamic type of the referenced object, and return a - pointer or reference to that type, respectively. In all - other cases, it will return the value's static type. - - Note that this feature will only work when debugging a C++ - program that includes RTTI for the object in question. - Otherwise, it will just return the static type of the value - as in `ptype foo' (*note ptype: Symbols.). - - The following methods are provided: - - -- Method on Value: __init__ VAL - Many Python values can be converted directly to a `gdb.Value' - via this object initializer. Specifically: - - Python boolean - A Python boolean is converted to the boolean type from - the current language. - - Python integer - A Python integer is converted to the C `long' type for - the current architecture. - - Python long - A Python long is converted to the C `long long' type for - the current architecture. - - Python float - A Python float is converted to the C `double' type for - the current architecture. - - Python string - A Python string is converted to a target string, using - the current target encoding. - - `gdb.Value' - If `val' is a `gdb.Value', then a copy of the value is - made. - - `gdb.LazyString' - If `val' is a `gdb.LazyString' (*note Lazy Strings In - Python::), then the lazy string's `value' method is - called, and its result is used. - - -- Method on Value: cast type - Return a new instance of `gdb.Value' that is the result of - casting this instance to the type described by TYPE, which - must be a `gdb.Type' object. If the cast cannot be performed - for some reason, this method throws an exception. - - -- Method on Value: dereference - For pointer data types, this method returns a new `gdb.Value' - object whose contents is the object pointed to by the - pointer. For example, if `foo' is a C pointer to an `int', - declared in your C program as - - int *foo; - - then you can use the corresponding `gdb.Value' to access what - `foo' points to like this: - - bar = foo.dereference () - - The result `bar' will be a `gdb.Value' object holding the - value pointed to by `foo'. - - -- Method on Value: dynamic_cast type - Like `Value.cast', but works as if the C++ `dynamic_cast' - operator were used. Consult a C++ reference for details. - - -- Method on Value: reinterpret_cast type - Like `Value.cast', but works as if the C++ `reinterpret_cast' - operator were used. Consult a C++ reference for details. - - -- Method on Value: string [encoding] [errors] [length] - If this `gdb.Value' represents a string, then this method - converts the contents to a Python string. Otherwise, this - method will throw an exception. - - Strings are recognized in a language-specific way; whether a - given `gdb.Value' represents a string is determined by the - current language. - - For C-like languages, a value is a string if it is a pointer - to or an array of characters or ints. The string is assumed - to be terminated by a zero of the appropriate width. However - if the optional length argument is given, the string will be - converted to that given length, ignoring any embedded zeros - that the string may contain. - - If the optional ENCODING argument is given, it must be a - string naming the encoding of the string in the `gdb.Value', - such as `"ascii"', `"iso-8859-6"' or `"utf-8"'. It accepts - the same encodings as the corresponding argument to Python's - `string.decode' method, and the Python codec machinery will - be used to convert the string. If ENCODING is not given, or - if ENCODING is the empty string, then either the - `target-charset' (*note Character Sets::) will be used, or a - language-specific encoding will be used, if the current - language is able to supply one. - - The optional ERRORS argument is the same as the corresponding - argument to Python's `string.decode' method. - - If the optional LENGTH argument is given, the string will be - fetched and converted to the given length. - - -- Method on Value: lazy_string [encoding] [length] - If this `gdb.Value' represents a string, then this method - converts the contents to a `gdb.LazyString' (*note Lazy - Strings In Python::). Otherwise, this method will throw an - exception. - - If the optional ENCODING argument is given, it must be a - string naming the encoding of the `gdb.LazyString'. Some - examples are: `ascii', `iso-8859-6' or `utf-8'. If the - ENCODING argument is an encoding that GDB does recognize, GDB - will raise an error. - - When a lazy string is printed, the GDB encoding machinery is - used to convert the string during printing. If the optional - ENCODING argument is not provided, or is an empty string, GDB - will automatically select the encoding most suitable for the - string type. For further information on encoding in GDB - please see *note Character Sets::. - - If the optional LENGTH argument is given, the string will be - fetched and encoded to the length of characters specified. If - the LENGTH argument is not provided, the string will be - fetched and encoded until a null of appropriate width is - found. - - -File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API - -23.2.2.4 Types In Python -........................ - -GDB represents types from the inferior using the class `gdb.Type'. - - The following type-related functions are available in the `gdb' -module: - - -- Function: lookup_type name [block] - This function looks up a type by name. NAME is the name of the - type to look up. It must be a string. - - If BLOCK is given, then NAME is looked up in that scope. - Otherwise, it is searched for globally. - - Ordinarily, this function will return an instance of `gdb.Type'. - If the named type cannot be found, it will throw an exception. - - An instance of `Type' has the following attributes: - - -- Instance Variable of Type: code - The type code for this type. The type code will be one of the - `TYPE_CODE_' constants defined below. - - -- Instance Variable of Type: sizeof - The size of this type, in target `char' units. Usually, a - target's `char' type will be an 8-bit byte. However, on some - unusual platforms, this type may have a different size. - - -- Instance Variable of Type: tag - The tag name for this type. The tag name is the name after - `struct', `union', or `enum' in C and C++; not all languages - have this concept. If this type has no tag name, then `None' - is returned. - - The following methods are provided: - - -- Method on Type: fields - For structure and union types, this method returns the - fields. Range types have two fields, the minimum and maximum - values. Enum types have one field per enum constant. - Function and method types have one field per parameter. The - base types of C++ classes are also represented as fields. If - the type has no fields, or does not fit into one of these - categories, an empty sequence will be returned. - - Each field is an object, with some pre-defined attributes: - `bitpos' - This attribute is not available for `static' fields (as - in C++ or Java). For non-`static' fields, the value is - the bit position of the field. - - `name' - The name of the field, or `None' for anonymous fields. - - `artificial' - This is `True' if the field is artificial, usually - meaning that it was provided by the compiler and not the - user. This attribute is always provided, and is `False' - if the field is not artificial. - - `is_base_class' - This is `True' if the field represents a base class of a - C++ structure. This attribute is always provided, and - is `False' if the field is not a base class of the type - that is the argument of `fields', or if that type was - not a C++ class. - - `bitsize' - If the field is packed, or is a bitfield, then this will - have a non-zero value, which is the size of the field in - bits. Otherwise, this will be zero; in this case the - field's size is given by its type. - - `type' - The type of the field. This is usually an instance of - `Type', but it can be `None' in some situations. - - -- Method on Type: array N1 [N2] - Return a new `gdb.Type' object which represents an array of - this type. If one argument is given, it is the inclusive - upper bound of the array; in this case the lower bound is - zero. If two arguments are given, the first argument is the - lower bound of the array, and the second argument is the - upper bound of the array. An array's length must not be - negative, but the bounds can be. - - -- Method on Type: const - Return a new `gdb.Type' object which represents a - `const'-qualified variant of this type. - - -- Method on Type: volatile - Return a new `gdb.Type' object which represents a - `volatile'-qualified variant of this type. - - -- Method on Type: unqualified - Return a new `gdb.Type' object which represents an unqualified - variant of this type. That is, the result is neither `const' - nor `volatile'. - - -- Method on Type: range - Return a Python `Tuple' object that contains two elements: the - low bound of the argument type and the high bound of that - type. If the type does not have a range, GDB will raise a - `gdb.error' exception (*note Exception Handling::). - - -- Method on Type: reference - Return a new `gdb.Type' object which represents a reference - to this type. - - -- Method on Type: pointer - Return a new `gdb.Type' object which represents a pointer to - this type. - - -- Method on Type: strip_typedefs - Return a new `gdb.Type' that represents the real type, after - removing all layers of typedefs. - - -- Method on Type: target - Return a new `gdb.Type' object which represents the target - type of this type. - - For a pointer type, the target type is the type of the - pointed-to object. For an array type (meaning C-like - arrays), the target type is the type of the elements of the - array. For a function or method type, the target type is the - type of the return value. For a complex type, the target - type is the type of the elements. For a typedef, the target - type is the aliased type. - - If the type does not have a target, this method will throw an - exception. - - -- Method on Type: template_argument n [block] - If this `gdb.Type' is an instantiation of a template, this - will return a new `gdb.Type' which represents the type of the - Nth template argument. - - If this `gdb.Type' is not a template type, this will throw an - exception. Ordinarily, only C++ code will have template - types. - - If BLOCK is given, then NAME is looked up in that scope. - Otherwise, it is searched for globally. - - Each type has a code, which indicates what category this type falls -into. The available type categories are represented by constants -defined in the `gdb' module: - -`TYPE_CODE_PTR' - The type is a pointer. - -`TYPE_CODE_ARRAY' - The type is an array. - -`TYPE_CODE_STRUCT' - The type is a structure. - -`TYPE_CODE_UNION' - The type is a union. - -`TYPE_CODE_ENUM' - The type is an enum. - -`TYPE_CODE_FLAGS' - A bit flags type, used for things such as status registers. - -`TYPE_CODE_FUNC' - The type is a function. - -`TYPE_CODE_INT' - The type is an integer type. - -`TYPE_CODE_FLT' - A floating point type. - -`TYPE_CODE_VOID' - The special type `void'. - -`TYPE_CODE_SET' - A Pascal set type. - -`TYPE_CODE_RANGE' - A range type, that is, an integer type with bounds. - -`TYPE_CODE_STRING' - A string type. Note that this is only used for certain languages - with language-defined string types; C strings are not represented - this way. - -`TYPE_CODE_BITSTRING' - A string of bits. - -`TYPE_CODE_ERROR' - An unknown or erroneous type. - -`TYPE_CODE_METHOD' - A method type, as found in C++ or Java. - -`TYPE_CODE_METHODPTR' - A pointer-to-member-function. - -`TYPE_CODE_MEMBERPTR' - A pointer-to-member. - -`TYPE_CODE_REF' - A reference type. - -`TYPE_CODE_CHAR' - A character type. - -`TYPE_CODE_BOOL' - A boolean type. - -`TYPE_CODE_COMPLEX' - A complex float type. - -`TYPE_CODE_TYPEDEF' - A typedef to some other type. - -`TYPE_CODE_NAMESPACE' - A C++ namespace. - -`TYPE_CODE_DECFLOAT' - A decimal floating point type. - -`TYPE_CODE_INTERNAL_FUNCTION' - A function internal to GDB. This is the type used to represent - convenience functions. - - Further support for types is provided in the `gdb.types' Python -module (*note gdb.types::). - - -File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API - -23.2.2.5 Pretty Printing API -............................ - -An example output is provided (*note Pretty Printing::). - - A pretty-printer is just an object that holds a value and implements -a specific interface, defined here. - - -- Operation on pretty printer: children (self) - GDB will call this method on a pretty-printer to compute the - children of the pretty-printer's value. - - This method must return an object conforming to the Python iterator - protocol. Each item returned by the iterator must be a tuple - holding two elements. The first element is the "name" of the - child; the second element is the child's value. The value can be - any Python object which is convertible to a GDB value. - - This method is optional. If it does not exist, GDB will act as - though the value has no children. - - -- Operation on pretty printer: display_hint (self) - The CLI may call this method and use its result to change the - formatting of a value. The result will also be supplied to an MI - consumer as a `displayhint' attribute of the variable being - printed. - - This method is optional. If it does exist, this method must - return a string. - - Some display hints are predefined by GDB: - - `array' - Indicate that the object being printed is "array-like". The - CLI uses this to respect parameters such as `set print - elements' and `set print array'. - - `map' - Indicate that the object being printed is "map-like", and - that the children of this value can be assumed to alternate - between keys and values. - - `string' - Indicate that the object being printed is "string-like". If - the printer's `to_string' method returns a Python string of - some kind, then GDB will call its internal language-specific - string-printing function to format the string. For the CLI - this means adding quotation marks, possibly escaping some - characters, respecting `set print elements', and the like. - - -- Operation on pretty printer: to_string (self) - GDB will call this method to display the string representation of - the value passed to the object's constructor. - - When printing from the CLI, if the `to_string' method exists, then - GDB will prepend its result to the values returned by `children'. - Exactly how this formatting is done is dependent on the display - hint, and may change as more hints are added. Also, depending on - the print settings (*note Print Settings::), the CLI may print - just the result of `to_string' in a stack trace, omitting the - result of `children'. - - If this method returns a string, it is printed verbatim. - - Otherwise, if this method returns an instance of `gdb.Value', then - GDB prints this value. This may result in a call to another - pretty-printer. - - If instead the method returns a Python value which is convertible - to a `gdb.Value', then GDB performs the conversion and prints the - resulting value. Again, this may result in a call to another - pretty-printer. Python scalars (integers, floats, and booleans) - and strings are convertible to `gdb.Value'; other types are not. - - Finally, if this method returns `None' then no further operations - are peformed in this method and nothing is printed. - - If the result is not one of these types, an exception is raised. - - GDB provides a function which can be used to look up the default -pretty-printer for a `gdb.Value': - - -- Function: default_visualizer value - This function takes a `gdb.Value' object as an argument. If a - pretty-printer for this value exists, then it is returned. If no - such printer exists, then this returns `None'. - - -File: gdb.info, Node: Selecting Pretty-Printers, Next: Writing a Pretty-Printer, Prev: Pretty Printing API, Up: Python API - -23.2.2.6 Selecting Pretty-Printers -.................................. - -The Python list `gdb.pretty_printers' contains an array of functions or -callable objects that have been registered via addition as a -pretty-printer. Printers in this list are called `global' printers, -they're available when debugging all inferiors. Each `gdb.Progspace' -contains a `pretty_printers' attribute. Each `gdb.Objfile' also -contains a `pretty_printers' attribute. - - Each function on these lists is passed a single `gdb.Value' argument -and should return a pretty-printer object conforming to the interface -definition above (*note Pretty Printing API::). If a function cannot -create a pretty-printer for the value, it should return `None'. - - GDB first checks the `pretty_printers' attribute of each -`gdb.Objfile' in the current program space and iteratively calls each -enabled lookup routine in the list for that `gdb.Objfile' until it -receives a pretty-printer object. If no pretty-printer is found in the -objfile lists, GDB then searches the pretty-printer list of the current -program space, calling each enabled function until an object is -returned. After these lists have been exhausted, it tries the global -`gdb.pretty_printers' list, again calling each enabled function until an -object is returned. - - The order in which the objfiles are searched is not specified. For a -given list, functions are always invoked from the head of the list, and -iterated over sequentially until the end of the list, or a printer -object is returned. - - For various reasons a pretty-printer may not work. For example, the -underlying data structure may have changed and the pretty-printer is -out of date. - - The consequences of a broken pretty-printer are severe enough that -GDB provides support for enabling and disabling individual printers. -For example, if `print frame-arguments' is on, a backtrace can become -highly illegible if any argument is printed with a broken printer. - - Pretty-printers are enabled and disabled by attaching an `enabled' -attribute to the registered function or callable object. If this -attribute is present and its value is `False', the printer is disabled, -otherwise the printer is enabled. - - -File: gdb.info, Node: Writing a Pretty-Printer, Next: Inferiors In Python, Prev: Selecting Pretty-Printers, Up: Python API - -23.2.2.7 Writing a Pretty-Printer -................................. - -A pretty-printer consists of two parts: a lookup function to detect if -the type is supported, and the printer itself. - - Here is an example showing how a `std::string' printer might be -written. *Note Pretty Printing API::, for details on the API this class -must provide. - - class StdStringPrinter(object): - "Print a std::string" - - def __init__(self, val): - self.val = val - - def to_string(self): - return self.val['_M_dataplus']['_M_p'] - - def display_hint(self): - return 'string' - - And here is an example showing how a lookup function for the printer -example above might be written. - - def str_lookup_function(val): - lookup_tag = val.type.tag - if lookup_tag == None: - return None - regex = re.compile("^std::basic_string<char,.*>$") - if regex.match(lookup_tag): - return StdStringPrinter(val) - return None - - The example lookup function extracts the value's type, and attempts -to match it to a type that it can pretty-print. If it is a type the -printer can pretty-print, it will return a printer object. If not, it -returns `None'. - - We recommend that you put your core pretty-printers into a Python -package. If your pretty-printers are for use with a library, we -further recommend embedding a version number into the package name. -This practice will enable GDB to load multiple versions of your -pretty-printers at the same time, because they will have different -names. - - You should write auto-loaded code (*note Auto-loading::) such that it -can be evaluated multiple times without changing its meaning. An ideal -auto-load file will consist solely of `import's of your printer -modules, followed by a call to a register pretty-printers with the -current objfile. - - Taken as a whole, this approach will scale nicely to multiple -inferiors, each potentially using a different library version. -Embedding a version number in the Python package name will ensure that -GDB is able to load both sets of printers simultaneously. Then, -because the search for pretty-printers is done by objfile, and because -your auto-loaded code took care to register your library's printers -with a specific objfile, GDB will find the correct printers for the -specific version of the library used by each inferior. - - To continue the `std::string' example (*note Pretty Printing API::), -this code might appear in `gdb.libstdcxx.v6': - - def register_printers(objfile): - objfile.pretty_printers.add(str_lookup_function) - -And then the corresponding contents of the auto-load file would be: - - import gdb.libstdcxx.v6 - gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) - - The previous example illustrates a basic pretty-printer. There are -a few things that can be improved on. The printer doesn't have a name, -making it hard to identify in a list of installed printers. The lookup -function has a name, but lookup functions can have arbitrary, even -identical, names. - - Second, the printer only handles one type, whereas a library -typically has several types. One could install a lookup function for -each desired type in the library, but one could also have a single -lookup function recognize several types. The latter is the -conventional way this is handled. If a pretty-printer can handle -multiple data types, then its "subprinters" are the printers for the -individual data types. - - The `gdb.printing' module provides a formal way of solving these -problems (*note gdb.printing::). Here is another example that handles -multiple types. - - These are the types we are going to pretty-print: - - struct foo { int a, b; }; - struct bar { struct foo x, y; }; - - Here are the printers: - - class fooPrinter: - """Print a foo object.""" - - def __init__(self, val): - self.val = val - - def to_string(self): - return ("a=<" + str(self.val["a"]) + - "> b=<" + str(self.val["b"]) + ">") - - class barPrinter: - """Print a bar object.""" - - def __init__(self, val): - self.val = val - - def to_string(self): - return ("x=<" + str(self.val["x"]) + - "> y=<" + str(self.val["y"]) + ">") - - This example doesn't need a lookup function, that is handled by the -`gdb.printing' module. Instead a function is provided to build up the -object that handles the lookup. - - import gdb.printing - - def build_pretty_printer(): - pp = gdb.printing.RegexpCollectionPrettyPrinter( - "my_library") - pp.add_printer('foo', '^foo$', fooPrinter) - pp.add_printer('bar', '^bar$', barPrinter) - return pp - - And here is the autoload support: - - import gdb.printing - import my_library - gdb.printing.register_pretty_printer( - gdb.current_objfile(), - my_library.build_pretty_printer()) - - Finally, when this printer is loaded into GDB, here is the -corresponding output of `info pretty-printer': - - (gdb) info pretty-printer - my_library.so: - my_library - foo - bar - - -File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing a Pretty-Printer, Up: Python API - -23.2.2.8 Inferiors In Python -............................ - -Programs which are being run under GDB are called inferiors (*note -Inferiors and Programs::). Python scripts can access information about -and manipulate inferiors controlled by GDB via objects of the -`gdb.Inferior' class. - - The following inferior-related functions are available in the `gdb' -module: - - -- Function: inferiors - Return a tuple containing all inferior objects. - - A `gdb.Inferior' object has the following attributes: - - -- Instance Variable of Inferior: num - ID of inferior, as assigned by GDB. - - -- Instance Variable of Inferior: pid - Process ID of the inferior, as assigned by the underlying - operating system. - - -- Instance Variable of Inferior: was_attached - Boolean signaling whether the inferior was created using - `attach', or started by GDB itself. - - A `gdb.Inferior' object has the following methods: - - -- Method on Inferior: is_valid - Returns `True' if the `gdb.Inferior' object is valid, `False' - if not. A `gdb.Inferior' object will become invalid if the - inferior no longer exists within GDB. All other - `gdb.Inferior' methods will throw an exception if it is - invalid at the time the method is called. - - -- Method on Inferior: threads - This method returns a tuple holding all the threads which are - valid when it is called. If there are no valid threads, the - method will return an empty tuple. - - -- Method on Inferior: read_memory address length - Read LENGTH bytes of memory from the inferior, starting at - ADDRESS. Returns a buffer object, which behaves much like an - array or a string. It can be modified and given to the - `gdb.write_memory' function. - - -- Method on Inferior: write_memory address buffer [length] - Write the contents of BUFFER to the inferior, starting at - ADDRESS. The BUFFER parameter must be a Python object which - supports the buffer protocol, i.e., a string, an array or the - object returned from `gdb.read_memory'. If given, LENGTH - determines the number of bytes from BUFFER to be written. - - -- Method on Inferior: search_memory address length pattern - Search a region of the inferior memory starting at ADDRESS - with the given LENGTH using the search pattern supplied in - PATTERN. The PATTERN parameter must be a Python object which - supports the buffer protocol, i.e., a string, an array or the - object returned from `gdb.read_memory'. Returns a Python - `Long' containing the address where the pattern was found, or - `None' if the pattern could not be found. - - -File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API - -23.2.2.9 Events In Python -......................... - -GDB provides a general event facility so that Python code can be -notified of various state changes, particularly changes that occur in -the inferior. - - An "event" is just an object that describes some state change. The -type of the object and its attributes will vary depending on the details -of the change. All the existing events are described below. - - In order to be notified of an event, you must register an event -handler with an "event registry". An event registry is an object in the -`gdb.events' module which dispatches particular events. A registry -provides methods to register and unregister event handlers: - - -- Method on EventRegistry: connect object - Add the given callable OBJECT to the registry. This object - will be called when an event corresponding to this registry - occurs. - - -- Method on EventRegistry: disconnect object - Remove the given OBJECT from the registry. Once removed, the - object will no longer receive notifications of events. - - Here is an example: - - def exit_handler (event): - print "event type: exit" - print "exit code: %d" % (event.exit_code) - - gdb.events.exited.connect (exit_handler) - - In the above example we connect our handler `exit_handler' to the -registry `events.exited'. Once connected, `exit_handler' gets called -when the inferior exits. The argument "event" in this example is of -type `gdb.ExitedEvent'. As you can see in the example the -`ExitedEvent' object has an attribute which indicates the exit code of -the inferior. - - The following is a listing of the event registries that are -available and details of the events they emit: - -`events.cont' - Emits `gdb.ThreadEvent'. - - Some events can be thread specific when GDB is running in non-stop - mode. When represented in Python, these events all extend - `gdb.ThreadEvent'. Note, this event is not emitted directly; - instead, events which are emitted by this or other modules might - extend this event. Examples of these events are - `gdb.BreakpointEvent' and `gdb.ContinueEvent'. - - -- Instance Variable of ThreadEvent: inferior_thread - In non-stop mode this attribute will be set to the - specific thread which was involved in the emitted event. - Otherwise, it will be set to `None'. - - Emits `gdb.ContinueEvent' which extends `gdb.ThreadEvent'. - - This event indicates that the inferior has been continued after a - stop. For inherited attribute refer to `gdb.ThreadEvent' above. - -`events.exited' - Emits `events.ExitedEvent' which indicates that the inferior has - exited. `events.ExitedEvent' has one optional attribute. This - attribute will exist only in the case that the inferior exited - with some status. - -- Instance Variable of ExitedEvent: exit_code - An integer representing the exit code which the inferior - has returned. - -`events.stop' - Emits `gdb.StopEvent' which extends `gdb.ThreadEvent'. - - Indicates that the inferior has stopped. All events emitted by - this registry extend StopEvent. As a child of `gdb.ThreadEvent', - `gdb.StopEvent' will indicate the stopped thread when GDB is - running in non-stop mode. Refer to `gdb.ThreadEvent' above for - more details. - - Emits `gdb.SignalEvent' which extends `gdb.StopEvent'. - - This event indicates that the inferior or one of its threads has - received as signal. `gdb.SignalEvent' has the following - attributes: - - -- Instance Variable of SignalEvent: stop_signal - A string representing the signal received by the - inferior. A list of possible signal values can be - obtained by running the command `info signals' in the - GDB command prompt. - - Also emits `gdb.BreakpointEvent' which extends `gdb.StopEvent'. - - `gdb.BreakpointEvent' event indicates that a breakpoint has been - hit, and has the following attributes: - - -- Instance Variable of BreakpointEvent: breakpoint - A reference to the breakpoint that was hit of type - `gdb.Breakpoint'. *Note Breakpoints In Python::, for - details of the `gdb.Breakpoint' object. - - - -File: gdb.info, Node: Threads In Python, Next: Commands In Python, Prev: Events In Python, Up: Python API - -23.2.2.10 Threads In Python -........................... - -Python scripts can access information about, and manipulate inferior -threads controlled by GDB, via objects of the `gdb.InferiorThread' -class. - - The following thread-related functions are available in the `gdb' -module: - - -- Function: selected_thread - This function returns the thread object for the selected thread. - If there is no selected thread, this will return `None'. - - A `gdb.InferiorThread' object has the following attributes: - - -- Instance Variable of InferiorThread: name - The name of the thread. If the user specified a name using - `thread name', then this returns that name. Otherwise, if an - OS-supplied name is available, then it is returned. - Otherwise, this returns `None'. - - This attribute can be assigned to. The new value must be a - string object, which sets the new name, or `None', which - removes any user-specified thread name. - - -- Instance Variable of InferiorThread: num - ID of the thread, as assigned by GDB. - - -- Instance Variable of InferiorThread: ptid - ID of the thread, as assigned by the operating system. This - attribute is a tuple containing three integers. The first is - the Process ID (PID); the second is the Lightweight Process - ID (LWPID), and the third is the Thread ID (TID). Either the - LWPID or TID may be 0, which indicates that the operating - system does not use that identifier. - - A `gdb.InferiorThread' object has the following methods: - - -- Method on InferiorThread: is_valid - Returns `True' if the `gdb.InferiorThread' object is valid, - `False' if not. A `gdb.InferiorThread' object will become - invalid if the thread exits, or the inferior that the thread - belongs is deleted. All other `gdb.InferiorThread' methods - will throw an exception if it is invalid at the time the - method is called. - - -- Method on InferiorThread: switch - This changes GDB's currently selected thread to the one - represented by this object. - - -- Method on InferiorThread: is_stopped - Return a Boolean indicating whether the thread is stopped. - - -- Method on InferiorThread: is_running - Return a Boolean indicating whether the thread is running. - - -- Method on InferiorThread: is_exited - Return a Boolean indicating whether the thread is exited. - - -File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Threads In Python, Up: Python API - -23.2.2.11 Commands In Python -............................ - -You can implement new GDB CLI commands in Python. A CLI command is -implemented using an instance of the `gdb.Command' class, most commonly -using a subclass. - - -- Method on Command: __init__ name COMMAND_CLASS [COMPLETER_CLASS] - [PREFIX] - The object initializer for `Command' registers the new command - with GDB. This initializer is normally invoked from the subclass' - own `__init__' method. - - NAME is the name of the command. If NAME consists of multiple - words, then the initial words are looked for as prefix commands. - In this case, if one of the prefix commands does not exist, an - exception is raised. - - There is no support for multi-line commands. - - COMMAND_CLASS should be one of the `COMMAND_' constants defined - below. This argument tells GDB how to categorize the new command - in the help system. - - COMPLETER_CLASS is an optional argument. If given, it should be - one of the `COMPLETE_' constants defined below. This argument - tells GDB how to perform completion for this command. If not - given, GDB will attempt to complete using the object's `complete' - method (see below); if no such method is found, an error will - occur when completion is attempted. - - PREFIX is an optional argument. If `True', then the new command - is a prefix command; sub-commands of this command may be - registered. - - The help text for the new command is taken from the Python - documentation string for the command's class, if there is one. If - no documentation string is provided, the default value "This - command is not documented." is used. - - -- Method on Command: dont_repeat - By default, a GDB command is repeated when the user enters a blank - line at the command prompt. A command can suppress this behavior - by invoking the `dont_repeat' method. This is similar to the user - command `dont-repeat', see *note dont-repeat: Define. - - -- Method on Command: invoke argument from_tty - This method is called by GDB when this command is invoked. - - ARGUMENT is a string. It is the argument to the command, after - leading and trailing whitespace has been stripped. - - FROM_TTY is a boolean argument. When true, this means that the - command was entered by the user at the terminal; when false it - means that the command came from elsewhere. - - If this method throws an exception, it is turned into a GDB - `error' call. Otherwise, the return value is ignored. - - To break ARGUMENT up into an argv-like string use - `gdb.string_to_argv'. This function behaves identically to GDB's - internal argument lexer `buildargv'. It is recommended to use - this for consistency. Arguments are separated by spaces and may - be quoted. Example: - - print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") - ['1', '2 "3', '4 "5', "6 '7"] - - - -- Method on Command: complete text word - This method is called by GDB when the user attempts completion on - this command. All forms of completion are handled by this method, - that is, the <TAB> and <M-?> key bindings (*note Completion::), - and the `complete' command (*note complete: Help.). - - The arguments TEXT and WORD are both strings. TEXT holds the - complete command line up to the cursor's location. WORD holds the - last word of the command line; this is computed using a - word-breaking heuristic. - - The `complete' method can return several values: - * If the return value is a sequence, the contents of the - sequence are used as the completions. It is up to `complete' - to ensure that the contents actually do complete the word. A - zero-length sequence is allowed, it means that there were no - completions available. Only string elements of the sequence - are used; other elements in the sequence are ignored. - - * If the return value is one of the `COMPLETE_' constants - defined below, then the corresponding GDB-internal completion - function is invoked, and its result is used. - - * All other results are treated as though there were no - available completions. - - When a new command is registered, it must be declared as a member of -some general class of commands. This is used to classify top-level -commands in the on-line help system; note that prefix commands are not -listed under their own category but rather that of their top-level -command. The available classifications are represented by constants -defined in the `gdb' module: - -`COMMAND_NONE' - The command does not belong to any particular class. A command in - this category will not be displayed in any of the help categories. - -`COMMAND_RUNNING' - The command is related to running the inferior. For example, - `start', `step', and `continue' are in this category. Type `help - running' at the GDB prompt to see a list of commands in this - category. - -`COMMAND_DATA' - The command is related to data or variables. For example, `call', - `find', and `print' are in this category. Type `help data' at the - GDB prompt to see a list of commands in this category. - -`COMMAND_STACK' - The command has to do with manipulation of the stack. For example, - `backtrace', `frame', and `return' are in this category. Type - `help stack' at the GDB prompt to see a list of commands in this - category. - -`COMMAND_FILES' - This class is used for file-related commands. For example, - `file', `list' and `section' are in this category. Type `help - files' at the GDB prompt to see a list of commands in this - category. - -`COMMAND_SUPPORT' - This should be used for "support facilities", generally meaning - things that are useful to the user when interacting with GDB, but - not related to the state of the inferior. For example, `help', - `make', and `shell' are in this category. Type `help support' at - the GDB prompt to see a list of commands in this category. - -`COMMAND_STATUS' - The command is an `info'-related command, that is, related to the - state of GDB itself. For example, `info', `macro', and `show' are - in this category. Type `help status' at the GDB prompt to see a - list of commands in this category. - -`COMMAND_BREAKPOINTS' - The command has to do with breakpoints. For example, `break', - `clear', and `delete' are in this category. Type `help - breakpoints' at the GDB prompt to see a list of commands in this - category. - -`COMMAND_TRACEPOINTS' - The command has to do with tracepoints. For example, `trace', - `actions', and `tfind' are in this category. Type `help - tracepoints' at the GDB prompt to see a list of commands in this - category. - -`COMMAND_OBSCURE' - The command is only used in unusual circumstances, or is not of - general interest to users. For example, `checkpoint', `fork', and - `stop' are in this category. Type `help obscure' at the GDB - prompt to see a list of commands in this category. - -`COMMAND_MAINTENANCE' - The command is only useful to GDB maintainers. The `maintenance' - and `flushregs' commands are in this category. Type `help - internals' at the GDB prompt to see a list of commands in this - category. - - A new command can use a predefined completion function, either by -specifying it via an argument at initialization, or by returning it -from the `complete' method. These predefined completion constants are -all defined in the `gdb' module: - -`COMPLETE_NONE' - This constant means that no completion should be done. - -`COMPLETE_FILENAME' - This constant means that filename completion should be performed. - -`COMPLETE_LOCATION' - This constant means that location completion should be done. - *Note Specify Location::. - -`COMPLETE_COMMAND' - This constant means that completion should examine GDB command - names. - -`COMPLETE_SYMBOL' - This constant means that completion should be done using symbol - names as the source. - - The following code snippet shows how a trivial CLI command can be -implemented in Python: - - class HelloWorld (gdb.Command): - """Greet the whole world.""" - - def __init__ (self): - super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) - - def invoke (self, arg, from_tty): - print "Hello, World!" - - HelloWorld () - - The last line instantiates the class, and is necessary to trigger the -registration of the command with GDB. Depending on how the Python code -is read into GDB, you may need to import the `gdb' module explicitly. - - -File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API - -23.2.2.12 Parameters In Python -.............................. - -You can implement new GDB parameters using Python. A new parameter is -implemented as an instance of the `gdb.Parameter' class. - - Parameters are exposed to the user via the `set' and `show' -commands. *Note Help::. - - There are many parameters that already exist and can be set in GDB. -Two examples are: `set follow fork' and `set charset'. Setting these -parameters influences certain behavior in GDB. Similarly, you can -define parameters that can be used to influence behavior in custom -Python scripts and commands. - - -- Method on Parameter: __init__ name COMMAND-CLASS PARAMETER-CLASS - [ENUM-SEQUENCE] - The object initializer for `Parameter' registers the new parameter - with GDB. This initializer is normally invoked from the subclass' - own `__init__' method. - - NAME is the name of the new parameter. If NAME consists of - multiple words, then the initial words are looked for as prefix - parameters. An example of this can be illustrated with the `set - print' set of parameters. If NAME is `print foo', then `print' - will be searched as the prefix parameter. In this case the - parameter can subsequently be accessed in GDB as `set print foo'. - - If NAME consists of multiple words, and no prefix parameter group - can be found, an exception is raised. - - COMMAND-CLASS should be one of the `COMMAND_' constants (*note - Commands In Python::). This argument tells GDB how to categorize - the new parameter in the help system. - - PARAMETER-CLASS should be one of the `PARAM_' constants defined - below. This argument tells GDB the type of the new parameter; - this information is used for input validation and completion. - - If PARAMETER-CLASS is `PARAM_ENUM', then ENUM-SEQUENCE must be a - sequence of strings. These strings represent the possible values - for the parameter. - - If PARAMETER-CLASS is not `PARAM_ENUM', then the presence of a - fourth argument will cause an exception to be thrown. - - The help text for the new parameter is taken from the Python - documentation string for the parameter's class, if there is one. - If there is no documentation string, a default value is used. - - -- Instance Variable of Parameter: set_doc - If this attribute exists, and is a string, then its value is used - as the help text for this parameter's `set' command. The value is - examined when `Parameter.__init__' is invoked; subsequent changes - have no effect. - - -- Instance Variable of Parameter: show_doc - If this attribute exists, and is a string, then its value is used - as the help text for this parameter's `show' command. The value is - examined when `Parameter.__init__' is invoked; subsequent changes - have no effect. - - -- Instance Variable of Parameter: value - The `value' attribute holds the underlying value of the parameter. - It can be read and assigned to just as any other attribute. GDB - does validation when assignments are made. - - There are two methods that should be implemented in any `Parameter' -class. These are: - - -- Operation on parameter: get_set_string self - GDB will call this method when a PARAMETER's value has been - changed via the `set' API (for example, `set foo off'). The - `value' attribute has already been populated with the new value - and may be used in output. This method must return a string. - - -- Operation on parameter: get_show_string self svalue - GDB will call this method when a PARAMETER's `show' API has been - invoked (for example, `show foo'). The argument `svalue' receives - the string representation of the current value. This method must - return a string. - - When a new parameter is defined, its type must be specified. The -available types are represented by constants defined in the `gdb' -module: - -`PARAM_BOOLEAN' - The value is a plain boolean. The Python boolean values, `True' - and `False' are the only valid values. - -`PARAM_AUTO_BOOLEAN' - The value has three possible states: true, false, and `auto'. In - Python, true and false are represented using boolean constants, and - `auto' is represented using `None'. - -`PARAM_UINTEGER' - The value is an unsigned integer. The value of 0 should be - interpreted to mean "unlimited". - -`PARAM_INTEGER' - The value is a signed integer. The value of 0 should be - interpreted to mean "unlimited". - -`PARAM_STRING' - The value is a string. When the user modifies the string, any - escape sequences, such as `\t', `\f', and octal escapes, are - translated into corresponding characters and encoded into the - current host charset. - -`PARAM_STRING_NOESCAPE' - The value is a string. When the user modifies the string, escapes - are passed through untranslated. - -`PARAM_OPTIONAL_FILENAME' - The value is a either a filename (a string), or `None'. - -`PARAM_FILENAME' - The value is a filename. This is just like - `PARAM_STRING_NOESCAPE', but uses file names for completion. - -`PARAM_ZINTEGER' - The value is an integer. This is like `PARAM_INTEGER', except 0 - is interpreted as itself. - -`PARAM_ENUM' - The value is a string, which must be one of a collection string - constants provided when the parameter is created. - - -File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API - -23.2.2.13 Writing new convenience functions -........................................... - -You can implement new convenience functions (*note Convenience Vars::) -in Python. A convenience function is an instance of a subclass of the -class `gdb.Function'. - - -- Method on Function: __init__ name - The initializer for `Function' registers the new function with - GDB. The argument NAME is the name of the function, a string. - The function will be visible to the user as a convenience variable - of type `internal function', whose name is the same as the given - NAME. - - The documentation for the new function is taken from the - documentation string for the new class. - - -- Method on Function: invoke *ARGS - When a convenience function is evaluated, its arguments are - converted to instances of `gdb.Value', and then the function's - `invoke' method is called. Note that GDB does not predetermine - the arity of convenience functions. Instead, all available - arguments are passed to `invoke', following the standard Python - calling convention. In particular, a convenience function can - have default values for parameters without ill effect. - - The return value of this method is used as its value in the - enclosing expression. If an ordinary Python value is returned, it - is converted to a `gdb.Value' following the usual rules. - - The following code snippet shows how a trivial convenience function -can be implemented in Python: - - class Greet (gdb.Function): - """Return string to greet someone. - Takes a name as argument.""" - - def __init__ (self): - super (Greet, self).__init__ ("greet") - - def invoke (self, name): - return "Hello, %s!" % name.string () - - Greet () - - The last line instantiates the class, and is necessary to trigger the -registration of the function with GDB. Depending on how the Python -code is read into GDB, you may need to import the `gdb' module -explicitly. - - -File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API - -23.2.2.14 Program Spaces In Python -.................................. - -A program space, or "progspace", represents a symbolic view of an -address space. It consists of all of the objfiles of the program. -*Note Objfiles In Python::. *Note program spaces: Inferiors and -Programs, for more details about program spaces. - - The following progspace-related functions are available in the `gdb' -module: - - -- Function: current_progspace - This function returns the program space of the currently selected - inferior. *Note Inferiors and Programs::. - - -- Function: progspaces - Return a sequence of all the progspaces currently known to GDB. - - Each progspace is represented by an instance of the `gdb.Progspace' -class. - - -- Instance Variable of Progspace: filename - The file name of the progspace as a string. - - -- Instance Variable of Progspace: pretty_printers - The `pretty_printers' attribute is a list of functions. It is - used to look up pretty-printers. A `Value' is passed to each - function in order; if the function returns `None', then the search - continues. Otherwise, the return value should be an object which - is used to format the value. *Note Pretty Printing API::, for more - information. - - -File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API - -23.2.2.15 Objfiles In Python -............................ - -GDB loads symbols for an inferior from various symbol-containing files -(*note Files::). These include the primary executable file, any shared -libraries used by the inferior, and any separate debug info files -(*note Separate Debug Files::). GDB calls these symbol-containing -files "objfiles". - - The following objfile-related functions are available in the `gdb' -module: - - -- Function: current_objfile - When auto-loading a Python script (*note Auto-loading::), GDB sets - the "current objfile" to the corresponding objfile. This function - returns the current objfile. If there is no current objfile, this - function returns `None'. - - -- Function: objfiles - Return a sequence of all the objfiles current known to GDB. *Note - Objfiles In Python::. - - Each objfile is represented by an instance of the `gdb.Objfile' -class. - - -- Instance Variable of Objfile: filename - The file name of the objfile as a string. - - -- Instance Variable of Objfile: pretty_printers - The `pretty_printers' attribute is a list of functions. It is - used to look up pretty-printers. A `Value' is passed to each - function in order; if the function returns `None', then the search - continues. Otherwise, the return value should be an object which - is used to format the value. *Note Pretty Printing API::, for more - information. - - A `gdb.Objfile' object has the following methods: - - -- Method on Objfile: is_valid - Returns `True' if the `gdb.Objfile' object is valid, `False' if - not. A `gdb.Objfile' object can become invalid if the object file - it refers to is not loaded in GDB any longer. All other - `gdb.Objfile' methods will throw an exception if it is invalid at - the time the method is called. - - -File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API - -23.2.2.16 Accessing inferior stack frames from Python. -...................................................... - -When the debugged program stops, GDB is able to analyze its call stack -(*note Stack frames: Frames.). The `gdb.Frame' class represents a -frame in the stack. A `gdb.Frame' object is only valid while its -corresponding frame exists in the inferior's stack. If you try to use -an invalid frame object, GDB will throw a `gdb.error' exception (*note -Exception Handling::). - - Two `gdb.Frame' objects can be compared for equality with the `==' -operator, like: - - (gdb) python print gdb.newest_frame() == gdb.selected_frame () - True - - The following frame-related functions are available in the `gdb' -module: - - -- Function: selected_frame - Return the selected frame object. (*note Selecting a Frame: - Selection.). - - -- Function: newest_frame - Return the newest frame object for the selected thread. - - -- Function: frame_stop_reason_string reason - Return a string explaining the reason why GDB stopped unwinding - frames, as expressed by the given REASON code (an integer, see the - `unwind_stop_reason' method further down in this section). - - A `gdb.Frame' object has the following methods: - - -- Method on Frame: is_valid - Returns true if the `gdb.Frame' object is valid, false if not. - A frame object can become invalid if the frame it refers to - doesn't exist anymore in the inferior. All `gdb.Frame' - methods will throw an exception if it is invalid at the time - the method is called. - - -- Method on Frame: name - Returns the function name of the frame, or `None' if it can't - be obtained. - - -- Method on Frame: type - Returns the type of the frame. The value can be one of: - `gdb.NORMAL_FRAME' - An ordinary stack frame. - - `gdb.DUMMY_FRAME' - A fake stack frame that was created by GDB when - performing an inferior function call. - - `gdb.INLINE_FRAME' - A frame representing an inlined function. The function - was inlined into a `gdb.NORMAL_FRAME' that is older than - this one. - - `gdb.SIGTRAMP_FRAME' - A signal trampoline frame. This is the frame created by - the OS when it calls into a signal handler. - - `gdb.ARCH_FRAME' - A fake stack frame representing a cross-architecture - call. - - `gdb.SENTINEL_FRAME' - This is like `gdb.NORMAL_FRAME', but it is only used for - the newest frame. - - -- Method on Frame: unwind_stop_reason - Return an integer representing the reason why it's not - possible to find more frames toward the outermost frame. Use - `gdb.frame_stop_reason_string' to convert the value returned - by this function to a string. - - -- Method on Frame: pc - Returns the frame's resume address. - - -- Method on Frame: block - Return the frame's code block. *Note Blocks In Python::. - - -- Method on Frame: function - Return the symbol for the function corresponding to this - frame. *Note Symbols In Python::. - - -- Method on Frame: older - Return the frame that called this frame. - - -- Method on Frame: newer - Return the frame called by this frame. - - -- Method on Frame: find_sal - Return the frame's symtab and line object. *Note Symbol - Tables In Python::. - - -- Method on Frame: read_var variable [block] - Return the value of VARIABLE in this frame. If the optional - argument BLOCK is provided, search for the variable from that - block; otherwise start at the frame's current block (which is - determined by the frame's current program counter). VARIABLE - must be a string or a `gdb.Symbol' object. BLOCK must be a - `gdb.Block' object. - - -- Method on Frame: select - Set this frame to be the selected frame. *Note Examining the - Stack: Stack. - - -File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API - -23.2.2.17 Accessing frame blocks from Python. -............................................. - -Within each frame, GDB maintains information on each block stored in -that frame. These blocks are organized hierarchically, and are -represented individually in Python as a `gdb.Block'. Please see *note -Frames In Python::, for a more in-depth discussion on frames. -Furthermore, see *note Examining the Stack: Stack, for more detailed -technical information on GDB's book-keeping of the stack. - - The following block-related functions are available in the `gdb' -module: - - -- Function: block_for_pc pc - Return the `gdb.Block' containing the given PC value. If the - block cannot be found for the PC value specified, the function - will return `None'. - - A `gdb.Block' object has the following methods: - - -- Method on Block: is_valid - Returns `True' if the `gdb.Block' object is valid, `False' if - not. A block object can become invalid if the block it - refers to doesn't exist anymore in the inferior. All other - `gdb.Block' methods will throw an exception if it is invalid - at the time the method is called. This method is also made - available to the Python iterator object that `gdb.Block' - provides in an iteration context and via the Python `iter' - built-in function. - - A `gdb.Block' object has the following attributes: - - -- Instance Variable of Block: start - The start address of the block. This attribute is not - writable. - - -- Instance Variable of Block: end - The end address of the block. This attribute is not writable. - - -- Instance Variable of Block: function - The name of the block represented as a `gdb.Symbol'. If the - block is not named, then this attribute holds `None'. This - attribute is not writable. - - -- Instance Variable of Block: superblock - The block containing this block. If this parent block does - not exist, this attribute holds `None'. This attribute is - not writable. - - -File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API - -23.2.2.18 Python representation of Symbols. -........................................... - -GDB represents every variable, function and type as an entry in a -symbol table. *Note Examining the Symbol Table: Symbols. Similarly, -Python represents these symbols in GDB with the `gdb.Symbol' object. - - The following symbol-related functions are available in the `gdb' -module: - - -- Function: lookup_symbol name [block] [domain] - This function searches for a symbol by name. The search scope can - be restricted to the parameters defined in the optional domain and - block arguments. - - NAME is the name of the symbol. It must be a string. The - optional BLOCK argument restricts the search to symbols visible in - that BLOCK. The BLOCK argument must be a `gdb.Block' object. If - omitted, the block for the current frame is used. The optional - DOMAIN argument restricts the search to the domain type. The - DOMAIN argument must be a domain constant defined in the `gdb' - module and described later in this chapter. - - The result is a tuple of two elements. The first element is a - `gdb.Symbol' object or `None' if the symbol is not found. If the - symbol is found, the second element is `True' if the symbol is a - field of a method's object (e.g., `this' in C++), otherwise it is - `False'. If the symbol is not found, the second element is - `False'. - - -- Function: lookup_global_symbol name [domain] - This function searches for a global symbol by name. The search - scope can be restricted to by the domain argument. - - NAME is the name of the symbol. It must be a string. The - optional DOMAIN argument restricts the search to the domain type. - The DOMAIN argument must be a domain constant defined in the `gdb' - module and described later in this chapter. - - The result is a `gdb.Symbol' object or `None' if the symbol is not - found. - - A `gdb.Symbol' object has the following attributes: - - -- Instance Variable of Symbol: type - The type of the symbol or `None' if no type is recorded. - This attribute is represented as a `gdb.Type' object. *Note - Types In Python::. This attribute is not writable. - - -- Instance Variable of Symbol: symtab - The symbol table in which the symbol appears. This attribute - is represented as a `gdb.Symtab' object. *Note Symbol Tables - In Python::. This attribute is not writable. - - -- Instance Variable of Symbol: name - The name of the symbol as a string. This attribute is not - writable. - - -- Instance Variable of Symbol: linkage_name - The name of the symbol, as used by the linker (i.e., may be - mangled). This attribute is not writable. - - -- Instance Variable of Symbol: print_name - The name of the symbol in a form suitable for output. This - is either `name' or `linkage_name', depending on whether the - user asked GDB to display demangled or mangled names. - - -- Instance Variable of Symbol: addr_class - The address class of the symbol. This classifies how to find - the value of a symbol. Each address class is a constant - defined in the `gdb' module and described later in this - chapter. - - -- Instance Variable of Symbol: is_argument - `True' if the symbol is an argument of a function. - - -- Instance Variable of Symbol: is_constant - `True' if the symbol is a constant. - - -- Instance Variable of Symbol: is_function - `True' if the symbol is a function or a method. - - -- Instance Variable of Symbol: is_variable - `True' if the symbol is a variable. - - A `gdb.Symbol' object has the following methods: - - -- Method on Symbol: is_valid - Returns `True' if the `gdb.Symbol' object is valid, `False' - if not. A `gdb.Symbol' object can become invalid if the - symbol it refers to does not exist in GDB any longer. All - other `gdb.Symbol' methods will throw an exception if it is - invalid at the time the method is called. - - The available domain categories in `gdb.Symbol' are represented as -constants in the `gdb' module: - -`SYMBOL_UNDEF_DOMAIN' - This is used when a domain has not been discovered or none of the - following domains apply. This usually indicates an error either - in the symbol information or in GDB's handling of symbols. - -`SYMBOL_VAR_DOMAIN' - This domain contains variables, function names, typedef names and - enum type values. - -`SYMBOL_STRUCT_DOMAIN' - This domain holds struct, union and enum type names. - -`SYMBOL_LABEL_DOMAIN' - This domain contains names of labels (for gotos). - -`SYMBOL_VARIABLES_DOMAIN' - This domain holds a subset of the `SYMBOLS_VAR_DOMAIN'; it - contains everything minus functions and types. - -`SYMBOL_FUNCTION_DOMAIN' - This domain contains all functions. - -`SYMBOL_TYPES_DOMAIN' - This domain contains all types. - - The available address class categories in `gdb.Symbol' are -represented as constants in the `gdb' module: - -`SYMBOL_LOC_UNDEF' - If this is returned by address class, it indicates an error either - in the symbol information or in GDB's handling of symbols. - -`SYMBOL_LOC_CONST' - Value is constant int. - -`SYMBOL_LOC_STATIC' - Value is at a fixed address. - -`SYMBOL_LOC_REGISTER' - Value is in a register. - -`SYMBOL_LOC_ARG' - Value is an argument. This value is at the offset stored within - the symbol inside the frame's argument list. - -`SYMBOL_LOC_REF_ARG' - Value address is stored in the frame's argument list. Just like - `LOC_ARG' except that the value's address is stored at the offset, - not the value itself. - -`SYMBOL_LOC_REGPARM_ADDR' - Value is a specified register. Just like `LOC_REGISTER' except - the register holds the address of the argument instead of the - argument itself. - -`SYMBOL_LOC_LOCAL' - Value is a local variable. - -`SYMBOL_LOC_TYPEDEF' - Value not used. Symbols in the domain `SYMBOL_STRUCT_DOMAIN' all - have this class. - -`SYMBOL_LOC_BLOCK' - Value is a block. - -`SYMBOL_LOC_CONST_BYTES' - Value is a byte-sequence. - -`SYMBOL_LOC_UNRESOLVED' - Value is at a fixed address, but the address of the variable has - to be determined from the minimal symbol table whenever the - variable is referenced. - -`SYMBOL_LOC_OPTIMIZED_OUT' - The value does not actually exist in the program. - -`SYMBOL_LOC_COMPUTED' - The value's address is a computed location. - - -File: gdb.info, Node: Symbol Tables In Python, Next: Lazy Strings In Python, Prev: Symbols In Python, Up: Python API - -23.2.2.19 Symbol table representation in Python. -................................................ - -Access to symbol table data maintained by GDB on the inferior is -exposed to Python via two objects: `gdb.Symtab_and_line' and -`gdb.Symtab'. Symbol table and line data for a frame is returned from -the `find_sal' method in `gdb.Frame' object. *Note Frames In Python::. - - For more information on GDB's symbol table management, see *note -Examining the Symbol Table: Symbols, for more information. - - A `gdb.Symtab_and_line' object has the following attributes: - - -- Instance Variable of Symtab_and_line: symtab - The symbol table object (`gdb.Symtab') for this frame. This - attribute is not writable. - - -- Instance Variable of Symtab_and_line: pc - Indicates the current program counter address. This - attribute is not writable. - - -- Instance Variable of Symtab_and_line: line - Indicates the current line number for this object. This - attribute is not writable. - - A `gdb.Symtab_and_line' object has the following methods: - - -- Method on Symtab_and_line: is_valid - Returns `True' if the `gdb.Symtab_and_line' object is valid, - `False' if not. A `gdb.Symtab_and_line' object can become - invalid if the Symbol table and line object it refers to does - not exist in GDB any longer. All other `gdb.Symtab_and_line' - methods will throw an exception if it is invalid at the time - the method is called. - - A `gdb.Symtab' object has the following attributes: - - -- Instance Variable of Symtab: filename - The symbol table's source filename. This attribute is not - writable. - - -- Instance Variable of Symtab: objfile - The symbol table's backing object file. *Note Objfiles In - Python::. This attribute is not writable. - - A `gdb.Symtab' object has the following methods: - - -- Method on Symtab: is_valid - Returns `True' if the `gdb.Symtab' object is valid, `False' - if not. A `gdb.Symtab' object can become invalid if the - symbol table it refers to does not exist in GDB any longer. - All other `gdb.Symtab' methods will throw an exception if it - is invalid at the time the method is called. - - -- Method on Symtab: fullname - Return the symbol table's source absolute file name. - - -File: gdb.info, Node: Breakpoints In Python, Prev: Lazy Strings In Python, Up: Python API - -23.2.2.20 Manipulating breakpoints using Python -............................................... - -Python code can manipulate breakpoints via the `gdb.Breakpoint' class. - - -- Method on Breakpoint: __init__ spec [type] [wp_class] [internal] - Create a new breakpoint. SPEC is a string naming the location of - the breakpoint, or an expression that defines a watchpoint. The - contents can be any location recognized by the `break' command, or - in the case of a watchpoint, by the `watch' command. The optional - TYPE denotes the breakpoint to create from the types defined later - in this chapter. This argument can be either: `BP_BREAKPOINT' or - `BP_WATCHPOINT'. TYPE defaults to `BP_BREAKPOINT'. The optional - INTERNAL argument allows the breakpoint to become invisible to the - user. The breakpoint will neither be reported when created, nor - will it be listed in the output from `info breakpoints' (but will - be listed with the `maint info breakpoints' command). The - optional WP_CLASS argument defines the class of watchpoint to - create, if TYPE is `BP_WATCHPOINT'. If a watchpoint class is not - provided, it is assumed to be a WP_WRITE class. - - -- Operation on gdb.Breakpoint: stop (self) - The `gdb.Breakpoint' class can be sub-classed and, in particular, - you may choose to implement the `stop' method. If this method is - defined as a sub-class of `gdb.Breakpoint', it will be called when - the inferior reaches any location of a breakpoint which - instantiates that sub-class. If the method returns `True', the - inferior will be stopped at the location of the breakpoint, - otherwise the inferior will continue. - - If there are multiple breakpoints at the same location with a - `stop' method, each one will be called regardless of the return - status of the previous. This ensures that all `stop' methods have - a chance to execute at that location. In this scenario if one of - the methods returns `True' but the others return `False', the - inferior will still be stopped. - - Example `stop' implementation: - - class MyBreakpoint (gdb.Breakpoint): - def stop (self): - inf_val = gdb.parse_and_eval("foo") - if inf_val == 3: - return True - return False - - The available watchpoint types represented by constants are defined -in the `gdb' module: - -`WP_READ' - Read only watchpoint. - -`WP_WRITE' - Write only watchpoint. - -`WP_ACCESS' - Read/Write watchpoint. - - -- Method on Breakpoint: is_valid - Return `True' if this `Breakpoint' object is valid, `False' - otherwise. A `Breakpoint' object can become invalid if the user - deletes the breakpoint. In this case, the object still exists, - but the underlying breakpoint does not. In the cases of - watchpoint scope, the watchpoint remains valid even if execution - of the inferior leaves the scope of that watchpoint. - - -- Method on Breakpoint: delete - Permanently deletes the GDB breakpoint. This also invalidates the - Python `Breakpoint' object. Any further access to this object's - attributes or methods will raise an error. - - -- Instance Variable of Breakpoint: enabled - This attribute is `True' if the breakpoint is enabled, and `False' - otherwise. This attribute is writable. - - -- Instance Variable of Breakpoint: silent - This attribute is `True' if the breakpoint is silent, and `False' - otherwise. This attribute is writable. - - Note that a breakpoint can also be silent if it has commands and - the first command is `silent'. This is not reported by the - `silent' attribute. - - -- Instance Variable of Breakpoint: thread - If the breakpoint is thread-specific, this attribute holds the - thread id. If the breakpoint is not thread-specific, this - attribute is `None'. This attribute is writable. - - -- Instance Variable of Breakpoint: task - If the breakpoint is Ada task-specific, this attribute holds the - Ada task id. If the breakpoint is not task-specific (or the - underlying language is not Ada), this attribute is `None'. This - attribute is writable. - - -- Instance Variable of Breakpoint: ignore_count - This attribute holds the ignore count for the breakpoint, an - integer. This attribute is writable. - - -- Instance Variable of Breakpoint: number - This attribute holds the breakpoint's number -- the identifier - used by the user to manipulate the breakpoint. This attribute is - not writable. - - -- Instance Variable of Breakpoint: type - This attribute holds the breakpoint's type -- the identifier used - to determine the actual breakpoint type or use-case. This - attribute is not writable. - - -- Instance Variable of Breakpoint: visible - This attribute tells whether the breakpoint is visible to the user - when set, or when the `info breakpoints' command is run. This - attribute is not writable. - - The available types are represented by constants defined in the `gdb' -module: - -`BP_BREAKPOINT' - Normal code breakpoint. - -`BP_WATCHPOINT' - Watchpoint breakpoint. - -`BP_HARDWARE_WATCHPOINT' - Hardware assisted watchpoint. - -`BP_READ_WATCHPOINT' - Hardware assisted read watchpoint. - -`BP_ACCESS_WATCHPOINT' - Hardware assisted access watchpoint. - - -- Instance Variable of Breakpoint: hit_count - This attribute holds the hit count for the breakpoint, an integer. - This attribute is writable, but currently it can only be set to - zero. - - -- Instance Variable of Breakpoint: location - This attribute holds the location of the breakpoint, as specified - by the user. It is a string. If the breakpoint does not have a - location (that is, it is a watchpoint) the attribute's value is - `None'. This attribute is not writable. - - -- Instance Variable of Breakpoint: expression - This attribute holds a breakpoint expression, as specified by the - user. It is a string. If the breakpoint does not have an - expression (the breakpoint is not a watchpoint) the attribute's - value is `None'. This attribute is not writable. - - -- Instance Variable of Breakpoint: condition - This attribute holds the condition of the breakpoint, as specified - by the user. It is a string. If there is no condition, this - attribute's value is `None'. This attribute is writable. - - -- Instance Variable of Breakpoint: commands - This attribute holds the commands attached to the breakpoint. If - there are commands, this attribute's value is a string holding all - the commands, separated by newlines. If there are no commands, - this attribute is `None'. This attribute is not writable. - - -File: gdb.info, Node: Lazy Strings In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API - -23.2.2.21 Python representation of lazy strings. -................................................ - -A "lazy string" is a string whose contents is not retrieved or encoded -until it is needed. - - A `gdb.LazyString' is represented in GDB as an `address' that points -to a region of memory, an `encoding' that will be used to encode that -region of memory, and a `length' to delimit the region of memory that -represents the string. The difference between a `gdb.LazyString' and a -string wrapped within a `gdb.Value' is that a `gdb.LazyString' will be -treated differently by GDB when printing. A `gdb.LazyString' is -retrieved and encoded during printing, while a `gdb.Value' wrapping a -string is immediately retrieved and encoded on creation. - - A `gdb.LazyString' object has the following functions: - - -- Method on LazyString: value - Convert the `gdb.LazyString' to a `gdb.Value'. This value will - point to the string in memory, but will lose all the delayed - retrieval, encoding and handling that GDB applies to a - `gdb.LazyString'. - - -- Instance Variable of LazyString: address - This attribute holds the address of the string. This attribute is - not writable. - - -- Instance Variable of LazyString: length - This attribute holds the length of the string in characters. If - the length is -1, then the string will be fetched and encoded up - to the first null of appropriate width. This attribute is not - writable. - - -- Instance Variable of LazyString: encoding - This attribute holds the encoding that will be applied to the - string when the string is printed by GDB. If the encoding is not - set, or contains an empty string, then GDB will select the most - appropriate encoding when the string is printed. This attribute - is not writable. - - -- Instance Variable of LazyString: type - This attribute holds the type that is represented by the lazy - string's type. For a lazy string this will always be a pointer - type. To resolve this to the lazy string's character type, use - the type's `target' method. *Note Types In Python::. This - attribute is not writable. - - -File: gdb.info, Node: Auto-loading, Next: Python modules, Prev: Python API, Up: Python - -23.2.3 Auto-loading -------------------- - -When a new object file is read (for example, due to the `file' command, -or because the inferior has loaded a shared library), GDB will look for -Python support scripts in several ways: `OBJFILE-gdb.py' and -`.debug_gdb_scripts' section. - -* Menu: - -* objfile-gdb.py file:: The `OBJFILE-gdb.py' file -* .debug_gdb_scripts section:: The `.debug_gdb_scripts' section -* Which flavor to choose?:: - - The auto-loading feature is useful for supplying application-specific -debugging commands and scripts. - - Auto-loading can be enabled or disabled, and the list of auto-loaded -scripts can be printed. - -`set auto-load-scripts [yes|no]' - Enable or disable the auto-loading of Python scripts. - -`show auto-load-scripts' - Show whether auto-loading of Python scripts is enabled or disabled. - -`info auto-load-scripts [REGEXP]' - Print the list of all scripts that GDB auto-loaded. - - Also printed is the list of scripts that were mentioned in the - `.debug_gdb_scripts' section and were not found (*note - .debug_gdb_scripts section::). This is useful because their names - are not printed when GDB tries to load them and fails. There may - be many of them, and printing an error message for each one is - problematic. - - If REGEXP is supplied only scripts with matching names are printed. - - Example: - - (gdb) info auto-load-scripts - Loaded Script - Yes py-section-script.py - full name: /tmp/py-section-script.py - Missing my-foo-pretty-printers.py - - When reading an auto-loaded file, GDB sets the "current objfile". -This is available via the `gdb.current_objfile' function (*note -Objfiles In Python::). This can be useful for registering -objfile-specific pretty-printers. - - -File: gdb.info, Node: objfile-gdb.py file, Next: .debug_gdb_scripts section, Up: Auto-loading - -23.2.3.1 The `OBJFILE-gdb.py' file -.................................. - -When a new object file is read, GDB looks for a file named -`OBJFILE-gdb.py', where OBJFILE is the object file's real name, formed -by ensuring that the file name is absolute, following all symlinks, and -resolving `.' and `..' components. If this file exists and is -readable, GDB will evaluate it as a Python script. - - If this file does not exist, and if the parameter -`debug-file-directory' is set (*note Separate Debug Files::), then GDB -will look for REAL-NAME in all of the directories mentioned in the -value of `debug-file-directory'. - - Finally, if this file does not exist, then GDB will look for a file -named `DATA-DIRECTORY/python/auto-load/REAL-NAME', where DATA-DIRECTORY -is GDB's data directory (available via `show data-directory', *note -Data Files::), and REAL-NAME is the object file's real name, as -described above. - - GDB does not track which files it has already auto-loaded this way. -GDB will load the associated script every time the corresponding -OBJFILE is opened. So your `-gdb.py' file should be careful to avoid -errors if it is evaluated more than once. - - -File: gdb.info, Node: .debug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdb.py file, Up: Auto-loading - -23.2.3.2 The `.debug_gdb_scripts' section -......................................... - -For systems using file formats like ELF and COFF, when GDB loads a new -object file it will look for a special section named -`.debug_gdb_scripts'. If this section exists, its contents is a list -of names of scripts to load. - - GDB will look for each specified script file first in the current -directory and then along the source search path (*note Specifying -Source Directories: Source Path.), except that `$cdir' is not searched, -since the compilation directory is not relevant to scripts. - - Entries can be placed in section `.debug_gdb_scripts' with, for -example, this GCC macro: - - /* Note: The "MS" section flags are to remove duplicates. */ - #define DEFINE_GDB_SCRIPT(script_name) \ - asm("\ - .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ - .byte 1\n\ - .asciz \"" script_name "\"\n\ - .popsection \n\ - "); - -Then one can reference the macro in a header or source file like this: - - DEFINE_GDB_SCRIPT ("my-app-scripts.py") - - The script name may include directories if desired. - - If the macro is put in a header, any application or library using -this header will get a reference to the specified script. - - -File: gdb.info, Node: Which flavor to choose?, Prev: .debug_gdb_scripts section, Up: Auto-loading - -23.2.3.3 Which flavor to choose? -................................ - -Given the multiple ways of auto-loading Python scripts, it might not -always be clear which one to choose. This section provides some -guidance. - - Benefits of the `-gdb.py' way: - - * Can be used with file formats that don't support multiple sections. - - * Ease of finding scripts for public libraries. - - Scripts specified in the `.debug_gdb_scripts' section are searched - for in the source search path. For publicly installed libraries, - e.g., `libstdc++', there typically isn't a source directory in - which to find the script. - - * Doesn't require source code additions. - - Benefits of the `.debug_gdb_scripts' way: - - * Works with static linking. - - Scripts for libraries done the `-gdb.py' way require an objfile to - trigger their loading. When an application is statically linked - the only objfile available is the executable, and it is cumbersome - to attach all the scripts from all the input libraries to the - executable's `-gdb.py' script. - - * Works with classes that are entirely inlined. - - Some classes can be entirely inlined, and thus there may not be an - associated shared library to attach a `-gdb.py' script to. - - * Scripts needn't be copied out of the source tree. - - In some circumstances, apps can be built out of large collections - of internal libraries, and the build infrastructure necessary to - install the `-gdb.py' scripts in a place where GDB can find them is - cumbersome. It may be easier to specify the scripts in the - `.debug_gdb_scripts' section as relative paths, and add a path to - the top of the source tree to the source search path. - - -File: gdb.info, Node: Python modules, Prev: Auto-loading, Up: Python - -23.2.4 Python modules ---------------------- - -GDB comes with a module to assist writing Python code. - -* Menu: - -* gdb.printing:: Building and registering pretty-printers. -* gdb.types:: Utilities for working with types. - - -File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules - -23.2.4.1 gdb.printing -..................... - -This module provides a collection of utilities for working with -pretty-printers. - -`PrettyPrinter (NAME, SUBPRINTERS=None)' - This class specifies the API that makes `info pretty-printer', - `enable pretty-printer' and `disable pretty-printer' work. - Pretty-printers should generally inherit from this class. - -`SubPrettyPrinter (NAME)' - For printers that handle multiple types, this class specifies the - corresponding API for the subprinters. - -`RegexpCollectionPrettyPrinter (NAME)' - Utility class for handling multiple printers, all recognized via - regular expressions. *Note Writing a Pretty-Printer::, for an - example. - -`register_pretty_printer (OBJ, PRINTER, REPLACE=False)' - Register PRINTER with the pretty-printer list of OBJ. If REPLACE - is `True' then any existing copy of the printer is replaced. - Otherwise a `RuntimeError' exception is raised if a printer with - the same name already exists. - - -File: gdb.info, Node: gdb.types, Prev: gdb.printing, Up: Python modules - -23.2.4.2 gdb.types -.................. - -This module provides a collection of utilities for working with -`gdb.Types' objects. - -`get_basic_type (TYPE)' - Return TYPE with const and volatile qualifiers stripped, and with - typedefs and C++ references converted to the underlying type. - - C++ example: - - typedef const int const_int; - const_int foo (3); - const_int& foo_ref (foo); - int main () { return 0; } - - Then in gdb: - - (gdb) start - (gdb) python import gdb.types - (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") - (gdb) python print gdb.types.get_basic_type(foo_ref.type) - int - -`has_field (TYPE, FIELD)' - Return `True' if TYPE, assumed to be a type with fields (e.g., a - structure or union), has field FIELD. - -`make_enum_dict (ENUM_TYPE)' - Return a Python `dictionary' type produced from ENUM_TYPE. - - -File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top - -24 Command Interpreters -*********************** - -GDB supports multiple command interpreters, and some command -infrastructure to allow users or user interface writers to switch -between interpreters or run commands in other interpreters. - - GDB currently supports two command interpreters, the console -interpreter (sometimes called the command-line interpreter or CLI) and -the machine interface interpreter (or GDB/MI). This manual describes -both of these interfaces in great detail. - - By default, GDB will start with the console interpreter. However, -the user may choose to start GDB with another interpreter by specifying -the `-i' or `--interpreter' startup options. Defined interpreters -include: - -`console' - The traditional console or command-line interpreter. This is the - most often used interpreter with GDB. With no interpreter - specified at runtime, GDB will use this interpreter. - -`mi' - The newest GDB/MI interface (currently `mi2'). Used primarily by - programs wishing to use GDB as a backend for a debugger GUI or an - IDE. For more information, see *note The GDB/MI Interface: GDB/MI. - -`mi2' - The current GDB/MI interface. - -`mi1' - The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. - - - The interpreter being used by GDB may not be dynamically switched at -runtime. Although possible, this could lead to a very precarious -situation. Consider an IDE using GDB/MI. If a user enters the command -"interpreter-set console" in a console view, GDB would switch to using -the console interpreter, rendering the IDE inoperable! - - Although you may only choose a single interpreter at startup, you -may execute commands in any interpreter from the current interpreter -using the appropriate command. If you are running the console -interpreter, simply use the `interpreter-exec' command: - - interpreter-exec mi "-data-list-register-names" - - GDB/MI has a similar command, although it is only available in -versions of GDB which support GDB/MI version 2 (or greater). - - -File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top - -25 GDB Text User Interface -************************** - -* Menu: - -* TUI Overview:: TUI overview -* TUI Keys:: TUI key bindings -* TUI Single Key Mode:: TUI single key mode -* TUI Commands:: TUI-specific commands -* TUI Configuration:: TUI configuration variables - - The GDB Text User Interface (TUI) is a terminal interface which uses -the `curses' library to show the source file, the assembly output, the -program registers and GDB commands in separate text windows. The TUI -mode is supported only on platforms where a suitable version of the -`curses' library is available. - - The TUI mode is enabled by default when you invoke GDB as either -`gdbtui' or `gdb -tui'. You can also switch in and out of TUI mode -while GDB runs by using various TUI commands and key bindings, such as -`C-x C-a'. *Note TUI Key Bindings: TUI Keys. - - -File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI - -25.1 TUI Overview -================= - -In TUI mode, GDB can display several text windows: - -_command_ - This window is the GDB command window with the GDB prompt and the - GDB output. The GDB input is still managed using readline. - -_source_ - The source window shows the source file of the program. The - current line and active breakpoints are displayed in this window. - -_assembly_ - The assembly window shows the disassembly output of the program. - -_register_ - This window shows the processor registers. Registers are - highlighted when their values change. - - The source and assembly windows show the current program position by -highlighting the current line and marking it with a `>' marker. -Breakpoints are indicated with two markers. The first marker indicates -the breakpoint type: - -`B' - Breakpoint which was hit at least once. - -`b' - Breakpoint which was never hit. - -`H' - Hardware breakpoint which was hit at least once. - -`h' - Hardware breakpoint which was never hit. - - The second marker indicates whether the breakpoint is enabled or not: - -`+' - Breakpoint is enabled. - -`-' - Breakpoint is disabled. - - The source, assembly and register windows are updated when the -current thread changes, when the frame changes, or when the program -counter changes. - - These windows are not all visible at the same time. The command -window is always visible. The others can be arranged in several -layouts: - - * source only, - - * assembly only, - - * source and assembly, - - * source and registers, or - - * assembly and registers. - - A status line above the command window shows the following -information: - -_target_ - Indicates the current GDB target. (*note Specifying a Debugging - Target: Targets.). - -_process_ - Gives the current process or thread number. When no process is - being debugged, this field is set to `No process'. - -_function_ - Gives the current function name for the selected frame. The name - is demangled if demangling is turned on (*note Print Settings::). - When there is no symbol corresponding to the current program - counter, the string `??' is displayed. - -_line_ - Indicates the current line number for the selected frame. When - the current line number is not known, the string `??' is displayed. - -_pc_ - Indicates the current program counter address. - - -File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI - -25.2 TUI Key Bindings -===================== - -The TUI installs several key bindings in the readline keymaps (*note -Command Line Editing::). The following key bindings are installed for -both TUI mode and the GDB standard mode. - -`C-x C-a' -`C-x a' -`C-x A' - Enter or leave the TUI mode. When leaving the TUI mode, the - curses window management stops and GDB operates using its standard - mode, writing on the terminal directly. When reentering the TUI - mode, control is given back to the curses windows. The screen is - then refreshed. - -`C-x 1' - Use a TUI layout with only one window. The layout will either be - `source' or `assembly'. When the TUI mode is not active, it will - switch to the TUI mode. - - Think of this key binding as the Emacs `C-x 1' binding. - -`C-x 2' - Use a TUI layout with at least two windows. When the current - layout already has two windows, the next layout with two windows - is used. When a new layout is chosen, one window will always be - common to the previous layout and the new one. - - Think of it as the Emacs `C-x 2' binding. - -`C-x o' - Change the active window. The TUI associates several key bindings - (like scrolling and arrow keys) with the active window. This - command gives the focus to the next TUI window. - - Think of it as the Emacs `C-x o' binding. - -`C-x s' - Switch in and out of the TUI SingleKey mode that binds single keys - to GDB commands (*note TUI Single Key Mode::). - - The following key bindings only work in the TUI mode: - -<PgUp> - Scroll the active window one page up. - -<PgDn> - Scroll the active window one page down. - -<Up> - Scroll the active window one line up. - -<Down> - Scroll the active window one line down. - -<Left> - Scroll the active window one column left. - -<Right> - Scroll the active window one column right. - -`C-L' - Refresh the screen. - - Because the arrow keys scroll the active window in the TUI mode, they -are not available for their normal use by readline unless the command -window has the focus. When another window is active, you must use -other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to -control the command window. - - -File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI - -25.3 TUI Single Key Mode -======================== - -The TUI also provides a "SingleKey" mode, which binds several -frequently used GDB commands to single keys. Type `C-x s' to switch -into this mode, where the following key bindings are used: - -`c' - continue - -`d' - down - -`f' - finish - -`n' - next - -`q' - exit the SingleKey mode. - -`r' - run - -`s' - step - -`u' - up - -`v' - info locals - -`w' - where - - Other keys temporarily switch to the GDB command prompt. The key -that was pressed is inserted in the editing buffer so that it is -possible to type most GDB commands without interaction with the TUI -SingleKey mode. Once the command is entered the TUI SingleKey mode is -restored. The only way to permanently leave this mode is by typing `q' -or `C-x s'. - - -File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI - -25.4 TUI-specific Commands -========================== - -The TUI has specific commands to control the text windows. These -commands are always available, even when GDB is not in the TUI mode. -When GDB is in the standard mode, most of these commands will -automatically switch to the TUI mode. - - Note that if GDB's `stdout' is not connected to a terminal, or GDB -has been started with the machine interface interpreter (*note The -GDB/MI Interface: GDB/MI.), most of these commands will fail with an -error, because it would not be possible or desirable to enable curses -window management. - -`info win' - List and give the size of all displayed windows. - -`layout next' - Display the next layout. - -`layout prev' - Display the previous layout. - -`layout src' - Display the source window only. - -`layout asm' - Display the assembly window only. - -`layout split' - Display the source and assembly window. - -`layout regs' - Display the register window together with the source or assembly - window. - -`focus next' - Make the next window active for scrolling. - -`focus prev' - Make the previous window active for scrolling. - -`focus src' - Make the source window active for scrolling. - -`focus asm' - Make the assembly window active for scrolling. - -`focus regs' - Make the register window active for scrolling. - -`focus cmd' - Make the command window active for scrolling. - -`refresh' - Refresh the screen. This is similar to typing `C-L'. - -`tui reg float' - Show the floating point registers in the register window. - -`tui reg general' - Show the general registers in the register window. - -`tui reg next' - Show the next register group. The list of register groups as well - as their order is target specific. The predefined register groups - are the following: `general', `float', `system', `vector', `all', - `save', `restore'. - -`tui reg system' - Show the system registers in the register window. - -`update' - Update the source window and the current execution point. - -`winheight NAME +COUNT' -`winheight NAME -COUNT' - Change the height of the window NAME by COUNT lines. Positive - counts increase the height, while negative counts decrease it. - -`tabset NCHARS' - Set the width of tab stops to be NCHARS characters. - - -File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI - -25.5 TUI Configuration Variables -================================ - -Several configuration variables control the appearance of TUI windows. - -`set tui border-kind KIND' - Select the border appearance for the source, assembly and register - windows. The possible values are the following: - `space' - Use a space character to draw the border. - - `ascii' - Use ASCII characters `+', `-' and `|' to draw the border. - - `acs' - Use the Alternate Character Set to draw the border. The - border is drawn using character line graphics if the terminal - supports them. - -`set tui border-mode MODE' -`set tui active-border-mode MODE' - Select the display attributes for the borders of the inactive - windows or the active window. The MODE can be one of the - following: - `normal' - Use normal attributes to display the border. - - `standout' - Use standout mode. - - `reverse' - Use reverse video mode. - - `half' - Use half bright mode. - - `half-standout' - Use half bright and standout mode. - - `bold' - Use extra bright or bold mode. - - `bold-standout' - Use extra bright or bold and standout mode. - - -File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top - -26 Using GDB under GNU Emacs -**************************** - -A special interface allows you to use GNU Emacs to view (and edit) the -source files for the program you are debugging with GDB. - - To use this interface, use the command `M-x gdb' in Emacs. Give the -executable file you want to debug as an argument. This command starts -GDB as a subprocess of Emacs, with input and output through a newly -created Emacs buffer. - - Running GDB under Emacs can be just like running GDB normally except -for two things: - - * All "terminal" input and output goes through an Emacs buffer, - called the GUD buffer. - - This applies both to GDB commands and their output, and to the - input and output done by the program you are debugging. - - This is useful because it means that you can copy the text of - previous commands and input them again; you can even use parts of - the output in this way. - - All the facilities of Emacs' Shell mode are available for - interacting with your program. In particular, you can send - signals the usual way--for example, `C-c C-c' for an interrupt, - `C-c C-z' for a stop. - - * GDB displays source code through Emacs. - - Each time GDB displays a stack frame, Emacs automatically finds the - source file for that frame and puts an arrow (`=>') at the left - margin of the current line. Emacs uses a separate buffer for - source display, and splits the screen to show both your GDB session - and the source. - - Explicit GDB `list' or search commands still produce output as - usual, but you probably have no reason to use them from Emacs. - - We call this "text command mode". Emacs 22.1, and later, also uses -a graphical mode, enabled by default, which provides further buffers -that can control the execution and describe the state of your program. -*Note GDB Graphical Interface: (Emacs)GDB Graphical Interface. - - If you specify an absolute file name when prompted for the `M-x gdb' -argument, then Emacs sets your current working directory to where your -program resides. If you only specify the file name, then Emacs sets -your current working directory to to the directory associated with the -previous buffer. In this case, GDB may find your program by searching -your environment's `PATH' variable, but on some operating systems it -might not find the source. So, although the GDB input and output -session proceeds normally, the auxiliary buffer does not display the -current source and line of execution. - - The initial working directory of GDB is printed on the top line of -the GUD buffer and this serves as a default for the commands that -specify files for GDB to operate on. *Note Commands to Specify Files: -Files. - - By default, `M-x gdb' calls the program called `gdb'. If you need -to call GDB by a different name (for example, if you keep several -configurations around, with different names) you can customize the -Emacs variable `gud-gdb-command-name' to run the one you want. - - In the GUD buffer, you can use these special Emacs commands in -addition to the standard Shell mode commands: - -`C-h m' - Describe the features of Emacs' GUD Mode. - -`C-c C-s' - Execute to another source line, like the GDB `step' command; also - update the display window to show the current file and location. - -`C-c C-n' - Execute to next source line in this function, skipping all function - calls, like the GDB `next' command. Then update the display window - to show the current file and location. - -`C-c C-i' - Execute one instruction, like the GDB `stepi' command; update - display window accordingly. - -`C-c C-f' - Execute until exit from the selected stack frame, like the GDB - `finish' command. - -`C-c C-r' - Continue execution of your program, like the GDB `continue' - command. - -`C-c <' - Go up the number of frames indicated by the numeric argument - (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' - command. - -`C-c >' - Go down the number of frames indicated by the numeric argument, - like the GDB `down' command. - - In any source file, the Emacs command `C-x <SPC>' (`gud-break') -tells GDB to set a breakpoint on the source line point is on. - - In text command mode, if you type `M-x speedbar', Emacs displays a -separate frame which shows a backtrace when the GUD buffer is current. -Move point to any frame in the stack and type <RET> to make it become -the current frame and display the associated source in the source -buffer. Alternatively, click `Mouse-2' to make the selected frame -become the current one. In graphical mode, the speedbar displays watch -expressions. - - If you accidentally delete the source-display buffer, an easy way to -get it back is to type the command `f' in the GDB buffer, to request a -frame display; when you run under Emacs, this recreates the source -buffer if necessary to show you the context of the current frame. - - The source files displayed in Emacs are in ordinary Emacs buffers -which are visiting the source files in the usual way. You can edit the -files with these buffers if you wish; but keep in mind that GDB -communicates with Emacs in terms of line numbers. If you add or delete -lines from the text, the line numbers that GDB knows cease to -correspond properly with the code. - - A more detailed description of Emacs' interaction with GDB is given -in the Emacs manual (*note Debuggers: (Emacs)Debuggers.). - - -File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top - -27 The GDB/MI Interface -*********************** - -Function and Purpose -==================== - -GDB/MI is a line based machine oriented text interface to GDB and is -activated by specifying using the `--interpreter' command line option -(*note Mode Options::). It is specifically intended to support the -development of systems which use the debugger as just one small -component of a larger system. - - This chapter is a specification of the GDB/MI interface. It is -written in the form of a reference manual. - - Note that GDB/MI is still under construction, so some of the -features described below are incomplete and subject to change (*note -GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). - -Notation and Terminology -======================== - -This chapter uses the following notation: - - * `|' separates two alternatives. - - * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or - may not be given. - - * `( GROUP )*' means that GROUP inside the parentheses may repeat - zero or more times. - - * `( GROUP )+' means that GROUP inside the parentheses may repeat - one or more times. - - * `"STRING"' means a literal STRING. - -* Menu: - -* GDB/MI General Design:: -* GDB/MI Command Syntax:: -* GDB/MI Compatibility with CLI:: -* GDB/MI Development and Front Ends:: -* GDB/MI Output Records:: -* GDB/MI Simple Examples:: -* GDB/MI Command Description Format:: -* GDB/MI Breakpoint Commands:: -* GDB/MI Program Context:: -* GDB/MI Thread Commands:: -* GDB/MI Program Execution:: -* GDB/MI Stack Manipulation:: -* GDB/MI Variable Objects:: -* GDB/MI Data Manipulation:: -* GDB/MI Tracepoint Commands:: -* GDB/MI Symbol Query:: -* GDB/MI File Commands:: -* GDB/MI Target Manipulation:: -* GDB/MI File Transfer Commands:: -* GDB/MI Miscellaneous Commands:: - - -File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI - -27.1 GDB/MI General Design -========================== - -Interaction of a GDB/MI frontend with GDB involves three -parts--commands sent to GDB, responses to those commands and -notifications. Each command results in exactly one response, -indicating either successful completion of the command, or an error. -For the commands that do not resume the target, the response contains -the requested information. For the commands that resume the target, the -response only indicates whether the target was successfully resumed. -Notifications is the mechanism for reporting changes in the state of the -target, or in GDB state, that cannot conveniently be associated with a -command and reported as part of that command response. - - The important examples of notifications are: - * Exec notifications. These are used to report changes in target - state--when a target is resumed, or stopped. It would not be - feasible to include this information in response of resuming - commands, because one resume commands can result in multiple - events in different threads. Also, quite some time may pass - before any event happens in the target, while a frontend needs to - know whether the resuming command itself was successfully executed. - - * Console output, and status notifications. Console output - notifications are used to report output of CLI commands, as well as - diagnostics for other commands. Status notifications are used to - report the progress of a long-running operation. Naturally, - including this information in command response would mean no - output is produced until the command is finished, which is - undesirable. - - * General notifications. Commands may have various side effects on - the GDB or target state beyond their official purpose. For - example, a command may change the selected thread. Although such - changes can be included in command response, using notification - allows for more orthogonal frontend design. - - - There's no guarantee that whenever an MI command reports an error, -GDB or the target are in any specific state, and especially, the state -is not reverted to the state before the MI command was processed. -Therefore, whenever an MI command results in an error, we recommend -that the frontend refreshes all the information shown in the user -interface. - -* Menu: - -* Context management:: -* Asynchronous and non-stop modes:: -* Thread groups:: - - -File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design - -27.1.1 Context management -------------------------- - -In most cases when GDB accesses the target, this access is done in -context of a specific thread and frame (*note Frames::). Often, even -when accessing global data, the target requires that a thread be -specified. The CLI interface maintains the selected thread and frame, -and supplies them to target on each command. This is convenient, -because a command line user would not want to specify that information -explicitly on each command, and because user interacts with GDB via a -single terminal, so no confusion is possible as to what thread and -frame are the current ones. - - In the case of MI, the concept of selected thread and frame is less -useful. First, a frontend can easily remember this information itself. -Second, a graphical frontend can have more than one window, each one -used for debugging a different thread, and the frontend might want to -access additional threads for internal purposes. This increases the -risk that by relying on implicitly selected thread, the frontend may be -operating on a wrong one. Therefore, each MI command should explicitly -specify which thread and frame to operate on. To make it possible, -each MI command accepts the `--thread' and `--frame' options, the value -to each is GDB identifier for thread and frame to operate on. - - Usually, each top-level window in a frontend allows the user to -select a thread and a frame, and remembers the user selection for -further operations. However, in some cases GDB may suggest that the -current thread be changed. For example, when stopping on a breakpoint -it is reasonable to switch to the thread where breakpoint is hit. For -another example, if the user issues the CLI `thread' command via the -frontend, it is desirable to change the frontend's selected thread to -the one specified by user. GDB communicates the suggestion to change -current thread using the `=thread-selected' notification. No such -notification is available for the selected frame at the moment. - - Note that historically, MI shares the selected thread with CLI, so -frontends used the `-thread-select' to execute commands in the right -context. However, getting this to work right is cumbersome. The -simplest way is for frontend to emit `-thread-select' command before -every command. This doubles the number of commands that need to be -sent. The alternative approach is to suppress `-thread-select' if the -selected thread in GDB is supposed to be identical to the thread the -frontend wants to operate on. However, getting this optimization right -can be tricky. In particular, if the frontend sends several commands -to GDB, and one of the commands changes the selected thread, then the -behaviour of subsequent commands will change. So, a frontend should -either wait for response from such problematic commands, or explicitly -add `-thread-select' for all subsequent commands. No frontend is known -to do this exactly right, so it is suggested to just always pass the -`--thread' and `--frame' options. - - -File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design - -27.1.2 Asynchronous command execution and non-stop mode -------------------------------------------------------- - -On some targets, GDB is capable of processing MI commands even while -the target is running. This is called "asynchronous command execution" -(*note Background Execution::). The frontend may specify a preferrence -for asynchronous execution using the `-gdb-set target-async 1' command, -which should be emitted before either running the executable or -attaching to the target. After the frontend has started the executable -or attached to the target, it can find if asynchronous execution is -enabled using the `-list-target-features' command. - - Even if GDB can accept a command while target is running, many -commands that access the target do not work when the target is running. -Therefore, asynchronous command execution is most useful when combined -with non-stop mode (*note Non-Stop Mode::). Then, it is possible to -examine the state of one thread, while other threads are running. - - When a given thread is running, MI commands that try to access the -target in the context of that thread may not work, or may work only on -some targets. In particular, commands that try to operate on thread's -stack will not work, on any target. Commands that read memory, or -modify breakpoints, may work or not work, depending on the target. Note -that even commands that operate on global state, such as `print', -`set', and breakpoint commands, still access the target in the context -of a specific thread, so frontend should try to find a stopped thread -and perform the operation on that thread (using the `--thread' option). - - Which commands will work in the context of a running thread is -highly target dependent. However, the two commands `-exec-interrupt', -to stop a thread, and `-thread-info', to find the state of a thread, -will always work. - - -File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design - -27.1.3 Thread groups --------------------- - -GDB may be used to debug several processes at the same time. On some -platfroms, GDB may support debugging of several hardware systems, each -one having several cores with several different processes running on -each core. This section describes the MI mechanism to support such -debugging scenarios. - - The key observation is that regardless of the structure of the -target, MI can have a global list of threads, because most commands that -accept the `--thread' option do not need to know what process that -thread belongs to. Therefore, it is not necessary to introduce neither -additional `--process' option, nor an notion of the current process in -the MI interface. The only strictly new feature that is required is -the ability to find how the threads are grouped into processes. - - To allow the user to discover such grouping, and to support arbitrary -hierarchy of machines/cores/processes, MI introduces the concept of a -"thread group". Thread group is a collection of threads and other -thread groups. A thread group always has a string identifier, a type, -and may have additional attributes specific to the type. A new -command, `-list-thread-groups', returns the list of top-level thread -groups, which correspond to processes that GDB is debugging at the -moment. By passing an identifier of a thread group to the -`-list-thread-groups' command, it is possible to obtain the members of -specific thread group. - - To allow the user to easily discover processes, and other objects, he -wishes to debug, a concept of "available thread group" is introduced. -Available thread group is an thread group that GDB is not debugging, -but that can be attached to, using the `-target-attach' command. The -list of available top-level thread groups can be obtained using -`-list-thread-groups --available'. In general, the content of a thread -group may be only retrieved only after attaching to that thread group. - - Thread groups are related to inferiors (*note Inferiors and -Programs::). Each inferior corresponds to a thread group of a special -type `process', and some additional operations are permitted on such -thread groups. - - -File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI - -27.2 GDB/MI Command Syntax -========================== - -* Menu: - -* GDB/MI Input Syntax:: -* GDB/MI Output Syntax:: - - -File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax - -27.2.1 GDB/MI Input Syntax --------------------------- - -`COMMAND ==>' - `CLI-COMMAND | MI-COMMAND' - -`CLI-COMMAND ==>' - `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB - CLI command. - -`MI-COMMAND ==>' - `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " - PARAMETER )* NL' - -`TOKEN ==>' - "any sequence of digits" - -`OPTION ==>' - `"-" PARAMETER [ " " PARAMETER ]' - -`PARAMETER ==>' - `NON-BLANK-SEQUENCE | C-STRING' - -`OPERATION ==>' - _any of the operations described in this chapter_ - -`NON-BLANK-SEQUENCE ==>' - _anything, provided it doesn't contain special characters such as - "-", NL, """ and of course " "_ - -`C-STRING ==>' - `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' - -`NL ==>' - `CR | CR-LF' - -Notes: - - * The CLI commands are still handled by the MI interpreter; their - output is described below. - - * The `TOKEN', when present, is passed back when the command - finishes. - - * Some MI commands accept optional arguments as part of the parameter - list. Each option is identified by a leading `-' (dash) and may be - followed by an optional argument parameter. Options occur first - in the parameter list and can be delimited from normal parameters - using `--' (this is useful when some parameters begin with a dash). - - Pragmatics: - - * We want easy access to the existing CLI syntax (for debugging). - - * We want it to be easy to spot a MI operation. - - -File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax - -27.2.2 GDB/MI Output Syntax ---------------------------- - -The output from GDB/MI consists of zero or more out-of-band records -followed, optionally, by a single result record. This result record is -for the most recent command. The sequence of output records is -terminated by `(gdb)'. - - If an input command was prefixed with a `TOKEN' then the -corresponding output for that command will also be prefixed by that same -TOKEN. - -`OUTPUT ==>' - `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' - -`RESULT-RECORD ==>' - ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' - -`OUT-OF-BAND-RECORD ==>' - `ASYNC-RECORD | STREAM-RECORD' - -`ASYNC-RECORD ==>' - `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' - -`EXEC-ASYNC-OUTPUT ==>' - `[ TOKEN ] "*" ASYNC-OUTPUT' - -`STATUS-ASYNC-OUTPUT ==>' - `[ TOKEN ] "+" ASYNC-OUTPUT' - -`NOTIFY-ASYNC-OUTPUT ==>' - `[ TOKEN ] "=" ASYNC-OUTPUT' - -`ASYNC-OUTPUT ==>' - `ASYNC-CLASS ( "," RESULT )* NL' - -`RESULT-CLASS ==>' - `"done" | "running" | "connected" | "error" | "exit"' - -`ASYNC-CLASS ==>' - `"stopped" | OTHERS' (where OTHERS will be added depending on the - needs--this is still in development). - -`RESULT ==>' - ` VARIABLE "=" VALUE' - -`VARIABLE ==>' - ` STRING ' - -`VALUE ==>' - ` CONST | TUPLE | LIST ' - -`CONST ==>' - `C-STRING' - -`TUPLE ==>' - ` "{}" | "{" RESULT ( "," RESULT )* "}" ' - -`LIST ==>' - ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* - "]" ' - -`STREAM-RECORD ==>' - `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' - -`CONSOLE-STREAM-OUTPUT ==>' - `"~" C-STRING' - -`TARGET-STREAM-OUTPUT ==>' - `"@" C-STRING' - -`LOG-STREAM-OUTPUT ==>' - `"&" C-STRING' - -`NL ==>' - `CR | CR-LF' - -`TOKEN ==>' - _any sequence of digits_. - -Notes: - - * All output sequences end in a single line containing a period. - - * The `TOKEN' is from the corresponding request. Note that for all - async output, while the token is allowed by the grammar and may be - output by future versions of GDB for select async output messages, - it is generally omitted. Frontends should treat all async output - as reporting general changes in the state of the target and there - should be no need to associate async output to any prior command. - - * STATUS-ASYNC-OUTPUT contains on-going status information about the - progress of a slow operation. It can be discarded. All status - output is prefixed by `+'. - - * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target - (stopped, started, disappeared). All async output is prefixed by - `*'. - - * NOTIFY-ASYNC-OUTPUT contains supplementary information that the - client should handle (e.g., a new breakpoint information). All - notify output is prefixed by `='. - - * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in - the console. It is the textual response to a CLI command. All - the console output is prefixed by `~'. - - * TARGET-STREAM-OUTPUT is the output produced by the target program. - All the target output is prefixed by `@'. - - * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for - instance messages that should be displayed as part of an error - log. All the log output is prefixed by `&'. - - * New GDB/MI commands should only output LISTS containing VALUES. - - - *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details -about the various output records. - - -File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI - -27.3 GDB/MI Compatibility with CLI -================================== - -For the developers convenience CLI commands can be entered directly, -but there may be some unexpected behaviour. For example, commands that -query the user will behave as if the user replied yes, breakpoint -command lists are not executed and some CLI commands, such as `if', -`when' and `define', prompt for further input with `>', which is not -valid MI output. - - This feature may be removed at some stage in the future and it is -recommended that front ends use the `-interpreter-exec' command (*note --interpreter-exec::). - - -File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI - -27.4 GDB/MI Development and Front Ends -====================================== - -The application which takes the MI output and presents the state of the -program being debugged to the user is called a "front end". - - Although GDB/MI is still incomplete, it is currently being used by a -variety of front ends to GDB. This makes it difficult to introduce new -functionality without breaking existing usage. This section tries to -minimize the problems by describing how the protocol might change. - - Some changes in MI need not break a carefully designed front end, and -for these the MI version will remain unchanged. The following is a -list of changes that may occur within one level, so front ends should -parse MI output in a way that can handle them: - - * New MI commands may be added. - - * New fields may be added to the output of any MI command. - - * The range of values for fields with specified values, e.g., - `in_scope' (*note -var-update::) may be extended. - - - If the changes are likely to break front ends, the MI version level -will be increased by one. This will allow the front end to parse the -output according to the MI version. Apart from mi0, new versions of -GDB will not support old versions of MI and it will be the -responsibility of the front end to work with the new one. - - The best way to avoid unexpected changes in MI that might break your -front end is to make your project known to GDB developers and follow -development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>. - - -File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI - -27.5 GDB/MI Output Records -========================== - -* Menu: - -* GDB/MI Result Records:: -* GDB/MI Stream Records:: -* GDB/MI Async Records:: -* GDB/MI Frame Information:: -* GDB/MI Thread Information:: -* GDB/MI Ada Exception Information:: - - -File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records - -27.5.1 GDB/MI Result Records ----------------------------- - -In addition to a number of out-of-band notifications, the response to a -GDB/MI command includes one of the following result indications: - -`"^done" [ "," RESULTS ]' - The synchronous operation was successful, `RESULTS' are the return - values. - -`"^running"' - This result record is equivalent to `^done'. Historically, it was - output instead of `^done' if the command has resumed the target. - This behaviour is maintained for backward compatibility, but all - frontends should treat `^done' and `^running' identically and rely - on the `*running' output record to determine which threads are - resumed. - -`"^connected"' - GDB has connected to a remote target. - -`"^error" "," C-STRING' - The operation failed. The `C-STRING' contains the corresponding - error message. - -`"^exit"' - GDB has terminated. - - - -File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records - -27.5.2 GDB/MI Stream Records ----------------------------- - -GDB internally maintains a number of output streams: the console, the -target, and the log. The output intended for each of these streams is -funneled through the GDB/MI interface using "stream records". - - Each stream record begins with a unique "prefix character" which -identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output -Syntax.). In addition to the prefix, each stream record contains a -`STRING-OUTPUT'. This is either raw text (with an implicit new line) -or a quoted C string (which does not contain an implicit newline). - -`"~" STRING-OUTPUT' - The console output stream contains text that should be displayed - in the CLI console window. It contains the textual responses to - CLI commands. - -`"@" STRING-OUTPUT' - The target output stream contains any textual output from the - running target. This is only present when GDB's event loop is - truly asynchronous, which is currently only the case for remote - targets. - -`"&" STRING-OUTPUT' - The log stream contains debugging messages being produced by GDB's - internals. - - -File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Frame Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records - -27.5.3 GDB/MI Async Records ---------------------------- - -"Async" records are used to notify the GDB/MI client of additional -changes that have occurred. Those changes can either be a consequence -of GDB/MI commands (e.g., a breakpoint modified) or a result of target -activity (e.g., target stopped). - - The following is the list of possible async records: - -`*running,thread-id="THREAD"' - The target is now running. The THREAD field tells which specific - thread is now running, and can be `all' if all threads are - running. The frontend should assume that no interaction with a - running thread is possible after this notification is produced. - The frontend should not assume that this notification is output - only once for any command. GDB may emit this notification several - times, either for different threads, because it cannot resume all - threads together, or even for a single thread, if the thread must - be stepped though some code before letting it run freely. - -`*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' - The target has stopped. The REASON field can have one of the - following values: - - `breakpoint-hit' - A breakpoint was reached. - - `watchpoint-trigger' - A watchpoint was triggered. - - `read-watchpoint-trigger' - A read watchpoint was triggered. - - `access-watchpoint-trigger' - An access watchpoint was triggered. - - `function-finished' - An -exec-finish or similar CLI command was accomplished. - - `location-reached' - An -exec-until or similar CLI command was accomplished. - - `watchpoint-scope' - A watchpoint has gone out of scope. - - `end-stepping-range' - An -exec-next, -exec-next-instruction, -exec-step, - -exec-step-instruction or similar CLI command was - accomplished. - - `exited-signalled' - The inferior exited because of a signal. - - `exited' - The inferior exited. - - `exited-normally' - The inferior exited normally. - - `signal-received' - A signal was received by the inferior. - - The ID field identifies the thread that directly caused the stop - - for example by hitting a breakpoint. Depending on whether all-stop - mode is in effect (*note All-Stop Mode::), GDB may either stop all - threads, or only the thread that directly triggered the stop. If - all threads are stopped, the STOPPED field will have the value of - `"all"'. Otherwise, the value of the STOPPED field will be a list - of thread identifiers. Presently, this list will always include a - single thread, but frontend should be prepared to see several - threads in the list. The CORE field reports the processor core on - which the stop event has happened. This field may be absent if - such information is not available. - -`=thread-group-added,id="ID"' -`=thread-group-removed,id="ID"' - A thread group was either added or removed. The ID field contains - the GDB identifier of the thread group. When a thread group is - added, it generally might not be associated with a running - process. When a thread group is removed, its id becomes invalid - and cannot be used in any way. - -`=thread-group-started,id="ID",pid="PID"' - A thread group became associated with a running program, either - because the program was just started or the thread group was - attached to a program. The ID field contains the GDB identifier - of the thread group. The PID field contains process identifier, - specific to the operating system. - -`=thread-group-exited,id="ID"[,exit-code="CODE"]' - A thread group is no longer associated with a running program, - either because the program has exited, or because it was detached - from. The ID field contains the GDB identifier of the thread - group. CODE is the exit code of the inferior; it exists only when - the inferior exited with some code. - -`=thread-created,id="ID",group-id="GID"' -`=thread-exited,id="ID",group-id="GID"' - A thread either was created, or has exited. The ID field contains - the GDB identifier of the thread. The GID field identifies the - thread group this thread belongs to. - -`=thread-selected,id="ID"' - Informs that the selected thread was changed as result of the last - command. This notification is not emitted as result of - `-thread-select' command but is emitted whenever an MI command - that is not documented to change the selected thread actually - changes it. In particular, invoking, directly or indirectly (via - user-defined command), the CLI `thread' command, will generate - this notification. - - We suggest that in response to this notification, front ends - highlight the selected thread and cause subsequent commands to - apply to that thread. - -`=library-loaded,...' - Reports that a new library file was loaded by the program. This - notification has 4 fields--ID, TARGET-NAME, HOST-NAME, and - SYMBOLS-LOADED. The ID field is an opaque identifier of the - library. For remote debugging case, TARGET-NAME and HOST-NAME - fields give the name of the library file on the target, and on the - host respectively. For native debugging, both those fields have - the same value. The SYMBOLS-LOADED field is emitted only for - backward compatibility and should not be relied on to convey any - useful information. The THREAD-GROUP field, if present, specifies - the id of the thread group in whose context the library was - loaded. If the field is absent, it means the library was loaded - in the context of all present thread groups. - -`=library-unloaded,...' - Reports that a library was unloaded by the program. This - notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the - same meaning as for the `=library-loaded' notification. The - THREAD-GROUP field, if present, specifies the id of the thread - group in whose context the library was unloaded. If the field is - absent, it means the library was unloaded in the context of all - present thread groups. - - - -File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records - -27.5.4 GDB/MI Frame Information -------------------------------- - -Response from many MI commands includes an information about stack -frame. This information is a tuple that may have the following fields: - -`level' - The level of the stack frame. The innermost frame has the level of - zero. This field is always present. - -`func' - The name of the function corresponding to the frame. This field - may be absent if GDB is unable to determine the function name. - -`addr' - The code address for the frame. This field is always present. - -`file' - The name of the source files that correspond to the frame's code - address. This field may be absent. - -`line' - The source line corresponding to the frames' code address. This - field may be absent. - -`from' - The name of the binary file (either executable or shared library) - the corresponds to the frame's code address. This field may be - absent. - - - -File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records - -27.5.5 GDB/MI Thread Information --------------------------------- - -Whenever GDB has to report an information about a thread, it uses a -tuple with the following fields: - -`id' - The numeric id assigned to the thread by GDB. This field is - always present. - -`target-id' - Target-specific string identifying the thread. This field is - always present. - -`details' - Additional information about the thread provided by the target. - It is supposed to be human-readable and not interpreted by the - frontend. This field is optional. - -`state' - Either `stopped' or `running', depending on whether the thread is - presently running. This field is always present. - -`core' - The value of this field is an integer number of the processor core - the thread was last seen on. This field is optional. - - -File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records - -27.5.6 GDB/MI Ada Exception Information ---------------------------------------- - -Whenever a `*stopped' record is emitted because the program stopped -after hitting an exception catchpoint (*note Set Catchpoints::), GDB -provides the name of the exception that was raised via the -`exception-name' field. - - -File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI - -27.6 Simple Examples of GDB/MI Interaction -========================================== - -This subsection presents several simple examples of interaction using -the GDB/MI interface. In these examples, `->' means that the following -line is passed to GDB/MI as input, while `<-' means the output received -from GDB/MI. - - Note the line breaks shown in the examples are here only for -readability, they don't appear in the real output. - -Setting a Breakpoint --------------------- - -Setting a breakpoint generates synchronous output which contains -detailed information of the breakpoint. - - -> -break-insert main - <- ^done,bkpt={number="1",type="breakpoint",disp="keep", - enabled="y",addr="0x08048564",func="main",file="myprog.c", - fullname="/home/nickrob/myprog.c",line="68",times="0"} - <- (gdb) - -Program Execution ------------------ - -Program execution generates asynchronous records and MI gives the -reason that execution stopped. - - -> -exec-run - <- ^running - <- (gdb) - <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", - frame={addr="0x08048564",func="main", - args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], - file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} - <- (gdb) - -> -exec-continue - <- ^running - <- (gdb) - <- *stopped,reason="exited-normally" - <- (gdb) - -Quitting GDB ------------- - -Quitting GDB just prints the result class `^exit'. - - -> (gdb) - <- -gdb-exit - <- ^exit - - Please note that `^exit' is printed immediately, but it might take -some time for GDB to actually exit. During that time, GDB performs -necessary cleanups, including killing programs being debugged or -disconnecting from debug hardware, so the frontend should wait till GDB -exits and should only forcibly kill GDB if it fails to exit in -reasonable time. - -A Bad Command -------------- - -Here's what happens if you pass a non-existent command: - - -> -rubbish - <- ^error,msg="Undefined MI command: rubbish" - <- (gdb) - - -File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI - -27.7 GDB/MI Command Description Format -====================================== - -The remaining sections describe blocks of commands. Each block of -commands is laid out in a fashion similar to this section. - -Motivation ----------- - -The motivation for this collection of commands. - -Introduction ------------- - -A brief introduction to this collection of commands as a whole. - -Commands --------- - -For each command in the block, the following is described: - -Synopsis -........ - - -command ARGS... - -Result -...... - -GDB Command -........... - -The corresponding GDB CLI command(s), if any. - -Example -....... - -Example(s) formatted for readability. Some of the described commands -have not been implemented yet and these are labeled N.A. (not -available). - - -File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI - -27.8 GDB/MI Breakpoint Commands -=============================== - -This section documents GDB/MI commands for manipulating breakpoints. - -The `-break-after' Command --------------------------- - -Synopsis -........ - - -break-after NUMBER COUNT - - The breakpoint number NUMBER is not in effect until it has been hit -COUNT times. To see how this is reflected in the output of the -`-break-list' command, see the description of the `-break-list' command -below. - -GDB Command -........... - -The corresponding GDB command is `ignore'. - -Example -....... - - (gdb) - -break-insert main - ^done,bkpt={number="1",type="breakpoint",disp="keep", - enabled="y",addr="0x000100d0",func="main",file="hello.c", - fullname="/home/foo/hello.c",line="5",times="0"} - (gdb) - -break-after 1 3 - ~ - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", - line="5",times="0",ignore="3"}]} - (gdb) - -The `-break-commands' Command ------------------------------ - -Synopsis -........ - - -break-commands NUMBER [ COMMAND1 ... COMMANDN ] - - Specifies the CLI commands that should be executed when breakpoint -NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. -If no command is specified, any previously-set commands are cleared. -*Note Break Commands::. Typical use of this functionality is tracing a -program, that is, printing of values of some variables whenever -breakpoint is hit and then continuing. - -GDB Command -........... - -The corresponding GDB command is `commands'. - -Example -....... - - (gdb) - -break-insert main - ^done,bkpt={number="1",type="breakpoint",disp="keep", - enabled="y",addr="0x000100d0",func="main",file="hello.c", - fullname="/home/foo/hello.c",line="5",times="0"} - (gdb) - -break-commands 1 "print v" "continue" - ^done - (gdb) - -The `-break-condition' Command ------------------------------- - -Synopsis -........ - - -break-condition NUMBER EXPR - - Breakpoint NUMBER will stop the program only if the condition in -EXPR is true. The condition becomes part of the `-break-list' output -(see the description of the `-break-list' command below). - -GDB Command -........... - -The corresponding GDB command is `condition'. - -Example -....... - - (gdb) - -break-condition 1 1 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", - line="5",cond="1",times="0",ignore="3"}]} - (gdb) - -The `-break-delete' Command ---------------------------- - -Synopsis -........ - - -break-delete ( BREAKPOINT )+ - - Delete the breakpoint(s) whose number(s) are specified in the -argument list. This is obviously reflected in the breakpoint list. - -GDB Command -........... - -The corresponding GDB command is `delete'. - -Example -....... - - (gdb) - -break-delete 1 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="0",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[]} - (gdb) - -The `-break-disable' Command ----------------------------- - -Synopsis -........ - - -break-disable ( BREAKPOINT )+ - - Disable the named BREAKPOINT(s). The field `enabled' in the break -list is now set to `n' for the named BREAKPOINT(s). - -GDB Command -........... - -The corresponding GDB command is `disable'. - -Example -....... - - (gdb) - -break-disable 2 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", - addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", - line="5",times="0"}]} - (gdb) - -The `-break-enable' Command ---------------------------- - -Synopsis -........ - - -break-enable ( BREAKPOINT )+ - - Enable (previously disabled) BREAKPOINT(s). - -GDB Command -........... - -The corresponding GDB command is `enable'. - -Example -....... - - (gdb) - -break-enable 2 - ^done - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", - line="5",times="0"}]} - (gdb) - -The `-break-info' Command -------------------------- - -Synopsis -........ - - -break-info BREAKPOINT - - Get information about a single breakpoint. - -GDB Command -........... - -The corresponding GDB command is `info break BREAKPOINT'. - -Example -....... - -N.A. - -The `-break-insert' Command ---------------------------- - -Synopsis -........ - - -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] - [ -c CONDITION ] [ -i IGNORE-COUNT ] - [ -p THREAD ] [ LOCATION ] - -If specified, LOCATION, can be one of: - - * function - - * filename:linenum - - * filename:function - - * *address - - The possible optional parameters of this command are: - -`-t' - Insert a temporary breakpoint. - -`-h' - Insert a hardware breakpoint. - -`-c CONDITION' - Make the breakpoint conditional on CONDITION. - -`-i IGNORE-COUNT' - Initialize the IGNORE-COUNT. - -`-f' - If LOCATION cannot be parsed (for example if it refers to unknown - files or functions), create a pending breakpoint. Without this - flag, GDB will report an error, and won't create a breakpoint, if - LOCATION cannot be parsed. - -`-d' - Create a disabled breakpoint. - -`-a' - Create a tracepoint. *Note Tracepoints::. When this parameter is - used together with `-h', a fast tracepoint is created. - -Result -...... - -The result is in the form: - - ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", - enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", - fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] - times="TIMES"} - -where NUMBER is the GDB number for this breakpoint, FUNCNAME is the -name of the function where the breakpoint was inserted, FILENAME is the -name of the source file which contains this function, LINENO is the -source line number within that file and TIMES the number of times that -the breakpoint has been hit (always 0 for -break-insert but may be -greater for -break-info or -break-list which use the same output). - - Note: this format is open to change. - -GDB Command -........... - -The corresponding GDB commands are `break', `tbreak', `hbreak', -`thbreak', and `rbreak'. - -Example -....... - - (gdb) - -break-insert main - ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", - fullname="/home/foo/recursive2.c,line="4",times="0"} - (gdb) - -break-insert -t foo - ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", - fullname="/home/foo/recursive2.c,line="11",times="0"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x0001072c", func="main",file="recursive2.c", - fullname="/home/foo/recursive2.c,"line="4",times="0"}, - bkpt={number="2",type="breakpoint",disp="del",enabled="y", - addr="0x00010774",func="foo",file="recursive2.c", - fullname="/home/foo/recursive2.c",line="11",times="0"}]} - (gdb) - -break-insert -r foo.* - ~int foo(int, int); - ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c, - "fullname="/home/foo/recursive2.c",line="11",times="0"} - (gdb) - -The `-break-list' Command -------------------------- - -Synopsis -........ - - -break-list - - Displays the list of inserted breakpoints, showing the following -fields: - -`Number' - number of the breakpoint - -`Type' - type of the breakpoint: `breakpoint' or `watchpoint' - -`Disposition' - should the breakpoint be deleted or disabled when it is hit: `keep' - or `nokeep' - -`Enabled' - is the breakpoint enabled or no: `y' or `n' - -`Address' - memory location at which the breakpoint is set - -`What' - logical location of the breakpoint, expressed by function name, - file name, line number - -`Times' - number of times the breakpoint has been hit - - If there are no breakpoints or watchpoints, the `BreakpointTable' -`body' field is an empty list. - -GDB Command -........... - -The corresponding GDB command is `info break'. - -Example -....... - - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, - bkpt={number="2",type="breakpoint",disp="keep",enabled="y", - addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", - line="13",times="0"}]} - (gdb) - - Here's an example of the result when there are no breakpoints: - - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="0",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[]} - (gdb) - -The `-break-passcount' Command ------------------------------- - -Synopsis -........ - - -break-passcount TRACEPOINT-NUMBER PASSCOUNT - - Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If -the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, -error is emitted. This corresponds to CLI command `passcount'. - -The `-break-watch' Command --------------------------- - -Synopsis -........ - - -break-watch [ -a | -r ] - - Create a watchpoint. With the `-a' option it will create an -"access" watchpoint, i.e., a watchpoint that triggers either on a read -from or on a write to the memory location. With the `-r' option, the -watchpoint created is a "read" watchpoint, i.e., it will trigger only -when the memory location is accessed for reading. Without either of -the options, the watchpoint created is a regular watchpoint, i.e., it -will trigger when the memory location is accessed for writing. *Note -Setting Watchpoints: Set Watchpoints. - - Note that `-break-list' will report a single list of watchpoints and -breakpoints inserted. - -GDB Command -........... - -The corresponding GDB commands are `watch', `awatch', and `rwatch'. - -Example -....... - -Setting a watchpoint on a variable in the `main' function: - - (gdb) - -break-watch x - ^done,wpt={number="2",exp="x"} - (gdb) - -exec-continue - ^running - (gdb) - *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, - value={old="-268439212",new="55"}, - frame={func="main",args=[],file="recursive2.c", - fullname="/home/foo/bar/recursive2.c",line="5"} - (gdb) - - Setting a watchpoint on a variable local to a function. GDB will -stop the program execution twice: first for the variable changing -value, then for the watchpoint going out of scope. - - (gdb) - -break-watch C - ^done,wpt={number="5",exp="C"} - (gdb) - -exec-continue - ^running - (gdb) - *stopped,reason="watchpoint-trigger", - wpt={number="5",exp="C"},value={old="-276895068",new="3"}, - frame={func="callee4",args=[], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} - (gdb) - -exec-continue - ^running - (gdb) - *stopped,reason="watchpoint-scope",wpnum="5", - frame={func="callee3",args=[{name="strarg", - value="0x11940 \"A string argument.\""}], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} - (gdb) - - Listing breakpoints and watchpoints, at different points in the -program execution. Note that once the watchpoint goes out of scope, it -is deleted. - - (gdb) - -break-watch C - ^done,wpt={number="2",exp="C"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"}, - bkpt={number="2",type="watchpoint",disp="keep", - enabled="y",addr="",what="C",times="0"}]} - (gdb) - -exec-continue - ^running - (gdb) - *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, - value={old="-276895068",new="3"}, - frame={func="callee4",args=[], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="2",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, - bkpt={number="2",type="watchpoint",disp="keep", - enabled="y",addr="",what="C",times="-5"}]} - (gdb) - -exec-continue - ^running - ^done,reason="watchpoint-scope",wpnum="2", - frame={func="callee3",args=[{name="strarg", - value="0x11940 \"A string argument.\""}], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} - (gdb) - -break-list - ^done,BreakpointTable={nr_rows="1",nr_cols="6", - hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, - {width="14",alignment="-1",col_name="type",colhdr="Type"}, - {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, - {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, - {width="10",alignment="-1",col_name="addr",colhdr="Address"}, - {width="40",alignment="2",col_name="what",colhdr="What"}], - body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", - times="1"}]} - (gdb) - - -File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI - -27.9 GDB/MI Program Context -============================ - -The `-exec-arguments' Command ------------------------------ - -Synopsis -........ - - -exec-arguments ARGS - - Set the inferior program arguments, to be used in the next -`-exec-run'. - -GDB Command -........... - -The corresponding GDB command is `set args'. - -Example -....... - - (gdb) - -exec-arguments -v word - ^done - (gdb) - -The `-environment-cd' Command ------------------------------ - -Synopsis -........ - - -environment-cd PATHDIR - - Set GDB's working directory. - -GDB Command -........... - -The corresponding GDB command is `cd'. - -Example -....... - - (gdb) - -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb - ^done - (gdb) - -The `-environment-directory' Command ------------------------------------- - -Synopsis -........ - - -environment-directory [ -r ] [ PATHDIR ]+ - - Add directories PATHDIR to beginning of search path for source files. -If the `-r' option is used, the search path is reset to the default -search path. If directories PATHDIR are supplied in addition to the -`-r' option, the search path is first reset and then addition occurs as -normal. Multiple directories may be specified, separated by blanks. -Specifying multiple directories in a single command results in the -directories added to the beginning of the search path in the same order -they were presented in the command. If blanks are needed as part of a -directory name, double-quotes should be used around the name. In the -command output, the path will show up separated by the system -directory-separator character. The directory-separator character must -not be used in any directory name. If no directories are specified, -the current search path is displayed. - -GDB Command -........... - -The corresponding GDB command is `dir'. - -Example -....... - - (gdb) - -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb - ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" - (gdb) - -environment-directory "" - ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" - (gdb) - -environment-directory -r /home/jjohnstn/src/gdb /usr/src - ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" - (gdb) - -environment-directory -r - ^done,source-path="$cdir:$cwd" - (gdb) - -The `-environment-path' Command -------------------------------- - -Synopsis -........ - - -environment-path [ -r ] [ PATHDIR ]+ - - Add directories PATHDIR to beginning of search path for object files. -If the `-r' option is used, the search path is reset to the original -search path that existed at gdb start-up. If directories PATHDIR are -supplied in addition to the `-r' option, the search path is first reset -and then addition occurs as normal. Multiple directories may be -specified, separated by blanks. Specifying multiple directories in a -single command results in the directories added to the beginning of the -search path in the same order they were presented in the command. If -blanks are needed as part of a directory name, double-quotes should be -used around the name. In the command output, the path will show up -separated by the system directory-separator character. The -directory-separator character must not be used in any directory name. -If no directories are specified, the current path is displayed. - -GDB Command -........... - -The corresponding GDB command is `path'. - -Example -....... - - (gdb) - -environment-path - ^done,path="/usr/bin" - (gdb) - -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin - ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" - (gdb) - -environment-path -r /usr/local/bin - ^done,path="/usr/local/bin:/usr/bin" - (gdb) - -The `-environment-pwd' Command ------------------------------- - -Synopsis -........ - - -environment-pwd - - Show the current working directory. - -GDB Command -........... - -The corresponding GDB command is `pwd'. - -Example -....... - - (gdb) - -environment-pwd - ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" - (gdb) - - -File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Program Context, Up: GDB/MI - -27.10 GDB/MI Thread Commands -============================ - -The `-thread-info' Command --------------------------- - -Synopsis -........ - - -thread-info [ THREAD-ID ] - - Reports information about either a specific thread, if the THREAD-ID -parameter is present, or about all threads. When printing information -about all threads, also reports the current thread. - -GDB Command -........... - -The `info thread' command prints the same information about all threads. - -Result -...... - -The result is a list of threads. The following attributes are defined -for a given thread: - -`current' - This field exists only for the current thread. It has the value - `*'. - -`id' - The identifier that GDB uses to refer to the thread. - -`target-id' - The identifier that the target uses to refer to the thread. - -`details' - Extra information about the thread, in a target-specific format. - This field is optional. - -`name' - The name of the thread. If the user specified a name using the - `thread name' command, then this name is given. Otherwise, if GDB - can extract the thread name from the target, then that name is - given. If GDB cannot find the thread name, then this field is - omitted. - -`frame' - The stack frame currently executing in the thread. - -`state' - The thread's state. The `state' field may have the following - values: - - `stopped' - The thread is stopped. Frame information is available for - stopped threads. - - `running' - The thread is running. There's no frame information for - running threads. - - -`core' - If GDB can find the CPU core on which this thread is running, then - this field is the core identifier. This field is optional. - - -Example -....... - - -thread-info - ^done,threads=[ - {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", - frame={level="0",addr="0xffffe410",func="__kernel_vsyscall", - args=[]},state="running"}, - {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", - frame={level="0",addr="0x0804891f",func="foo", - args=[{name="i",value="10"}], - file="/tmp/a.c",fullname="/tmp/a.c",line="158"}, - state="running"}], - current-thread-id="1" - (gdb) - -The `-thread-list-ids' Command ------------------------------- - -Synopsis -........ - - -thread-list-ids - - Produces a list of the currently known GDB thread ids. At the end -of the list it also prints the total number of such threads. - - This command is retained for historical reasons, the `-thread-info' -command should be used instead. - -GDB Command -........... - -Part of `info threads' supplies the same information. - -Example -....... - - (gdb) - -thread-list-ids - ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, - current-thread-id="1",number-of-threads="3" - (gdb) - -The `-thread-select' Command ----------------------------- - -Synopsis -........ - - -thread-select THREADNUM - - Make THREADNUM the current thread. It prints the number of the new -current thread, and the topmost frame for that thread. - - This command is deprecated in favor of explicitly using the -`--thread' option to each command. - -GDB Command -........... - -The corresponding GDB command is `thread'. - -Example -....... - - (gdb) - -exec-next - ^running - (gdb) - *stopped,reason="end-stepping-range",thread-id="2",line="187", - file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" - (gdb) - -thread-list-ids - ^done, - thread-ids={thread-id="3",thread-id="2",thread-id="1"}, - number-of-threads="3" - (gdb) - -thread-select 3 - ^done,new-thread-id="3", - frame={level="0",func="vprintf", - args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, - {name="arg",value="0x2"}],file="vprintf.c",line="31"} - (gdb) - - -File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI - -27.11 GDB/MI Program Execution -============================== - -These are the asynchronous commands which generate the out-of-band -record `*stopped'. Currently GDB only really executes asynchronously -with remote targets and this interaction is mimicked in other cases. - -The `-exec-continue' Command ----------------------------- - -Synopsis -........ - - -exec-continue [--reverse] [--all|--thread-group N] - - Resumes the execution of the inferior program, which will continue -to execute until it reaches a debugger stop event. If the `--reverse' -option is specified, execution resumes in reverse until it reaches a -stop event. Stop events may include - * breakpoints or watchpoints - - * signals or exceptions - - * the end of the process (or its beginning under `--reverse') - - * the end or beginning of a replay log if one is being used. - In all-stop mode (*note All-Stop Mode::), may resume only one -thread, or all threads, depending on the value of the -`scheduler-locking' variable. If `--all' is specified, all threads (in -all inferiors) will be resumed. The `--all' option is ignored in -all-stop mode. If the `--thread-group' options is specified, then all -threads in that thread group are resumed. - -GDB Command -........... - -The corresponding GDB corresponding is `continue'. - -Example -....... - - -exec-continue - ^running - (gdb) - @Hello world - *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ - func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", - line="13"} - (gdb) - -The `-exec-finish' Command --------------------------- - -Synopsis -........ - - -exec-finish [--reverse] - - Resumes the execution of the inferior program until the current -function is exited. Displays the results returned by the function. If -the `--reverse' option is specified, resumes the reverse execution of -the inferior program until the point where current function was called. - -GDB Command -........... - -The corresponding GDB command is `finish'. - -Example -....... - -Function returning `void'. - - -exec-finish - ^running - (gdb) - @hello from foo - *stopped,reason="function-finished",frame={func="main",args=[], - file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} - (gdb) - - Function returning other than `void'. The name of the internal GDB -variable storing the result is printed, together with the value itself. - - -exec-finish - ^running - (gdb) - *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", - args=[{name="a",value="1"],{name="b",value="9"}}, - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - gdb-result-var="$1",return-value="0" - (gdb) - -The `-exec-interrupt' Command ------------------------------ - -Synopsis -........ - - -exec-interrupt [--all|--thread-group N] - - Interrupts the background execution of the target. Note how the -token associated with the stop message is the one for the execution -command that has been interrupted. The token for the interrupt itself -only appears in the `^done' output. If the user is trying to interrupt -a non-running program, an error message will be printed. - - Note that when asynchronous execution is enabled, this command is -asynchronous just like other execution commands. That is, first the -`^done' response will be printed, and the target stop will be reported -after that using the `*stopped' notification. - - In non-stop mode, only the context thread is interrupted by default. -All threads (in all inferiors) will be interrupted if the `--all' -option is specified. If the `--thread-group' option is specified, all -threads in that group will be interrupted. - -GDB Command -........... - -The corresponding GDB command is `interrupt'. - -Example -....... - - (gdb) - 111-exec-continue - 111^running - - (gdb) - 222-exec-interrupt - 222^done - (gdb) - 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", - frame={addr="0x00010140",func="foo",args=[],file="try.c", - fullname="/home/foo/bar/try.c",line="13"} - (gdb) - - (gdb) - -exec-interrupt - ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." - (gdb) - -The `-exec-jump' Command ------------------------- - -Synopsis -........ - - -exec-jump LOCATION - - Resumes execution of the inferior program at the location specified -by parameter. *Note Specify Location::, for a description of the -different forms of LOCATION. - -GDB Command -........... - -The corresponding GDB command is `jump'. - -Example -....... - - -exec-jump foo.c:10 - *running,thread-id="all" - ^running - -The `-exec-next' Command ------------------------- - -Synopsis -........ - - -exec-next [--reverse] - - Resumes execution of the inferior program, stopping when the -beginning of the next source line is reached. - - If the `--reverse' option is specified, resumes reverse execution of -the inferior program, stopping at the beginning of the previous source -line. If you issue this command on the first line of a function, it -will take you back to the caller of that function, to the source line -where the function was called. - -GDB Command -........... - -The corresponding GDB command is `next'. - -Example -....... - - -exec-next - ^running - (gdb) - *stopped,reason="end-stepping-range",line="8",file="hello.c" - (gdb) - -The `-exec-next-instruction' Command ------------------------------------- - -Synopsis -........ - - -exec-next-instruction [--reverse] - - Executes one machine instruction. If the instruction is a function -call, continues until the function returns. If the program stops at an -instruction in the middle of a source line, the address will be printed -as well. - - If the `--reverse' option is specified, resumes reverse execution of -the inferior program, stopping at the previous instruction. If the -previously executed instruction was a return from another function, it -will continue to execute in reverse until the call to that function -(from the current stack frame) is reached. - -GDB Command -........... - -The corresponding GDB command is `nexti'. - -Example -....... - - (gdb) - -exec-next-instruction - ^running - - (gdb) - *stopped,reason="end-stepping-range", - addr="0x000100d4",line="5",file="hello.c" - (gdb) - -The `-exec-return' Command --------------------------- - -Synopsis -........ - - -exec-return - - Makes current function return immediately. Doesn't execute the -inferior. Displays the new current frame. - -GDB Command -........... - -The corresponding GDB command is `return'. - -Example -....... - - (gdb) - 200-break-insert callee4 - 200^done,bkpt={number="1",addr="0x00010734", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} - (gdb) - 000-exec-run - 000^running - (gdb) - 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", - frame={func="callee4",args=[], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} - (gdb) - 205-break-delete - 205^done - (gdb) - 111-exec-return - 111^done,frame={level="0",func="callee3", - args=[{name="strarg", - value="0x11940 \"A string argument.\""}], - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} - (gdb) - -The `-exec-run' Command ------------------------ - -Synopsis -........ - - -exec-run [--all | --thread-group N] - - Starts execution of the inferior from the beginning. The inferior -executes until either a breakpoint is encountered or the program exits. -In the latter case the output will include an exit code, if the program -has exited exceptionally. - - When no option is specified, the current inferior is started. If the -`--thread-group' option is specified, it should refer to a thread group -of type `process', and that thread group will be started. If the -`--all' option is specified, then all inferiors will be started. - -GDB Command -........... - -The corresponding GDB command is `run'. - -Examples -........ - - (gdb) - -break-insert main - ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} - (gdb) - -exec-run - ^running - (gdb) - *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", - frame={func="main",args=[],file="recursive2.c", - fullname="/home/foo/bar/recursive2.c",line="4"} - (gdb) - -Program exited normally: - - (gdb) - -exec-run - ^running - (gdb) - x = 55 - *stopped,reason="exited-normally" - (gdb) - -Program exited exceptionally: - - (gdb) - -exec-run - ^running - (gdb) - x = 55 - *stopped,reason="exited",exit-code="01" - (gdb) - - Another way the program can terminate is if it receives a signal -such as `SIGINT'. In this case, GDB/MI displays this: - - (gdb) - *stopped,reason="exited-signalled",signal-name="SIGINT", - signal-meaning="Interrupt" - -The `-exec-step' Command ------------------------- - -Synopsis -........ - - -exec-step [--reverse] - - Resumes execution of the inferior program, stopping when the -beginning of the next source line is reached, if the next source line -is not a function call. If it is, stop at the first instruction of the -called function. If the `--reverse' option is specified, resumes -reverse execution of the inferior program, stopping at the beginning of -the previously executed source line. - -GDB Command -........... - -The corresponding GDB command is `step'. - -Example -....... - -Stepping into a function: - - -exec-step - ^running - (gdb) - *stopped,reason="end-stepping-range", - frame={func="foo",args=[{name="a",value="10"}, - {name="b",value="0"}],file="recursive2.c", - fullname="/home/foo/bar/recursive2.c",line="11"} - (gdb) - - Regular stepping: - - -exec-step - ^running - (gdb) - *stopped,reason="end-stepping-range",line="14",file="recursive2.c" - (gdb) - -The `-exec-step-instruction' Command ------------------------------------- - -Synopsis -........ - - -exec-step-instruction [--reverse] - - Resumes the inferior which executes one machine instruction. If the -`--reverse' option is specified, resumes reverse execution of the -inferior program, stopping at the previously executed instruction. The -output, once GDB has stopped, will vary depending on whether we have -stopped in the middle of a source line or not. In the former case, the -address at which the program stopped will be printed as well. - -GDB Command -........... - -The corresponding GDB command is `stepi'. - -Example -....... - - (gdb) - -exec-step-instruction - ^running - - (gdb) - *stopped,reason="end-stepping-range", - frame={func="foo",args=[],file="try.c", - fullname="/home/foo/bar/try.c",line="10"} - (gdb) - -exec-step-instruction - ^running - - (gdb) - *stopped,reason="end-stepping-range", - frame={addr="0x000100f4",func="foo",args=[],file="try.c", - fullname="/home/foo/bar/try.c",line="10"} - (gdb) - -The `-exec-until' Command -------------------------- - -Synopsis -........ - - -exec-until [ LOCATION ] - - Executes the inferior until the LOCATION specified in the argument -is reached. If there is no argument, the inferior executes until a -source line greater than the current one is reached. The reason for -stopping in this case will be `location-reached'. - -GDB Command -........... - -The corresponding GDB command is `until'. - -Example -....... - - (gdb) - -exec-until recursive2.c:6 - ^running - (gdb) - x = 55 - *stopped,reason="location-reached",frame={func="main",args=[], - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} - (gdb) - - -File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI - -27.12 GDB/MI Stack Manipulation Commands -======================================== - -The `-stack-info-frame' Command -------------------------------- - -Synopsis -........ - - -stack-info-frame - - Get info on the selected frame. - -GDB Command -........... - -The corresponding GDB command is `info frame' or `frame' (without -arguments). - -Example -....... - - (gdb) - -stack-info-frame - ^done,frame={level="1",addr="0x0001076c",func="callee3", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} - (gdb) - -The `-stack-info-depth' Command -------------------------------- - -Synopsis -........ - - -stack-info-depth [ MAX-DEPTH ] - - Return the depth of the stack. If the integer argument MAX-DEPTH is -specified, do not count beyond MAX-DEPTH frames. - -GDB Command -........... - -There's no equivalent GDB command. - -Example -....... - -For a stack with frame levels 0 through 11: - - (gdb) - -stack-info-depth - ^done,depth="12" - (gdb) - -stack-info-depth 4 - ^done,depth="4" - (gdb) - -stack-info-depth 12 - ^done,depth="12" - (gdb) - -stack-info-depth 11 - ^done,depth="11" - (gdb) - -stack-info-depth 13 - ^done,depth="12" - (gdb) - -The `-stack-list-arguments' Command ------------------------------------ - -Synopsis -........ - - -stack-list-arguments PRINT-VALUES - [ LOW-FRAME HIGH-FRAME ] - - Display a list of the arguments for the frames between LOW-FRAME and -HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, -list the arguments for the whole call stack. If the two arguments are -equal, show the single frame at the corresponding level. It is an -error if LOW-FRAME is larger than the actual number of frames. On the -other hand, HIGH-FRAME may be larger than the actual number of frames, -in which case only existing frames will be returned. - - If PRINT-VALUES is 0 or `--no-values', print only the names of the -variables; if it is 1 or `--all-values', print also their values; and -if it is 2 or `--simple-values', print the name, type and value for -simple data types, and the name and type for arrays, structures and -unions. - - Use of this command to obtain arguments in a single frame is -deprecated in favor of the `-stack-list-variables' command. - -GDB Command -........... - -GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' -command which partially overlaps with the functionality of -`-stack-list-arguments'. - -Example -....... - - (gdb) - -stack-list-frames - ^done, - stack=[ - frame={level="0",addr="0x00010734",func="callee4", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, - frame={level="1",addr="0x0001076c",func="callee3", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, - frame={level="2",addr="0x0001078c",func="callee2", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, - frame={level="3",addr="0x000107b4",func="callee1", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, - frame={level="4",addr="0x000107e0",func="main", - file="../../../devo/gdb/testsuite/gdb.mi/basics.c", - fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] - (gdb) - -stack-list-arguments 0 - ^done, - stack-args=[ - frame={level="0",args=[]}, - frame={level="1",args=[name="strarg"]}, - frame={level="2",args=[name="intarg",name="strarg"]}, - frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, - frame={level="4",args=[]}] - (gdb) - -stack-list-arguments 1 - ^done, - stack-args=[ - frame={level="0",args=[]}, - frame={level="1", - args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, - frame={level="2",args=[ - {name="intarg",value="2"}, - {name="strarg",value="0x11940 \"A string argument.\""}]}, - {frame={level="3",args=[ - {name="intarg",value="2"}, - {name="strarg",value="0x11940 \"A string argument.\""}, - {name="fltarg",value="3.5"}]}, - frame={level="4",args=[]}] - (gdb) - -stack-list-arguments 0 2 2 - ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] - (gdb) - -stack-list-arguments 1 2 2 - ^done,stack-args=[frame={level="2", - args=[{name="intarg",value="2"}, - {name="strarg",value="0x11940 \"A string argument.\""}]}] - (gdb) - -The `-stack-list-frames' Command --------------------------------- - -Synopsis -........ - - -stack-list-frames [ LOW-FRAME HIGH-FRAME ] - - List the frames currently on the stack. For each frame it displays -the following info: - -`LEVEL' - The frame number, 0 being the topmost frame, i.e., the innermost - function. - -`ADDR' - The `$pc' value for that frame. - -`FUNC' - Function name. - -`FILE' - File name of the source file where the function lives. - -`FULLNAME' - The full file name of the source file where the function lives. - -`LINE' - Line number corresponding to the `$pc'. - -`FROM' - The shared library where this function is defined. This is only - given if the frame's function is not known. - - If invoked without arguments, this command prints a backtrace for the -whole stack. If given two integer arguments, it shows the frames whose -levels are between the two arguments (inclusive). If the two arguments -are equal, it shows the single frame at the corresponding level. It is -an error if LOW-FRAME is larger than the actual number of frames. On -the other hand, HIGH-FRAME may be larger than the actual number of -frames, in which case only existing frames will be returned. - -GDB Command -........... - -The corresponding GDB commands are `backtrace' and `where'. - -Example -....... - -Full stack backtrace: - - (gdb) - -stack-list-frames - ^done,stack= - [frame={level="0",addr="0x0001076c",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, - frame={level="1",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="2",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="3",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="4",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="5",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="6",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="7",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="8",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="9",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="10",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="11",addr="0x00010738",func="main", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] - (gdb) - - Show frames between LOW_FRAME and HIGH_FRAME: - - (gdb) - -stack-list-frames 3 5 - ^done,stack= - [frame={level="3",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="4",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, - frame={level="5",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] - (gdb) - - Show a single frame: - - (gdb) - -stack-list-frames 3 3 - ^done,stack= - [frame={level="3",addr="0x000107a4",func="foo", - file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] - (gdb) - -The `-stack-list-locals' Command --------------------------------- - -Synopsis -........ - - -stack-list-locals PRINT-VALUES - - Display the local variable names for the selected frame. If -PRINT-VALUES is 0 or `--no-values', print only the names of the -variables; if it is 1 or `--all-values', print also their values; and -if it is 2 or `--simple-values', print the name, type and value for -simple data types, and the name and type for arrays, structures and -unions. In this last case, a frontend can immediately display the -value of simple data types and create variable objects for other data -types when the user wishes to explore their values in more detail. - - This command is deprecated in favor of the `-stack-list-variables' -command. - -GDB Command -........... - -`info locals' in GDB, `gdb_get_locals' in `gdbtk'. - -Example -....... - - (gdb) - -stack-list-locals 0 - ^done,locals=[name="A",name="B",name="C"] - (gdb) - -stack-list-locals --all-values - ^done,locals=[{name="A",value="1"},{name="B",value="2"}, - {name="C",value="{1, 2, 3}"}] - -stack-list-locals --simple-values - ^done,locals=[{name="A",type="int",value="1"}, - {name="B",type="int",value="2"},{name="C",type="int [3]"}] - (gdb) - -The `-stack-list-variables' Command ------------------------------------ - -Synopsis -........ - - -stack-list-variables PRINT-VALUES - - Display the names of local variables and function arguments for the -selected frame. If PRINT-VALUES is 0 or `--no-values', print only the -names of the variables; if it is 1 or `--all-values', print also their -values; and if it is 2 or `--simple-values', print the name, type and -value for simple data types, and the name and type for arrays, -structures and unions. - -Example -....... - - (gdb) - -stack-list-variables --thread 1 --frame 0 --all-values - ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] - (gdb) - -The `-stack-select-frame' Command ---------------------------------- - -Synopsis -........ - - -stack-select-frame FRAMENUM - - Change the selected frame. Select a different frame FRAMENUM on the -stack. - - This command in deprecated in favor of passing the `--frame' option -to every command. - -GDB Command -........... - -The corresponding GDB commands are `frame', `up', `down', -`select-frame', `up-silent', and `down-silent'. - -Example -....... - - (gdb) - -stack-select-frame 2 - ^done - (gdb) - - -File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI - -27.13 GDB/MI Variable Objects -============================= - -Introduction to Variable Objects --------------------------------- - -Variable objects are "object-oriented" MI interface for examining and -changing values of expressions. Unlike some other MI interfaces that -work with expressions, variable objects are specifically designed for -simple and efficient presentation in the frontend. A variable object -is identified by string name. When a variable object is created, the -frontend specifies the expression for that variable object. The -expression can be a simple variable, or it can be an arbitrary complex -expression, and can even involve CPU registers. After creating a -variable object, the frontend can invoke other variable object -operations--for example to obtain or change the value of a variable -object, or to change display format. - - Variable objects have hierarchical tree structure. Any variable -object that corresponds to a composite type, such as structure in C, has -a number of child variable objects, for example corresponding to each -element of a structure. A child variable object can itself have -children, recursively. Recursion ends when we reach leaf variable -objects, which always have built-in types. Child variable objects are -created only by explicit request, so if a frontend is not interested in -the children of a particular variable object, no child will be created. - - For a leaf variable object it is possible to obtain its value as a -string, or set the value from a string. String value can be also -obtained for a non-leaf variable object, but it's generally a string -that only indicates the type of the object, and does not list its -contents. Assignment to a non-leaf variable object is not allowed. - - A frontend does not need to read the values of all variable objects -each time the program stops. Instead, MI provides an update command -that lists all variable objects whose values has changed since the last -update operation. This considerably reduces the amount of data that -must be transferred to the frontend. As noted above, children variable -objects are created on demand, and only leaf variable objects have a -real value. As result, gdb will read target memory only for leaf -variables that frontend has created. - - The automatic update is not always desirable. For example, a -frontend might want to keep a value of some expression for future -reference, and never update it. For another example, fetching memory -is relatively slow for embedded targets, so a frontend might want to -disable automatic update for the variables that are either not visible -on the screen, or "closed". This is possible using so called "frozen -variable objects". Such variable objects are never implicitly updated. - - Variable objects can be either "fixed" or "floating". For the fixed -variable object, the expression is parsed when the variable object is -created, including associating identifiers to specific variables. The -meaning of expression never changes. For a floating variable object -the values of variables whose names appear in the expressions are -re-evaluated every time in the context of the current frame. Consider -this example: - - void do_work(...) - { - struct work_state state; - - if (...) - do_work(...); - } - - If a fixed variable object for the `state' variable is created in -this function, and we enter the recursive call, the the variable object -will report the value of `state' in the top-level `do_work' invocation. -On the other hand, a floating variable object will report the value of -`state' in the current frame. - - If an expression specified when creating a fixed variable object -refers to a local variable, the variable object becomes bound to the -thread and frame in which the variable object is created. When such -variable object is updated, GDB makes sure that the thread/frame -combination the variable object is bound to still exists, and -re-evaluates the variable object in context of that thread/frame. - - The following is the complete set of GDB/MI operations defined to -access this functionality: - -*Operation* *Description* -`-enable-pretty-printing' enable Python-based pretty-printing -`-var-create' create a variable object -`-var-delete' delete the variable object and/or its - children -`-var-set-format' set the display format of this variable -`-var-show-format' show the display format of this variable -`-var-info-num-children' tells how many children this object has -`-var-list-children' return a list of the object's children -`-var-info-type' show the type of this variable object -`-var-info-expression' print parent-relative expression that this - variable object represents -`-var-info-path-expression' print full expression that this variable - object represents -`-var-show-attributes' is this variable editable? does it exist - here? -`-var-evaluate-expression' get the value of this variable -`-var-assign' set the value of this variable -`-var-update' update the variable and its children -`-var-set-frozen' set frozeness attribute -`-var-set-update-range' set range of children to display on update - - In the next subsection we describe each operation in detail and -suggest how it can be used. - -Description And Use of Operations on Variable Objects ------------------------------------------------------ - -The `-enable-pretty-printing' Command -------------------------------------- - - -enable-pretty-printing - - GDB allows Python-based visualizers to affect the output of the MI -variable object commands. However, because there was no way to -implement this in a fully backward-compatible way, a front end must -request that this functionality be enabled. - - Once enabled, this feature cannot be disabled. - - Note that if Python support has not been compiled into GDB, this -command will still succeed (and do nothing). - - This feature is currently (as of GDB 7.0) experimental, and may work -differently in future versions of GDB. - -The `-var-create' Command -------------------------- - -Synopsis -........ - - -var-create {NAME | "-"} - {FRAME-ADDR | "*" | "@"} EXPRESSION - - This operation creates a variable object, which allows the -monitoring of a variable, the result of an expression, a memory cell or -a CPU register. - - The NAME parameter is the string by which the object can be -referenced. It must be unique. If `-' is specified, the varobj system -will generate a string "varNNNNNN" automatically. It will be unique -provided that one does not specify NAME of that format. The command -fails if a duplicate name is found. - - The frame under which the expression should be evaluated can be -specified by FRAME-ADDR. A `*' indicates that the current frame should -be used. A `@' indicates that a floating variable object must be -created. - - EXPRESSION is any expression valid on the current language set (must -not begin with a `*'), or one of the following: - - * `*ADDR', where ADDR is the address of a memory cell - - * `*ADDR-ADDR' -- a memory address range (TBD) - - * `$REGNAME' -- a CPU register name - - A varobj's contents may be provided by a Python-based -pretty-printer. In this case the varobj is known as a "dynamic -varobj". Dynamic varobjs have slightly different semantics in some -cases. If the `-enable-pretty-printing' command is not sent, then GDB -will never create a dynamic varobj. This ensures backward -compatibility for existing clients. - -Result -...... - -This operation returns attributes of the newly-created varobj. These -are: - -`name' - The name of the varobj. - -`numchild' - The number of children of the varobj. This number is not - necessarily reliable for a dynamic varobj. Instead, you must - examine the `has_more' attribute. - -`value' - The varobj's scalar value. For a varobj whose type is some sort of - aggregate (e.g., a `struct'), or for a dynamic varobj, this value - will not be interesting. - -`type' - The varobj's type. This is a string representation of the type, as - would be printed by the GDB CLI. - -`thread-id' - If a variable object is bound to a specific thread, then this is - the thread's identifier. - -`has_more' - For a dynamic varobj, this indicates whether there appear to be any - children available. For a non-dynamic varobj, this will be 0. - -`dynamic' - This attribute will be present and have the value `1' if the - varobj is a dynamic varobj. If the varobj is not a dynamic varobj, - then this attribute will not be present. - -`displayhint' - A dynamic varobj can supply a display hint to the front end. The - value comes directly from the Python pretty-printer object's - `display_hint' method. *Note Pretty Printing API::. - - Typical output will look like this: - - name="NAME",numchild="N",type="TYPE",thread-id="M", - has_more="HAS_MORE" - -The `-var-delete' Command -------------------------- - -Synopsis -........ - - -var-delete [ -c ] NAME - - Deletes a previously created variable object and all of its children. -With the `-c' option, just deletes the children. - - Returns an error if the object NAME is not found. - -The `-var-set-format' Command ------------------------------ - -Synopsis -........ - - -var-set-format NAME FORMAT-SPEC - - Sets the output format for the value of the object NAME to be -FORMAT-SPEC. - - The syntax for the FORMAT-SPEC is as follows: - - FORMAT-SPEC ==> - {binary | decimal | hexadecimal | octal | natural} - - The natural format is the default format choosen automatically based -on the variable type (like decimal for an `int', hex for pointers, -etc.). - - For a variable with children, the format is set only on the variable -itself, and the children are not affected. - -The `-var-show-format' Command ------------------------------- - -Synopsis -........ - - -var-show-format NAME - - Returns the format used to display the value of the object NAME. - - FORMAT ==> - FORMAT-SPEC - -The `-var-info-num-children' Command ------------------------------------- - -Synopsis -........ - - -var-info-num-children NAME - - Returns the number of children of a variable object NAME: - - numchild=N - - Note that this number is not completely reliable for a dynamic -varobj. It will return the current number of children, but more -children may be available. - -The `-var-list-children' Command --------------------------------- - -Synopsis -........ - - -var-list-children [PRINT-VALUES] NAME [FROM TO] -Return a list of the children of the specified variable object and -create variable objects for them, if they do not already exist. With a -single argument or if PRINT-VALUES has a value of 0 or `--no-values', -print only the names of the variables; if PRINT-VALUES is 1 or -`--all-values', also print their values; and if it is 2 or -`--simple-values' print the name and value for simple data types and -just the name for arrays, structures and unions. - - FROM and TO, if specified, indicate the range of children to report. -If FROM or TO is less than zero, the range is reset and all children -will be reported. Otherwise, children starting at FROM (zero-based) -and up to and excluding TO will be reported. - - If a child range is requested, it will only affect the current call -to `-var-list-children', but not future calls to `-var-update'. For -this, you must instead use `-var-set-update-range'. The intent of this -approach is to enable a front end to implement any update approach it -likes; for example, scrolling a view may cause the front end to request -more children with `-var-list-children', and then the front end could -call `-var-set-update-range' with a different range to ensure that -future updates are restricted to just the visible items. - - For each child the following results are returned: - -NAME - Name of the variable object created for this child. - -EXP - The expression to be shown to the user by the front end to - designate this child. For example this may be the name of a - structure member. - - For a dynamic varobj, this value cannot be used to form an - expression. There is no way to do this at all with a dynamic - varobj. - - For C/C++ structures there are several pseudo children returned to - designate access qualifiers. For these pseudo children EXP is - `public', `private', or `protected'. In this case the type and - value are not present. - - A dynamic varobj will not report the access qualifying - pseudo-children, regardless of the language. This information is - not available at all with a dynamic varobj. - -NUMCHILD - Number of children this child has. For a dynamic varobj, this - will be 0. - -TYPE - The type of the child. - -VALUE - If values were requested, this is the value. - -THREAD-ID - If this variable object is associated with a thread, this is the - thread id. Otherwise this result is not present. - -FROZEN - If the variable object is frozen, this variable will be present - with a value of 1. - - The result may have its own attributes: - -`displayhint' - A dynamic varobj can supply a display hint to the front end. The - value comes directly from the Python pretty-printer object's - `display_hint' method. *Note Pretty Printing API::. - -`has_more' - This is an integer attribute which is nonzero if there are children - remaining after the end of the selected range. - -Example -....... - - (gdb) - -var-list-children n - ^done,numchild=N,children=[child={name=NAME,exp=EXP, - numchild=N,type=TYPE},(repeats N times)] - (gdb) - -var-list-children --all-values n - ^done,numchild=N,children=[child={name=NAME,exp=EXP, - numchild=N,value=VALUE,type=TYPE},(repeats N times)] - -The `-var-info-type' Command ----------------------------- - -Synopsis -........ - - -var-info-type NAME - - Returns the type of the specified variable NAME. The type is -returned as a string in the same format as it is output by the GDB CLI: - - type=TYPENAME - -The `-var-info-expression' Command ----------------------------------- - -Synopsis -........ - - -var-info-expression NAME - - Returns a string that is suitable for presenting this variable -object in user interface. The string is generally not valid expression -in the current language, and cannot be evaluated. - - For example, if `a' is an array, and variable object `A' was created -for `a', then we'll get this output: - - (gdb) -var-info-expression A.1 - ^done,lang="C",exp="1" - -Here, the values of `lang' can be `{"C" | "C++" | "Java"}'. - - Note that the output of the `-var-list-children' command also -includes those expressions, so the `-var-info-expression' command is of -limited use. - -The `-var-info-path-expression' Command ---------------------------------------- - -Synopsis -........ - - -var-info-path-expression NAME - - Returns an expression that can be evaluated in the current context -and will yield the same value that a variable object has. Compare this -with the `-var-info-expression' command, which result can be used only -for UI presentation. Typical use of the `-var-info-path-expression' -command is creating a watchpoint from a variable object. - - This command is currently not valid for children of a dynamic varobj, -and will give an error when invoked on one. - - For example, suppose `C' is a C++ class, derived from class `Base', -and that the `Base' class has a member called `m_size'. Assume a -variable `c' is has the type of `C' and a variable object `C' was -created for variable `c'. Then, we'll get this output: - (gdb) -var-info-path-expression C.Base.public.m_size - ^done,path_expr=((Base)c).m_size) - -The `-var-show-attributes' Command ----------------------------------- - -Synopsis -........ - - -var-show-attributes NAME - - List attributes of the specified variable object NAME: - - status=ATTR [ ( ,ATTR )* ] - -where ATTR is `{ { editable | noneditable } | TBD }'. - -The `-var-evaluate-expression' Command --------------------------------------- - -Synopsis -........ - - -var-evaluate-expression [-f FORMAT-SPEC] NAME - - Evaluates the expression that is represented by the specified -variable object and returns its value as a string. The format of the -string can be specified with the `-f' option. The possible values of -this option are the same as for `-var-set-format' (*note --var-set-format::). If the `-f' option is not specified, the current -display format will be used. The current display format can be changed -using the `-var-set-format' command. - - value=VALUE - - Note that one must invoke `-var-list-children' for a variable before -the value of a child variable can be evaluated. - -The `-var-assign' Command -------------------------- - -Synopsis -........ - - -var-assign NAME EXPRESSION - - Assigns the value of EXPRESSION to the variable object specified by -NAME. The object must be `editable'. If the variable's value is -altered by the assign, the variable will show up in any subsequent -`-var-update' list. - -Example -....... - - (gdb) - -var-assign var1 3 - ^done,value="3" - (gdb) - -var-update * - ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] - (gdb) - -The `-var-update' Command -------------------------- - -Synopsis -........ - - -var-update [PRINT-VALUES] {NAME | "*"} - - Reevaluate the expressions corresponding to the variable object NAME -and all its direct and indirect children, and return the list of -variable objects whose values have changed; NAME must be a root -variable object. Here, "changed" means that the result of -`-var-evaluate-expression' before and after the `-var-update' is -different. If `*' is used as the variable object names, all existing -variable objects are updated, except for frozen ones (*note --var-set-frozen::). The option PRINT-VALUES determines whether both -names and values, or just names are printed. The possible values of -this option are the same as for `-var-list-children' (*note --var-list-children::). It is recommended to use the `--all-values' -option, to reduce the number of MI commands needed on each program stop. - - With the `*' parameter, if a variable object is bound to a currently -running thread, it will not be updated, without any diagnostic. - - If `-var-set-update-range' was previously used on a varobj, then -only the selected range of children will be reported. - - `-var-update' reports all the changed varobjs in a tuple named -`changelist'. - - Each item in the change list is itself a tuple holding: - -`name' - The name of the varobj. - -`value' - If values were requested for this update, then this field will be - present and will hold the value of the varobj. - -`in_scope' - This field is a string which may take one of three values: - - `"true"' - The variable object's current value is valid. - - `"false"' - The variable object does not currently hold a valid value but - it may hold one in the future if its associated expression - comes back into scope. - - `"invalid"' - The variable object no longer holds a valid value. This can - occur when the executable file being debugged has changed, - either through recompilation or by using the GDB `file' - command. The front end should normally choose to delete - these variable objects. - - In the future new values may be added to this list so the front - should be prepared for this possibility. *Note GDB/MI Development - and Front Ends: GDB/MI Development and Front Ends. - -`type_changed' - This is only present if the varobj is still valid. If the type - changed, then this will be the string `true'; otherwise it will be - `false'. - -`new_type' - If the varobj's type changed, then this field will be present and - will hold the new type. - -`new_num_children' - For a dynamic varobj, if the number of children changed, or if the - type changed, this will be the new number of children. - - The `numchild' field in other varobj responses is generally not - valid for a dynamic varobj - it will show the number of children - that GDB knows about, but because dynamic varobjs lazily - instantiate their children, this will not reflect the number of - children which may be available. - - The `new_num_children' attribute only reports changes to the - number of children known by GDB. This is the only way to detect - whether an update has removed children (which necessarily can only - happen at the end of the update range). - -`displayhint' - The display hint, if any. - -`has_more' - This is an integer value, which will be 1 if there are more - children available outside the varobj's update range. - -`dynamic' - This attribute will be present and have the value `1' if the - varobj is a dynamic varobj. If the varobj is not a dynamic varobj, - then this attribute will not be present. - -`new_children' - If new children were added to a dynamic varobj within the selected - update range (as set by `-var-set-update-range'), then they will - be listed in this attribute. - -Example -....... - - (gdb) - -var-assign var1 3 - ^done,value="3" - (gdb) - -var-update --all-values var1 - ^done,changelist=[{name="var1",value="3",in_scope="true", - type_changed="false"}] - (gdb) - -The `-var-set-frozen' Command ------------------------------ - -Synopsis -........ - - -var-set-frozen NAME FLAG - - Set the frozenness flag on the variable object NAME. The FLAG -parameter should be either `1' to make the variable frozen or `0' to -make it unfrozen. If a variable object is frozen, then neither itself, -nor any of its children, are implicitly updated by `-var-update' of a -parent variable or by `-var-update *'. Only `-var-update' of the -variable itself will update its value and values of its children. -After a variable object is unfrozen, it is implicitly updated by all -subsequent `-var-update' operations. Unfreezing a variable does not -update it, only subsequent `-var-update' does. - -Example -....... - - (gdb) - -var-set-frozen V 1 - ^done - (gdb) - -The `-var-set-update-range' command ------------------------------------ - -Synopsis -........ - - -var-set-update-range NAME FROM TO - - Set the range of children to be returned by future invocations of -`-var-update'. - - FROM and TO indicate the range of children to report. If FROM or TO -is less than zero, the range is reset and all children will be -reported. Otherwise, children starting at FROM (zero-based) and up to -and excluding TO will be reported. - -Example -....... - - (gdb) - -var-set-update-range V 1 2 - ^done - -The `-var-set-visualizer' command ---------------------------------- - -Synopsis -........ - - -var-set-visualizer NAME VISUALIZER - - Set a visualizer for the variable object NAME. - - VISUALIZER is the visualizer to use. The special value `None' means -to disable any visualizer in use. - - If not `None', VISUALIZER must be a Python expression. This -expression must evaluate to a callable object which accepts a single -argument. GDB will call this object with the value of the varobj NAME -as an argument (this is done so that the same Python pretty-printing -code can be used for both the CLI and MI). When called, this object -must return an object which conforms to the pretty-printing interface -(*note Pretty Printing API::). - - The pre-defined function `gdb.default_visualizer' may be used to -select a visualizer by following the built-in process (*note Selecting -Pretty-Printers::). This is done automatically when a varobj is -created, and so ordinarily is not needed. - - This feature is only available if Python support is enabled. The MI -command `-list-features' (*note GDB/MI Miscellaneous Commands::) can be -used to check this. - -Example -....... - -Resetting the visualizer: - - (gdb) - -var-set-visualizer V None - ^done - - Reselecting the default (type-based) visualizer: - - (gdb) - -var-set-visualizer V gdb.default_visualizer - ^done - - Suppose `SomeClass' is a visualizer class. A lambda expression can -be used to instantiate this class for a varobj: - - (gdb) - -var-set-visualizer V "lambda val: SomeClass()" - ^done - - -File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI - -27.14 GDB/MI Data Manipulation -============================== - -This section describes the GDB/MI commands that manipulate data: -examine memory and registers, evaluate expressions, etc. - -The `-data-disassemble' Command -------------------------------- - -Synopsis -........ - - -data-disassemble - [ -s START-ADDR -e END-ADDR ] - | [ -f FILENAME -l LINENUM [ -n LINES ] ] - -- MODE - -Where: - -`START-ADDR' - is the beginning address (or `$pc') - -`END-ADDR' - is the end address - -`FILENAME' - is the name of the file to disassemble - -`LINENUM' - is the line number to disassemble around - -`LINES' - is the number of disassembly lines to be produced. If it is -1, - the whole function will be disassembled, in case no END-ADDR is - specified. If END-ADDR is specified as a non-zero value, and - LINES is lower than the number of disassembly lines between - START-ADDR and END-ADDR, only LINES lines are displayed; if LINES - is higher than the number of lines between START-ADDR and - END-ADDR, only the lines up to END-ADDR are displayed. - -`MODE' - is either 0 (meaning only disassembly), 1 (meaning mixed source and - disassembly), 2 (meaning disassembly with raw opcodes), or 3 - (meaning mixed source and disassembly with raw opcodes). - -Result -...... - -The output for each instruction is composed of four fields: - - * Address - - * Func-name - - * Offset - - * Instruction - - Note that whatever included in the instruction field, is not -manipulated directly by GDB/MI, i.e., it is not possible to adjust its -format. - -GDB Command -........... - -There's no direct mapping from this command to the CLI. - -Example -....... - -Disassemble from the current value of `$pc' to `$pc + 20': - - (gdb) - -data-disassemble -s $pc -e "$pc + 20" -- 0 - ^done, - asm_insns=[ - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}, - {address="0x000107c8",func-name="main",offset="12", - inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, - {address="0x000107cc",func-name="main",offset="16", - inst="sethi %hi(0x11800), %o2"}, - {address="0x000107d0",func-name="main",offset="20", - inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] - (gdb) - - Disassemble the whole `main' function. Line 32 is part of `main'. - - -data-disassemble -f basics.c -l 32 -- 0 - ^done,asm_insns=[ - {address="0x000107bc",func-name="main",offset="0", - inst="save %sp, -112, %sp"}, - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}, - [...] - {address="0x0001081c",func-name="main",offset="96",inst="ret "}, - {address="0x00010820",func-name="main",offset="100",inst="restore "}] - (gdb) - - Disassemble 3 instructions from the start of `main': - - (gdb) - -data-disassemble -f basics.c -l 32 -n 3 -- 0 - ^done,asm_insns=[ - {address="0x000107bc",func-name="main",offset="0", - inst="save %sp, -112, %sp"}, - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}] - (gdb) - - Disassemble 3 instructions from the start of `main' in mixed mode: - - (gdb) - -data-disassemble -f basics.c -l 32 -n 3 -- 1 - ^done,asm_insns=[ - src_and_asm_line={line="31", - file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ - {address="0x000107bc",func-name="main",offset="0", - inst="save %sp, -112, %sp"}]}, - src_and_asm_line={line="32", - file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ - testsuite/gdb.mi/basics.c",line_asm_insn=[ - {address="0x000107c0",func-name="main",offset="4", - inst="mov 2, %o0"}, - {address="0x000107c4",func-name="main",offset="8", - inst="sethi %hi(0x11800), %o2"}]}] - (gdb) - -The `-data-evaluate-expression' Command ---------------------------------------- - -Synopsis -........ - - -data-evaluate-expression EXPR - - Evaluate EXPR as an expression. The expression could contain an -inferior function call. The function call will execute synchronously. -If the expression contains spaces, it must be enclosed in double quotes. - -GDB Command -........... - -The corresponding GDB commands are `print', `output', and `call'. In -`gdbtk' only, there's a corresponding `gdb_eval' command. - -Example -....... - -In the following example, the numbers that precede the commands are the -"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command -Syntax. Notice how GDB/MI returns the same tokens in its output. - - 211-data-evaluate-expression A - 211^done,value="1" - (gdb) - 311-data-evaluate-expression &A - 311^done,value="0xefffeb7c" - (gdb) - 411-data-evaluate-expression A+3 - 411^done,value="4" - (gdb) - 511-data-evaluate-expression "A + 3" - 511^done,value="4" - (gdb) - -The `-data-list-changed-registers' Command ------------------------------------------- - -Synopsis -........ - - -data-list-changed-registers - - Display a list of the registers that have changed. - -GDB Command -........... - -GDB doesn't have a direct analog for this command; `gdbtk' has the -corresponding command `gdb_changed_register_list'. - -Example -....... - -On a PPC MBX board: - - (gdb) - -exec-continue - ^running - - (gdb) - *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ - func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", - line="5"} - (gdb) - -data-list-changed-registers - ^done,changed-registers=["0","1","2","4","5","6","7","8","9", - "10","11","13","14","15","16","17","18","19","20","21","22","23", - "24","25","26","27","28","30","31","64","65","66","67","69"] - (gdb) - -The `-data-list-register-names' Command ---------------------------------------- - -Synopsis -........ - - -data-list-register-names [ ( REGNO )+ ] - - Show a list of register names for the current target. If no -arguments are given, it shows a list of the names of all the registers. -If integer numbers are given as arguments, it will print a list of the -names of the registers corresponding to the arguments. To ensure -consistency between a register name and its number, the output list may -include empty register names. - -GDB Command -........... - -GDB does not have a command which corresponds to -`-data-list-register-names'. In `gdbtk' there is a corresponding -command `gdb_regnames'. - -Example -....... - -For the PPC MBX board: - (gdb) - -data-list-register-names - ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", - "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", - "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", - "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", - "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", - "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", - "", "pc","ps","cr","lr","ctr","xer"] - (gdb) - -data-list-register-names 1 2 3 - ^done,register-names=["r1","r2","r3"] - (gdb) - -The `-data-list-register-values' Command ----------------------------------------- - -Synopsis -........ - - -data-list-register-values FMT [ ( REGNO )*] - - Display the registers' contents. FMT is the format according to -which the registers' contents are to be returned, followed by an -optional list of numbers specifying the registers to display. A -missing list of numbers indicates that the contents of all the -registers must be returned. - - Allowed formats for FMT are: - -`x' - Hexadecimal - -`o' - Octal - -`t' - Binary - -`d' - Decimal - -`r' - Raw - -`N' - Natural - -GDB Command -........... - -The corresponding GDB commands are `info reg', `info all-reg', and (in -`gdbtk') `gdb_fetch_registers'. - -Example -....... - -For a PPC MBX board (note: line breaks are for readability only, they -don't appear in the actual output): - - (gdb) - -data-list-register-values r 64 65 - ^done,register-values=[{number="64",value="0xfe00a300"}, - {number="65",value="0x00029002"}] - (gdb) - -data-list-register-values x - ^done,register-values=[{number="0",value="0xfe0043c8"}, - {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, - {number="3",value="0x0"},{number="4",value="0xa"}, - {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, - {number="7",value="0xfe011e98"},{number="8",value="0x2"}, - {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, - {number="11",value="0x1"},{number="12",value="0x0"}, - {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, - {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, - {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, - {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, - {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, - {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, - {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, - {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, - {number="29",value="0x0"},{number="30",value="0xfe010000"}, - {number="31",value="0x0"},{number="32",value="0x0"}, - {number="33",value="0x0"},{number="34",value="0x0"}, - {number="35",value="0x0"},{number="36",value="0x0"}, - {number="37",value="0x0"},{number="38",value="0x0"}, - {number="39",value="0x0"},{number="40",value="0x0"}, - {number="41",value="0x0"},{number="42",value="0x0"}, - {number="43",value="0x0"},{number="44",value="0x0"}, - {number="45",value="0x0"},{number="46",value="0x0"}, - {number="47",value="0x0"},{number="48",value="0x0"}, - {number="49",value="0x0"},{number="50",value="0x0"}, - {number="51",value="0x0"},{number="52",value="0x0"}, - {number="53",value="0x0"},{number="54",value="0x0"}, - {number="55",value="0x0"},{number="56",value="0x0"}, - {number="57",value="0x0"},{number="58",value="0x0"}, - {number="59",value="0x0"},{number="60",value="0x0"}, - {number="61",value="0x0"},{number="62",value="0x0"}, - {number="63",value="0x0"},{number="64",value="0xfe00a300"}, - {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, - {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, - {number="69",value="0x20002b03"}] - (gdb) - -The `-data-read-memory' Command -------------------------------- - -This command is deprecated, use `-data-read-memory-bytes' instead. - -Synopsis -........ - - -data-read-memory [ -o BYTE-OFFSET ] - ADDRESS WORD-FORMAT WORD-SIZE - NR-ROWS NR-COLS [ ASCHAR ] - -where: - -`ADDRESS' - An expression specifying the address of the first memory word to be - read. Complex expressions containing embedded white space should - be quoted using the C convention. - -`WORD-FORMAT' - The format to be used to print the memory words. The notation is - the same as for GDB's `print' command (*note Output Formats: - Output Formats.). - -`WORD-SIZE' - The size of each memory word in bytes. - -`NR-ROWS' - The number of rows in the output table. - -`NR-COLS' - The number of columns in the output table. - -`ASCHAR' - If present, indicates that each row should include an ASCII dump. - The value of ASCHAR is used as a padding character when a byte is - not a member of the printable ASCII character set (printable ASCII - characters are those whose code is between 32 and 126, - inclusively). - -`BYTE-OFFSET' - An offset to add to the ADDRESS before fetching memory. - - This command displays memory contents as a table of NR-ROWS by -NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS * -NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes'). -Should less than the requested number of bytes be returned by the -target, the missing words are identified using `N/A'. The number of -bytes read from the target is returned in `nr-bytes' and the starting -address used to read memory in `addr'. - - The address of the next/previous row or page is available in -`next-row' and `prev-row', `next-page' and `prev-page'. - -GDB Command -........... - -The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory -read command. - -Example -....... - -Read six bytes of memory starting at `bytes+6' but then offset by `-6' -bytes. Format as three rows of two columns. One byte per word. -Display each word in hex. - - (gdb) - 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 - 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", - next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", - prev-page="0x0000138a",memory=[ - {addr="0x00001390",data=["0x00","0x01"]}, - {addr="0x00001392",data=["0x02","0x03"]}, - {addr="0x00001394",data=["0x04","0x05"]}] - (gdb) - - Read two bytes of memory starting at address `shorts + 64' and -display as a single word formatted in decimal. - - (gdb) - 5-data-read-memory shorts+64 d 2 1 1 - 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", - next-row="0x00001512",prev-row="0x0000150e", - next-page="0x00001512",prev-page="0x0000150e",memory=[ - {addr="0x00001510",data=["128"]}] - (gdb) - - Read thirty two bytes of memory starting at `bytes+16' and format as -eight rows of four columns. Include a string encoding with `x' used as -the non-printable character. - - (gdb) - 4-data-read-memory bytes+16 x 1 8 4 x - 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", - next-row="0x000013c0",prev-row="0x0000139c", - next-page="0x000013c0",prev-page="0x00001380",memory=[ - {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, - {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, - {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, - {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, - {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, - {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, - {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, - {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] - (gdb) - -The `-data-read-memory-bytes' Command -------------------------------------- - -Synopsis -........ - - -data-read-memory-bytes [ -o BYTE-OFFSET ] - ADDRESS COUNT - -where: - -`ADDRESS' - An expression specifying the address of the first memory word to be - read. Complex expressions containing embedded white space should - be quoted using the C convention. - -`COUNT' - The number of bytes to read. This should be an integer literal. - -`BYTE-OFFSET' - The offsets in bytes relative to ADDRESS at which to start - reading. This should be an integer literal. This option is - provided so that a frontend is not required to first evaluate - address and then perform address arithmetics itself. - - - This command attempts to read all accessible memory regions in the -specified range. First, all regions marked as unreadable in the memory -map (if one is defined) will be skipped. *Note Memory Region -Attributes::. Second, GDB will attempt to read the remaining regions. -For each one, if reading full region results in an errors, GDB will try -to read a subset of the region. - - In general, every single byte in the region may be readable or not, -and the only way to read every readable byte is to try a read at every -address, which is not practical. Therefore, GDB will attempt to read -all accessible bytes at either beginning or the end of the region, -using a binary division scheme. This heuristic works well for reading -accross a memory map boundary. Note that if a region has a readable -range that is neither at the beginning or the end, GDB will not read it. - - The result record (*note GDB/MI Result Records::) that is output of -the command includes a field named `memory' whose content is a list of -tuples. Each tuple represent a successfully read memory block and has -the following fields: - -`begin' - The start address of the memory block, as hexadecimal literal. - -`end' - The end address of the memory block, as hexadecimal literal. - -`offset' - The offset of the memory block, as hexadecimal literal, relative to - the start address passed to `-data-read-memory-bytes'. - -`contents' - The contents of the memory block, in hex. - - -GDB Command -........... - -The corresponding GDB command is `x'. - -Example -....... - - (gdb) - -data-read-memory-bytes &a 10 - ^done,memory=[{begin="0xbffff154",offset="0x00000000", - end="0xbffff15e", - contents="01000000020000000300"}] - (gdb) - -The `-data-write-memory-bytes' Command --------------------------------------- - -Synopsis -........ - - -data-write-memory-bytes ADDRESS CONTENTS - -where: - -`ADDRESS' - An expression specifying the address of the first memory word to be - read. Complex expressions containing embedded white space should - be quoted using the C convention. - -`CONTENTS' - The hex-encoded bytes to write. - - -GDB Command -........... - -There's no corresponding GDB command. - -Example -....... - - (gdb) - -data-write-memory-bytes &a "aabbccdd" - ^done - (gdb) - - -File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI - -27.15 GDB/MI Tracepoint Commands -================================ - -The commands defined in this section implement MI support for -tracepoints. For detailed introduction, see *note Tracepoints::. - -The `-trace-find' Command -------------------------- - -Synopsis -........ - - -trace-find MODE [PARAMETERS...] - - Find a trace frame using criteria defined by MODE and PARAMETERS. -The following table lists permissible modes and their parameters. For -details of operation, see *note tfind::. - -`none' - No parameters are required. Stops examining trace frames. - -`frame-number' - An integer is required as parameter. Selects tracepoint frame with - that index. - -`tracepoint-number' - An integer is required as parameter. Finds next trace frame that - corresponds to tracepoint with the specified number. - -`pc' - An address is required as parameter. Finds next trace frame that - corresponds to any tracepoint at the specified address. - -`pc-inside-range' - Two addresses are required as parameters. Finds next trace frame - that corresponds to a tracepoint at an address inside the - specified range. Both bounds are considered to be inside the - range. - -`pc-outside-range' - Two addresses are required as parameters. Finds next trace frame - that corresponds to a tracepoint at an address outside the - specified range. Both bounds are considered to be inside the - range. - -`line' - Line specification is required as parameter. *Note Specify - Location::. Finds next trace frame that corresponds to a - tracepoint at the specified location. - - - If `none' was passed as MODE, the response does not have fields. -Otherwise, the response may have the following fields: - -`found' - This field has either `0' or `1' as the value, depending on - whether a matching tracepoint was found. - -`traceframe' - The index of the found traceframe. This field is present iff the - `found' field has value of `1'. - -`tracepoint' - The index of the found tracepoint. This field is present iff the - `found' field has value of `1'. - -`frame' - The information about the frame corresponding to the found trace - frame. This field is present only if a trace frame was found. - *Note GDB/MI Frame Information::, for description of this field. - - -GDB Command -........... - -The corresponding GDB command is `tfind'. - --trace-define-variable ----------------------- - -Synopsis -........ - - -trace-define-variable NAME [ VALUE ] - - Create trace variable NAME if it does not exist. If VALUE is -specified, sets the initial value of the specified trace variable to -that value. Note that the NAME should start with the `$' character. - -GDB Command -........... - -The corresponding GDB command is `tvariable'. - --trace-list-variables ---------------------- - -Synopsis -........ - - -trace-list-variables - - Return a table of all defined trace variables. Each element of the -table has the following fields: - -`name' - The name of the trace variable. This field is always present. - -`initial' - The initial value. This is a 64-bit signed integer. This field - is always present. - -`current' - The value the trace variable has at the moment. This is a 64-bit - signed integer. This field is absent iff current value is not - defined, for example if the trace was never run, or is presently - running. - - -GDB Command -........... - -The corresponding GDB command is `tvariables'. - -Example -....... - - (gdb) - -trace-list-variables - ^done,trace-variables={nr_rows="1",nr_cols="3", - hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, - {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, - {width="11",alignment="-1",col_name="current",colhdr="Current"}], - body=[variable={name="$trace_timestamp",initial="0"} - variable={name="$foo",initial="10",current="15"}]} - (gdb) - --trace-save ------------ - -Synopsis -........ - - -trace-save [-r ] FILENAME - - Saves the collected trace data to FILENAME. Without the `-r' -option, the data is downloaded from the target and saved in a local -file. With the `-r' option the target is asked to perform the save. - -GDB Command -........... - -The corresponding GDB command is `tsave'. - --trace-start ------------- - -Synopsis -........ - - -trace-start - - Starts a tracing experiments. The result of this command does not -have any fields. - -GDB Command -........... - -The corresponding GDB command is `tstart'. - --trace-status -------------- - -Synopsis -........ - - -trace-status - - Obtains the status of a tracing experiment. The result may include -the following fields: - -`supported' - May have a value of either `0', when no tracing operations are - supported, `1', when all tracing operations are supported, or - `file' when examining trace file. In the latter case, examining - of trace frame is possible but new tracing experiement cannot be - started. This field is always present. - -`running' - May have a value of either `0' or `1' depending on whether tracing - experiement is in progress on target. This field is present if - `supported' field is not `0'. - -`stop-reason' - Report the reason why the tracing was stopped last time. This - field may be absent iff tracing was never stopped on target yet. - The value of `request' means the tracing was stopped as result of - the `-trace-stop' command. The value of `overflow' means the - tracing buffer is full. The value of `disconnection' means - tracing was automatically stopped when GDB has disconnected. The - value of `passcount' means tracing was stopped when a tracepoint - was passed a maximal number of times for that tracepoint. This - field is present if `supported' field is not `0'. - -`stopping-tracepoint' - The number of tracepoint whose passcount as exceeded. This field - is present iff the `stop-reason' field has the value of - `passcount'. - -`frames' -`frames-created' - The `frames' field is a count of the total number of trace frames - in the trace buffer, while `frames-created' is the total created - during the run, including ones that were discarded, such as when a - circular trace buffer filled up. Both fields are optional. - -`buffer-size' -`buffer-free' - These fields tell the current size of the tracing buffer and the - remaining space. These fields are optional. - -`circular' - The value of the circular trace buffer flag. `1' means that the - trace buffer is circular and old trace frames will be discarded if - necessary to make room, `0' means that the trace buffer is linear - and may fill up. - -`disconnected' - The value of the disconnected tracing flag. `1' means that - tracing will continue after GDB disconnects, `0' means that the - trace run will stop. - - -GDB Command -........... - -The corresponding GDB command is `tstatus'. - --trace-stop ------------ - -Synopsis -........ - - -trace-stop - - Stops a tracing experiment. The result of this command has the same -fields as `-trace-status', except that the `supported' and `running' -fields are not output. - -GDB Command -........... - -The corresponding GDB command is `tstop'. - - -File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI - -27.16 GDB/MI Symbol Query Commands -================================== - -The `-symbol-list-lines' Command --------------------------------- - -Synopsis -........ - - -symbol-list-lines FILENAME - - Print the list of lines that contain code and their associated -program addresses for the given source filename. The entries are -sorted in ascending PC order. - -GDB Command -........... - -There is no corresponding GDB command. - -Example -....... - - (gdb) - -symbol-list-lines basics.c - ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] - (gdb) - - -File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI - -27.17 GDB/MI File Commands -========================== - -This section describes the GDB/MI commands to specify executable file -names and to read in and obtain symbol table information. - -The `-file-exec-and-symbols' Command ------------------------------------- - -Synopsis -........ - - -file-exec-and-symbols FILE - - Specify the executable file to be debugged. This file is the one -from which the symbol table is also read. If no file is specified, the -command clears the executable and symbol information. If breakpoints -are set when using this command with no arguments, GDB will produce -error messages. Otherwise, no output is produced, except a completion -notification. - -GDB Command -........... - -The corresponding GDB command is `file'. - -Example -....... - - (gdb) - -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx - ^done - (gdb) - -The `-file-exec-file' Command ------------------------------ - -Synopsis -........ - - -file-exec-file FILE - - Specify the executable file to be debugged. Unlike -`-file-exec-and-symbols', the symbol table is _not_ read from this -file. If used without argument, GDB clears the information about the -executable file. No output is produced, except a completion -notification. - -GDB Command -........... - -The corresponding GDB command is `exec-file'. - -Example -....... - - (gdb) - -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx - ^done - (gdb) - -The `-file-list-exec-source-file' Command ------------------------------------------ - -Synopsis -........ - - -file-list-exec-source-file - - List the line number, the current source file, and the absolute path -to the current source file for the current executable. The macro -information field has a value of `1' or `0' depending on whether or not -the file includes preprocessor macro information. - -GDB Command -........... - -The GDB equivalent is `info source' - -Example -....... - - (gdb) - 123-file-list-exec-source-file - 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" - (gdb) - -The `-file-list-exec-source-files' Command ------------------------------------------- - -Synopsis -........ - - -file-list-exec-source-files - - List the source files for the current executable. - - It will always output the filename, but only when GDB can find the -absolute file name of a source file, will it output the fullname. - -GDB Command -........... - -The GDB equivalent is `info sources'. `gdbtk' has an analogous command -`gdb_listfiles'. - -Example -....... - - (gdb) - -file-list-exec-source-files - ^done,files=[ - {file=foo.c,fullname=/home/foo.c}, - {file=/home/bar.c,fullname=/home/bar.c}, - {file=gdb_could_not_find_fullpath.c}] - (gdb) - -The `-file-symbol-file' Command -------------------------------- - -Synopsis -........ - - -file-symbol-file FILE - - Read symbol table info from the specified FILE argument. When used -without arguments, clears GDB's symbol table info. No output is -produced, except for a completion notification. - -GDB Command -........... - -The corresponding GDB command is `symbol-file'. - -Example -....... - - (gdb) - -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx - ^done - (gdb) - - -File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI - -27.18 GDB/MI Target Manipulation Commands -========================================= - -The `-target-attach' Command ----------------------------- - -Synopsis -........ - - -target-attach PID | GID | FILE - - Attach to a process PID or a file FILE outside of GDB, or a thread -group GID. If attaching to a thread group, the id previously returned -by `-list-thread-groups --available' must be used. - -GDB Command -........... - -The corresponding GDB command is `attach'. - -Example -....... - - (gdb) - -target-attach 34 - =thread-created,id="1" - *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} - ^done - (gdb) - -The `-target-detach' Command ----------------------------- - -Synopsis -........ - - -target-detach [ PID | GID ] - - Detach from the remote target which normally resumes its execution. -If either PID or GID is specified, detaches from either the specified -process, or specified thread group. There's no output. - -GDB Command -........... - -The corresponding GDB command is `detach'. - -Example -....... - - (gdb) - -target-detach - ^done - (gdb) - -The `-target-disconnect' Command --------------------------------- - -Synopsis -........ - - -target-disconnect - - Disconnect from the remote target. There's no output and the target -is generally not resumed. - -GDB Command -........... - -The corresponding GDB command is `disconnect'. - -Example -....... - - (gdb) - -target-disconnect - ^done - (gdb) - -The `-target-download' Command ------------------------------- - -Synopsis -........ - - -target-download - - Loads the executable onto the remote target. It prints out an -update message every half second, which includes the fields: - -`section' - The name of the section. - -`section-sent' - The size of what has been sent so far for that section. - -`section-size' - The size of the section. - -`total-sent' - The total size of what was sent so far (the current and the - previous sections). - -`total-size' - The size of the overall executable to download. - -Each message is sent as status record (*note GDB/MI Output Syntax: -GDB/MI Output Syntax.). - - In addition, it prints the name and size of the sections, as they are -downloaded. These messages include the following fields: - -`section' - The name of the section. - -`section-size' - The size of the section. - -`total-size' - The size of the overall executable to download. - -At the end, a summary is printed. - -GDB Command -........... - -The corresponding GDB command is `load'. - -Example -....... - -Note: each status message appears on a single line. Here the messages -have been broken down so that they can fit onto a page. - - (gdb) - -target-download - +download,{section=".text",section-size="6668",total-size="9880"} - +download,{section=".text",section-sent="512",section-size="6668", - total-sent="512",total-size="9880"} - +download,{section=".text",section-sent="1024",section-size="6668", - total-sent="1024",total-size="9880"} - +download,{section=".text",section-sent="1536",section-size="6668", - total-sent="1536",total-size="9880"} - +download,{section=".text",section-sent="2048",section-size="6668", - total-sent="2048",total-size="9880"} - +download,{section=".text",section-sent="2560",section-size="6668", - total-sent="2560",total-size="9880"} - +download,{section=".text",section-sent="3072",section-size="6668", - total-sent="3072",total-size="9880"} - +download,{section=".text",section-sent="3584",section-size="6668", - total-sent="3584",total-size="9880"} - +download,{section=".text",section-sent="4096",section-size="6668", - total-sent="4096",total-size="9880"} - +download,{section=".text",section-sent="4608",section-size="6668", - total-sent="4608",total-size="9880"} - +download,{section=".text",section-sent="5120",section-size="6668", - total-sent="5120",total-size="9880"} - +download,{section=".text",section-sent="5632",section-size="6668", - total-sent="5632",total-size="9880"} - +download,{section=".text",section-sent="6144",section-size="6668", - total-sent="6144",total-size="9880"} - +download,{section=".text",section-sent="6656",section-size="6668", - total-sent="6656",total-size="9880"} - +download,{section=".init",section-size="28",total-size="9880"} - +download,{section=".fini",section-size="28",total-size="9880"} - +download,{section=".data",section-size="3156",total-size="9880"} - +download,{section=".data",section-sent="512",section-size="3156", - total-sent="7236",total-size="9880"} - +download,{section=".data",section-sent="1024",section-size="3156", - total-sent="7748",total-size="9880"} - +download,{section=".data",section-sent="1536",section-size="3156", - total-sent="8260",total-size="9880"} - +download,{section=".data",section-sent="2048",section-size="3156", - total-sent="8772",total-size="9880"} - +download,{section=".data",section-sent="2560",section-size="3156", - total-sent="9284",total-size="9880"} - +download,{section=".data",section-sent="3072",section-size="3156", - total-sent="9796",total-size="9880"} - ^done,address="0x10004",load-size="9880",transfer-rate="6586", - write-rate="429" - (gdb) - -GDB Command -........... - -No equivalent. - -Example -....... - -N.A. - -The `-target-select' Command ----------------------------- - -Synopsis -........ - - -target-select TYPE PARAMETERS ... - - Connect GDB to the remote target. This command takes two args: - -`TYPE' - The type of target, for instance `remote', etc. - -`PARAMETERS' - Device names, host names and the like. *Note Commands for - Managing Targets: Target Commands, for more details. - - The output is a connection notification, followed by the address at -which the target program is, in the following form: - - ^connected,addr="ADDRESS",func="FUNCTION NAME", - args=[ARG LIST] - -GDB Command -........... - -The corresponding GDB command is `target'. - -Example -....... - - (gdb) - -target-select remote /dev/ttya - ^connected,addr="0xfe00a300",func="??",args=[] - (gdb) - - -File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI - -27.19 GDB/MI File Transfer Commands -=================================== - -The `-target-file-put' Command ------------------------------- - -Synopsis -........ - - -target-file-put HOSTFILE TARGETFILE - - Copy file HOSTFILE from the host system (the machine running GDB) to -TARGETFILE on the target system. - -GDB Command -........... - -The corresponding GDB command is `remote put'. - -Example -....... - - (gdb) - -target-file-put localfile remotefile - ^done - (gdb) - -The `-target-file-get' Command ------------------------------- - -Synopsis -........ - - -target-file-get TARGETFILE HOSTFILE - - Copy file TARGETFILE from the target system to HOSTFILE on the host -system. - -GDB Command -........... - -The corresponding GDB command is `remote get'. - -Example -....... - - (gdb) - -target-file-get remotefile localfile - ^done - (gdb) - -The `-target-file-delete' Command ---------------------------------- - -Synopsis -........ - - -target-file-delete TARGETFILE - - Delete TARGETFILE from the target system. - -GDB Command -........... - -The corresponding GDB command is `remote delete'. - -Example -....... - - (gdb) - -target-file-delete remotefile - ^done - (gdb) - - -File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI - -27.20 Miscellaneous GDB/MI Commands -=================================== - -The `-gdb-exit' Command ------------------------ - -Synopsis -........ - - -gdb-exit - - Exit GDB immediately. - -GDB Command -........... - -Approximately corresponds to `quit'. - -Example -....... - - (gdb) - -gdb-exit - ^exit - -The `-gdb-set' Command ----------------------- - -Synopsis -........ - - -gdb-set - - Set an internal GDB variable. - -GDB Command -........... - -The corresponding GDB command is `set'. - -Example -....... - - (gdb) - -gdb-set $foo=3 - ^done - (gdb) - -The `-gdb-show' Command ------------------------ - -Synopsis -........ - - -gdb-show - - Show the current value of a GDB variable. - -GDB Command -........... - -The corresponding GDB command is `show'. - -Example -....... - - (gdb) - -gdb-show annotate - ^done,value="0" - (gdb) - -The `-gdb-version' Command --------------------------- - -Synopsis -........ - - -gdb-version - - Show version information for GDB. Used mostly in testing. - -GDB Command -........... - -The GDB equivalent is `show version'. GDB by default shows this -information when you start an interactive session. - -Example -....... - - (gdb) - -gdb-version - ~GNU gdb 5.2.1 - ~Copyright 2000 Free Software Foundation, Inc. - ~GDB is free software, covered by the GNU General Public License, and - ~you are welcome to change it and/or 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. - ~This GDB was configured as - "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". - ^done - (gdb) - -The `-list-features' Command ----------------------------- - -Returns a list of particular features of the MI protocol that this -version of gdb implements. A feature can be a command, or a new field -in an output of some command, or even an important bugfix. While a -frontend can sometimes detect presence of a feature at runtime, it is -easier to perform detection at debugger startup. - - The command returns a list of strings, with each string naming an -available feature. Each returned string is just a name, it does not -have any internal structure. The list of possible feature names is -given below. - - Example output: - - (gdb) -list-features - ^done,result=["feature1","feature2"] - - The current list of features is: - -`frozen-varobjs' - Indicates presence of the `-var-set-frozen' command, as well as - possible presense of the `frozen' field in the output of - `-varobj-create'. - -`pending-breakpoints' - Indicates presence of the `-f' option to the `-break-insert' - command. - -`python' - Indicates presence of Python scripting support, Python-based - pretty-printing commands, and possible presence of the - `display_hint' field in the output of `-var-list-children' - -`thread-info' - Indicates presence of the `-thread-info' command. - -`data-read-memory-bytes' - Indicates presense of the `-data-read-memory-bytes' and the - `-data-write-memory-bytes' commands. - - -The `-list-target-features' Command ------------------------------------ - -Returns a list of particular features that are supported by the target. -Those features affect the permitted MI commands, but unlike the -features reported by the `-list-features' command, the features depend -on which target GDB is using at the moment. Whenever a target can -change, due to commands such as `-target-select', `-target-attach' or -`-exec-run', the list of target features may change, and the frontend -should obtain it again. Example output: - - (gdb) -list-features - ^done,result=["async"] - - The current list of features is: - -`async' - Indicates that the target is capable of asynchronous command - execution, which means that GDB will accept further commands while - the target is running. - -`reverse' - Indicates that the target is capable of reverse execution. *Note - Reverse Execution::, for more information. - - -The `-list-thread-groups' Command ---------------------------------- - -Synopsis --------- - - -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] - - Lists thread groups (*note Thread groups::). When a single thread -group is passed as the argument, lists the children of that group. -When several thread group are passed, lists information about those -thread groups. Without any parameters, lists information about all -top-level thread groups. - - Normally, thread groups that are being debugged are reported. With -the `--available' option, GDB reports thread groups available on the -target. - - The output of this command may have either a `threads' result or a -`groups' result. The `thread' result has a list of tuples as value, -with each tuple describing a thread (*note GDB/MI Thread -Information::). The `groups' result has a list of tuples as value, -each tuple describing a thread group. If top-level groups are -requested (that is, no parameter is passed), or when several groups are -passed, the output always has a `groups' result. The format of the -`group' result is described below. - - To reduce the number of roundtrips it's possible to list thread -groups together with their children, by passing the `--recurse' option -and the recursion depth. Presently, only recursion depth of 1 is -permitted. If this option is present, then every reported thread group -will also include its children, either as `group' or `threads' field. - - In general, any combination of option and parameters is permitted, -with the following caveats: - - * When a single thread group is passed, the output will typically be - the `threads' result. Because threads may not contain anything, - the `recurse' option will be ignored. - - * When the `--available' option is passed, limited information may - be available. In particular, the list of threads of a process - might be inaccessible. Further, specifying specific thread groups - might not give any performance advantage over listing all thread - groups. The frontend should assume that `-list-thread-groups - --available' is always an expensive operation and cache the - results. - - - The `groups' result is a list of tuples, where each tuple may have -the following fields: - -`id' - Identifier of the thread group. This field is always present. - The identifier is an opaque string; frontends should not try to - convert it to an integer, even though it might look like one. - -`type' - The type of the thread group. At present, only `process' is a - valid type. - -`pid' - The target-specific process identifier. This field is only present - for thread groups of type `process' and only if the process exists. - -`num_children' - The number of children this thread group has. This field may be - absent for an available thread group. - -`threads' - This field has a list of tuples as value, each tuple describing a - thread. It may be present if the `--recurse' option is specified, - and it's actually possible to obtain the threads. - -`cores' - This field is a list of integers, each identifying a core that one - thread of the group is running on. This field may be absent if - such information is not available. - -`executable' - The name of the executable file that corresponds to this thread - group. The field is only present for thread groups of type - `process', and only if there is a corresponding executable file. - - -Example -------- - - gdb - -list-thread-groups - ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] - -list-thread-groups 17 - ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", - frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, - {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", - frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], - file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]] - -list-thread-groups --available - ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] - -list-thread-groups --available --recurse 1 - ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], - threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, - {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] - -list-thread-groups --available --recurse 1 17 18 - ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], - threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, - {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] - -The `-add-inferior' Command ---------------------------- - -Synopsis --------- - - -add-inferior - - Creates a new inferior (*note Inferiors and Programs::). The created -inferior is not associated with any executable. Such association may -be established with the `-file-exec-and-symbols' command (*note GDB/MI -File Commands::). The command response has a single field, -`thread-group', whose value is the identifier of the thread group -corresponding to the new inferior. - -Example -------- - - gdb - -add-inferior - ^done,thread-group="i3" - -The `-interpreter-exec' Command -------------------------------- - -Synopsis --------- - - -interpreter-exec INTERPRETER COMMAND -Execute the specified COMMAND in the given INTERPRETER. - -GDB Command ------------ - -The corresponding GDB command is `interpreter-exec'. - -Example -------- - - (gdb) - -interpreter-exec console "break main" - &"During symbol reading, couldn't parse type; debugger out of date?.\n" - &"During symbol reading, bad structure-type format.\n" - ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" - ^done - (gdb) - -The `-inferior-tty-set' Command -------------------------------- - -Synopsis --------- - - -inferior-tty-set /dev/pts/1 - - Set terminal for future runs of the program being debugged. - -GDB Command ------------ - -The corresponding GDB command is `set inferior-tty' /dev/pts/1. - -Example -------- - - (gdb) - -inferior-tty-set /dev/pts/1 - ^done - (gdb) - -The `-inferior-tty-show' Command --------------------------------- - -Synopsis --------- - - -inferior-tty-show - - Show terminal for future runs of program being debugged. - -GDB Command ------------ - -The corresponding GDB command is `show inferior-tty'. - -Example -------- - - (gdb) - -inferior-tty-set /dev/pts/1 - ^done - (gdb) - -inferior-tty-show - ^done,inferior_tty_terminal="/dev/pts/1" - (gdb) - -The `-enable-timings' Command ------------------------------ - -Synopsis --------- - - -enable-timings [yes | no] - - Toggle the printing of the wallclock, user and system times for an MI -command as a field in its output. This command is to help frontend -developers optimize the performance of their code. No argument is -equivalent to `yes'. - -GDB Command ------------ - -No equivalent. - -Example -------- - - (gdb) - -enable-timings - ^done - (gdb) - -break-insert main - ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", - addr="0x080484ed",func="main",file="myprog.c", - fullname="/home/nickrob/myprog.c",line="73",times="0"}, - time={wallclock="0.05185",user="0.00800",system="0.00000"} - (gdb) - -enable-timings no - ^done - (gdb) - -exec-run - ^running - (gdb) - *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", - frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, - {name="argv",value="0xbfb60364"}],file="myprog.c", - fullname="/home/nickrob/myprog.c",line="73"} - (gdb) - - -File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top - -28 GDB Annotations -****************** - -This chapter describes annotations in GDB. Annotations were designed -to interface GDB to graphical user interfaces or other similar programs -which want to interact with GDB at a relatively high level. - - The annotation mechanism has largely been superseded by GDB/MI -(*note GDB/MI::). - -* Menu: - -* Annotations Overview:: What annotations are; the general syntax. -* Server Prefix:: Issuing a command without affecting user state. -* Prompting:: Annotations marking GDB's need for input. -* Errors:: Annotations for error messages. -* Invalidation:: Some annotations describe things now invalid. -* Annotations for Running:: - Whether the program is running, how it stopped, etc. -* Source Annotations:: Annotations describing source code. - - -File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations - -28.1 What is an Annotation? -=========================== - -Annotations start with a newline character, two `control-z' characters, -and the name of the annotation. If there is no additional information -associated with this annotation, the name of the annotation is followed -immediately by a newline. If there is additional information, the name -of the annotation is followed by a space, the additional information, -and a newline. The additional information cannot contain newline -characters. - - Any output not beginning with a newline and two `control-z' -characters denotes literal output from GDB. Currently there is no need -for GDB to output a newline followed by two `control-z' characters, but -if there was such a need, the annotations could be extended with an -`escape' annotation which means those three characters as output. - - The annotation LEVEL, which is specified using the `--annotate' -command line option (*note Mode Options::), controls how much -information GDB prints together with its prompt, values of expressions, -source lines, and other types of output. Level 0 is for no -annotations, 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 annotations have been made obsolete (*note -Limitations of the Annotation Interface: (annotate)Limitations.). - -`set annotate LEVEL' - The GDB command `set annotate' sets the level of annotations to - the specified LEVEL. - -`show annotate' - Show the current annotation level. - - This chapter describes level 3 annotations. - - A simple example of starting up GDB with annotations is: - - $ gdb --annotate=3 - GNU gdb 6.0 - Copyright 2003 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, - and you are welcome to change it and/or 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. - This GDB was configured as "i386-pc-linux-gnu" - - ^Z^Zpre-prompt - (gdb) - ^Z^Zprompt - quit - - ^Z^Zpost-prompt - $ - - Here `quit' is input to GDB; the rest is output from GDB. The three -lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are -annotations; the rest is output from GDB. - - -File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations - -28.2 The Server Prefix -====================== - -If you prefix a command with `server ' then it will not affect the -command history, nor will it affect GDB's notion of which command to -repeat if <RET> is pressed on a line by itself. This means that -commands can be run behind a user's back by a front-end in a -transparent manner. - - The `server ' prefix does not affect the recording of values into -the value history; to print a value without recording it into the value -history, use the `output' command instead of the `print' command. - - Using this prefix also disables confirmation requests (*note -confirmation requests::). - - -File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations - -28.3 Annotation for GDB Input -============================= - -When GDB prompts for input, it annotates this fact so it is possible to -know when to send output, when the output from a given command is over, -etc. - - Different kinds of input each have a different "input type". Each -input type has three annotations: a `pre-' annotation, which denotes -the beginning of any prompt which is being output, a plain annotation, -which denotes the end of the prompt, and then a `post-' annotation -which denotes the end of any echo which may (or may not) be associated -with the input. For example, the `prompt' input type features the -following annotations: - - ^Z^Zpre-prompt - ^Z^Zprompt - ^Z^Zpost-prompt - - The input types are - -`prompt' - When GDB is prompting for a command (the main GDB prompt). - -`commands' - When GDB prompts for a set of commands, like in the `commands' - command. The annotations are repeated for each command which is - input. - -`overload-choice' - When GDB wants the user to select between various overloaded - functions. - -`query' - When GDB wants the user to confirm a potentially dangerous - operation. - -`prompt-for-continue' - When GDB is asking the user to press return to continue. Note: - Don't expect this to work well; instead use `set height 0' to - disable prompting. This is because the counting of lines is buggy - in the presence of annotations. - - -File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations - -28.4 Errors -=========== - - ^Z^Zquit - - This annotation occurs right before GDB responds to an interrupt. - - ^Z^Zerror - - This annotation occurs right before GDB responds to an error. - - Quit and error annotations indicate that any annotations which GDB -was in the middle of may end abruptly. For example, if a -`value-history-begin' annotation is followed by a `error', one cannot -expect to receive the matching `value-history-end'. One cannot expect -not to receive it either, however; an error annotation does not -necessarily mean that GDB is immediately returning all the way to the -top level. - - A quit or error annotation may be preceded by - - ^Z^Zerror-begin - - Any output between that and the quit or error annotation is the error -message. - - Warning messages are not yet annotated. - - -File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations - -28.5 Invalidation Notices -========================= - -The following annotations say that certain pieces of state may have -changed. - -`^Z^Zframes-invalid' - The frames (for example, output from the `backtrace' command) may - have changed. - -`^Z^Zbreakpoints-invalid' - The breakpoints may have changed. For example, the user just - added or deleted a breakpoint. - - -File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations - -28.6 Running the Program -======================== - -When the program starts executing due to a GDB command such as `step' -or `continue', - - ^Z^Zstarting - - is output. When the program stops, - - ^Z^Zstopped - - is output. Before the `stopped' annotation, a variety of -annotations describe how the program stopped. - -`^Z^Zexited EXIT-STATUS' - The program exited, and EXIT-STATUS is the exit status (zero for - successful exit, otherwise nonzero). - -`^Z^Zsignalled' - The program exited with a signal. After the `^Z^Zsignalled', the - annotation continues: - - INTRO-TEXT - ^Z^Zsignal-name - NAME - ^Z^Zsignal-name-end - MIDDLE-TEXT - ^Z^Zsignal-string - STRING - ^Z^Zsignal-string-end - END-TEXT - - where NAME is the name of the signal, such as `SIGILL' or - `SIGSEGV', and STRING is the explanation of the signal, such as - `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, - MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no - particular format. - -`^Z^Zsignal' - The syntax of this annotation is just like `signalled', but GDB is - just saying that the program received the signal, not that it was - terminated with it. - -`^Z^Zbreakpoint NUMBER' - The program hit breakpoint number NUMBER. - -`^Z^Zwatchpoint NUMBER' - The program hit watchpoint number NUMBER. - - -File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations - -28.7 Displaying Source -====================== - -The following annotation is used instead of displaying source code: - - ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR - - where FILENAME is an absolute file name indicating which source -file, LINE is the line number within that file (where 1 is the first -line in the file), CHARACTER is the character position within the file -(where 0 is the first character in the file) (for most debug formats -this will necessarily point to the beginning of a line), MIDDLE is -`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at -the beginning of the line, and ADDR is the address in the target -program associated with the source which is being displayed. ADDR is -in the form `0x' followed by one or more lowercase hex digits (note -that this does not depend on the language). - - -File: gdb.info, Node: JIT Interface, Next: GDB Bugs, Prev: Annotations, Up: Top - -29 JIT Compilation Interface -**************************** - -This chapter documents GDB's "just-in-time" (JIT) compilation -interface. A JIT compiler is a program or library that generates native -executable code at runtime and executes it, usually in order to achieve -good performance while maintaining platform independence. - - Programs that use JIT compilation are normally difficult to debug -because portions of their code are generated at runtime, instead of -being loaded from object files, which is where GDB normally finds the -program's symbols and debug information. In order to debug programs -that use JIT compilation, GDB has an interface that allows the program -to register in-memory symbol files with GDB at runtime. - - If you are using GDB to debug a program that uses this interface, -then it should work transparently so long as you have not stripped the -binary. If you are developing a JIT compiler, then the interface is -documented in the rest of this chapter. At this time, the only known -client of this interface is the LLVM JIT. - - Broadly speaking, the JIT interface mirrors the dynamic loader -interface. The JIT compiler communicates with GDB by writing data into -a global variable and calling a fuction at a well-known symbol. When -GDB attaches, it reads a linked list of symbol files from the global -variable to find existing code, and puts a breakpoint in the function -so that it can find out about additional code. - -* Menu: - -* Declarations:: Relevant C struct declarations -* Registering Code:: Steps to register code -* Unregistering Code:: Steps to unregister code - - -File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface - -29.1 JIT Declarations -===================== - -These are the relevant struct declarations that a C program should -include to implement the interface: - - typedef enum - { - JIT_NOACTION = 0, - JIT_REGISTER_FN, - JIT_UNREGISTER_FN - } jit_actions_t; - - struct jit_code_entry - { - struct jit_code_entry *next_entry; - struct jit_code_entry *prev_entry; - const char *symfile_addr; - uint64_t symfile_size; - }; - - struct jit_descriptor - { - uint32_t version; - /* This type should be jit_actions_t, but we use uint32_t - to be explicit about the bitwidth. */ - uint32_t action_flag; - struct jit_code_entry *relevant_entry; - struct jit_code_entry *first_entry; - }; - - /* GDB puts a breakpoint in this function. */ - void __attribute__((noinline)) __jit_debug_register_code() { }; - - /* Make sure to specify the version statically, because the - debugger may check the version before we can set it. */ - struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; - - If the JIT is multi-threaded, then it is important that the JIT -synchronize any modifications to this global data properly, which can -easily be done by putting a global mutex around modifications to these -structures. - - -File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface - -29.2 Registering Code -===================== - -To register code with GDB, the JIT should follow this protocol: - - * Generate an object file in memory with symbols and other desired - debug information. The file must include the virtual addresses of - the sections. - - * Create a code entry for the file, which gives the start and size - of the symbol file. - - * Add it to the linked list in the JIT descriptor. - - * Point the relevant_entry field of the descriptor at the entry. - - * Set `action_flag' to `JIT_REGISTER' and call - `__jit_debug_register_code'. - - When GDB is attached and the breakpoint fires, GDB uses the -`relevant_entry' pointer so it doesn't have to walk the list looking for -new code. However, the linked list must still be maintained in order -to allow GDB to attach to a running process and still find the symbol -files. - - -File: gdb.info, Node: Unregistering Code, Prev: Registering Code, Up: JIT Interface - -29.3 Unregistering Code -======================= - -If code is freed, then the JIT should use the following protocol: - - * Remove the code entry corresponding to the code from the linked - list. - - * Point the `relevant_entry' field of the descriptor at the code - entry. - - * Set `action_flag' to `JIT_UNREGISTER' and call - `__jit_debug_register_code'. - - If the JIT frees or recompiles code without unregistering it, then -GDB and the JIT will leak the memory used for the associated symbol -files. - - -File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interface, Up: Top - -30 Reporting Bugs in GDB -************************ - -Your bug reports play an essential role in making GDB reliable. - - Reporting a bug may help you by bringing a solution to your problem, -or it may not. But in any case the principal function of a bug report -is to help the entire community by making the next version of GDB work -better. Bug reports are your contribution to the maintenance of GDB. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -* Menu: - -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs - - -File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs - -30.1 Have You Found a Bug? -========================== - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the debugger gets a fatal signal, for any input whatever, that - is a GDB bug. Reliable debuggers never crash. - - * If GDB produces an error message for valid input, that is a bug. - (Note that if you're cross debugging, the problem may also be - somewhere in the connection to the target.) - - * If GDB does not produce an error message for invalid input, that - is a bug. However, you should note that your idea of "invalid - input" might be our idea of "an extension" or "support for - traditional practice". - - * If you are an experienced user of debugging tools, your suggestions - for improvement of GDB are welcome in any case. - - -File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs - -30.2 How to Report Bugs -======================= - -A number of companies and individuals offer support for GNU products. -If you obtained GDB from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file `etc/SERVICE' in the GNU Emacs distribution. - - In any event, we also recommend that you submit bug reports for GDB. -The preferred method is to submit them directly using GDB's Bugs web -page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the -e-mail gateway <bug-gdb@gnu.org> can be used. - - *Do not send bug reports to `info-gdb', or to `help-gdb', or to any -newsgroups.* Most users of GDB do not want to receive bug reports. -Those that do have arranged to receive `bug-gdb'. - - The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which -serves as a repeater. The mailing list and the newsgroup carry exactly -the same messages. Often people think of posting bug reports to the -newsgroup instead of mailing them. This appears to work, but it has one -problem which can be crucial: a newsgroup posting often lacks a mail -path back to the sender. Thus, if we need to ask for more information, -we may be unable to reach you. For this reason, it is better to send -bug reports to the mailing list. - - The fundamental principle of reporting bugs usefully is this: -*report all the facts*. If you are not sure whether to state a fact or -leave it out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of the variable you use in an example does not -matter. Well, probably it does not, but one cannot be sure. Perhaps -the bug is a stray memory reference which happens to fetch from the -location where that name is stored in memory; perhaps, if the name were -different, the contents of that location would fool the debugger into -doing the right thing despite the bug. Play it safe and give a -specific, complete example. That is the easiest thing for you to do, -and the most helpful. - - Keep in mind that the purpose of a bug report is to enable us to fix -the bug. It may be that the bug has been reported previously, but -neither you nor we can know that unless your bug report is complete and -self-contained. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" Those bug reports are useless, and we urge everyone to _refuse -to respond to them_ except to chide the sender to report bugs properly. - - To enable us to fix the bug, you should include all these things: - - * The version of GDB. GDB announces it if you start with no - arguments; you can also print it at any time using `show version'. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of GDB. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile GDB--e.g. - "gcc-2.8.1". - - * What compiler (and its version) was used to compile the program - you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP - C Compiler". For GCC, you can say `gcc --version' to get this - information; for other compilers, see the documentation for those - compilers. - - * The command arguments you gave the compiler to compile your - example and observe the bug. For example, did you use `-O'? To - guarantee you will not omit something important, list them all. A - copy of the Makefile (or the output from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input script, and all necessary source files, that will - reproduce the bug. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that GDB gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - Even if the problem you experience is a fatal signal, you should - still say so explicitly. Suppose something strange is going on, - such as, your copy of GDB is out of synch, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - To collect all this information, you can use a session recording - program such as `script', which is available on many Unix systems. - Just run your GDB session inside `script' and then include the - `typescript' file with your bug report. - - Another way to record a GDB session is to run GDB inside Emacs and - then save the entire buffer to a file. - - * If you wish to suggest changes to the GDB source, send us context - diffs. If you even discuss something in the GDB source, refer to - it by context, not by line number. - - The line numbers in our development sources will not match those - in your sources. Your line numbers would convey no useful - information to us. - - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - Often people who encounter a bug spend a lot of time investigating - which changes to the input file will make the bug go away and which - changes will not affect it. - - This is often time consuming and not very useful, because the way - we will find the bug is by running a single example under the - debugger with breakpoints, not by pure deduction from a series of - examples. We recommend that you save your time for something else. - - Of course, if you can find a simpler example to report _instead_ - of the original one, that is a convenience for us. Errors in the - output will be easier to spot, running under the debugger will take - less time, and so on. - - However, simplification is not vital; if you do not want to do - this, report the bug anyway and send us the entire test case you - used. - - * A patch for the bug. - - A patch for the bug does help us if it is a good one. But do not - omit the necessary information, such as the test case, on the - assumption that a patch is all we need. We might see problems - with your patch and decide to fix the problem another way, or we - might not understand it at all. - - Sometimes with a program as complicated as GDB it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify - that the bug is fixed. - - And if we cannot understand what bug you are trying to fix, or why - your patch should be an improvement, we will not install it. A - test case will help us to understand. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - - -File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top - -31 Command Line Editing -*********************** - -This chapter describes the basic features of the GNU command line -editing interface. - -* Menu: - -* Introduction and Notation:: Notation used in this text. -* Readline Interaction:: The minimum set of commands for editing a line. -* Readline Init File:: Customizing Readline from a user's view. -* Bindable Readline Commands:: A description of most of the Readline commands - available for binding -* Readline vi Mode:: A short description of how to make Readline - behave like the vi editor. - - -File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing - -31.1 Introduction to Line Editing -================================= - -The following paragraphs describe the notation used to represent -keystrokes. - - The text `C-k' is read as `Control-K' and describes the character -produced when the <k> key is pressed while the Control key is depressed. - - The text `M-k' is read as `Meta-K' and describes the character -produced when the Meta key (if you have one) is depressed, and the <k> -key is pressed. The Meta key is labeled <ALT> on many keyboards. On -keyboards with two keys labeled <ALT> (usually to either side of the -space bar), the <ALT> on the left side is generally set to work as a -Meta key. The <ALT> key on the right may also be configured to work as -a Meta key or may be configured as some other modifier, such as a -Compose key for typing accented characters. - - If you do not have a Meta or <ALT> key, or another key working as a -Meta key, the identical keystroke can be generated by typing <ESC> -_first_, and then typing <k>. Either process is known as "metafying" -the <k> key. - - The text `M-C-k' is read as `Meta-Control-k' and describes the -character produced by "metafying" `C-k'. - - In addition, several keys have their own names. Specifically, -<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves -when seen in this text, or in an init file (*note Readline Init File::). -If your keyboard lacks a <LFD> key, typing <C-j> will produce the -desired character. The <RET> key may be labeled <Return> or <Enter> on -some keyboards. - - -File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing - -31.2 Readline Interaction -========================= - -Often during an interactive session you type in a long line of text, -only to notice that the first word on the line is misspelled. The -Readline library gives you a set of commands for manipulating the text -as you type it in, allowing you to just fix your typo, and not forcing -you to retype the majority of the line. Using these editing commands, -you move the cursor to the place that needs correction, and delete or -insert the text of the corrections. Then, when you are satisfied with -the line, you simply press <RET>. You do not have to be at the end of -the line to press <RET>; the entire line is accepted regardless of the -location of the cursor within the line. - -* Menu: - -* Readline Bare Essentials:: The least you need to know about Readline. -* Readline Movement Commands:: Moving about the input line. -* Readline Killing Commands:: How to delete text, and how to get it back! -* Readline Arguments:: Giving numeric arguments to commands. -* Searching:: Searching through previous lines. - - -File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction - -31.2.1 Readline Bare Essentials -------------------------------- - -In order to enter characters into the line, simply type them. The typed -character appears where the cursor was, and then the cursor moves one -space to the right. If you mistype a character, you can use your erase -character to back up and delete the mistyped character. - - Sometimes you may mistype a character, and not notice the error -until you have typed several other characters. In that case, you can -type `C-b' to move the cursor to the left, and then correct your -mistake. Afterwards, you can move the cursor to the right with `C-f'. - - When you add text in the middle of a line, you will notice that -characters to the right of the cursor are `pushed over' to make room -for the text that you have inserted. Likewise, when you delete text -behind the cursor, characters to the right of the cursor are `pulled -back' to fill in the blank space created by the removal of the text. A -list of the bare essentials for editing the text of an input line -follows. - -`C-b' - Move back one character. - -`C-f' - Move forward one character. - -<DEL> or <Backspace> - Delete the character to the left of the cursor. - -`C-d' - Delete the character underneath the cursor. - -Printing characters - Insert the character into the line at the cursor. - -`C-_' or `C-x C-u' - Undo the last editing command. You can undo all the way back to an - empty line. - -(Depending on your configuration, the <Backspace> key be set to delete -the character to the left of the cursor and the <DEL> key set to delete -the character underneath the cursor, like `C-d', rather than the -character to the left of the cursor.) - - -File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction - -31.2.2 Readline Movement Commands ---------------------------------- - -The above table describes the most basic keystrokes that you need in -order to do editing of the input line. For your convenience, many -other commands have been added in addition to `C-b', `C-f', `C-d', and -<DEL>. Here are some commands for moving more rapidly about the line. - -`C-a' - Move to the start of the line. - -`C-e' - Move to the end of the line. - -`M-f' - Move forward a word, where a word is composed of letters and - digits. - -`M-b' - Move backward a word. - -`C-l' - Clear the screen, reprinting the current line at the top. - - Notice how `C-f' moves forward a character, while `M-f' moves -forward a word. It is a loose convention that control keystrokes -operate on characters while meta keystrokes operate on words. - - -File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction - -31.2.3 Readline Killing Commands --------------------------------- - -"Killing" text means to delete the text from the line, but to save it -away for later use, usually by "yanking" (re-inserting) it back into -the line. (`Cut' and `paste' are more recent jargon for `kill' and -`yank'.) - - If the description for a command says that it `kills' text, then you -can be sure that you can get the text back in a different (or the same) -place later. - - When you use a kill command, the text is saved in a "kill-ring". -Any number of consecutive kills save all of the killed text together, so -that when you yank it back, you get it all. The kill ring is not line -specific; the text that you killed on a previously typed line is -available to be yanked back later, when you are typing another line. - - Here is the list of commands for killing text. - -`C-k' - Kill the text from the current cursor position to the end of the - line. - -`M-d' - Kill from the cursor to the end of the current word, or, if between - words, to the end of the next word. Word boundaries are the same - as those used by `M-f'. - -`M-<DEL>' - Kill from the cursor the start of the current word, or, if between - words, to the start of the previous word. Word boundaries are the - same as those used by `M-b'. - -`C-w' - Kill from the cursor to the previous whitespace. This is - different than `M-<DEL>' because the word boundaries differ. - - - Here is how to "yank" the text back into the line. Yanking means to -copy the most-recently-killed text from the kill buffer. - -`C-y' - Yank the most recently killed text back into the buffer at the - cursor. - -`M-y' - Rotate the kill-ring, and yank the new top. You can only do this - if the prior command is `C-y' or `M-y'. - - -File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction - -31.2.4 Readline Arguments -------------------------- - -You can pass numeric arguments to Readline commands. Sometimes the -argument acts as a repeat count, other times it is the sign of the -argument that is significant. If you pass a negative argument to a -command which normally acts in a forward direction, that command will -act in a backward direction. For example, to kill text back to the -start of the line, you might type `M-- C-k'. - - The general way to pass numeric arguments to a command is to type -meta digits before the command. If the first `digit' typed is a minus -sign (`-'), then the sign of the argument will be negative. Once you -have typed one meta digit to get the argument started, you can type the -remainder of the digits, and then the command. For example, to give -the `C-d' command an argument of 10, you could type `M-1 0 C-d', which -will delete the next ten characters on the input line. - - -File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction - -31.2.5 Searching for Commands in the History --------------------------------------------- - -Readline provides commands for searching through the command history -for lines containing a specified string. There are two search modes: -"incremental" and "non-incremental". - - Incremental searches begin before the user has finished typing the -search string. As each character of the search string is typed, -Readline displays the next entry from the history matching the string -typed so far. An incremental search requires only as many characters -as needed to find the desired history entry. To search backward in the -history for a particular string, type `C-r'. Typing `C-s' searches -forward through the history. The characters present in the value of -the `isearch-terminators' variable are used to terminate an incremental -search. If that variable has not been assigned a value, the <ESC> and -`C-J' characters will terminate an incremental search. `C-g' will -abort an incremental search and restore the original line. When the -search is terminated, the history entry containing the search string -becomes the current line. - - To find other matching entries in the history list, type `C-r' or -`C-s' as appropriate. This will search backward or forward in the -history for the next entry matching the search string typed so far. -Any other key sequence bound to a Readline command will terminate the -search and execute that command. For instance, a <RET> will terminate -the search and accept the line, thereby executing the command from the -history list. A movement command will terminate the search, make the -last line found the current line, and begin editing. - - Readline remembers the last incremental search string. If two -`C-r's are typed without any intervening characters defining a new -search string, any remembered search string is used. - - Non-incremental searches read the entire search string before -starting to search for matching history lines. The search string may be -typed by the user or be part of the contents of the current line. - - -File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing - -31.3 Readline Init File -======================= - -Although the Readline library comes with a set of Emacs-like -keybindings installed by default, it is possible to use a different set -of keybindings. Any user can customize programs that use Readline by -putting commands in an "inputrc" file, conventionally in his home -directory. The name of this file is taken from the value of the -environment variable `INPUTRC'. If that variable is unset, the default -is `~/.inputrc'. - - When a program which uses the Readline library starts up, the init -file is read, and the key bindings are set. - - In addition, the `C-x C-r' command re-reads this init file, thus -incorporating any changes that you might have made to it. - -* Menu: - -* Readline Init File Syntax:: Syntax for the commands in the inputrc file. - -* Conditional Init Constructs:: Conditional key bindings in the inputrc file. - -* Sample Init File:: An example inputrc file. - - -File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File - -31.3.1 Readline Init File Syntax --------------------------------- - -There are only a few basic constructs allowed in the Readline init -file. Blank lines are ignored. Lines beginning with a `#' are -comments. Lines beginning with a `$' indicate conditional constructs -(*note Conditional Init Constructs::). Other lines denote variable -settings and key bindings. - -Variable Settings - You can modify the run-time behavior of Readline by altering the - values of variables in Readline using the `set' command within the - init file. The syntax is simple: - - set VARIABLE VALUE - - Here, for example, is how to change from the default Emacs-like - key binding to use `vi' line editing commands: - - set editing-mode vi - - Variable names and values, where appropriate, are recognized - without regard to case. Unrecognized variable names are ignored. - - Boolean variables (those that can be set to on or off) are set to - on if the value is null or empty, ON (case-insensitive), or 1. - Any other value results in the variable being set to off. - - A great deal of run-time behavior is changeable with the following - variables. - - `bell-style' - Controls what happens when Readline wants to ring the - terminal bell. If set to `none', Readline never rings the - bell. If set to `visible', Readline uses a visible bell if - one is available. If set to `audible' (the default), - Readline attempts to ring the terminal's bell. - - `bind-tty-special-chars' - If set to `on', Readline attempts to bind the control - characters treated specially by the kernel's terminal driver - to their Readline equivalents. - - `comment-begin' - The string to insert at the beginning of the line when the - `insert-comment' command is executed. The default value is - `"#"'. - - `completion-ignore-case' - If set to `on', Readline performs filename matching and - completion in a case-insensitive fashion. The default value - is `off'. - - `completion-query-items' - The number of possible completions that determines when the - user is asked whether the list of possibilities should be - displayed. If the number of possible completions is greater - than this value, Readline will ask the user whether or not he - wishes to view them; otherwise, they are simply listed. This - variable must be set to an integer value greater than or - equal to 0. A negative value means Readline should never ask. - The default limit is `100'. - - `convert-meta' - If set to `on', Readline will convert characters with the - eighth bit set to an ASCII key sequence by stripping the - eighth bit and prefixing an <ESC> character, converting them - to a meta-prefixed key sequence. The default value is `on'. - - `disable-completion' - If set to `On', Readline will inhibit word completion. - Completion characters will be inserted into the line as if - they had been mapped to `self-insert'. The default is `off'. - - `editing-mode' - The `editing-mode' variable controls which default set of key - bindings is used. By default, Readline starts up in Emacs - editing mode, where the keystrokes are most similar to Emacs. - This variable can be set to either `emacs' or `vi'. - - `enable-keypad' - When set to `on', Readline will try to enable the application - keypad when it is called. Some systems need this to enable - the arrow keys. The default is `off'. - - `expand-tilde' - If set to `on', tilde expansion is performed when Readline - attempts word completion. The default is `off'. - - `history-preserve-point' - If set to `on', the history code attempts to place point at - the same location on each history line retrieved with - `previous-history' or `next-history'. The default is `off'. - - `horizontal-scroll-mode' - This variable can be set to either `on' or `off'. Setting it - to `on' means that the text of the lines being edited will - scroll horizontally on a single screen line when they are - longer than the width of the screen, instead of wrapping onto - a new screen line. By default, this variable is set to `off'. - - `input-meta' - If set to `on', Readline will enable eight-bit input (it will - not clear the eighth bit in the characters it reads), - regardless of what the terminal claims it can support. The - default value is `off'. The name `meta-flag' is a synonym - for this variable. - - `isearch-terminators' - The string of characters that should terminate an incremental - search without subsequently executing the character as a - command (*note Searching::). If this variable has not been - given a value, the characters <ESC> and `C-J' will terminate - an incremental search. - - `keymap' - Sets Readline's idea of the current keymap for key binding - commands. Acceptable `keymap' names are `emacs', - `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', - `vi-command', and `vi-insert'. `vi' is equivalent to - `vi-command'; `emacs' is equivalent to `emacs-standard'. The - default value is `emacs'. The value of the `editing-mode' - variable also affects the default keymap. - - `mark-directories' - If set to `on', completed directory names have a slash - appended. The default is `on'. - - `mark-modified-lines' - This variable, when set to `on', causes Readline to display an - asterisk (`*') at the start of history lines which have been - modified. This variable is `off' by default. - - `mark-symlinked-directories' - If set to `on', completed names which are symbolic links to - directories have a slash appended (subject to the value of - `mark-directories'). The default is `off'. - - `match-hidden-files' - This variable, when set to `on', causes Readline to match - files whose names begin with a `.' (hidden files) when - performing filename completion, unless the leading `.' is - supplied by the user in the filename to be completed. This - variable is `on' by default. - - `output-meta' - If set to `on', Readline will display characters with the - eighth bit set directly rather than as a meta-prefixed escape - sequence. The default is `off'. - - `page-completions' - If set to `on', Readline uses an internal `more'-like pager - to display a screenful of possible completions at a time. - This variable is `on' by default. - - `print-completions-horizontally' - If set to `on', Readline will display completions with matches - sorted horizontally in alphabetical order, rather than down - the screen. The default is `off'. - - `show-all-if-ambiguous' - This alters the default behavior of the completion functions. - If set to `on', words which have more than one possible - completion cause the matches to be listed immediately instead - of ringing the bell. The default value is `off'. - - `show-all-if-unmodified' - This alters the default behavior of the completion functions - in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to - `on', words which have more than one possible completion - without any possible partial completion (the possible - completions don't share a common prefix) cause the matches to - be listed immediately instead of ringing the bell. The - default value is `off'. - - `visible-stats' - If set to `on', a character denoting a file's type is - appended to the filename when listing possible completions. - The default is `off'. - - -Key Bindings - The syntax for controlling key bindings in the init file is - simple. First you need to find the name of the command that you - want to change. The following sections contain tables of the - command name, the default keybinding, if any, and a short - description of what the command does. - - Once you know the name of the command, simply place on a line in - the init file the name of the key you wish to bind the command to, - a colon, and then the name of the command. The name of the key - can be expressed in different ways, depending on what you find most - comfortable. - - In addition to command names, readline allows keys to be bound to - a string that is inserted when the key is pressed (a MACRO). - - KEYNAME: FUNCTION-NAME or MACRO - KEYNAME is the name of a key spelled out in English. For - example: - Control-u: universal-argument - Meta-Rubout: backward-kill-word - Control-o: "> output" - - In the above example, `C-u' is bound to the function - `universal-argument', `M-DEL' is bound to the function - `backward-kill-word', and `C-o' is bound to run the macro - expressed on the right hand side (that is, to insert the text - `> output' into the line). - - A number of symbolic character names are recognized while - processing this key binding syntax: DEL, ESC, ESCAPE, LFD, - NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. - - "KEYSEQ": FUNCTION-NAME or MACRO - KEYSEQ differs from KEYNAME above in that strings denoting an - entire key sequence can be specified, by placing the key - sequence in double quotes. Some GNU Emacs style key escapes - can be used, as in the following example, but the special - character names are not recognized. - - "\C-u": universal-argument - "\C-x\C-r": re-read-init-file - "\e[11~": "Function Key 1" - - In the above example, `C-u' is again bound to the function - `universal-argument' (just as it was in the first example), - `C-x C-r' is bound to the function `re-read-init-file', and - `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function - Key 1'. - - - The following GNU Emacs style escape sequences are available when - specifying key sequences: - - `\C-' - control prefix - - `\M-' - meta prefix - - `\e' - an escape character - - `\\' - backslash - - `\"' - <">, a double quotation mark - - `\'' - <'>, a single quote or apostrophe - - In addition to the GNU Emacs style escape sequences, a second set - of backslash escapes is available: - - `\a' - alert (bell) - - `\b' - backspace - - `\d' - delete - - `\f' - form feed - - `\n' - newline - - `\r' - carriage return - - `\t' - horizontal tab - - `\v' - vertical tab - - `\NNN' - the eight-bit character whose value is the octal value NNN - (one to three digits) - - `\xHH' - the eight-bit character whose value is the hexadecimal value - HH (one or two hex digits) - - When entering the text of a macro, single or double quotes must be - used to indicate a macro definition. Unquoted text is assumed to - be a function name. In the macro body, the backslash escapes - described above are expanded. Backslash will quote any other - character in the macro text, including `"' and `''. For example, - the following binding will make `C-x \' insert a single `\' into - the line: - "\C-x\\": "\\" - - - -File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File - -31.3.2 Conditional Init Constructs ----------------------------------- - -Readline implements a facility similar in spirit to the conditional -compilation features of the C preprocessor which allows key bindings -and variable settings to be performed as the result of tests. There -are four parser directives used. - -`$if' - The `$if' construct allows bindings to be made based on the - editing mode, the terminal being used, or the application using - Readline. The text of the test extends to the end of the line; no - characters are required to isolate it. - - `mode' - The `mode=' form of the `$if' directive is used to test - whether Readline is in `emacs' or `vi' mode. This may be - used in conjunction with the `set keymap' command, for - instance, to set bindings in the `emacs-standard' and - `emacs-ctlx' keymaps only if Readline is starting out in - `emacs' mode. - - `term' - The `term=' form may be used to include terminal-specific key - bindings, perhaps to bind the key sequences output by the - terminal's function keys. The word on the right side of the - `=' is tested against both the full name of the terminal and - the portion of the terminal name before the first `-'. This - allows `sun' to match both `sun' and `sun-cmd', for instance. - - `application' - The APPLICATION construct is used to include - application-specific settings. Each program using the - Readline library sets the APPLICATION NAME, and you can test - for a particular value. This could be used to bind key - sequences to functions useful for a specific program. For - instance, the following command adds a key sequence that - quotes the current or previous word in Bash: - $if Bash - # Quote the current or previous word - "\C-xq": "\eb\"\ef\"" - $endif - -`$endif' - This command, as seen in the previous example, terminates an `$if' - command. - -`$else' - Commands in this branch of the `$if' directive are executed if the - test fails. - -`$include' - This directive takes a single filename as an argument and reads - commands and bindings from that file. For example, the following - directive reads from `/etc/inputrc': - $include /etc/inputrc - - -File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File - -31.3.3 Sample Init File ------------------------ - -Here is an example of an INPUTRC file. This illustrates key binding, -variable assignment, and conditional syntax. - - - # This file controls the behaviour of line input editing for - # programs that use the GNU Readline library. Existing - # programs include FTP, Bash, and GDB. - # - # You can re-read the inputrc file with C-x C-r. - # Lines beginning with '#' are comments. - # - # First, include any systemwide bindings and variable - # assignments from /etc/Inputrc - $include /etc/Inputrc - - # - # Set various bindings for emacs mode. - - set editing-mode emacs - - $if mode=emacs - - Meta-Control-h: backward-kill-word Text after the function name is ignored - - # - # Arrow keys in keypad mode - # - #"\M-OD": backward-char - #"\M-OC": forward-char - #"\M-OA": previous-history - #"\M-OB": next-history - # - # Arrow keys in ANSI mode - # - "\M-[D": backward-char - "\M-[C": forward-char - "\M-[A": previous-history - "\M-[B": next-history - # - # Arrow keys in 8 bit keypad mode - # - #"\M-\C-OD": backward-char - #"\M-\C-OC": forward-char - #"\M-\C-OA": previous-history - #"\M-\C-OB": next-history - # - # Arrow keys in 8 bit ANSI mode - # - #"\M-\C-[D": backward-char - #"\M-\C-[C": forward-char - #"\M-\C-[A": previous-history - #"\M-\C-[B": next-history - - C-q: quoted-insert - - $endif - - # An old-style binding. This happens to be the default. - TAB: complete - - # Macros that are convenient for shell interaction - $if Bash - # edit the path - "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" - # prepare to type a quoted word -- - # insert open and close double quotes - # and move to just after the open quote - "\C-x\"": "\"\"\C-b" - # insert a backslash (testing backslash escapes - # in sequences and macros) - "\C-x\\": "\\" - # Quote the current or previous word - "\C-xq": "\eb\"\ef\"" - # Add a binding to refresh the line, which is unbound - "\C-xr": redraw-current-line - # Edit variable on current line. - "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" - $endif - - # use a visible bell if one is available - set bell-style visible - - # don't strip characters to 7 bits when reading - set input-meta on - - # allow iso-latin1 characters to be inserted rather - # than converted to prefix-meta sequences - set convert-meta off - - # display characters with the eighth bit set directly - # rather than as meta-prefixed characters - set output-meta on - - # if there are more than 150 possible completions for - # a word, ask the user if he wants to see all of them - set completion-query-items 150 - - # For FTP - $if Ftp - "\C-xg": "get \M-?" - "\C-xt": "put \M-?" - "\M-.": yank-last-arg - $endif - - -File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing - -31.4 Bindable Readline Commands -=============================== - -* Menu: - -* Commands For Moving:: Moving about the line. -* Commands For History:: Getting at previous lines. -* Commands For Text:: Commands for changing text. -* Commands For Killing:: Commands for killing and yanking. -* Numeric Arguments:: Specifying numeric arguments, repeat counts. -* Commands For Completion:: Getting Readline to do the typing for you. -* Keyboard Macros:: Saving and re-executing typed characters -* Miscellaneous Commands:: Other miscellaneous commands. - - This section describes Readline commands that may be bound to key -sequences. Command names without an accompanying key sequence are -unbound by default. - - In the following descriptions, "point" refers to the current cursor -position, and "mark" refers to a cursor position saved by the -`set-mark' command. The text between the point and mark is referred to -as the "region". - - -File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands - -31.4.1 Commands For Moving --------------------------- - -`beginning-of-line (C-a)' - Move to the start of the current line. - -`end-of-line (C-e)' - Move to the end of the line. - -`forward-char (C-f)' - Move forward a character. - -`backward-char (C-b)' - Move back a character. - -`forward-word (M-f)' - Move forward to the end of the next word. Words are composed of - letters and digits. - -`backward-word (M-b)' - Move back to the start of the current or previous word. Words are - composed of letters and digits. - -`clear-screen (C-l)' - Clear the screen and redraw the current line, leaving the current - line at the top of the screen. - -`redraw-current-line ()' - Refresh the current line. By default, this is unbound. - - - -File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands - -31.4.2 Commands For Manipulating The History --------------------------------------------- - -`accept-line (Newline or Return)' - Accept the line regardless of where the cursor is. If this line is - non-empty, it may be added to the history list for future recall - with `add_history()'. If this line is a modified history line, - the history line is restored to its original state. - -`previous-history (C-p)' - Move `back' through the history list, fetching the previous - command. - -`next-history (C-n)' - Move `forward' through the history list, fetching the next command. - -`beginning-of-history (M-<)' - Move to the first line in the history. - -`end-of-history (M->)' - Move to the end of the input history, i.e., the line currently - being entered. - -`reverse-search-history (C-r)' - Search backward starting at the current line and moving `up' - through the history as necessary. This is an incremental search. - -`forward-search-history (C-s)' - Search forward starting at the current line and moving `down' - through the the history as necessary. This is an incremental - search. - -`non-incremental-reverse-search-history (M-p)' - Search backward starting at the current line and moving `up' - through the history as necessary using a non-incremental search - for a string supplied by the user. - -`non-incremental-forward-search-history (M-n)' - Search forward starting at the current line and moving `down' - through the the history as necessary using a non-incremental search - for a string supplied by the user. - -`history-search-forward ()' - Search forward through the history for the string of characters - between the start of the current line and the point. This is a - non-incremental search. By default, this command is unbound. - -`history-search-backward ()' - Search backward through the history for the string of characters - between the start of the current line and the point. This is a - non-incremental search. By default, this command is unbound. - -`yank-nth-arg (M-C-y)' - Insert the first argument to the previous command (usually the - second word on the previous line) at point. With an argument N, - insert the Nth word from the previous command (the words in the - previous command begin with word 0). A negative argument inserts - the Nth word from the end of the previous command. Once the - argument N is computed, the argument is extracted as if the `!N' - history expansion had been specified. - -`yank-last-arg (M-. or M-_)' - Insert last argument to the previous command (the last word of the - previous history entry). With an argument, behave exactly like - `yank-nth-arg'. Successive calls to `yank-last-arg' move back - through the history list, inserting the last argument of each line - in turn. The history expansion facilities are used to extract the - last argument, as if the `!$' history expansion had been specified. - - - -File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands - -31.4.3 Commands For Changing Text ---------------------------------- - -`delete-char (C-d)' - Delete the character at point. If point is at the beginning of - the line, there are no characters in the line, and the last - character typed was not bound to `delete-char', then return EOF. - -`backward-delete-char (Rubout)' - Delete the character behind the cursor. A numeric argument means - to kill the characters instead of deleting them. - -`forward-backward-delete-char ()' - Delete the character under the cursor, unless the cursor is at the - end of the line, in which case the character behind the cursor is - deleted. By default, this is not bound to a key. - -`quoted-insert (C-q or C-v)' - Add the next character typed to the line verbatim. This is how to - insert key sequences like `C-q', for example. - -`tab-insert (M-<TAB>)' - Insert a tab character. - -`self-insert (a, b, A, 1, !, ...)' - Insert yourself. - -`transpose-chars (C-t)' - Drag the character before the cursor forward over the character at - the cursor, moving the cursor forward as well. If the insertion - point is at the end of the line, then this transposes the last two - characters of the line. Negative arguments have no effect. - -`transpose-words (M-t)' - Drag the word before point past the word after point, moving point - past that word as well. If the insertion point is at the end of - the line, this transposes the last two words on the line. - -`upcase-word (M-u)' - Uppercase the current (or following) word. With a negative - argument, uppercase the previous word, but do not move the cursor. - -`downcase-word (M-l)' - Lowercase the current (or following) word. With a negative - argument, lowercase the previous word, but do not move the cursor. - -`capitalize-word (M-c)' - Capitalize the current (or following) word. With a negative - argument, capitalize the previous word, but do not move the cursor. - -`overwrite-mode ()' - Toggle overwrite mode. With an explicit positive numeric argument, - switches to overwrite mode. With an explicit non-positive numeric - argument, switches to insert mode. This command affects only - `emacs' mode; `vi' mode does overwrite differently. Each call to - `readline()' starts in insert mode. - - In overwrite mode, characters bound to `self-insert' replace the - text at point rather than pushing the text to the right. - Characters bound to `backward-delete-char' replace the character - before point with a space. - - By default, this command is unbound. - - - -File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands - -31.4.4 Killing And Yanking --------------------------- - -`kill-line (C-k)' - Kill the text from point to the end of the line. - -`backward-kill-line (C-x Rubout)' - Kill backward to the beginning of the line. - -`unix-line-discard (C-u)' - Kill backward from the cursor to the beginning of the current line. - -`kill-whole-line ()' - Kill all characters on the current line, no matter where point is. - By default, this is unbound. - -`kill-word (M-d)' - Kill from point to the end of the current word, or if between - words, to the end of the next word. Word boundaries are the same - as `forward-word'. - -`backward-kill-word (M-<DEL>)' - Kill the word behind point. Word boundaries are the same as - `backward-word'. - -`unix-word-rubout (C-w)' - Kill the word behind point, using white space as a word boundary. - The killed text is saved on the kill-ring. - -`unix-filename-rubout ()' - Kill the word behind point, using white space and the slash - character as the word boundaries. The killed text is saved on the - kill-ring. - -`delete-horizontal-space ()' - Delete all spaces and tabs around point. By default, this is - unbound. - -`kill-region ()' - Kill the text in the current region. By default, this command is - unbound. - -`copy-region-as-kill ()' - Copy the text in the region to the kill buffer, so it can be yanked - right away. By default, this command is unbound. - -`copy-backward-word ()' - Copy the word before point to the kill buffer. The word - boundaries are the same as `backward-word'. By default, this - command is unbound. - -`copy-forward-word ()' - Copy the word following point to the kill buffer. The word - boundaries are the same as `forward-word'. By default, this - command is unbound. - -`yank (C-y)' - Yank the top of the kill ring into the buffer at point. - -`yank-pop (M-y)' - Rotate the kill-ring, and yank the new top. You can only do this - if the prior command is `yank' or `yank-pop'. - - -File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands - -31.4.5 Specifying Numeric Arguments ------------------------------------ - -`digit-argument (M-0, M-1, ... M--)' - Add this digit to the argument already accumulating, or start a new - argument. `M--' starts a negative argument. - -`universal-argument ()' - This is another way to specify an argument. If this command is - followed by one or more digits, optionally with a leading minus - sign, those digits define the argument. If the command is - followed by digits, executing `universal-argument' again ends the - numeric argument, but is otherwise ignored. As a special case, if - this command is immediately followed by a character that is - neither a digit or minus sign, the argument count for the next - command is multiplied by four. The argument count is initially - one, so executing this function the first time makes the argument - count four, a second time makes the argument count sixteen, and so - on. By default, this is not bound to a key. - - -File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands - -31.4.6 Letting Readline Type For You ------------------------------------- - -`complete (<TAB>)' - Attempt to perform completion on the text before point. The - actual completion performed is application-specific. The default - is filename completion. - -`possible-completions (M-?)' - List the possible completions of the text before point. - -`insert-completions (M-*)' - Insert all completions of the text before point that would have - been generated by `possible-completions'. - -`menu-complete ()' - Similar to `complete', but replaces the word to be completed with - a single match from the list of possible completions. Repeated - execution of `menu-complete' steps through the list of possible - completions, inserting each match in turn. At the end of the list - of completions, the bell is rung (subject to the setting of - `bell-style') and the original text is restored. An argument of N - moves N positions forward in the list of matches; a negative - argument may be used to move backward through the list. This - command is intended to be bound to <TAB>, but is unbound by - default. - -`delete-char-or-list ()' - Deletes the character under the cursor if not at the beginning or - end of the line (like `delete-char'). If at the end of the line, - behaves identically to `possible-completions'. This command is - unbound by default. - - - -File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands - -31.4.7 Keyboard Macros ----------------------- - -`start-kbd-macro (C-x ()' - Begin saving the characters typed into the current keyboard macro. - -`end-kbd-macro (C-x ))' - Stop saving the characters typed into the current keyboard macro - and save the definition. - -`call-last-kbd-macro (C-x e)' - Re-execute the last keyboard macro defined, by making the - characters in the macro appear as if typed at the keyboard. - - - -File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands - -31.4.8 Some Miscellaneous Commands ----------------------------------- - -`re-read-init-file (C-x C-r)' - Read in the contents of the INPUTRC file, and incorporate any - bindings or variable assignments found there. - -`abort (C-g)' - Abort the current editing command and ring the terminal's bell - (subject to the setting of `bell-style'). - -`do-uppercase-version (M-a, M-b, M-X, ...)' - If the metafied character X is lowercase, run the command that is - bound to the corresponding uppercase character. - -`prefix-meta (<ESC>)' - Metafy the next character typed. This is for keyboards without a - meta key. Typing `<ESC> f' is equivalent to typing `M-f'. - -`undo (C-_ or C-x C-u)' - Incremental undo, separately remembered for each line. - -`revert-line (M-r)' - Undo all changes made to this line. This is like executing the - `undo' command enough times to get back to the beginning. - -`tilde-expand (M-~)' - Perform tilde expansion on the current word. - -`set-mark (C-@)' - Set the mark to the point. If a numeric argument is supplied, the - mark is set to that position. - -`exchange-point-and-mark (C-x C-x)' - Swap the point with the mark. The current cursor position is set - to the saved position, and the old cursor position is saved as the - mark. - -`character-search (C-])' - A character is read and point is moved to the next occurrence of - that character. A negative count searches for previous - occurrences. - -`character-search-backward (M-C-])' - A character is read and point is moved to the previous occurrence - of that character. A negative count searches for subsequent - occurrences. - -`insert-comment (M-#)' - Without a numeric argument, the value of the `comment-begin' - variable is inserted at the beginning of the current line. If a - numeric argument is supplied, this command acts as a toggle: if - the characters at the beginning of the line do not match the value - of `comment-begin', the value is inserted, otherwise the - characters in `comment-begin' are deleted from the beginning of - the line. In either case, the line is accepted as if a newline - had been typed. - -`dump-functions ()' - Print all of the functions and their key bindings to the Readline - output stream. If a numeric argument is supplied, the output is - formatted in such a way that it can be made part of an INPUTRC - file. This command is unbound by default. - -`dump-variables ()' - Print all of the settable variables and their values to the - Readline output stream. If a numeric argument is supplied, the - output is formatted in such a way that it can be made part of an - INPUTRC file. This command is unbound by default. - -`dump-macros ()' - Print all of the Readline key sequences bound to macros and the - strings they output. If a numeric argument is supplied, the - output is formatted in such a way that it can be made part of an - INPUTRC file. This command is unbound by default. - -`emacs-editing-mode (C-e)' - When in `vi' command mode, this causes a switch to `emacs' editing - mode. - -`vi-editing-mode (M-C-j)' - When in `emacs' editing mode, this causes a switch to `vi' editing - mode. - - - -File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing - -31.5 Readline vi Mode -===================== - -While the Readline library does not have a full set of `vi' editing -functions, it does contain enough to allow simple editing of the line. -The Readline `vi' mode behaves as specified in the POSIX 1003.2 -standard. - - In order to switch interactively between `emacs' and `vi' editing -modes, use the command `M-C-j' (bound to emacs-editing-mode when in -`vi' mode and to vi-editing-mode in `emacs' mode). The Readline -default is `emacs' mode. - - When you enter a line in `vi' mode, you are already placed in -`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches -you into `command' mode, where you can edit the text of the line with -the standard `vi' movement keys, move to previous history lines with -`k' and subsequent lines with `j', and so forth. - - -File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top - -32 Using History Interactively -****************************** - -This chapter describes how to use the GNU History Library interactively, -from a user's standpoint. It should be considered a user's guide. For -information on using the GNU History Library in other programs, see the -GNU Readline Library Manual. - -* Menu: - -* History Interaction:: What it feels like using History as a user. - - -File: gdb.info, Node: History Interaction, Up: Using History Interactively - -32.1 History Expansion -====================== - -The History library provides a history expansion feature that is similar -to the history expansion provided by `csh'. This section describes the -syntax used to manipulate the history information. - - History expansions introduce words from the history list into the -input stream, making it easy to repeat commands, insert the arguments -to a previous command into the current input line, or fix errors in -previous commands quickly. - - History expansion takes place in two parts. The first is to -determine which line from the history list should be used during -substitution. The second is to select portions of that line for -inclusion into the current one. The line selected from the history is -called the "event", and the portions of that line that are acted upon -are called "words". Various "modifiers" are available to manipulate -the selected words. The line is broken into words in the same fashion -that Bash does, so that several words surrounded by quotes are -considered one word. History expansions are introduced by the -appearance of the history expansion character, which is `!' by default. - -* Menu: - -* Event Designators:: How to specify which history line to use. -* Word Designators:: Specifying which words are of interest. -* Modifiers:: Modifying the results of substitution. - - -File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction - -32.1.1 Event Designators ------------------------- - -An event designator is a reference to a command line entry in the -history list. - -`!' - Start a history substitution, except when followed by a space, tab, - the end of the line, or `='. - -`!N' - Refer to command line N. - -`!-N' - Refer to the command N lines back. - -`!!' - Refer to the previous command. This is a synonym for `!-1'. - -`!STRING' - Refer to the most recent command starting with STRING. - -`!?STRING[?]' - Refer to the most recent command containing STRING. The trailing - `?' may be omitted if the STRING is followed immediately by a - newline. - -`^STRING1^STRING2^' - Quick Substitution. Repeat the last command, replacing STRING1 - with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. - -`!#' - The entire command line typed so far. - - - -File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction - -32.1.2 Word Designators ------------------------ - -Word designators are used to select desired words from the event. A -`:' separates the event specification from the word designator. It may -be omitted if the word designator begins with a `^', `$', `*', `-', or -`%'. Words are numbered from the beginning of the line, with the first -word being denoted by 0 (zero). Words are inserted into the current -line separated by single spaces. - - For example, - -`!!' - designates the preceding command. When you type this, the - preceding command is repeated in toto. - -`!!:$' - designates the last argument of the preceding command. This may be - shortened to `!$'. - -`!fi:2' - designates the second argument of the most recent command starting - with the letters `fi'. - - Here are the word designators: - -`0 (zero)' - The `0'th word. For many applications, this is the command word. - -`N' - The Nth word. - -`^' - The first argument; that is, word 1. - -`$' - The last argument. - -`%' - The word matched by the most recent `?STRING?' search. - -`X-Y' - A range of words; `-Y' abbreviates `0-Y'. - -`*' - All of the words, except the `0'th. This is a synonym for `1-$'. - It is not an error to use `*' if there is just one word in the - event; the empty string is returned in that case. - -`X*' - Abbreviates `X-$' - -`X-' - Abbreviates `X-$' like `X*', but omits the last word. - - - If a word designator is supplied without an event specification, the -previous command is used as the event. - - -File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction - -32.1.3 Modifiers ----------------- - -After the optional word designator, you can add a sequence of one or -more of the following modifiers, each preceded by a `:'. - -`h' - Remove a trailing pathname component, leaving only the head. - -`t' - Remove all leading pathname components, leaving the tail. - -`r' - Remove a trailing suffix of the form `.SUFFIX', leaving the - basename. - -`e' - Remove all but the trailing suffix. - -`p' - Print the new command but do not execute it. - -`s/OLD/NEW/' - Substitute NEW for the first occurrence of OLD in the event line. - Any delimiter may be used in place of `/'. The delimiter may be - quoted in OLD and NEW with a single backslash. If `&' appears in - NEW, it is replaced by OLD. A single backslash will quote the - `&'. The final delimiter is optional if it is the last character - on the input line. - -`&' - Repeat the previous substitution. - -`g' -`a' - Cause changes to be applied over the entire event line. Used in - conjunction with `s', as in `gs/OLD/NEW/', or with `&'. - -`G' - Apply the following `s' modifier once to each word in the event. - - - -File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top - -Appendix A In Memoriam -********************** - -The GDB project mourns the loss of the following long-time contributors: - -`Fred Fish' - Fred was a long-standing contributor to GDB (1991-2006), and to - Free Software in general. Outside of GDB, he was known in the - Amiga world for his series of Fish Disks, and the GeekGadget - project. - -`Michael Snyder' - Michael was one of the Global Maintainers of the GDB project, with - contributions recorded as early as 1996, until 2011. In addition - to his day to day participation, he was a large driving force - behind adding Reverse Debugging to GDB. - - Beyond their technical contributions to the project, they were also -enjoyable members of the Free Software Community. We will miss them. - - -File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top - -Appendix B Formatting Documentation -*********************************** - -The GDB 4 release includes an already-formatted reference card, ready -for printing with PostScript or Ghostscript, in the `gdb' subdirectory -of the main source directory(1). If you can use PostScript or -Ghostscript with your printer, you can print the reference card -immediately with `refcard.ps'. - - The release also includes the source for the reference card. You -can format it, using TeX, by typing: - - make refcard.dvi - - The GDB reference card is designed to print in "landscape" mode on -US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches -high. You will need to specify this form of printing as an option to -your DVI output program. - - All the documentation for GDB comes as part of the machine-readable -distribution. The documentation is written in Texinfo format, which is -a documentation system that uses a single source file to produce both -on-line information and a printed manual. You can use one of the Info -formatting commands to create the on-line version of the documentation -and TeX (or `texi2roff') to typeset the printed version. - - GDB includes an already formatted copy of the on-line Info version -of this manual in the `gdb' subdirectory. The main Info file is -`gdb-7.3.1-gg2/gdb/gdb.info', and it refers to subordinate files -matching `gdb.info*' in the same directory. If necessary, you can -print out these files, or read them with any editor; but they are -easier to read using the `info' subsystem in GNU Emacs or the -standalone `info' program, available as part of the GNU Texinfo -distribution. - - If you want to format these Info files yourself, you need one of the -Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. - - If you have `makeinfo' installed, and are in the top level GDB -source directory (`gdb-7.3.1-gg2', in the case of version 7.3.1-gg2), -you can make the Info file by typing: - - cd gdb - make gdb.info - - If you want to typeset and print copies of this manual, you need TeX, -a program to print its DVI output files, and `texinfo.tex', the Texinfo -definitions file. - - TeX is a typesetting program; it does not print files directly, but -produces output files called DVI files. To print a typeset document, -you need a program to print DVI files. If your system has TeX -installed, chances are it has such a program. The precise command to -use depends on your system; `lpr -d' is common; another (for PostScript -devices) is `dvips'. The DVI print command may require a file name -without any extension or a `.dvi' extension. - - TeX also requires a macro definitions file called `texinfo.tex'. -This file tells TeX how to typeset a document written in Texinfo -format. On its own, TeX cannot either read or typeset a Texinfo file. -`texinfo.tex' is distributed with GDB and is located in the -`gdb-VERSION-NUMBER/texinfo' directory. - - If you have TeX and a DVI printer program installed, you can typeset -and print this manual. First switch to the `gdb' subdirectory of the -main source directory (for example, to `gdb-7.3.1-gg2/gdb') and type: - - make gdb.dvi - - Then give `gdb.dvi' to your DVI printing program. - - ---------- Footnotes ---------- - - (1) In `gdb-7.3.1-gg2/gdb/refcard.ps' of the version 7.3.1-gg2 -release. - - -File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top - -Appendix C Installing GDB -************************* - -* Menu: - -* Requirements:: Requirements for building GDB -* Running Configure:: Invoking the GDB `configure' script -* Separate Objdir:: Compiling GDB in another directory -* Config Names:: Specifying names for hosts and targets -* Configure Options:: Summary of options for configure -* System-wide configuration:: Having a system-wide init file - - -File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB - -C.1 Requirements for Building GDB -================================= - -Building GDB requires various tools and packages to be available. -Other packages will be used only if they are found. - -Tools/Packages Necessary for Building GDB -========================================= - -ISO C90 compiler - GDB is written in ISO C90. It should be buildable with any - working C90 compiler, e.g. GCC. - - -Tools/Packages Optional for Building GDB -======================================== - -Expat - GDB can use the Expat XML parsing library. This library may be - included with your operating system distribution; if it is not, you - can get the latest version from `http://expat.sourceforge.net'. - The `configure' script will search for this library in several - standard locations; if it is installed in an unusual path, you can - use the `--with-libexpat-prefix' option to specify its location. - - Expat is used for: - - * Remote protocol memory maps (*note Memory Map Format::) - - * Target descriptions (*note Target Descriptions::) - - * Remote shared library lists (*note Library List Format::) - - * MS-Windows shared libraries (*note Shared Libraries::) - - * Traceframe info (*note Traceframe Info Format::) - -zlib - GDB will use the `zlib' library, if available, to read compressed - debug sections. Some linkers, such as GNU gold, are capable of - producing binaries with compressed debug sections. If GDB is - compiled with `zlib', it will be able to read the debug - information in such binaries. - - The `zlib' library is likely included with your operating system - distribution; if it is not, you can get the latest version from - `http://zlib.net'. - -iconv - GDB's features related to character sets (*note Character Sets::) - require a functioning `iconv' implementation. If you are on a GNU - system, then this is provided by the GNU C Library. Some other - systems also provide a working `iconv'. - - If GDB is using the `iconv' program which is installed in a - non-standard place, you will need to tell GDB where to find it. - This is done with `--with-iconv-bin' which specifies the directory - that contains the `iconv' program. - - On systems without `iconv', you can install GNU Libiconv. If you - have previously installed Libiconv, you can use the - `--with-libiconv-prefix' option to configure. - - GDB's top-level `configure' and `Makefile' will arrange to build - Libiconv if a directory named `libiconv' appears in the top-most - source directory. If Libiconv is built this way, and if the - operating system does not provide a suitable `iconv' - implementation, then the just-built library will automatically be - used by GDB. One easy way to set this up is to download GNU - Libiconv, unpack it, and then rename the directory holding the - Libiconv source code to `libiconv'. - - -File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB - -C.2 Invoking the GDB `configure' Script -======================================= - -GDB comes with a `configure' script that automates the process of -preparing GDB for installation; you can then use `make' to build the -`gdb' program. - - The GDB distribution includes all the source code you need for GDB -in a single directory, whose name is usually composed by appending the -version number to `gdb'. - - For example, the GDB version 7.3.1-gg2 distribution is in the -`gdb-7.3.1-gg2' directory. That directory contains: - -`gdb-7.3.1-gg2/configure (and supporting files)' - script for configuring GDB and all its supporting libraries - -`gdb-7.3.1-gg2/gdb' - the source specific to GDB itself - -`gdb-7.3.1-gg2/bfd' - source for the Binary File Descriptor library - -`gdb-7.3.1-gg2/include' - GNU include files - -`gdb-7.3.1-gg2/libiberty' - source for the `-liberty' free software library - -`gdb-7.3.1-gg2/opcodes' - source for the library of opcode tables and disassemblers - -`gdb-7.3.1-gg2/readline' - source for the GNU command-line interface - -`gdb-7.3.1-gg2/glob' - source for the GNU filename pattern-matching subroutine - -`gdb-7.3.1-gg2/mmalloc' - source for the GNU memory-mapped malloc package - - The simplest way to configure and build GDB is to run `configure' -from the `gdb-VERSION-NUMBER' source directory, which in this example -is the `gdb-7.3.1-gg2' directory. - - First switch to the `gdb-VERSION-NUMBER' source directory if you are -not already in it; then run `configure'. Pass the identifier for the -platform on which GDB will run as an argument. - - For example: - - cd gdb-7.3.1-gg2 - ./configure HOST - make - -where HOST is an identifier such as `sun4' or `decstation', that -identifies the platform where GDB will run. (You can often leave off -HOST; `configure' tries to guess the correct value by examining your -system.) - - Running `configure HOST' and then running `make' builds the `bfd', -`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. -The configured source files, and the binaries, are left in the -corresponding source directories. - - `configure' is a Bourne-shell (`/bin/sh') script; if your system -does not recognize this automatically when you run a different shell, -you may need to run `sh' on it explicitly: - - sh configure HOST - - If you run `configure' from a directory that contains source -directories for multiple libraries or programs, such as the -`gdb-7.3.1-gg2' source directory for version 7.3.1-gg2, `configure' -creates configuration files for every directory level underneath (unless -you tell it not to, with the `--norecursion' option). - - You should run the `configure' script from the top directory in the -source tree, the `gdb-VERSION-NUMBER' directory. If you run -`configure' from one of the subdirectories, you will configure only -that subdirectory. That is usually not what you want. In particular, -if you run the first `configure' from the `gdb' subdirectory of the -`gdb-VERSION-NUMBER' directory, you will omit the configuration of -`bfd', `readline', and other sibling directories of the `gdb' -subdirectory. This leads to build errors about missing include files -such as `bfd/bfd.h'. - - You can install `gdb' anywhere; it has no hardwired paths. However, -you should make sure that the shell on your path (named by the `SHELL' -environment variable) is publicly readable. Remember that GDB uses the -shell to start your program--some systems refuse to let GDB debug child -processes whose programs are not readable. - - -File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB - -C.3 Compiling GDB in Another Directory -====================================== - -If you want to run GDB versions for several host or target machines, -you need a different `gdb' compiled for each combination of host and -target. `configure' is designed to make this easy by allowing you to -generate each configuration in a separate subdirectory, rather than in -the source directory. If your `make' program handles the `VPATH' -feature (GNU `make' does), running `make' in each of these directories -builds the `gdb' program specified there. - - To build `gdb' in a separate directory, run `configure' with the -`--srcdir' option to specify where to find the source. (You also need -to specify a path to find `configure' itself from your working -directory. If the path to `configure' would be the same as the -argument to `--srcdir', you can leave out the `--srcdir' option; it is -assumed.) - - For example, with version 7.3.1-gg2, you can build GDB in a separate -directory for a Sun 4 like this: - - cd gdb-7.3.1-gg2 - mkdir ../gdb-sun4 - cd ../gdb-sun4 - ../gdb-7.3.1-gg2/configure sun4 - make - - When `configure' builds a configuration using a remote source -directory, it creates a tree for the binaries with the same structure -(and using the same names) as the tree under the source directory. In -the example, you'd find the Sun 4 library `libiberty.a' in the -directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. - - Make sure that your path to the `configure' script has just one -instance of `gdb' in it. If your path to `configure' looks like -`../gdb-7.3.1-gg2/gdb/configure', you are configuring only one -subdirectory of GDB, not the whole package. This leads to build errors -about missing include files such as `bfd/bfd.h'. - - One popular reason to build several GDB configurations in separate -directories is to configure GDB for cross-compiling (where GDB runs on -one machine--the "host"--while debugging programs that run on another -machine--the "target"). You specify a cross-debugging target by giving -the `--target=TARGET' option to `configure'. - - When you run `make' to build a program or library, you must run it -in a configured directory--whatever directory you were in when you -called `configure' (or one of its subdirectories). - - The `Makefile' that `configure' generates in each source directory -also runs recursively. If you type `make' in a source directory such -as `gdb-7.3.1-gg2' (or in a separate configured directory configured -with `--srcdir=DIRNAME/gdb-7.3.1-gg2'), you will build all the required -libraries, and then build GDB. - - When you have multiple hosts or targets configured in separate -directories, you can run `make' on them in parallel (for example, if -they are NFS-mounted on each of the hosts); they will not interfere -with each other. - - -File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB - -C.4 Specifying Names for Hosts and Targets -========================================== - -The specifications used for hosts and targets in the `configure' script -are based on a three-part naming scheme, but some short predefined -aliases are also supported. The full naming scheme encodes three pieces -of information in the following pattern: - - ARCHITECTURE-VENDOR-OS - - For example, you can use the alias `sun4' as a HOST argument, or as -the value for TARGET in a `--target=TARGET' option. The equivalent -full name is `sparc-sun-sunos4'. - - The `configure' script accompanying GDB does not provide any query -facility to list all supported host and target names or aliases. -`configure' calls the Bourne shell script `config.sub' to map -abbreviations to full names; you can read the script, if you wish, or -you can use it to test your guesses on abbreviations--for example: - - % sh config.sub i386-linux - i386-pc-linux-gnu - % sh config.sub alpha-linux - alpha-unknown-linux-gnu - % sh config.sub hp9k700 - hppa1.1-hp-hpux - % sh config.sub sun4 - sparc-sun-sunos4.1.1 - % sh config.sub sun3 - m68k-sun-sunos4.1.1 - % sh config.sub i986v - Invalid configuration `i986v': machine `i986v' not recognized - -`config.sub' is also distributed in the GDB source directory -(`gdb-7.3.1-gg2', for version 7.3.1-gg2). - - -File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB - -C.5 `configure' Options -======================= - -Here is a summary of the `configure' options and arguments that are -most often useful for building GDB. `configure' also has several other -options not listed here. *note (configure.info)What Configure Does::, -for a full explanation of `configure'. - - configure [--help] - [--prefix=DIR] - [--exec-prefix=DIR] - [--srcdir=DIRNAME] - [--norecursion] [--rm] - [--target=TARGET] - HOST - -You may introduce options with a single `-' rather than `--' if you -prefer; but you may abbreviate option names if you use `--'. - -`--help' - Display a quick summary of how to invoke `configure'. - -`--prefix=DIR' - Configure the source to install programs and files under directory - `DIR'. - -`--exec-prefix=DIR' - Configure the source to install programs under directory `DIR'. - -`--srcdir=DIRNAME' - *Warning: using this option requires GNU `make', or another `make' - that implements the `VPATH' feature.* - Use this option to make configurations in directories separate - from the GDB source directories. Among other things, you can use - this to build (or maintain) several configurations simultaneously, - in separate directories. `configure' writes - configuration-specific files in the current directory, but - arranges for them to use the source in the directory DIRNAME. - `configure' creates directories under the working directory in - parallel to the source directories below DIRNAME. - -`--norecursion' - Configure only the directory level where `configure' is executed; - do not propagate configuration to subdirectories. - -`--target=TARGET' - Configure GDB for cross-debugging programs running on the specified - TARGET. Without this option, GDB is configured to debug programs - that run on the same machine (HOST) as GDB itself. - - There is no convenient way to generate a list of all available - targets. - -`HOST ...' - Configure GDB to run on the specified HOST. - - There is no convenient way to generate a list of all available - hosts. - - There are many other options available as well, but they are -generally needed for special purposes only. - - -File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB - -C.6 System-wide configuration and settings -========================================== - -GDB can be configured to have a system-wide init file; this file will -be read and executed at startup (*note What GDB does during startup: -Startup.). - - Here is the corresponding configure option: - -`--with-system-gdbinit=FILE' - Specify that the default location of the system-wide init file is - FILE. - - If GDB has been configured with the option `--prefix=$prefix', it -may be subject to relocation. Two possible cases: - - * If the default location of this init file contains `$prefix', it - will be subject to relocation. Suppose that the configure options - are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'; - if GDB is moved from `$prefix' to `$install', the system init file - is looked for as `$install/etc/gdbinit' instead of - `$prefix/etc/gdbinit'. - - * By contrast, if the default location does not contain the prefix, - it will not be relocated. E.g. if GDB has been configured with - `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', - then GDB will always look for `/usr/share/gdb/gdbinit', wherever - GDB is installed. - - -File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top - -Appendix D Maintenance Commands -******************************* - -In addition to commands intended for GDB users, GDB includes a number -of commands intended for GDB developers, that are not documented -elsewhere in this manual. These commands are provided here for -reference. (For commands that turn on debugging messages, see *note -Debugging Output::.) - -`maint agent EXPRESSION' -`maint agent-eval EXPRESSION' - Translate the given EXPRESSION into remote agent bytecodes. This - command is useful for debugging the Agent Expression mechanism - (*note Agent Expressions::). The `agent' version produces an - expression useful for data collection, such as by tracepoints, - while `maint agent-eval' produces an expression that evaluates - directly to a result. For instance, a collection expression for - `globa + globb' will include bytecodes to record four bytes of - memory at each of the addresses of `globa' and `globb', while - discarding the result of the addition, while an evaluation - expression will do the addition and return the sum. - -`maint info breakpoints' - Using the same format as `info breakpoints', display both the - breakpoints you've set explicitly, and those GDB is using for - internal purposes. Internal breakpoints are shown with negative - breakpoint numbers. The type column identifies what kind of - breakpoint is shown: - - `breakpoint' - Normal, explicitly set breakpoint. - - `watchpoint' - Normal, explicitly set watchpoint. - - `longjmp' - Internal breakpoint, used to handle correctly stepping through - `longjmp' calls. - - `longjmp resume' - Internal breakpoint at the target of a `longjmp'. - - `until' - Temporary internal breakpoint used by the GDB `until' command. - - `finish' - Temporary internal breakpoint used by the GDB `finish' - command. - - `shlib events' - Shared library events. - - -`set displaced-stepping' -`show displaced-stepping' - Control whether or not GDB will do "displaced stepping" if the - target supports it. Displaced stepping is a way to single-step - over breakpoints without removing them from the inferior, by - executing an out-of-line copy of the instruction that was - originally at the breakpoint location. It is also known as - out-of-line single-stepping. - - `set displaced-stepping on' - If the target architecture supports it, GDB will use - displaced stepping to step over breakpoints. - - `set displaced-stepping off' - GDB will not use displaced stepping to step over breakpoints, - even if such is supported by the target architecture. - - `set displaced-stepping auto' - This is the default mode. GDB will use displaced stepping - only if non-stop mode is active (*note Non-Stop Mode::) and - the target architecture supports displaced stepping. - -`maint check-symtabs' - Check the consistency of psymtabs and symtabs. - -`maint cplus first_component NAME' - Print the first C++ class/namespace component of NAME. - -`maint cplus namespace' - Print the list of possible C++ namespaces. - -`maint demangle NAME' - Demangle a C++ or Objective-C mangled NAME. - -`maint deprecate COMMAND [REPLACEMENT]' -`maint undeprecate COMMAND' - Deprecate or undeprecate the named COMMAND. Deprecated commands - cause GDB to issue a warning when you use them. The optional - argument REPLACEMENT says which newer command should be used in - favor of the deprecated one; if it is given, GDB will mention the - replacement as part of the warning. - -`maint dump-me' - Cause a fatal signal in the debugger and force it to dump its core. - This is supported only on systems which support aborting a program - with the `SIGQUIT' signal. - -`maint internal-error [MESSAGE-TEXT]' -`maint internal-warning [MESSAGE-TEXT]' - Cause GDB to call the internal function `internal_error' or - `internal_warning' and hence behave as though an internal error or - internal warning has been detected. In addition to reporting the - internal problem, these functions give the user the opportunity to - either quit GDB or create a core file of the current GDB session. - - These commands take an optional parameter MESSAGE-TEXT that is - used as the text of the error or warning message. - - Here's an example of using `internal-error': - - (gdb) maint internal-error testing, 1, 2 - .../maint.c:121: internal-error: testing, 1, 2 - A problem internal to GDB has been detected. Further - debugging may prove unreliable. - Quit this debugging session? (y or n) n - Create a core file? (y or n) n - (gdb) - -`maint set internal-error ACTION [ask|yes|no]' -`maint show internal-error ACTION' -`maint set internal-warning ACTION [ask|yes|no]' -`maint show internal-warning ACTION' - When GDB reports an internal problem (error or warning) it gives - the user the opportunity to both quit GDB and create a core file - of the current GDB session. These commands let you override the - default behaviour for each particular ACTION, described in the - table below. - - `quit' - You can specify that GDB should always (yes) or never (no) - quit. The default is to ask the user what to do. - - `corefile' - You can specify that GDB should always (yes) or never (no) - create a core file. The default is to ask the user what to - do. - -`maint packet TEXT' - If GDB is talking to an inferior via the serial protocol, then - this command sends the string TEXT to the inferior, and displays - the response packet. GDB supplies the initial `$' character, the - terminating `#' character, and the checksum. - -`maint print architecture [FILE]' - Print the entire architecture configuration. The optional argument - FILE names the file where the output goes. - -`maint print c-tdesc' - Print the current target description (*note Target Descriptions::) - as a C source file. The created source file can be used in GDB - when an XML parser is not available to parse the description. - -`maint print dummy-frames' - Prints the contents of GDB's internal dummy-frame stack. - - (gdb) b add - ... - (gdb) print add(2,3) - Breakpoint 2, add (a=2, b=3) at ... - 58 return (a + b); - The program being debugged stopped while in a function called from GDB. - ... - (gdb) maint print dummy-frames - 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 - top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} - call_lo=0x01014000 call_hi=0x01014001 - (gdb) - - Takes an optional file parameter. - -`maint print registers [FILE]' -`maint print raw-registers [FILE]' -`maint print cooked-registers [FILE]' -`maint print register-groups [FILE]' - Print GDB's internal register data structures. - - The command `maint print raw-registers' includes the contents of - the raw register cache; the command `maint print cooked-registers' - includes the (cooked) value of all registers, including registers - which aren't available on the target nor visible to user; and the - command `maint print register-groups' includes the groups that each - register is a member of. *Note Registers: (gdbint)Registers. - - These commands take an optional parameter, a file name to which to - write the information. - -`maint print reggroups [FILE]' - Print GDB's internal register group data structures. The optional - argument FILE tells to what file to write the information. - - The register groups info looks like this: - - (gdb) maint print reggroups - Group Type - general user - float user - all user - vector user - system user - save internal - restore internal - -`flushregs' - This command forces GDB to flush its internal register cache. - -`maint print objfiles' - Print a dump of all known object files. For each object file, this - command prints its name, address in memory, and all of its psymtabs - and symtabs. - -`maint print section-scripts [REGEXP]' - Print a dump of scripts specified in the `.debug_gdb_section' - section. If REGEXP is specified, only print scripts loaded by - object files matching REGEXP. For each script, this command - prints its name as specified in the objfile, and the full path if - known. *Note .debug_gdb_scripts section::. - -`maint print statistics' - This command prints, for each object file in the program, various - data about that object file followed by the byte cache ("bcache") - statistics for the object file. The objfile data includes the - number of minimal, partial, full, and stabs symbols, the number of - types defined by the objfile, the number of as yet unexpanded psym - tables, the number of line tables and string tables, and the - amount of memory used by the various tables. The bcache - statistics include the counts, sizes, and counts of duplicates of - all and unique objects, max, average, and median entry size, total - memory used and its overhead and savings, and various measures of - the hash table size and chain lengths. - -`maint print target-stack' - A "target" is an interface between the debugger and a particular - kind of file or process. Targets can be stacked in "strata", so - that more than one target can potentially respond to a request. - In particular, memory accesses will walk down the stack of targets - until they find a target that is interested in handling that - particular address. - - This command prints a short description of each layer that was - pushed on the "target stack", starting from the top layer down to - the bottom one. - -`maint print type EXPR' - Print the type chain for a type specified by EXPR. The argument - can be either a type name or a symbol. If it is a symbol, the - type of that symbol is described. The type chain produced by this - command is a recursive definition of the data type as stored in - GDB's data structures, including its flags and contained types. - -`maint set dwarf2 always-disassemble' - -`maint show dwarf2 always-disassemble' - Control the behavior of `info address' when using DWARF debugging - information. - - The default is `off', which means that GDB should try to describe - a variable's location in an easily readable format. When `on', - GDB will instead display the DWARF location expression in an - assembly-like format. Note that some locations are too complex - for GDB to describe simply; in this case you will always see the - disassembly form. - - Here is an example of the resulting disassembly: - - (gdb) info addr argc - Symbol "argc" is a complex DWARF expression: - 1: DW_OP_fbreg 0 - - For more information on these expressions, see the DWARF standard - (http://www.dwarfstd.org/). - -`maint set dwarf2 max-cache-age' -`maint show dwarf2 max-cache-age' - Control the DWARF 2 compilation unit cache. - - In object files with inter-compilation-unit references, such as - those produced by the GCC option `-feliminate-dwarf2-dups', the - DWARF 2 reader needs to frequently refer to previously read - compilation units. This setting controls how long a compilation - unit will remain in the cache if it is not referenced. A higher - limit means that cached compilation units will be stored in memory - longer, and more total memory will be used. Setting it to zero - disables caching, which will slow down GDB startup, but reduce - memory consumption. - -`maint set profile' -`maint show profile' - Control profiling of GDB. - - Profiling will be disabled until you use the `maint set profile' - command to enable it. When you enable profiling, the system will - begin collecting timing and execution count data; when you disable - profiling or exit GDB, the results will be written to a log file. - Remember that if you use profiling, GDB will overwrite the - profiling log file (often called `gmon.out'). If you have a - record of important profiling data in a `gmon.out' file, be sure - to move it to a safe location. - - Configuring with `--enable-profiling' arranges for GDB to be - compiled with the `-pg' compiler option. - -`maint set show-debug-regs' -`maint show show-debug-regs' - Control whether to show variables that mirror the hardware debug - registers. Use `ON' to enable, `OFF' to disable. If enabled, the - debug registers values are shown when GDB inserts or removes a - hardware breakpoint or watchpoint, and when the inferior triggers - a hardware-assisted breakpoint or watchpoint. - -`maint set show-all-tib' -`maint show show-all-tib' - Control whether to show all non zero areas within a 1k block - starting at thread local base, when using the `info w32 - thread-information-block' command. - -`maint space' - Control whether to display memory usage for each command. If set - to a nonzero value, GDB will display how much memory each command - took, following the command's own output. This can also be - requested by invoking GDB with the `--statistics' command-line - switch (*note Mode Options::). - -`maint time' - Control whether to display the execution time for each command. If - set to a nonzero value, GDB will display how much time it took to - execute each command, following the command's own output. The - time is not printed for the commands that run the target, since - there's no mechanism currently to compute how much time was spend - by GDB and how much time was spend by the program been debugged. - it's not possibly currently This can also be requested by invoking - GDB with the `--statistics' command-line switch (*note Mode - Options::). - -`maint translate-address [SECTION] ADDR' - Find the symbol stored at the location specified by the address - ADDR and an optional section name SECTION. If found, GDB prints - the name of the closest symbol and an offset from the symbol's - location to the specified address. This is similar to the `info - address' command (*note Symbols::), except that this command also - allows to find symbols in other sections. - - If section was not specified, the section in which the symbol was - found is also printed. For dynamically linked executables, the - name of executable or shared library containing the symbol is - printed as well. - - - The following command is useful for non-interactive invocations of -GDB, such as in the test suite. - -`set watchdog NSEC' - Set the maximum number of seconds GDB will wait for the target - operation to finish. If this time expires, GDB reports and error - and the command is aborted. - -`show watchdog' - Show the current setting of the target wait timeout. - - -File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top - -Appendix E GDB Remote Serial Protocol -************************************* - -* Menu: - -* Overview:: -* Packets:: -* Stop Reply Packets:: -* General Query Packets:: -* Architecture-Specific Protocol Details:: -* Tracepoint Packets:: -* Host I/O Packets:: -* Interrupts:: -* Notification Packets:: -* Remote Non-Stop:: -* Packet Acknowledgment:: -* Examples:: -* File-I/O Remote Protocol Extension:: -* Library List Format:: -* Memory Map Format:: -* Thread List Format:: -* Traceframe Info Format:: - - -File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol - -E.1 Overview -============ - -There may be occasions when you need to know something about the -protocol--for example, if there is only one serial port to your target -machine, you might want your program to do something special if it -recognizes a packet meant for GDB. - - In the examples below, `->' and `<-' are used to indicate -transmitted and received data, respectively. - - All GDB commands and responses (other than acknowledgments and -notifications, see *note Notification Packets::) are sent as a PACKET. -A PACKET is introduced with the character `$', the actual PACKET-DATA, -and the terminating character `#' followed by a two-digit CHECKSUM: - - `$'PACKET-DATA`#'CHECKSUM - The two-digit CHECKSUM is computed as the modulo 256 sum of all -characters between the leading `$' and the trailing `#' (an eight bit -unsigned checksum). - - Implementors should note that prior to GDB 5.0 the protocol -specification also included an optional two-digit SEQUENCE-ID: - - `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM - -That SEQUENCE-ID was appended to the acknowledgment. GDB has never -output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 -must not accept SEQUENCE-ID. - - When either the host or the target machine receives a packet, the -first response expected is an acknowledgment: either `+' (to indicate -the package was received correctly) or `-' (to request retransmission): - - -> `$'PACKET-DATA`#'CHECKSUM - <- `+' - The `+'/`-' acknowledgments can be disabled once a connection is -established. *Note Packet Acknowledgment::, for details. - - The host (GDB) sends COMMANDs, and the target (the debugging stub -incorporated in your program) sends a RESPONSE. In the case of step -and continue COMMANDs, the response is only sent when the operation has -completed, and the target has again stopped all threads in all attached -processes. This is the default all-stop mode behavior, but the remote -protocol also supports GDB's non-stop execution mode; see *note Remote -Non-Stop::, for details. - - PACKET-DATA consists of a sequence of characters with the exception -of `#' and `$' (see `X' packet for additional exceptions). - - Fields within the packet should be separated using `,' `;' or `:'. -Except where otherwise noted all numbers are represented in HEX with -leading zeros suppressed. - - Implementors should note that prior to GDB 5.0, the character `:' -could not appear as the third character in a packet (as it would -potentially conflict with the SEQUENCE-ID). - - Binary data in most packets is encoded either as two hexadecimal -digits per byte of binary data. This allowed the traditional remote -protocol to work over connections which were only seven-bit clean. -Some packets designed more recently assume an eight-bit clean -connection, and use a more efficient encoding to send and receive -binary data. - - The binary data representation uses `7d' (ASCII `}') as an escape -character. Any escaped byte is transmitted as the escape character -followed by the original character XORed with `0x20'. For example, the -byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The -bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}') -must always be escaped. Responses sent by the stub must also escape -`0x2a' (ASCII `*'), so that it is not interpreted as the start of a -run-length encoded sequence (described next). - - Response DATA can be run-length encoded to save space. Run-length -encoding replaces runs of identical characters with one instance of the -repeated character, followed by a `*' and a repeat count. The repeat -count is itself sent encoded, to avoid binary characters in DATA: a -value of N is sent as `N+29'. For a repeat count greater or equal to -3, this produces a printable ASCII character, e.g. a space (ASCII code -32) for a repeat count of 3. (This is because run-length encoding -starts to win for counts 3 or more.) Thus, for example, `0* ' is a -run-length encoding of "0000": the space character after `*' means -repeat the leading `0' `32 - 29 = 3' more times. - - The printable characters `#' and `$' or with a numeric value greater -than 126 must not be used. Runs of six repeats (`#') or seven repeats -(`$') can be expanded using a repeat count of only five (`"'). For -example, `00000000' can be encoded as `0*"00'. - - The error response returned for some packets includes a two character -error number. That number is not well defined. - - For any COMMAND not supported by the stub, an empty response -(`$#00') should be returned. That way it is possible to extend the -protocol. A newer GDB can tell if a packet is supported based on that -response. - - A stub is required to support the `g', `G', `m', `M', `c', and `s' -COMMANDs. All other COMMANDs are optional. - - -File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol - -E.2 Packets -=========== - -The following table provides a complete list of all currently defined -COMMANDs and their corresponding response DATA. *Note File-I/O Remote -Protocol Extension::, for details about the File I/O extension of the -remote protocol. - - Each packet's description has a template showing the packet's overall -syntax, followed by an explanation of the packet's meaning. We include -spaces in some of the templates for clarity; these are not part of the -packet's syntax. No GDB packet uses spaces to separate its components. -For example, a template like `foo BAR BAZ' describes a packet beginning -with the three ASCII bytes `foo', followed by a BAR, followed directly -by a BAZ. GDB does not transmit a space character between the `foo' -and the BAR, or between the BAR and the BAZ. - - Several packets and replies include a THREAD-ID field to identify a -thread. Normally these are positive numbers with a target-specific -interpretation, formatted as big-endian hex strings. A THREAD-ID can -also be a literal `-1' to indicate all threads, or `0' to pick any -thread. - - In addition, the remote protocol supports a multiprocess feature in -which the THREAD-ID syntax is extended to optionally include both -process and thread ID fields, as `pPID.TID'. The PID (process) and TID -(thread) components each have the format described above: a positive -number with target-specific interpretation formatted as a big-endian -hex string, literal `-1' to indicate all processes or threads -(respectively), or `0' to indicate an arbitrary process or thread. -Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It -is an error to specify all processes but a specific thread, such as -`p-1.TID'. Note that the `p' prefix is _not_ used for those packets -and replies explicitly documented to include a process ID, rather than -a THREAD-ID. - - The multiprocess THREAD-ID syntax extensions are only used if both -GDB and the stub report support for the `multiprocess' feature using -`qSupported'. *Note multiprocess extensions::, for more information. - - Note that all packet forms beginning with an upper- or lower-case -letter, other than those described here, are reserved for future use. - - Here are the packet descriptions. - -`!' - Enable extended mode. In extended mode, the remote server is made - persistent. The `R' packet is used to restart the program being - debugged. - - Reply: - `OK' - The remote target both supports and has enabled extended mode. - -`?' - Indicate the reason the target halted. The reply is the same as - for step and continue. This packet has a special interpretation - when the target is in non-stop mode; see *note Remote Non-Stop::. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`A ARGLEN,ARGNUM,ARG,...' - Initialized `argv[]' array passed into program. ARGLEN specifies - the number of bytes in the hex encoded byte stream ARG. See - `gdbserver' for more details. - - Reply: - `OK' - The arguments were set. - - `E NN' - An error occurred. - -`b BAUD' - (Don't use this packet; its behavior is not well-defined.) Change - the serial line speed to BAUD. - - JTC: _When does the transport layer state change? When it's - received, or after the ACK is transmitted. In either case, there - are problems if the command or the acknowledgment packet is - dropped._ - - Stan: _If people really wanted to add something like this, and get - it working for the first time, they ought to modify ser-unix.c to - send some kind of out-of-band message to a specially-setup stub - and have the switch happen "in between" packets, so that from - remote protocol's point of view, nothing actually happened._ - -`B ADDR,MODE' - Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR. - - Don't use this packet. Use the `Z' and `z' packets instead (*note - insert breakpoint or watchpoint packet::). - -`bc' - Backward continue. Execute the target system in reverse. No - parameter. *Note Reverse Execution::, for more information. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`bs' - Backward single step. Execute one instruction in reverse. No - parameter. *Note Reverse Execution::, for more information. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`c [ADDR]' - Continue. ADDR is address to resume. If ADDR is omitted, resume - at current address. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`C SIG[;ADDR]' - Continue with signal SIG (hex signal number). If `;ADDR' is - omitted, resume at same address. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`d' - Toggle debug flag. - - Don't use this packet; instead, define a general set packet (*note - General Query Packets::). - -`D' -`D;PID' - The first form of the packet is used to detach GDB from the remote - system. It is sent to the remote target before GDB disconnects - via the `detach' command. - - The second form, including a process ID, is used when multiprocess - protocol extensions are enabled (*note multiprocess extensions::), - to detach only a specific process. The PID is specified as a - big-endian hex string. - - Reply: - `OK' - for success - - `E NN' - for an error - -`F RC,EE,CF;XX' - A reply from GDB to an `F' packet sent by the target. This is - part of the File-I/O protocol extension. *Note File-I/O Remote - Protocol Extension::, for the specification. - -`g' - Read general registers. - - Reply: - `XX...' - Each byte of register data is described by two hex digits. - The bytes with the register are transmitted in target byte - order. The size of each register and their position within - the `g' packet are determined by the GDB internal gdbarch - functions `DEPRECATED_REGISTER_RAW_SIZE' and - `gdbarch_register_name'. The specification of several - standard `g' packets is specified below. - - When reading registers from a trace frame (*note Using the - Collected Data: Analyze Collected Data.), the stub may also - return a string of literal `x''s in place of the register - data digits, to indicate that the corresponding register has - not been collected, thus its value is unavailable. For - example, for an architecture with 4 registers of 4 bytes - each, the following reply indicates to GDB that registers 0 - and 2 have not been collected, while registers 1 and 3 have - been collected, and both have zero value: - - -> `g' - <- `xxxxxxxx00000000xxxxxxxx00000000' - - `E NN' - for an error. - -`G XX...' - Write general registers. *Note read registers packet::, for a - description of the XX... data. - - Reply: - `OK' - for success - - `E NN' - for an error - -`H C THREAD-ID' - Set thread for subsequent operations (`m', `M', `g', `G', et.al.). - C depends on the operation to be performed: it should be `c' for - step and continue operations, `g' for other operations. The - thread designator THREAD-ID has the format and interpretation - described in *note thread-id syntax::. - - Reply: - `OK' - for success - - `E NN' - for an error - -`i [ADDR[,NNN]]' - Step the remote target by a single clock cycle. If `,NNN' is - present, cycle step NNN cycles. If ADDR is present, cycle step - starting at that address. - -`I' - Signal, then cycle step. *Note step with signal packet::. *Note - cycle step packet::. - -`k' - Kill request. - - FIXME: _There is no description of how to operate when a specific - thread context has been selected (i.e. does 'k' kill only that - thread?)_. - -`m ADDR,LENGTH' - Read LENGTH bytes of memory starting at address ADDR. Note that - ADDR may not be aligned to any particular boundary. - - The stub need not use any particular size or alignment when - gathering data from memory for the response; even if ADDR is - word-aligned and LENGTH is a multiple of the word size, the stub - is free to use byte accesses, or not. For this reason, this - packet may not be suitable for accessing memory-mapped I/O devices. - - Reply: - `XX...' - Memory contents; each byte is transmitted as a two-digit - hexadecimal number. The reply may contain fewer bytes than - requested if the server was able to read only part of the - region of memory. - - `E NN' - NN is errno - -`M ADDR,LENGTH:XX...' - Write LENGTH bytes of memory starting at address ADDR. XX... is - the data; each byte is transmitted as a two-digit hexadecimal - number. - - Reply: - `OK' - for success - - `E NN' - for an error (this includes the case where only part of the - data was written). - -`p N' - Read the value of register N; N is in hex. *Note read registers - packet::, for a description of how the returned register value is - encoded. - - Reply: - `XX...' - the register's value - - `E NN' - for an error - - `' - Indicating an unrecognized QUERY. - -`P N...=R...' - Write register N... with value R.... The register number N is in - hexadecimal, and R... contains two hex digits for each byte in the - register (target byte order). - - Reply: - `OK' - for success - - `E NN' - for an error - -`q NAME PARAMS...' -`Q NAME PARAMS...' - General query (`q') and set (`Q'). These packets are described - fully in *note General Query Packets::. - -`r' - Reset the entire system. - - Don't use this packet; use the `R' packet instead. - -`R XX' - Restart the program being debugged. XX, while needed, is ignored. - This packet is only available in extended mode (*note extended - mode::). - - The `R' packet has no reply. - -`s [ADDR]' - Single step. ADDR is the address at which to resume. If ADDR is - omitted, resume at same address. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`S SIG[;ADDR]' - Step with signal. This is analogous to the `C' packet, but - requests a single-step, rather than a normal resumption of - execution. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`t ADDR:PP,MM' - Search backwards starting at address ADDR for a match with pattern - PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 - digits. - -`T THREAD-ID' - Find out if the thread THREAD-ID is alive. *Note thread-id - syntax::. - - Reply: - `OK' - thread is still alive - - `E NN' - thread is dead - -`v' - Packets starting with `v' are identified by a multi-letter name, - up to the first `;' or `?' (or the end of the packet). - -`vAttach;PID' - Attach to a new process with the specified process ID PID. The - process ID is a hexadecimal integer identifying the process. In - all-stop mode, all threads in the attached process are stopped; in - non-stop mode, it may be attached without being stopped if that is - supported by the target. - - This packet is only available in extended mode (*note extended - mode::). - - Reply: - `E NN' - for an error - - `Any stop packet' - for success in all-stop mode (*note Stop Reply Packets::) - - `OK' - for success in non-stop mode (*note Remote Non-Stop::) - -`vCont[;ACTION[:THREAD-ID]]...' - Resume the inferior, specifying different actions for each thread. - If an action is specified with no THREAD-ID, then it is applied to - any threads that don't have a specific action specified; if no - default action is specified then other threads should remain - stopped in all-stop mode and in their current state in non-stop - mode. Specifying multiple default actions is an error; specifying - no actions is also an error. Thread IDs are specified using the - syntax described in *note thread-id syntax::. - - Currently supported actions are: - - `c' - Continue. - - `C SIG' - Continue with signal SIG. The signal SIG should be two hex - digits. - - `s' - Step. - - `S SIG' - Step with signal SIG. The signal SIG should be two hex - digits. - - `t' - Stop. - - The optional argument ADDR normally associated with the `c', `C', - `s', and `S' packets is not supported in `vCont'. - - The `t' action is only relevant in non-stop mode (*note Remote - Non-Stop::) and may be ignored by the stub otherwise. A stop - reply should be generated for any affected thread not already - stopped. When a thread is stopped by means of a `t' action, the - corresponding stop reply should indicate that the thread has - stopped with signal `0', regardless of whether the target uses - some other signal as an implementation detail. - - Reply: *Note Stop Reply Packets::, for the reply specifications. - -`vCont?' - Request a list of actions supported by the `vCont' packet. - - Reply: - `vCont[;ACTION...]' - The `vCont' packet is supported. Each ACTION is a supported - command in the `vCont' packet. - - `' - The `vCont' packet is not supported. - -`vFile:OPERATION:PARAMETER...' - Perform a file operation on the target system. For details, see - *note Host I/O Packets::. - -`vFlashErase:ADDR,LENGTH' - Direct the stub to erase LENGTH bytes of flash starting at ADDR. - The region may enclose any number of flash blocks, but its start - and end must fall on block boundaries, as indicated by the flash - block size appearing in the memory map (*note Memory Map - Format::). GDB groups flash memory programming operations - together, and sends a `vFlashDone' request after each group; the - stub is allowed to delay erase operation until the `vFlashDone' - packet is received. - - The stub must support `vCont' if it reports support for - multiprocess extensions (*note multiprocess extensions::). Note - that in this case `vCont' actions can be specified to apply to all - threads in a process by using the `pPID.-1' form of the THREAD-ID. - - Reply: - `OK' - for success - - `E NN' - for an error - -`vFlashWrite:ADDR:XX...' - Direct the stub to write data to flash address ADDR. The data is - passed in binary form using the same encoding as for the `X' - packet (*note Binary Data::). The memory ranges specified by - `vFlashWrite' packets preceding a `vFlashDone' packet must not - overlap, and must appear in order of increasing addresses - (although `vFlashErase' packets for higher addresses may already - have been received; the ordering is guaranteed only between - `vFlashWrite' packets). If a packet writes to an address that was - neither erased by a preceding `vFlashErase' packet nor by some - other target-specific method, the results are unpredictable. - - Reply: - `OK' - for success - - `E.memtype' - for vFlashWrite addressing non-flash memory - - `E NN' - for an error - -`vFlashDone' - Indicate to the stub that flash programming operation is finished. - The stub is permitted to delay or batch the effects of a group of - `vFlashErase' and `vFlashWrite' packets until a `vFlashDone' - packet is received. The contents of the affected regions of flash - memory are unpredictable until the `vFlashDone' request is - completed. - -`vKill;PID' - Kill the process with the specified process ID. PID is a - hexadecimal integer identifying the process. This packet is used - in preference to `k' when multiprocess protocol extensions are - supported; see *note multiprocess extensions::. - - Reply: - `E NN' - for an error - - `OK' - for success - -`vRun;FILENAME[;ARGUMENT]...' - Run the program FILENAME, passing it each ARGUMENT on its command - line. The file and arguments are hex-encoded strings. If - FILENAME is an empty string, the stub may use a default program - (e.g. the last program run). The program is created in the stopped - state. - - This packet is only available in extended mode (*note extended - mode::). - - Reply: - `E NN' - for an error - - `Any stop packet' - for success (*note Stop Reply Packets::) - -`vStopped' - In non-stop mode (*note Remote Non-Stop::), acknowledge a previous - stop reply and prompt for the stub to report another one. - - Reply: - `Any stop packet' - if there is another unreported stop event (*note Stop Reply - Packets::) - - `OK' - if there are no unreported stop events - -`X ADDR,LENGTH:XX...' - Write data to memory, where the data is transmitted in binary. - ADDR is address, LENGTH is number of bytes, `XX...' is binary data - (*note Binary Data::). - - Reply: - `OK' - for success - - `E NN' - for an error - -`z TYPE,ADDR,KIND' -`Z TYPE,ADDR,KIND' - Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint - starting at address ADDRESS of kind KIND. - - Each breakpoint and watchpoint packet TYPE is documented - separately. - - _Implementation notes: A remote target shall return an empty string - for an unrecognized breakpoint or watchpoint packet TYPE. A - remote target shall support either both or neither of a given - `ZTYPE...' and `zTYPE...' packet pair. To avoid potential - problems with duplicate packets, the operations should be - implemented in an idempotent way._ - -`z0,ADDR,KIND' -`Z0,ADDR,KIND' - Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR - of type KIND. - - A memory breakpoint is implemented by replacing the instruction at - ADDR with a software breakpoint or trap instruction. The KIND is - target-specific and typically indicates the size of the breakpoint - in bytes that should be inserted. E.g., the ARM and MIPS can - insert either a 2 or 4 byte breakpoint. Some architectures have - additional meanings for KIND; see *note Architecture-Specific - Protocol Details::. - - _Implementation note: It is possible for a target to copy or move - code that contains memory breakpoints (e.g., when implementing - overlays). The behavior of this packet, in the presence of such a - target, is not defined._ - - Reply: - `OK' - success - - `' - not supported - - `E NN' - for an error - -`z1,ADDR,KIND' -`Z1,ADDR,KIND' - Insert (`Z1') or remove (`z1') a hardware breakpoint at address - ADDR. - - A hardware breakpoint is implemented using a mechanism that is not - dependant on being able to modify the target's memory. KIND has - the same meaning as in `Z0' packets. - - _Implementation note: A hardware breakpoint is not affected by code - movement._ - - Reply: - `OK' - success - - `' - not supported - - `E NN' - for an error - -`z2,ADDR,KIND' -`Z2,ADDR,KIND' - Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND - is interpreted as the number of bytes to watch. - - Reply: - `OK' - success - - `' - not supported - - `E NN' - for an error - -`z3,ADDR,KIND' -`Z3,ADDR,KIND' - Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is - interpreted as the number of bytes to watch. - - Reply: - `OK' - success - - `' - not supported - - `E NN' - for an error - -`z4,ADDR,KIND' -`Z4,ADDR,KIND' - Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND - is interpreted as the number of bytes to watch. - - Reply: - `OK' - success - - `' - not supported - - `E NN' - for an error - - - -File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol - -E.3 Stop Reply Packets -====================== - -The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?' -packets can receive any of the below as a reply. Except for `?' and -`vStopped', that reply is only returned when the target halts. In the -below the exact meaning of "signal number" is defined by the header -`include/gdb/signals.h' in the GDB source code. - - As in the description of request packets, we include spaces in the -reply templates for clarity; these are not part of the reply packet's -syntax. No GDB stop reply packet uses spaces to separate its -components. - -`S AA' - The program received signal number AA (a two-digit hexadecimal - number). This is equivalent to a `T' response with no N:R pairs. - -`T AA N1:R1;N2:R2;...' - The program received signal number AA (a two-digit hexadecimal - number). This is equivalent to an `S' response, except that the - `N:R' pairs can carry values of important registers and other - information directly in the stop reply packet, reducing round-trip - latency. Single-step and breakpoint traps are reported this way. - Each `N:R' pair is interpreted as follows: - - * If N is a hexadecimal number, it is a register number, and the - corresponding R gives that register's value. R is a series - of bytes in target byte order, with each byte given by a - two-digit hex number. - - * If N is `thread', then R is the THREAD-ID of the stopped - thread, as specified in *note thread-id syntax::. - - * If N is `core', then R is the hexadecimal number of the core - on which the stop event was detected. - - * If N is a recognized "stop reason", it describes a more - specific event that stopped the target. The currently - defined stop reasons are listed below. AA should be `05', - the trap signal. At most one stop reason should be present. - - * Otherwise, GDB should ignore this `N:R' pair and go on to the - next; this allows us to extend the protocol in the future. - - The currently defined stop reasons are: - - `watch' - `rwatch' - `awatch' - The packet indicates a watchpoint hit, and R is the data - address, in hex. - - `library' - The packet indicates that the loaded libraries have changed. - GDB should use `qXfer:libraries:read' to fetch a new list of - loaded libraries. R is ignored. - - `replaylog' - The packet indicates that the target cannot continue replaying - logged execution events, because it has reached the end (or - the beginning when executing backward) of the log. The value - of R will be either `begin' or `end'. *Note Reverse - Execution::, for more information. - -`W AA' -`W AA ; process:PID' - The process exited, and AA is the exit status. This is only - applicable to certain targets. - - The second form of the response, including the process ID of the - exited process, can be used only when GDB has reported support for - multiprocess protocol extensions; see *note multiprocess - extensions::. The PID is formatted as a big-endian hex string. - -`X AA' -`X AA ; process:PID' - The process terminated with signal AA. - - The second form of the response, including the process ID of the - terminated process, can be used only when GDB has reported support - for multiprocess protocol extensions; see *note multiprocess - extensions::. The PID is formatted as a big-endian hex string. - -`O XX...' - `XX...' is hex encoding of ASCII data, to be written as the - program's console output. This can happen at any time while the - program is running and the debugger should continue to wait for - `W', `T', etc. This reply is not permitted in non-stop mode. - -`F CALL-ID,PARAMETER...' - CALL-ID is the identifier which says which host system call should - be called. This is just the name of the function. Translation - into the correct system call is only applicable as it's defined in - GDB. *Note File-I/O Remote Protocol Extension::, for a list of - implemented system calls. - - `PARAMETER...' is a list of parameters as defined for this very - system call. - - The target replies with this packet when it expects GDB to call a - host system call on behalf of the target. GDB replies with an - appropriate `F' packet and keeps up waiting for the next reply - packet from the target. The latest `C', `c', `S' or `s' action is - expected to be continued. *Note File-I/O Remote Protocol - Extension::, for more details. - - - -File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol - -E.4 General Query Packets -========================= - -Packets starting with `q' are "general query packets"; packets starting -with `Q' are "general set packets". General query and set packets are -a semi-unified form for retrieving and sending information to and from -the stub. - - The initial letter of a query or set packet is followed by a name -indicating what sort of thing the packet applies to. For example, GDB -may use a `qSymbol' packet to exchange symbol definitions with the -stub. These packet names follow some conventions: - - * The name must not contain commas, colons or semicolons. - - * Most GDB query and set packets have a leading upper case letter. - - * The names of custom vendor packets should use a company prefix, in - lower case, followed by a period. For example, packets designed at - the Acme Corporation might begin with `qacme.foo' (for querying - foos) or `Qacme.bar' (for setting bars). - - The name of a query or set packet should be separated from any -parameters by a `:'; the parameters themselves should be separated by -`,' or `;'. Stubs must be careful to match the full packet name, and -check for a separator or the end of the packet, in case two packet -names share a common prefix. New packets should not begin with `qC', -`qP', or `qL'(1). - - Like the descriptions of the other packets, each description here -has a template showing the packet's overall syntax, followed by an -explanation of the packet's meaning. We include spaces in some of the -templates for clarity; these are not part of the packet's syntax. No -GDB packet uses spaces to separate its components. - - Here are the currently defined query and set packets: - -`QAllow:OP:VAL...' - Specify which operations GDB expects to request of the target, as - a semicolon-separated list of operation name and value pairs. - Possible values for OP include `WriteReg', `WriteMem', - `InsertBreak', `InsertTrace', `InsertFastTrace', and `Stop'. VAL - is either 0, indicating that GDB will not request the operation, - or 1, indicating that it may. (The target can then use this to - set up its own internals optimally, for instance if the debugger - never expects to insert breakpoints, it may not need to install - its own trap handler.) - -`qC' - Return the current thread ID. - - Reply: - `QC THREAD-ID' - Where THREAD-ID is a thread ID as documented in *note - thread-id syntax::. - - `(anything else)' - Any other reply implies the old thread ID. - -`qCRC:ADDR,LENGTH' - Compute the CRC checksum of a block of memory using CRC-32 defined - in IEEE 802.3. The CRC is computed byte at a time, taking the most - significant bit of each byte first. The initial pattern code - `0xffffffff' is used to ensure leading zeros affect the CRC. - - _Note:_ This is the same CRC used in validating separate debug - files (*note Debugging Information in Separate Files: Separate - Debug Files.). However the algorithm is slightly different. When - validating separate debug files, the CRC is computed taking the - _least_ significant bit of each byte first, and the final result - is inverted to detect trailing zeros. - - Reply: - `E NN' - An error (such as memory fault) - - `C CRC32' - The specified memory region's checksum is CRC32. - -`qfThreadInfo' -`qsThreadInfo' - Obtain a list of all active thread IDs from the target (OS). - Since there may be too many active threads to fit into one reply - packet, this query works iteratively: it may require more than one - query/reply sequence to obtain the entire list of threads. The - first query of the sequence will be the `qfThreadInfo' query; - subsequent queries in the sequence will be the `qsThreadInfo' - query. - - NOTE: This packet replaces the `qL' query (see below). - - Reply: - `m THREAD-ID' - A single thread ID - - `m THREAD-ID,THREAD-ID...' - a comma-separated list of thread IDs - - `l' - (lower case letter `L') denotes end of list. - - In response to each query, the target will reply with a list of - one or more thread IDs, separated by commas. GDB will respond to - each reply with a request for more thread ids (using the `qs' form - of the query), until the target responds with `l' (lower-case ell, - for "last"). Refer to *note thread-id syntax::, for the format of - the THREAD-ID fields. - -`qGetTLSAddr:THREAD-ID,OFFSET,LM' - Fetch the address associated with thread local storage specified - by THREAD-ID, OFFSET, and LM. - - THREAD-ID is the thread ID associated with the thread for which to - fetch the TLS address. *Note thread-id syntax::. - - OFFSET is the (big endian, hex encoded) offset associated with the - thread local variable. (This offset is obtained from the debug - information associated with the variable.) - - LM is the (big endian, hex encoded) OS/ABI-specific encoding of the - the load module associated with the thread local storage. For - example, a GNU/Linux system will pass the link map address of the - shared object associated with the thread local storage under - consideration. Other operating environments may choose to - represent the load module differently, so the precise meaning of - this parameter will vary. - - Reply: - `XX...' - Hex encoded (big endian) bytes representing the address of - the thread local storage requested. - - `E NN' - An error occurred. NN are hex digits. - - `' - An empty reply indicates that `qGetTLSAddr' is not supported - by the stub. - -`qGetTIBAddr:THREAD-ID' - Fetch address of the Windows OS specific Thread Information Block. - - THREAD-ID is the thread ID associated with the thread. - - Reply: - `XX...' - Hex encoded (big endian) bytes representing the linear - address of the thread information block. - - `E NN' - An error occured. This means that either the thread was not - found, or the address could not be retrieved. - - `' - An empty reply indicates that `qGetTIBAddr' is not supported - by the stub. - -`qL STARTFLAG THREADCOUNT NEXTTHREAD' - Obtain thread information from RTOS. Where: STARTFLAG (one hex - digit) is one to indicate the first query and zero to indicate a - subsequent query; THREADCOUNT (two hex digits) is the maximum - number of threads the response packet can contain; and NEXTTHREAD - (eight hex digits), for subsequent queries (STARTFLAG is zero), is - returned in the response as ARGTHREAD. - - Don't use this packet; use the `qfThreadInfo' query instead (see - above). - - Reply: - `qM COUNT DONE ARGTHREAD THREAD...' - Where: COUNT (two hex digits) is the number of threads being - returned; DONE (one hex digit) is zero to indicate more - threads and one indicates no further threads; ARGTHREADID - (eight hex digits) is NEXTTHREAD from the request packet; - THREAD... is a sequence of thread IDs from the target. - THREADID (eight hex digits). See - `remote.c:parse_threadlist_response()'. - -`qOffsets' - Get section offsets that the target used when relocating the - downloaded image. - - Reply: - `Text=XXX;Data=YYY[;Bss=ZZZ]' - Relocate the `Text' section by XXX from its original address. - Relocate the `Data' section by YYY from its original address. - If the object file format provides segment information (e.g. - ELF `PT_LOAD' program headers), GDB will relocate entire - segments by the supplied offsets. - - _Note: while a `Bss' offset may be included in the response, - GDB ignores this and instead applies the `Data' offset to the - `Bss' section._ - - `TextSeg=XXX[;DataSeg=YYY]' - Relocate the first segment of the object file, which - conventionally contains program code, to a starting address - of XXX. If `DataSeg' is specified, relocate the second - segment, which conventionally contains modifiable data, to a - starting address of YYY. GDB will report an error if the - object file does not contain segment information, or does not - contain at least as many segments as mentioned in the reply. - Extra segments are kept at fixed offsets relative to the last - relocated segment. - -`qP MODE THREAD-ID' - Returns information on THREAD-ID. Where: MODE is a hex encoded 32 - bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). - - Don't use this packet; use the `qThreadExtraInfo' query instead - (see below). - - Reply: see `remote.c:remote_unpack_thread_info_response()'. - -`QNonStop:1' - -`QNonStop:0' - Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode. - *Note Remote Non-Stop::, for more information. - - Reply: - `OK' - The request succeeded. - - `E NN' - An error occurred. NN are hex digits. - - `' - An empty reply indicates that `QNonStop' is not supported by - the stub. - - This packet is not probed by default; the remote stub must request - it, by supplying an appropriate `qSupported' response (*note - qSupported::). Use of this packet is controlled by the `set - non-stop' command; *note Non-Stop Mode::. - -`QPassSignals: SIGNAL [;SIGNAL]...' - Each listed SIGNAL should be passed directly to the inferior - process. Signals are numbered identically to continue packets and - stop replies (*note Stop Reply Packets::). Each SIGNAL list item - should be strictly greater than the previous item. These signals - do not need to stop the inferior, or be reported to GDB. All - other signals should be reported to GDB. Multiple `QPassSignals' - packets do not combine; any earlier `QPassSignals' list is - completely replaced by the new list. This packet improves - performance when using `handle SIGNAL nostop noprint pass'. - - Reply: - `OK' - The request succeeded. - - `E NN' - An error occurred. NN are hex digits. - - `' - An empty reply indicates that `QPassSignals' is not supported - by the stub. - - Use of this packet is controlled by the `set remote pass-signals' - command (*note set remote pass-signals: Remote Configuration.). - This packet is not probed by default; the remote stub must request - it, by supplying an appropriate `qSupported' response (*note - qSupported::). - -`qRcmd,COMMAND' - COMMAND (hex encoded) is passed to the local interpreter for - execution. Invalid commands should be reported using the output - string. Before the final result packet, the target may also - respond with a number of intermediate `OOUTPUT' console output - packets. _Implementors should note that providing access to a - stubs's interpreter may have security implications_. - - Reply: - `OK' - A command response with no output. - - `OUTPUT' - A command response with the hex encoded output string OUTPUT. - - `E NN' - Indicate a badly formed request. - - `' - An empty reply indicates that `qRcmd' is not recognized. - - (Note that the `qRcmd' packet's name is separated from the command - by a `,', not a `:', contrary to the naming conventions above. - Please don't use this packet as a model for new packets.) - -`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' - Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and - LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes, - hex encoded. - - Reply: - `0' - The pattern was not found. - - `1,address' - The pattern was found at ADDRESS. - - `E NN' - A badly formed request or an error was encountered while - searching memory. - - `' - An empty reply indicates that `qSearch:memory' is not - recognized. - -`QStartNoAckMode' - Request that the remote stub disable the normal `+'/`-' protocol - acknowledgments (*note Packet Acknowledgment::). - - Reply: - `OK' - The stub has switched to no-acknowledgment mode. GDB - acknowledges this reponse, but neither the stub nor GDB shall - send or expect further `+'/`-' acknowledgments in the current - connection. - - `' - An empty reply indicates that the stub does not support - no-acknowledgment mode. - -`qSupported [:GDBFEATURE [;GDBFEATURE]... ]' - Tell the remote stub about features supported by GDB, and query - the stub for features it supports. This packet allows GDB and the - remote stub to take advantage of each others' features. - `qSupported' also consolidates multiple feature probes at startup, - to improve GDB performance--a single larger packet performs better - than multiple smaller probe packets on high-latency links. Some - features may enable behavior which must not be on by default, e.g. - because it would confuse older clients or stubs. Other features - may describe packets which could be automatically probed for, but - are not. These features must be reported before GDB will use - them. This "default unsupported" behavior is not appropriate for - all packets, but it helps to keep the initial connection time - under control with new versions of GDB which support increasing - numbers of packets. - - Reply: - `STUBFEATURE [;STUBFEATURE]...' - The stub supports or does not support each returned - STUBFEATURE, depending on the form of each STUBFEATURE (see - below for the possible forms). - - `' - An empty reply indicates that `qSupported' is not recognized, - or that no features needed to be reported to GDB. - - The allowed forms for each feature (either a GDBFEATURE in the - `qSupported' packet, or a STUBFEATURE in the response) are: - - `NAME=VALUE' - The remote protocol feature NAME is supported, and associated - with the specified VALUE. The format of VALUE depends on the - feature, but it must not include a semicolon. - - `NAME+' - The remote protocol feature NAME is supported, and does not - need an associated value. - - `NAME-' - The remote protocol feature NAME is not supported. - - `NAME?' - The remote protocol feature NAME may be supported, and GDB - should auto-detect support in some other way when it is - needed. This form will not be used for GDBFEATURE - notifications, but may be used for STUBFEATURE responses. - - Whenever the stub receives a `qSupported' request, the supplied - set of GDB features should override any previous request. This - allows GDB to put the stub in a known state, even if the stub had - previously been communicating with a different version of GDB. - - The following values of GDBFEATURE (for the packet sent by GDB) - are defined: - - `multiprocess' - This feature indicates whether GDB supports multiprocess - extensions to the remote protocol. GDB does not use such - extensions unless the stub also reports that it supports them - by including `multiprocess+' in its `qSupported' reply. - *Note multiprocess extensions::, for details. - - `xmlRegisters' - This feature indicates that GDB supports the XML target - description. If the stub sees `xmlRegisters=' with target - specific strings separated by a comma, it will report register - description. - - `qRelocInsn' - This feature indicates whether GDB supports the `qRelocInsn' - packet (*note Relocate instruction reply packet: Tracepoint - Packets.). - - Stubs should ignore any unknown values for GDBFEATURE. Any GDB - which sends a `qSupported' packet supports receiving packets of - unlimited length (earlier versions of GDB may reject overly long - responses). Additional values for GDBFEATURE may be defined in - the future to let the stub take advantage of new features in GDB, - e.g. incompatible improvements in the remote protocol--the - `multiprocess' feature is an example of such a feature. The - stub's reply should be independent of the GDBFEATURE entries sent - by GDB; first GDB describes all the features it supports, and then - the stub replies with all the features it supports. - - Similarly, GDB will silently ignore unrecognized stub feature - responses, as long as each response uses one of the standard forms. - - Some features are flags. A stub which supports a flag feature - should respond with a `+' form response. Other features require - values, and the stub should respond with an `=' form response. - - Each feature has a default value, which GDB will use if - `qSupported' is not available or if the feature is not mentioned - in the `qSupported' response. The default values are fixed; a - stub is free to omit any feature responses that match the defaults. - - Not all features can be probed, but for those which can, the - probing mechanism is useful: in some cases, a stub's internal - architecture may not allow the protocol layer to know some - information about the underlying target in advance. This is - especially common in stubs which may be configured for multiple - targets. - - These are the currently defined stub features and their properties: - - Feature Name Value Default Probe Allowed - Required - `PacketSize' Yes `-' No - `qXfer:auxv:read' No `-' Yes - `qXfer:features:read' No `-' Yes - `qXfer:libraries:read' No `-' Yes - `qXfer:memory-map:read' No `-' Yes - `qXfer:sdata:read' No `-' Yes - `qXfer:spu:read' No `-' Yes - `qXfer:spu:write' No `-' Yes - `qXfer:siginfo:read' No `-' Yes - `qXfer:siginfo:write' No `-' Yes - `qXfer:threads:read' No `-' Yes - `qXfer:traceframe-info:read'No `-' Yes - `QNonStop' No `-' Yes - `QPassSignals' No `-' Yes - `QStartNoAckMode' No `-' Yes - `multiprocess' No `-' No - `ConditionalTracepoints'No `-' No - `ReverseContinue' No `-' No - `ReverseStep' No `-' No - `TracepointSource' No `-' No - `QAllow' No `-' No - - These are the currently defined stub features, in more detail: - - `PacketSize=BYTES' - The remote stub can accept packets up to at least BYTES in - length. GDB will send packets up to this size for bulk - transfers, and will never send larger packets. This is a - limit on the data characters in the packet, including the - frame and checksum. There is no trailing NUL byte in a - remote protocol packet; if the stub stores packets in a - NUL-terminated format, it should allow an extra byte in its - buffer for the NUL. If this stub feature is not supported, - GDB guesses based on the size of the `g' packet response. - - `qXfer:auxv:read' - The remote stub understands the `qXfer:auxv:read' packet - (*note qXfer auxiliary vector read::). - - `qXfer:features:read' - The remote stub understands the `qXfer:features:read' packet - (*note qXfer target description read::). - - `qXfer:libraries:read' - The remote stub understands the `qXfer:libraries:read' packet - (*note qXfer library list read::). - - `qXfer:memory-map:read' - The remote stub understands the `qXfer:memory-map:read' packet - (*note qXfer memory map read::). - - `qXfer:sdata:read' - The remote stub understands the `qXfer:sdata:read' packet - (*note qXfer sdata read::). - - `qXfer:spu:read' - The remote stub understands the `qXfer:spu:read' packet - (*note qXfer spu read::). - - `qXfer:spu:write' - The remote stub understands the `qXfer:spu:write' packet - (*note qXfer spu write::). - - `qXfer:siginfo:read' - The remote stub understands the `qXfer:siginfo:read' packet - (*note qXfer siginfo read::). - - `qXfer:siginfo:write' - The remote stub understands the `qXfer:siginfo:write' packet - (*note qXfer siginfo write::). - - `qXfer:threads:read' - The remote stub understands the `qXfer:threads:read' packet - (*note qXfer threads read::). - - `qXfer:traceframe-info:read' - The remote stub understands the `qXfer:traceframe-info:read' - packet (*note qXfer traceframe info read::). - - `QNonStop' - The remote stub understands the `QNonStop' packet (*note - QNonStop::). - - `QPassSignals' - The remote stub understands the `QPassSignals' packet (*note - QPassSignals::). - - `QStartNoAckMode' - The remote stub understands the `QStartNoAckMode' packet and - prefers to operate in no-acknowledgment mode. *Note Packet - Acknowledgment::. - - `multiprocess' - The remote stub understands the multiprocess extensions to - the remote protocol syntax. The multiprocess extensions - affect the syntax of thread IDs in both packets and replies - (*note thread-id syntax::), and add process IDs to the `D' - packet and `W' and `X' replies. Note that reporting this - feature indicates support for the syntactic extensions only, - not that the stub necessarily supports debugging of more than - one process at a time. The stub must not use multiprocess - extensions in packet replies unless GDB has also indicated it - supports them in its `qSupported' request. - - `qXfer:osdata:read' - The remote stub understands the `qXfer:osdata:read' packet - ((*note qXfer osdata read::). - - `ConditionalTracepoints' - The remote stub accepts and implements conditional - expressions defined for tracepoints (*note Tracepoint - Conditions::). - - `ReverseContinue' - The remote stub accepts and implements the reverse continue - packet (*note bc::). - - `ReverseStep' - The remote stub accepts and implements the reverse step packet - (*note bs::). - - `TracepointSource' - The remote stub understands the `QTDPsrc' packet that supplies - the source form of tracepoint definitions. - - `QAllow' - The remote stub understands the `QAllow' packet. - - `StaticTracepoint' - The remote stub supports static tracepoints. - - -`qSymbol::' - Notify the target that GDB is prepared to serve symbol lookup - requests. Accept requests from the target for the values of - symbols. - - Reply: - `OK' - The target does not need to look up any (more) symbols. - - `qSymbol:SYM_NAME' - The target requests the value of symbol SYM_NAME (hex - encoded). GDB may provide the value by using the - `qSymbol:SYM_VALUE:SYM_NAME' message, described below. - -`qSymbol:SYM_VALUE:SYM_NAME' - Set the value of SYM_NAME to SYM_VALUE. - - SYM_NAME (hex encoded) is the name of a symbol whose value the - target has previously requested. - - SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot - supply a value for SYM_NAME, then this field will be empty. - - Reply: - `OK' - The target does not need to look up any (more) symbols. - - `qSymbol:SYM_NAME' - The target requests the value of a new symbol SYM_NAME (hex - encoded). GDB will continue to supply the values of symbols - (if available), until the target ceases to request them. - -`qTBuffer' - -`QTBuffer' - -`QTDisconnected' -`QTDP' -`QTDPsrc' -`QTDV' -`qTfP' -`qTfV' -`QTFrame' - *Note Tracepoint Packets::. - -`qThreadExtraInfo,THREAD-ID' - Obtain a printable string description of a thread's attributes from - the target OS. THREAD-ID is a thread ID; see *note thread-id - syntax::. This string may contain anything that the target OS - thinks is interesting for GDB to tell the user about the thread. - The string is displayed in GDB's `info threads' display. Some - examples of possible thread extra info strings are `Runnable', or - `Blocked on Mutex'. - - Reply: - `XX...' - Where `XX...' is a hex encoding of ASCII data, comprising the - printable string containing the extra information about the - thread's attributes. - - (Note that the `qThreadExtraInfo' packet's name is separated from - the command by a `,', not a `:', contrary to the naming - conventions above. Please don't use this packet as a model for new - packets.) - -`QTSave' - -`qTsP' - -`qTsV' -`QTStart' -`QTStop' -`QTinit' -`QTro' -`qTStatus' -`qTV' -`qTfSTM' -`qTsSTM' -`qTSTMat' - *Note Tracepoint Packets::. - -`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' - Read uninterpreted bytes from the target's special data area - identified by the keyword OBJECT. Request LENGTH bytes starting - at OFFSET bytes into the data. The content and encoding of ANNEX - is specific to OBJECT; it can supply additional details about what - data to access. - - Here are the specific requests of this form defined so far. All - `qXfer:OBJECT:read:...' requests use the same reply formats, - listed below. - - `qXfer:auxv:read::OFFSET,LENGTH' - Access the target's "auxiliary vector". *Note auxiliary - vector: OS Information. Note ANNEX must be empty. - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:features:read:ANNEX:OFFSET,LENGTH' - Access the "target description". *Note Target - Descriptions::. The annex specifies which XML document to - access. The main description is always loaded from the - `target.xml' annex. - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:libraries:read:ANNEX:OFFSET,LENGTH' - Access the target's list of loaded libraries. *Note Library - List Format::. The annex part of the generic `qXfer' packet - must be empty (*note qXfer read::). - - Targets which maintain a list of libraries in the program's - memory do not need to implement this packet; it is designed - for platforms where the operating system manages the list of - loaded libraries. - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:memory-map:read::OFFSET,LENGTH' - Access the target's "memory-map". *Note Memory Map Format::. - The annex part of the generic `qXfer' packet must be empty - (*note qXfer read::). - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:sdata:read::OFFSET,LENGTH' - Read contents of the extra collected static tracepoint marker - information. The annex part of the generic `qXfer' packet - must be empty (*note qXfer read::). *Note Tracepoint Action - Lists: Tracepoint Actions. - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:siginfo:read::OFFSET,LENGTH' - Read contents of the extra signal information on the target - system. The annex part of the generic `qXfer' packet must be - empty (*note qXfer read::). - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:spu:read:ANNEX:OFFSET,LENGTH' - Read contents of an `spufs' file on the target system. The - annex specifies which file to read; it must be of the form - `ID/NAME', where ID specifies an SPU context ID in the target - process, and NAME identifes the `spufs' file in that context - to be accessed. - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:threads:read::OFFSET,LENGTH' - Access the list of threads on target. *Note Thread List - Format::. The annex part of the generic `qXfer' packet must - be empty (*note qXfer read::). - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:traceframe-info:read::OFFSET,LENGTH' - Return a description of the current traceframe's contents. - *Note Traceframe Info Format::. The annex part of the generic - `qXfer' packet must be empty (*note qXfer read::). - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:osdata:read::OFFSET,LENGTH' - Access the target's "operating system information". *Note - Operating System Information::. - - - Reply: - `m DATA' - Data DATA (*note Binary Data::) has been read from the - target. There may be more data at a higher address (although - it is permitted to return `m' even for the last valid block - of data, as long as at least one byte of data was read). - DATA may have fewer bytes than the LENGTH in the request. - - `l DATA' - Data DATA (*note Binary Data::) has been read from the target. - There is no more data to be read. DATA may have fewer bytes - than the LENGTH in the request. - - `l' - The OFFSET in the request is at the end of the data. There - is no more data to be read. - - `E00' - The request was malformed, or ANNEX was invalid. - - `E NN' - The offset was invalid, or there was an error encountered - reading the data. NN is a hex-encoded `errno' value. - - `' - An empty reply indicates the OBJECT string was not recognized - by the stub, or that the object does not support reading. - -`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' - Write uninterpreted bytes into the target's special data area - identified by the keyword OBJECT, starting at OFFSET bytes into - the data. DATA... is the binary-encoded data (*note Binary - Data::) to be written. The content and encoding of ANNEX is - specific to OBJECT; it can supply additional details about what - data to access. - - Here are the specific requests of this form defined so far. All - `qXfer:OBJECT:write:...' requests use the same reply formats, - listed below. - - `qXfer:siginfo:write::OFFSET:DATA...' - Write DATA to the extra signal information on the target - system. The annex part of the generic `qXfer' packet must be - empty (*note qXfer write::). - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - `qXfer:spu:write:ANNEX:OFFSET:DATA...' - Write DATA to an `spufs' file on the target system. The - annex specifies which file to write; it must be of the form - `ID/NAME', where ID specifies an SPU context ID in the target - process, and NAME identifes the `spufs' file in that context - to be accessed. - - This packet is not probed by default; the remote stub must - request it, by supplying an appropriate `qSupported' response - (*note qSupported::). - - Reply: - `NN' - NN (hex encoded) is the number of bytes written. This may be - fewer bytes than supplied in the request. - - `E00' - The request was malformed, or ANNEX was invalid. - - `E NN' - The offset was invalid, or there was an error encountered - writing the data. NN is a hex-encoded `errno' value. - - `' - An empty reply indicates the OBJECT string was not recognized - by the stub, or that the object does not support writing. - -`qXfer:OBJECT:OPERATION:...' - Requests of this form may be added in the future. When a stub does - not recognize the OBJECT keyword, or its support for OBJECT does - not recognize the OPERATION keyword, the stub must respond with an - empty packet. - -`qAttached:PID' - Return an indication of whether the remote server attached to an - existing process or created a new process. When the multiprocess - protocol extensions are supported (*note multiprocess - extensions::), PID is an integer in hexadecimal format identifying - the target process. Otherwise, GDB will omit the PID field and - the query packet will be simplified as `qAttached'. - - This query is used, for example, to know whether the remote process - should be detached or killed when a GDB session is ended with the - `quit' command. - - Reply: - `1' - The remote server attached to an existing process. - - `0' - The remote server created a new process. - - `E NN' - A badly formed request or an error was encountered. - - - ---------- Footnotes ---------- - - (1) The `qP' and `qL' packets predate these conventions, and have -arguments without any terminator for the packet name; we suspect they -are in widespread use in places that are difficult to upgrade. The -`qC' packet has no arguments, but some existing stubs (e.g. RedBoot) -are known to not check for the end of the packet. - - -File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol - -E.5 Architecture-Specific Protocol Details -========================================== - -This section describes how the remote protocol is applied to specific -target architectures. Also see *note Standard Target Features::, for -details of XML target descriptions for each architecture. - -E.5.1 ARM ---------- - -E.5.1.1 Breakpoint Kinds -........................ - -These breakpoint kinds are defined for the `Z0' and `Z1' packets. - -2 - 16-bit Thumb mode breakpoint. - -3 - 32-bit Thumb mode (Thumb-2) breakpoint. - -4 - 32-bit ARM mode breakpoint. - - -E.5.2 MIPS ----------- - -E.5.2.1 Register Packet Format -.............................. - -The following `g'/`G' packets have previously been defined. In the -below, some thirty-two bit registers are transferred as sixty-four -bits. Those registers should be zero/sign extended (which?) to fill -the space allocated. Register bytes are transferred in target byte -order. The two nibbles within a register byte are transferred -most-significant - least-significant. - -MIPS32 - All registers are transferred as thirty-two bit quantities in the - order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 - floating-point registers; fsr; fir; fp. - -MIPS64 - All registers are transferred as sixty-four bit quantities - (including thirty-two bit registers such as `sr'). The ordering - is the same as `MIPS32'. - - - -File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol - -E.6 Tracepoint Packets -====================== - -Here we describe the packets GDB uses to implement tracepoints (*note -Tracepoints::). - -`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]' - Create a new tracepoint, number N, at ADDR. If ENA is `E', then - the tracepoint is enabled; if it is `D', then the tracepoint is - disabled. STEP is the tracepoint's step count, and PASS is its - pass count. If an `F' is present, then the tracepoint is to be a - fast tracepoint, and the FLEN is the number of bytes that the - target should copy elsewhere to make room for the tracepoint. If - an `X' is present, it introduces a tracepoint condition, which - consists of a hexadecimal length, followed by a comma and - hex-encoded bytes, in a manner similar to action encodings as - described below. If the trailing `-' is present, further `QTDP' - packets will follow to specify this tracepoint's actions. - - Replies: - `OK' - The packet was understood and carried out. - - `qRelocInsn' - *Note Relocate instruction reply packet: Tracepoint Packets. - - `' - The packet was not recognized. - -`QTDP:-N:ADDR:[S]ACTION...[-]' - Define actions to be taken when a tracepoint is hit. N and ADDR - must be the same as in the initial `QTDP' packet for this - tracepoint. This packet may only be sent immediately after - another `QTDP' packet that ended with a `-'. If the trailing `-' - is present, further `QTDP' packets will follow, specifying more - actions for this tracepoint. - - In the series of action packets for a given tracepoint, at most one - can have an `S' before its first ACTION. If such a packet is - sent, it and the following packets define "while-stepping" - actions. Any prior packets define ordinary actions -- that is, - those taken when the tracepoint is first hit. If no action packet - has an `S', then all the packets in the series specify ordinary - tracepoint actions. - - The `ACTION...' portion of the packet is a series of actions, - concatenated without separators. Each action has one of the - following forms: - - `R MASK' - Collect the registers whose bits are set in MASK. MASK is a - hexadecimal number whose I'th bit is set if register number I - should be collected. (The least significant bit is numbered - zero.) Note that MASK may be any number of digits long; it - may not fit in a 32-bit word. - - `M BASEREG,OFFSET,LEN' - Collect LEN bytes of memory starting at the address in - register number BASEREG, plus OFFSET. If BASEREG is `-1', - then the range has a fixed address: OFFSET is the address of - the lowest byte to collect. The BASEREG, OFFSET, and LEN - parameters are all unsigned hexadecimal values (the `-1' - value for BASEREG is a special case). - - `X LEN,EXPR' - Evaluate EXPR, whose length is LEN, and collect memory as it - directs. EXPR is an agent expression, as described in *note - Agent Expressions::. Each byte of the expression is encoded - as a two-digit hex number in the packet; LEN is the number of - bytes in the expression (and thus one-half the number of hex - digits in the packet). - - - Any number of actions may be packed together in a single `QTDP' - packet, as long as the packet does not exceed the maximum packet - length (400 bytes, for many stubs). There may be only one `R' - action per tracepoint, and it must precede any `M' or `X' actions. - Any registers referred to by `M' and `X' actions must be collected - by a preceding `R' action. (The "while-stepping" actions are - treated as if they were attached to a separate tracepoint, as far - as these restrictions are concerned.) - - Replies: - `OK' - The packet was understood and carried out. - - `qRelocInsn' - *Note Relocate instruction reply packet: Tracepoint Packets. - - `' - The packet was not recognized. - -`QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES' - Specify a source string of tracepoint N at address ADDR. This is - useful to get accurate reproduction of the tracepoints originally - downloaded at the beginning of the trace run. TYPE is the name of - the tracepoint part, such as `cond' for the tracepoint's - conditional expression (see below for a list of types), while - BYTES is the string, encoded in hexadecimal. - - START is the offset of the BYTES within the overall source string, - while SLEN is the total length of the source string. This is - intended for handling source strings that are longer than will fit - in a single packet. - - The available string types are `at' for the location, `cond' for - the conditional, and `cmd' for an action command. GDB sends a - separate packet for each command in the action list, in the same - order in which the commands are stored in the list. - - The target does not need to do anything with source strings except - report them back as part of the replies to the `qTfP'/`qTsP' query - packets. - - Although this packet is optional, and GDB will only send it if the - target replies with `TracepointSource' *Note General Query - Packets::, it makes both disconnected tracing and trace files much - easier to use. Otherwise the user must be careful that the - tracepoints in effect while looking at trace frames are identical - to the ones in effect during the trace run; even a small - discrepancy could cause `tdump' not to work, or a particular trace - frame not be found. - -`QTDV:N:VALUE' - Create a new trace state variable, number N, with an initial value - of VALUE, which is a 64-bit signed integer. Both N and VALUE are - encoded as hexadecimal values. GDB has the option of not using - this packet for initial values of zero; the target should simply - create the trace state variables as they are mentioned in - expressions. - -`QTFrame:N' - Select the N'th tracepoint frame from the buffer, and use the - register and memory contents recorded there to answer subsequent - request packets from GDB. - - A successful reply from the stub indicates that the stub has found - the requested frame. The response is a series of parts, - concatenated without separators, describing the frame we selected. - Each part has one of the following forms: - - `F F' - The selected frame is number N in the trace frame buffer; F - is a hexadecimal number. If F is `-1', then there was no - frame matching the criteria in the request packet. - - `T T' - The selected trace frame records a hit of tracepoint number T; - T is a hexadecimal number. - - -`QTFrame:pc:ADDR' - Like `QTFrame:N', but select the first tracepoint frame after the - currently selected frame whose PC is ADDR; ADDR is a hexadecimal - number. - -`QTFrame:tdp:T' - Like `QTFrame:N', but select the first tracepoint frame after the - currently selected frame that is a hit of tracepoint T; T is a - hexadecimal number. - -`QTFrame:range:START:END' - Like `QTFrame:N', but select the first tracepoint frame after the - currently selected frame whose PC is between START (inclusive) and - END (inclusive); START and END are hexadecimal numbers. - -`QTFrame:outside:START:END' - Like `QTFrame:range:START:END', but select the first frame - _outside_ the given range of addresses (exclusive). - -`QTStart' - Begin the tracepoint experiment. Begin collecting data from - tracepoint hits in the trace frame buffer. This packet supports - the `qRelocInsn' reply (*note Relocate instruction reply packet: - Tracepoint Packets.). - -`QTStop' - End the tracepoint experiment. Stop collecting trace frames. - -`QTinit' - Clear the table of tracepoints, and empty the trace frame buffer. - -`QTro:START1,END1:START2,END2:...' - Establish the given ranges of memory as "transparent". The stub - will answer requests for these ranges from memory's current - contents, if they were not collected as part of the tracepoint hit. - - GDB uses this to mark read-only regions of memory, like those - containing program code. Since these areas never change, they - should still have the same contents they did when the tracepoint - was hit, so there's no reason for the stub to refuse to provide - their contents. - -`QTDisconnected:VALUE' - Set the choice to what to do with the tracing run when GDB - disconnects from the target. A VALUE of 1 directs the target to - continue the tracing run, while 0 tells the target to stop tracing - if GDB is no longer in the picture. - -`qTStatus' - Ask the stub if there is a trace experiment running right now. - - The reply has the form: - - `TRUNNING[;FIELD]...' - RUNNING is a single digit `1' if the trace is presently - running, or `0' if not. It is followed by semicolon-separated - optional fields that an agent may use to report additional - status. - - - If the trace is not running, the agent may report any of several - explanations as one of the optional fields: - - `tnotrun:0' - No trace has been run yet. - - `tstop:0' - The trace was stopped by a user-originated stop command. - - `tfull:0' - The trace stopped because the trace buffer filled up. - - `tdisconnected:0' - The trace stopped because GDB disconnected from the target. - - `tpasscount:TPNUM' - The trace stopped because tracepoint TPNUM exceeded its pass - count. - - `terror:TEXT:TPNUM' - The trace stopped because tracepoint TPNUM had an error. The - string TEXT is available to describe the nature of the error - (for instance, a divide by zero in the condition expression). - TEXT is hex encoded. - - `tunknown:0' - The trace stopped for some other reason. - - - Additional optional fields supply statistical and other - information. Although not required, they are extremely useful for - users monitoring the progress of a trace run. If a trace has - stopped, and these numbers are reported, they must reflect the - state of the just-stopped trace. - - `tframes:N' - The number of trace frames in the buffer. - - `tcreated:N' - The total number of trace frames created during the run. This - may be larger than the trace frame count, if the buffer is - circular. - - `tsize:N' - The total size of the trace buffer, in bytes. - - `tfree:N' - The number of bytes still unused in the buffer. - - `circular:N' - The value of the circular trace buffer flag. `1' means that - the trace buffer is circular and old trace frames will be - discarded if necessary to make room, `0' means that the trace - buffer is linear and may fill up. - - `disconn:N' - The value of the disconnected tracing flag. `1' means that - tracing will continue after GDB disconnects, `0' means that - the trace run will stop. - - -`qTV:VAR' - Ask the stub for the value of the trace state variable number VAR. - - Replies: - `VVALUE' - The value of the variable is VALUE. This will be the current - value of the variable if the user is examining a running - target, or a saved value if the variable was collected in the - trace frame that the user is looking at. Note that multiple - requests may result in different reply values, such as when - requesting values while the program is running. - - `U' - The value of the variable is unknown. This would occur, for - example, if the user is examining a trace frame in which the - requested variable was not collected. - -`qTfP' -`qTsP' - These packets request data about tracepoints that are being used by - the target. GDB sends `qTfP' to get the first piece of data, and - multiple `qTsP' to get additional pieces. Replies to these - packets generally take the form of the `QTDP' packets that define - tracepoints. (FIXME add detailed syntax) - -`qTfV' -`qTsV' - These packets request data about trace state variables that are on - the target. GDB sends `qTfV' to get the first vari of data, and - multiple `qTsV' to get additional variables. Replies to these - packets follow the syntax of the `QTDV' packets that define trace - state variables. - -`qTfSTM' -`qTsSTM' - These packets request data about static tracepoint markers that - exist in the target program. GDB sends `qTfSTM' to get the first - piece of data, and multiple `qTsSTM' to get additional pieces. - Replies to these packets take the following form: - - Reply: - `m ADDRESS:ID:EXTRA' - A single marker - - `m ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...' - a comma-separated list of markers - - `l' - (lower case letter `L') denotes end of list. - - `E NN' - An error occurred. NN are hex digits. - - `' - An empty reply indicates that the request is not supported by - the stub. - - ADDRESS is encoded in hex. ID and EXTRA are strings encoded in - hex. - - In response to each query, the target will reply with a list of - one or more markers, separated by commas. GDB will respond to each - reply with a request for more markers (using the `qs' form of the - query), until the target responds with `l' (lower-case ell, for - "last"). - -`qTSTMat:ADDRESS' - This packets requests data about static tracepoint markers in the - target program at ADDRESS. Replies to this packet follow the - syntax of the `qTfSTM' and `qTsSTM' packets that list static - tracepoint markers. - -`QTSave:FILENAME' - This packet directs the target to save trace data to the file name - FILENAME in the target's filesystem. FILENAME is encoded as a hex - string; the interpretation of the file name (relative vs absolute, - wild cards, etc) is up to the target. - -`qTBuffer:OFFSET,LEN' - Return up to LEN bytes of the current contents of trace buffer, - starting at OFFSET. The trace buffer is treated as if it were a - contiguous collection of traceframes, as per the trace file format. - The reply consists as many hex-encoded bytes as the target can - deliver in a packet; it is not an error to return fewer than were - asked for. A reply consisting of just `l' indicates that no bytes - are available. - -`QTBuffer:circular:VALUE' - This packet directs the target to use a circular trace buffer if - VALUE is 1, or a linear buffer if the value is 0. - - -E.6.1 Relocate instruction reply packet ---------------------------------------- - -When installing fast tracepoints in memory, the target may need to -relocate the instruction currently at the tracepoint address to a -different address in memory. For most instructions, a simple copy is -enough, but, for example, call instructions that implicitly push the -return address on the stack, and relative branches or other PC-relative -instructions require offset adjustment, so that the effect of executing -the instruction at a different address is the same as if it had -executed in the original location. - - In response to several of the tracepoint packets, the target may also -respond with a number of intermediate `qRelocInsn' request packets -before the final result packet, to have GDB handle this relocation -operation. If a packet supports this mechanism, its documentation will -explicitly say so. See for example the above descriptions for the -`QTStart' and `QTDP' packets. The format of the request is: - -`qRelocInsn:FROM;TO' - This requests GDB to copy instruction at address FROM to address - TO, possibly adjusted so that executing the instruction at TO has - the same effect as executing it at FROM. GDB writes the adjusted - instruction to target memory starting at TO. - - Replies: -`qRelocInsn:ADJUSTED_SIZE' - Informs the stub the relocation is complete. ADJUSTED_SIZE is the - length in bytes of resulting relocated instruction sequence. - -`E NN' - A badly formed request was detected, or an error was encountered - while relocating the instruction. - - -File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol - -E.7 Host I/O Packets -==================== - -The "Host I/O" packets allow GDB to perform I/O operations on the far -side of a remote link. For example, Host I/O is used to upload and -download files to a remote target with its own filesystem. Host I/O -uses the same constant values and data structure layout as the -target-initiated File-I/O protocol. However, the Host I/O packets are -structured differently. The target-initiated protocol relies on target -memory to store parameters and buffers. Host I/O requests are -initiated by GDB, and the target's memory is not involved. *Note -File-I/O Remote Protocol Extension::, for more details on the -target-initiated protocol. - - The Host I/O request packets all encode a single operation along with -its arguments. They have this format: - -`vFile:OPERATION: PARAMETER...' - OPERATION is the name of the particular request; the target should - compare the entire packet name up to the second colon when checking - for a supported operation. The format of PARAMETER depends on the - operation. Numbers are always passed in hexadecimal. Negative - numbers have an explicit minus sign (i.e. two's complement is not - used). Strings (e.g. filenames) are encoded as a series of - hexadecimal bytes. The last argument to a system call may be a - buffer of escaped binary data (*note Binary Data::). - - - The valid responses to Host I/O packets are: - -`F RESULT [, ERRNO] [; ATTACHMENT]' - RESULT is the integer value returned by this operation, usually - non-negative for success and -1 for errors. If an error has - occured, ERRNO will be included in the result. ERRNO will have a - value defined by the File-I/O protocol (*note Errno Values::). For - operations which return data, ATTACHMENT supplies the data as a - binary buffer. Binary buffers in response packets are escaped in - the normal way (*note Binary Data::). See the individual packet - documentation for the interpretation of RESULT and ATTACHMENT. - -`' - An empty response indicates that this operation is not recognized. - - - These are the supported Host I/O operations: - -`vFile:open: PATHNAME, FLAGS, MODE' - Open a file at PATHNAME and return a file descriptor for it, or - return -1 if an error occurs. PATHNAME is a string, FLAGS is an - integer indicating a mask of open flags (*note Open Flags::), and - MODE is an integer indicating a mask of mode bits to use if the - file is created (*note mode_t Values::). *Note open::, for - details of the open flags and mode values. - -`vFile:close: FD' - Close the open file corresponding to FD and return 0, or -1 if an - error occurs. - -`vFile:pread: FD, COUNT, OFFSET' - Read data from the open file corresponding to FD. Up to COUNT - bytes will be read from the file, starting at OFFSET relative to - the start of the file. The target may read fewer bytes; common - reasons include packet size limits and an end-of-file condition. - The number of bytes read is returned. Zero should only be - returned for a successful read at the end of the file, or if COUNT - was zero. - - The data read should be returned as a binary attachment on success. - If zero bytes were read, the response should include an empty - binary attachment (i.e. a trailing semicolon). The return value - is the number of target bytes read; the binary attachment may be - longer if some characters were escaped. - -`vFile:pwrite: FD, OFFSET, DATA' - Write DATA (a binary buffer) to the open file corresponding to FD. - Start the write at OFFSET from the start of the file. Unlike many - `write' system calls, there is no separate COUNT argument; the - length of DATA in the packet is used. `vFile:write' returns the - number of bytes written, which may be shorter than the length of - DATA, or -1 if an error occurred. - -`vFile:unlink: PATHNAME' - Delete the file at PATHNAME on the target. Return 0, or -1 if an - error occurs. PATHNAME is a string. - - - -File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol - -E.8 Interrupts -============== - -When a program on the remote target is running, GDB may attempt to -interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by -`g', control of which is specified via GDB's `interrupt-sequence'. - - The precise meaning of `BREAK' is defined by the transport mechanism -and may, in fact, be undefined. GDB does not currently define a -`BREAK' mechanism for any of the network interfaces except for TCP, in -which case GDB sends the `telnet' BREAK sequence. - - `Ctrl-C', on the other hand, is defined and implemented for all -transport mechanisms. It is represented by sending the single byte -`0x03' without any of the usual packet overhead described in the -Overview section (*note Overview::). When a `0x03' byte is transmitted -as part of a packet, it is considered to be packet data and does _not_ -represent an interrupt. E.g., an `X' packet (*note X packet::), used -for binary downloads, may include an unescaped `0x03' as part of its -packet. - - `BREAK' followed by `g' is also known as Magic SysRq g. When Linux -kernel receives this sequence from serial port, it stops execution and -connects to gdb. - - Stubs are not required to recognize these interrupt mechanisms and -the precise meaning associated with receipt of the interrupt is -implementation defined. If the target supports debugging of multiple -threads and/or processes, it should attempt to interrupt all -currently-executing threads and processes. If the stub is successful -at interrupting the running program, it should send one of the stop -reply packets (*note Stop Reply Packets::) to GDB as a result of -successfully stopping the program in all-stop mode, and a stop reply -for each stopped thread in non-stop mode. Interrupts received while the -program is stopped are discarded. - - -File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol - -E.9 Notification Packets -======================== - -The GDB remote serial protocol includes "notifications", packets that -require no acknowledgment. Both the GDB and the stub may send -notifications (although the only notifications defined at present are -sent by the stub). Notifications carry information without incurring -the round-trip latency of an acknowledgment, and so are useful for -low-impact communications where occasional packet loss is not a problem. - - A notification packet has the form `% DATA # CHECKSUM', where DATA -is the content of the notification, and CHECKSUM is a checksum of DATA, -computed and formatted as for ordinary GDB packets. A notification's -DATA never contains `$', `%' or `#' characters. Upon receiving a -notification, the recipient sends no `+' or `-' to acknowledge the -notification's receipt or to report its corruption. - - Every notification's DATA begins with a name, which contains no -colon characters, followed by a colon character. - - Recipients should silently ignore corrupted notifications and -notifications they do not understand. Recipients should restart -timeout periods on receipt of a well-formed notification, whether or -not they understand it. - - Senders should only send the notifications described here when this -protocol description specifies that they are permitted. In the future, -we may extend the protocol to permit existing notifications in new -contexts; this rule helps older senders avoid confusing newer -recipients. - - (Older versions of GDB ignore bytes received until they see the `$' -byte that begins an ordinary packet, so new stubs may transmit -notifications without fear of confusing older clients. There are no -notifications defined for GDB to send at the moment, but we assume that -most older stubs would ignore them, as well.) - - The following notification packets from the stub to GDB are defined: - -`Stop: REPLY' - Report an asynchronous stop event in non-stop mode. The REPLY has - the form of a stop reply, as described in *note Stop Reply - Packets::. Refer to *note Remote Non-Stop::, for information on - how these notifications are acknowledged by GDB. - - -File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol - -E.10 Remote Protocol Support for Non-Stop Mode -============================================== - -GDB's remote protocol supports non-stop debugging of multi-threaded -programs, as described in *note Non-Stop Mode::. If the stub supports -non-stop mode, it should report that to GDB by including `QNonStop+' in -its `qSupported' response (*note qSupported::). - - GDB typically sends a `QNonStop' packet only when establishing a new -connection with the stub. Entering non-stop mode does not alter the -state of any currently-running threads, but targets must stop all -threads in any already-attached processes when entering all-stop mode. -GDB uses the `?' packet as necessary to probe the target state after a -mode change. - - In non-stop mode, when an attached process encounters an event that -would otherwise be reported with a stop reply, it uses the asynchronous -notification mechanism (*note Notification Packets::) to inform GDB. -In contrast to all-stop mode, where all threads in all processes are -stopped when a stop reply is sent, in non-stop mode only the thread -reporting the stop event is stopped. That is, when reporting a `S' or -`T' response to indicate completion of a step operation, hitting a -breakpoint, or a fault, only the affected thread is stopped; any other -still-running threads continue to run. When reporting a `W' or `X' -response, all running threads belonging to other attached processes -continue to run. - - Only one stop reply notification at a time may be pending; if -additional stop events occur before GDB has acknowledged the previous -notification, they must be queued by the stub for later synchronous -transmission in response to `vStopped' packets from GDB. Because the -notification mechanism is unreliable, the stub is permitted to resend a -stop reply notification if it believes GDB may not have received it. -GDB ignores additional stop reply notifications received before it has -finished processing a previous notification and the stub has completed -sending any queued stop events. - - Otherwise, GDB must be prepared to receive a stop reply notification -at any time. Specifically, they may appear when GDB is not otherwise -reading input from the stub, or when GDB is expecting to read a normal -synchronous response or a `+'/`-' acknowledgment to a packet it has -sent. Notification packets are distinct from any other communication -from the stub so there is no ambiguity. - - After receiving a stop reply notification, GDB shall acknowledge it -by sending a `vStopped' packet (*note vStopped packet::) as a regular, -synchronous request to the stub. Such acknowledgment is not required -to happen immediately, as GDB is permitted to send other, unrelated -packets to the stub first, which the stub should process normally. - - Upon receiving a `vStopped' packet, if the stub has other queued -stop events to report to GDB, it shall respond by sending a normal stop -reply response. GDB shall then send another `vStopped' packet to -solicit further responses; again, it is permitted to send other, -unrelated packets as well which the stub should process normally. - - If the stub receives a `vStopped' packet and there are no additional -stop events to report, the stub shall return an `OK' response. At this -point, if further stop events occur, the stub shall send a new stop -reply notification, GDB shall accept the notification, and the process -shall be repeated. - - In non-stop mode, the target shall respond to the `?' packet as -follows. First, any incomplete stop reply notification/`vStopped' -sequence in progress is abandoned. The target must begin a new -sequence reporting stop events for all stopped threads, whether or not -it has previously reported those events to GDB. The first stop reply -is sent as a synchronous reply to the `?' packet, and subsequent stop -replies are sent as responses to `vStopped' packets using the mechanism -described above. The target must not send asynchronous stop reply -notifications until the sequence is complete. If all threads are -running when the target receives the `?' packet, or if the target is -not attached to any process, it shall respond `OK'. - - -File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol - -E.11 Packet Acknowledgment -========================== - -By default, when either the host or the target machine receives a -packet, the first response expected is an acknowledgment: either `+' -(to indicate the package was received correctly) or `-' (to request -retransmission). This mechanism allows the GDB remote protocol to -operate over unreliable transport mechanisms, such as a serial line. - - In cases where the transport mechanism is itself reliable (such as a -pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It -may be desirable to disable them in that case to reduce communication -overhead, or for other reasons. This can be accomplished by means of -the `QStartNoAckMode' packet; *note QStartNoAckMode::. - - When in no-acknowledgment mode, neither the stub nor GDB shall send -or expect `+'/`-' protocol acknowledgments. The packet and response -format still includes the normal checksum, as described in *note -Overview::, but the checksum may be ignored by the receiver. - - If the stub supports `QStartNoAckMode' and prefers to operate in -no-acknowledgment mode, it should report that to GDB by including -`QStartNoAckMode+' in its response to `qSupported'; *note qSupported::. -If GDB also supports `QStartNoAckMode' and it has not been disabled via -the `set remote noack-packet off' command (*note Remote -Configuration::), GDB may then send a `QStartNoAckMode' packet to the -stub. Only then may the stub actually turn off packet acknowledgments. -GDB sends a final `+' acknowledgment of the stub's `OK' response, which -can be safely ignored by the stub. - - Note that `set remote noack-packet' command only affects negotiation -between GDB and the stub when subsequent connections are made; it does -not affect the protocol acknowledgment state for any current connection. -Since `+'/`-' acknowledgments are enabled by default when a new -connection is established, there is also no protocol request to -re-enable the acknowledgments for the current connection, once disabled. - - -File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol - -E.12 Examples -============= - -Example sequence of a target being re-started. Notice how the restart -does not get any direct output: - - -> `R00' - <- `+' - _target restarts_ - -> `?' - <- `+' - <- `T001:1234123412341234' - -> `+' - - Example sequence of a target being stepped by a single instruction: - - -> `G1445...' - <- `+' - -> `s' - <- `+' - _time passes_ - <- `T001:1234123412341234' - -> `+' - -> `g' - <- `+' - <- `1455...' - -> `+' - - -File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol - -E.13 File-I/O Remote Protocol Extension -======================================= - -* Menu: - -* File-I/O Overview:: -* Protocol Basics:: -* The F Request Packet:: -* The F Reply Packet:: -* The Ctrl-C Message:: -* Console I/O:: -* List of Supported Calls:: -* Protocol-specific Representation of Datatypes:: -* Constants:: -* File-I/O Examples:: - - -File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension - -E.13.1 File-I/O Overview ------------------------- - -The "File I/O remote protocol extension" (short: File-I/O) allows the -target to use the host's file system and console I/O to perform various -system calls. System calls on the target system are translated into a -remote protocol packet to the host system, which then performs the -needed actions and returns a response packet to the target system. -This simulates file system operations even on targets that lack file -systems. - - The protocol is defined to be independent of both the host and -target systems. It uses its own internal representation of datatypes -and values. Both GDB and the target's GDB stub are responsible for -translating the system-dependent value representations into the internal -protocol representations when data is transmitted. - - The communication is synchronous. A system call is possible only -when GDB is waiting for a response from the `C', `c', `S' or `s' -packets. While GDB handles the request for a system call, the target -is stopped to allow deterministic access to the target's memory. -Therefore File-I/O is not interruptible by target signals. On the -other hand, it is possible to interrupt File-I/O by a user interrupt -(`Ctrl-C') within GDB. - - The target's request to perform a host system call does not finish -the latest `C', `c', `S' or `s' action. That means, after finishing -the system call, the target returns to continuing the previous activity -(continue, step). No additional continue or step request from GDB is -required. - - (gdb) continue - <- target requests 'system call X' - target is stopped, GDB executes system call - -> GDB returns result - ... target continues, GDB returns to wait for the target - <- target hits breakpoint and sends a Txx packet - - The protocol only supports I/O on the console and to regular files on -the host file system. Character or block special devices, pipes, named -pipes, sockets or any other communication method on the host system are -not supported by this protocol. - - File I/O is not supported in non-stop mode. - - -File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension - -E.13.2 Protocol Basics ----------------------- - -The File-I/O protocol uses the `F' packet as the request as well as -reply packet. Since a File-I/O system call can only occur when GDB is -waiting for a response from the continuing or stepping target, the -File-I/O request is a reply that GDB has to expect as a result of a -previous `C', `c', `S' or `s' packet. This `F' packet contains all -information needed to allow GDB to call the appropriate host system -call: - - * A unique identifier for the requested system call. - - * All parameters to the system call. Pointers are given as addresses - in the target memory address space. Pointers to strings are given - as pointer/length pair. Numerical values are given as they are. - Numerical control flags are given in a protocol-specific - representation. - - - At this point, GDB has to perform the following actions. - - * If the parameters include pointer values to data needed as input - to a system call, GDB requests this data from the target with a - standard `m' packet request. This additional communication has to - be expected by the target implementation and is handled as any - other `m' packet. - - * GDB translates all value from protocol representation to host - representation as needed. Datatypes are coerced into the host - types. - - * GDB calls the system call. - - * It then coerces datatypes back to protocol representation. - - * If the system call is expected to return data in buffer space - specified by pointer parameters to the call, the data is - transmitted to the target using a `M' or `X' packet. This packet - has to be expected by the target implementation and is handled as - any other `M' or `X' packet. - - - Eventually GDB replies with another `F' packet which contains all -necessary information for the target to continue. This at least -contains - - * Return value. - - * `errno', if has been changed by the system call. - - * "Ctrl-C" flag. - - - After having done the needed type and value coercion, the target -continues the latest continue or step action. - - -File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension - -E.13.3 The `F' Request Packet ------------------------------ - -The `F' request packet has the following format: - -`FCALL-ID,PARAMETER...' - CALL-ID is the identifier to indicate the host system call to be - called. This is just the name of the function. - - PARAMETER... are the parameters to the system call. Parameters - are hexadecimal integer values, either the actual values in case - of scalar datatypes, pointers to target buffer space in case of - compound datatypes and unspecified memory areas, or pointer/length - pairs in case of string parameters. These are appended to the - CALL-ID as a comma-delimited list. All values are transmitted in - ASCII string representation, pointer/length pairs separated by a - slash. - - - -File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension - -E.13.4 The `F' Reply Packet ---------------------------- - -The `F' reply packet has the following format: - -`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT' - RETCODE is the return code of the system call as hexadecimal value. - - ERRNO is the `errno' set by the call, in protocol-specific - representation. This parameter can be omitted if the call was - successful. - - CTRL-C FLAG is only sent if the user requested a break. In this - case, ERRNO must be sent as well, even if the call was successful. - The CTRL-C FLAG itself consists of the character `C': - - F0,0,C - - or, if the call was interrupted before the host call has been - performed: - - F-1,4,C - - assuming 4 is the protocol-specific representation of `EINTR'. - - - -File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension - -E.13.5 The `Ctrl-C' Message ---------------------------- - -If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply -Packet::), the target should behave as if it had gotten a break -message. The meaning for the target is "system call interrupted by -`SIGINT'". Consequentially, the target should actually stop (as with a -break message) and return to GDB with a `T02' packet. - - It's important for the target to know in which state the system call -was interrupted. There are two possible cases: - - * The system call hasn't been performed on the host yet. - - * The system call on the host has been finished. - - - These two states can be distinguished by the target by the value of -the returned `errno'. If it's the protocol representation of `EINTR', -the system call hasn't been performed. This is equivalent to the -`EINTR' handling on POSIX systems. In any other case, the target may -presume that the system call has been finished -- successfully or not --- and should behave as if the break message arrived right after the -system call. - - GDB must behave reliably. If the system call has not been called -yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno' -in the packet. If the system call on the host has been finished before -the user requests a break, the full action must be finished by GDB. -This requires sending `M' or `X' packets as necessary. The `F' packet -may only be sent when either nothing has happened or the full action -has been completed. - - -File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension - -E.13.6 Console I/O ------------------- - -By default and if not explicitly closed by the target system, the file -descriptors 0, 1 and 2 are connected to the GDB console. Output on the -GDB console is handled as any other file output operation (`write(1, -...)' or `write(2, ...)'). Console input is handled by GDB so that -after the target read request from file descriptor 0 all following -typing is buffered until either one of the following conditions is met: - - * The user types `Ctrl-c'. The behaviour is as explained above, and - the `read' system call is treated as finished. - - * The user presses <RET>. This is treated as end of input with a - trailing newline. - - * The user types `Ctrl-d'. This is treated as end of input. No - trailing character (neither newline nor `Ctrl-D') is appended to - the input. - - - If the user has typed more characters than fit in the buffer given to -the `read' call, the trailing characters are buffered in GDB until -either another `read(0, ...)' is requested by the target, or debugging -is stopped at the user's request. - - -File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension - -E.13.7 List of Supported Calls ------------------------------- - -* Menu: - -* open:: -* close:: -* read:: -* write:: -* lseek:: -* rename:: -* unlink:: -* stat/fstat:: -* gettimeofday:: -* isatty:: -* system:: - - -File: gdb.info, Node: open, Next: close, Up: List of Supported Calls - -open -.... - -Synopsis: - int open(const char *pathname, int flags); - int open(const char *pathname, int flags, mode_t mode); - -Request: - `Fopen,PATHPTR/LEN,FLAGS,MODE' - - FLAGS is the bitwise `OR' of the following values: - - `O_CREAT' - If the file does not exist it will be created. The host - rules apply as far as file ownership and time stamps are - concerned. - - `O_EXCL' - When used with `O_CREAT', if the file already exists it is an - error and open() fails. - - `O_TRUNC' - If the file already exists and the open mode allows writing - (`O_RDWR' or `O_WRONLY' is given) it will be truncated to - zero length. - - `O_APPEND' - The file is opened in append mode. - - `O_RDONLY' - The file is opened for reading only. - - `O_WRONLY' - The file is opened for writing only. - - `O_RDWR' - The file is opened for reading and writing. - - Other bits are silently ignored. - - MODE is the bitwise `OR' of the following values: - - `S_IRUSR' - User has read permission. - - `S_IWUSR' - User has write permission. - - `S_IRGRP' - Group has read permission. - - `S_IWGRP' - Group has write permission. - - `S_IROTH' - Others have read permission. - - `S_IWOTH' - Others have write permission. - - Other bits are silently ignored. - -Return value: - `open' returns the new file descriptor or -1 if an error occurred. - -Errors: - - `EEXIST' - PATHNAME already exists and `O_CREAT' and `O_EXCL' were used. - - `EISDIR' - PATHNAME refers to a directory. - - `EACCES' - The requested access is not allowed. - - `ENAMETOOLONG' - PATHNAME was too long. - - `ENOENT' - A directory component in PATHNAME does not exist. - - `ENODEV' - PATHNAME refers to a device, pipe, named pipe or socket. - - `EROFS' - PATHNAME refers to a file on a read-only filesystem and write - access was requested. - - `EFAULT' - PATHNAME is an invalid pointer value. - - `ENOSPC' - No space on device to create the file. - - `EMFILE' - The process already has the maximum number of files open. - - `ENFILE' - The limit on the total number of files open on the system has - been reached. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls - -close -..... - -Synopsis: - int close(int fd); - -Request: - `Fclose,FD' - -Return value: - `close' returns zero on success, or -1 if an error occurred. - -Errors: - - `EBADF' - FD isn't a valid open file descriptor. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls - -read -.... - -Synopsis: - int read(int fd, void *buf, unsigned int count); - -Request: - `Fread,FD,BUFPTR,COUNT' - -Return value: - On success, the number of bytes read is returned. Zero indicates - end of file. If count is zero, read returns zero as well. On - error, -1 is returned. - -Errors: - - `EBADF' - FD is not a valid file descriptor or is not open for reading. - - `EFAULT' - BUFPTR is an invalid pointer value. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls - -write -..... - -Synopsis: - int write(int fd, const void *buf, unsigned int count); - -Request: - `Fwrite,FD,BUFPTR,COUNT' - -Return value: - On success, the number of bytes written are returned. Zero - indicates nothing was written. On error, -1 is returned. - -Errors: - - `EBADF' - FD is not a valid file descriptor or is not open for writing. - - `EFAULT' - BUFPTR is an invalid pointer value. - - `EFBIG' - An attempt was made to write a file that exceeds the - host-specific maximum file size allowed. - - `ENOSPC' - No space on device to write the data. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls - -lseek -..... - -Synopsis: - long lseek (int fd, long offset, int flag); - -Request: - `Flseek,FD,OFFSET,FLAG' - - FLAG is one of: - - `SEEK_SET' - The offset is set to OFFSET bytes. - - `SEEK_CUR' - The offset is set to its current location plus OFFSET bytes. - - `SEEK_END' - The offset is set to the size of the file plus OFFSET bytes. - -Return value: - On success, the resulting unsigned offset in bytes from the - beginning of the file is returned. Otherwise, a value of -1 is - returned. - -Errors: - - `EBADF' - FD is not a valid open file descriptor. - - `ESPIPE' - FD is associated with the GDB console. - - `EINVAL' - FLAG is not a proper value. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls - -rename -...... - -Synopsis: - int rename(const char *oldpath, const char *newpath); - -Request: - `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' - -Return value: - On success, zero is returned. On error, -1 is returned. - -Errors: - - `EISDIR' - NEWPATH is an existing directory, but OLDPATH is not a - directory. - - `EEXIST' - NEWPATH is a non-empty directory. - - `EBUSY' - OLDPATH or NEWPATH is a directory that is in use by some - process. - - `EINVAL' - An attempt was made to make a directory a subdirectory of - itself. - - `ENOTDIR' - A component used as a directory in OLDPATH or new path is - not a directory. Or OLDPATH is a directory and NEWPATH - exists but is not a directory. - - `EFAULT' - OLDPATHPTR or NEWPATHPTR are invalid pointer values. - - `EACCES' - No access to the file or the path of the file. - - `ENAMETOOLONG' - OLDPATH or NEWPATH was too long. - - `ENOENT' - A directory component in OLDPATH or NEWPATH does not exist. - - `EROFS' - The file is on a read-only filesystem. - - `ENOSPC' - The device containing the file has no room for the new - directory entry. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls - -unlink -...... - -Synopsis: - int unlink(const char *pathname); - -Request: - `Funlink,PATHNAMEPTR/LEN' - -Return value: - On success, zero is returned. On error, -1 is returned. - -Errors: - - `EACCES' - No access to the file or the path of the file. - - `EPERM' - The system does not allow unlinking of directories. - - `EBUSY' - The file PATHNAME cannot be unlinked because it's being used - by another process. - - `EFAULT' - PATHNAMEPTR is an invalid pointer value. - - `ENAMETOOLONG' - PATHNAME was too long. - - `ENOENT' - A directory component in PATHNAME does not exist. - - `ENOTDIR' - A component of the path is not a directory. - - `EROFS' - The file is on a read-only filesystem. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls - -stat/fstat -.......... - -Synopsis: - int stat(const char *pathname, struct stat *buf); - int fstat(int fd, struct stat *buf); - -Request: - `Fstat,PATHNAMEPTR/LEN,BUFPTR' - `Ffstat,FD,BUFPTR' - -Return value: - On success, zero is returned. On error, -1 is returned. - -Errors: - - `EBADF' - FD is not a valid open file. - - `ENOENT' - A directory component in PATHNAME does not exist or the path - is an empty string. - - `ENOTDIR' - A component of the path is not a directory. - - `EFAULT' - PATHNAMEPTR is an invalid pointer value. - - `EACCES' - No access to the file or the path of the file. - - `ENAMETOOLONG' - PATHNAME was too long. - - `EINTR' - The call was interrupted by the user. - - - -File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls - -gettimeofday -............ - -Synopsis: - int gettimeofday(struct timeval *tv, void *tz); - -Request: - `Fgettimeofday,TVPTR,TZPTR' - -Return value: - On success, 0 is returned, -1 otherwise. - -Errors: - - `EINVAL' - TZ is a non-NULL pointer. - - `EFAULT' - TVPTR and/or TZPTR is an invalid pointer value. - - - -File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls - -isatty -...... - -Synopsis: - int isatty(int fd); - -Request: - `Fisatty,FD' - -Return value: - Returns 1 if FD refers to the GDB console, 0 otherwise. - -Errors: - - `EINTR' - The call was interrupted by the user. - - - Note that the `isatty' call is treated as a special case: it returns -1 to the target if the file descriptor is attached to the GDB console, -0 otherwise. Implementing through system calls would require -implementing `ioctl' and would be more complex than needed. - - -File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls - -system -...... - -Synopsis: - int system(const char *command); - -Request: - `Fsystem,COMMANDPTR/LEN' - -Return value: - If LEN is zero, the return value indicates whether a shell is - available. A zero return value indicates a shell is not available. - For non-zero LEN, the value returned is -1 on error and the return - status of the command otherwise. Only the exit status of the - command is returned, which is extracted from the host's `system' - return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh' - could not be executed, 127 is returned. - -Errors: - - `EINTR' - The call was interrupted by the user. - - - GDB takes over the full task of calling the necessary host calls to -perform the `system' call. The return value of `system' on the host is -simplified before it's returned to the target. Any termination signal -information from the child process is discarded, and the return value -consists entirely of the exit status of the called command. - - Due to security concerns, the `system' call is by default refused by -GDB. The user has to allow this call explicitly with the `set remote -system-call-allowed 1' command. - -`set remote system-call-allowed' - Control whether to allow the `system' calls in the File I/O - protocol for the remote target. The default is zero (disabled). - -`show remote system-call-allowed' - Show whether the `system' calls are allowed in the File I/O - protocol. - - -File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension - -E.13.8 Protocol-specific Representation of Datatypes ----------------------------------------------------- - -* Menu: - -* Integral Datatypes:: -* Pointer Values:: -* Memory Transfer:: -* struct stat:: -* struct timeval:: - - -File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes - -Integral Datatypes -.................. - -The integral datatypes used in the system calls are `int', `unsigned -int', `long', `unsigned long', `mode_t', and `time_t'. - - `int', `unsigned int', `mode_t' and `time_t' are implemented as 32 -bit values in this protocol. - - `long' and `unsigned long' are implemented as 64 bit types. - - *Note Limits::, for corresponding MIN and MAX values (similar to -those in `limits.h') to allow range checking on host and target. - - `time_t' datatypes are defined as seconds since the Epoch. - - All integral datatypes transferred as part of a memory read or write -of a structured datatype e.g. a `struct stat' have to be given in big -endian byte order. - - -File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes - -Pointer Values -.............. - -Pointers to target data are transmitted as they are. An exception is -made for pointers to buffers for which the length isn't transmitted as -part of the function call, namely strings. Strings are transmitted as -a pointer/length pair, both as hex values, e.g. - - `1aaf/12' - -which is a pointer to data of length 18 bytes at position 0x1aaf. The -length is defined as the full string length in bytes, including the -trailing null byte. For example, the string `"hello world"' at address -0x123456 is transmitted as - - `123456/d' - - -File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes - -Memory Transfer -............... - -Structured data which is transferred using a memory read or write (for -example, a `struct stat') is expected to be in a protocol-specific -format with all scalar multibyte datatypes being big endian. -Translation to this representation needs to be done both by the target -before the `F' packet is sent, and by GDB before it transfers memory to -the target. Transferred pointers to structured data should point to -the already-coerced data at any time. - - -File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes - -struct stat -........... - -The buffer of type `struct stat' used by the target and GDB is defined -as follows: - - struct stat { - unsigned int st_dev; /* device */ - unsigned int st_ino; /* inode */ - mode_t st_mode; /* protection */ - unsigned int st_nlink; /* number of hard links */ - unsigned int st_uid; /* user ID of owner */ - unsigned int st_gid; /* group ID of owner */ - unsigned int st_rdev; /* device type (if inode device) */ - unsigned long st_size; /* total size, in bytes */ - unsigned long st_blksize; /* blocksize for filesystem I/O */ - unsigned long st_blocks; /* number of blocks allocated */ - time_t st_atime; /* time of last access */ - time_t st_mtime; /* time of last modification */ - time_t st_ctime; /* time of last change */ - }; - - The integral datatypes conform to the definitions given in the -appropriate section (see *note Integral Datatypes::, for details) so -this structure is of size 64 bytes. - - The values of several fields have a restricted meaning and/or range -of values. - -`st_dev' - A value of 0 represents a file, 1 the console. - -`st_ino' - No valid meaning for the target. Transmitted unchanged. - -`st_mode' - Valid mode bits are described in *note Constants::. Any other - bits have currently no meaning for the target. - -`st_uid' -`st_gid' -`st_rdev' - No valid meaning for the target. Transmitted unchanged. - -`st_atime' -`st_mtime' -`st_ctime' - These values have a host and file system dependent accuracy. - Especially on Windows hosts, the file system may not support exact - timing values. - - The target gets a `struct stat' of the above representation and is -responsible for coercing it to the target representation before -continuing. - - Note that due to size differences between the host, target, and -protocol representations of `struct stat' members, these members could -eventually get truncated on the target. - - -File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes - -struct timeval -.............. - -The buffer of type `struct timeval' used by the File-I/O protocol is -defined as follows: - - struct timeval { - time_t tv_sec; /* second */ - long tv_usec; /* microsecond */ - }; - - The integral datatypes conform to the definitions given in the -appropriate section (see *note Integral Datatypes::, for details) so -this structure is of size 8 bytes. - - -File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension - -E.13.9 Constants ----------------- - -The following values are used for the constants inside of the protocol. -GDB and target are responsible for translating these values before and -after the call as needed. - -* Menu: - -* Open Flags:: -* mode_t Values:: -* Errno Values:: -* Lseek Flags:: -* Limits:: - - -File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants - -Open Flags -.......... - -All values are given in hexadecimal representation. - - O_RDONLY 0x0 - O_WRONLY 0x1 - O_RDWR 0x2 - O_APPEND 0x8 - O_CREAT 0x200 - O_TRUNC 0x400 - O_EXCL 0x800 - - -File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants - -mode_t Values -............. - -All values are given in octal representation. - - S_IFREG 0100000 - S_IFDIR 040000 - S_IRUSR 0400 - S_IWUSR 0200 - S_IXUSR 0100 - S_IRGRP 040 - S_IWGRP 020 - S_IXGRP 010 - S_IROTH 04 - S_IWOTH 02 - S_IXOTH 01 - - -File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants - -Errno Values -............ - -All values are given in decimal representation. - - EPERM 1 - ENOENT 2 - EINTR 4 - EBADF 9 - EACCES 13 - EFAULT 14 - EBUSY 16 - EEXIST 17 - ENODEV 19 - ENOTDIR 20 - EISDIR 21 - EINVAL 22 - ENFILE 23 - EMFILE 24 - EFBIG 27 - ENOSPC 28 - ESPIPE 29 - EROFS 30 - ENAMETOOLONG 91 - EUNKNOWN 9999 - - `EUNKNOWN' is used as a fallback error value if a host system returns - any error value not in the list of supported error numbers. - - -File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants - -Lseek Flags -........... - - SEEK_SET 0 - SEEK_CUR 1 - SEEK_END 2 - - -File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants - -Limits -...... - -All values are given in decimal representation. - - INT_MIN -2147483648 - INT_MAX 2147483647 - UINT_MAX 4294967295 - LONG_MIN -9223372036854775808 - LONG_MAX 9223372036854775807 - ULONG_MAX 18446744073709551615 - - -File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension - -E.13.10 File-I/O Examples -------------------------- - -Example sequence of a write call, file descriptor 3, buffer is at target -address 0x1234, 6 bytes should be written: - - <- `Fwrite,3,1234,6' - _request memory read from target_ - -> `m1234,6' - <- XXXXXX - _return "6 bytes written"_ - -> `F6' - - Example sequence of a read call, file descriptor 3, buffer is at -target address 0x1234, 6 bytes should be read: - - <- `Fread,3,1234,6' - _request memory write to target_ - -> `X1234,6:XXXXXX' - _return "6 bytes read"_ - -> `F6' - - Example sequence of a read call, call fails on the host due to -invalid file descriptor (`EBADF'): - - <- `Fread,3,1234,6' - -> `F-1,9' - - Example sequence of a read call, user presses `Ctrl-c' before -syscall on host is called: - - <- `Fread,3,1234,6' - -> `F-1,4,C' - <- `T02' - - Example sequence of a read call, user presses `Ctrl-c' after syscall -on host is called: - - <- `Fread,3,1234,6' - -> `X1234,6:XXXXXX' - <- `T02' - - -File: gdb.info, Node: Library List Format, Next: Memory Map Format, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol - -E.14 Library List Format -======================== - -On some platforms, a dynamic loader (e.g. `ld.so') runs in the same -process as your application to manage libraries. In this case, GDB can -use the loader's symbol table and normal memory operations to maintain -a list of shared libraries. On other platforms, the operating system -manages loaded libraries. GDB can not retrieve the list of currently -loaded libraries through memory operations, so it uses the -`qXfer:libraries:read' packet (*note qXfer library list read::) -instead. The remote stub queries the target's operating system and -reports which libraries are loaded. - - The `qXfer:libraries:read' packet returns an XML document which -lists loaded libraries and their offsets. Each library has an -associated name and one or more segment or section base addresses, -which report where the library was loaded in memory. - - For the common case of libraries that are fully linked binaries, the -library should have a list of segments. If the target supports dynamic -linking of a relocatable object file, its library XML element should -instead include a list of allocated sections. The segment or section -bases are start addresses, not relocation offsets; they do not depend -on the library's link-time base addresses. - - GDB must be linked with the Expat library to support XML library -lists. *Note Expat::. - - A simple memory map, with one loaded library relocated by a single -offset, looks like this: - - <library-list> - <library name="/lib/libc.so.6"> - <segment address="0x10000000"/> - </library> - </library-list> - - Another simple memory map, with one loaded library with three -allocated sections (.text, .data, .bss), looks like this: - - <library-list> - <library name="sharedlib.o"> - <section address="0x10000000"/> - <section address="0x20000000"/> - <section address="0x30000000"/> - </library> - </library-list> - - The format of a library list is described by this DTD: - - <!-- library-list: Root element with versioning --> - <!ELEMENT library-list (library)*> - <!ATTLIST library-list version CDATA #FIXED "1.0"> - <!ELEMENT library (segment*, section*)> - <!ATTLIST library name CDATA #REQUIRED> - <!ELEMENT segment EMPTY> - <!ATTLIST segment address CDATA #REQUIRED> - <!ELEMENT section EMPTY> - <!ATTLIST section address CDATA #REQUIRED> - - In addition, segments and section descriptors cannot be mixed within -a single library element, and you must supply at least one segment or -section for each library. - - -File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format, Up: Remote Protocol - -E.15 Memory Map Format -====================== - -To be able to write into flash memory, GDB needs to obtain a memory map -from the target. This section describes the format of the memory map. - - The memory map is obtained using the `qXfer:memory-map:read' (*note -qXfer memory map read::) packet and is an XML document that lists -memory regions. - - GDB must be linked with the Expat library to support XML memory -maps. *Note Expat::. - - The top-level structure of the document is shown below: - - <?xml version="1.0"?> - <!DOCTYPE memory-map - PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" - "http://sourceware.org/gdb/gdb-memory-map.dtd"> - <memory-map> - region... - </memory-map> - - Each region can be either: - - * A region of RAM starting at ADDR and extending for LENGTH bytes - from there: - - <memory type="ram" start="ADDR" length="LENGTH"/> - - * A region of read-only memory: - - <memory type="rom" start="ADDR" length="LENGTH"/> - - * A region of flash memory, with erasure blocks BLOCKSIZE bytes in - length: - - <memory type="flash" start="ADDR" length="LENGTH"> - <property name="blocksize">BLOCKSIZE</property> - </memory> - - - Regions must not overlap. GDB assumes that areas of memory not -covered by the memory map are RAM, and uses the ordinary `M' and `X' -packets to write to addresses in such ranges. - - The formal DTD for memory map format is given below: - - <!-- ................................................... --> - <!-- Memory Map XML DTD ................................ --> - <!-- File: memory-map.dtd .............................. --> - <!-- .................................... .............. --> - <!-- memory-map.dtd --> - <!-- memory-map: Root element with versioning --> - <!ELEMENT memory-map (memory | property)> - <!ATTLIST memory-map version CDATA #FIXED "1.0.0"> - <!ELEMENT memory (property)> - <!-- memory: Specifies a memory region, - and its type, or device. --> - <!ATTLIST memory type CDATA #REQUIRED - start CDATA #REQUIRED - length CDATA #REQUIRED - device CDATA #IMPLIED> - <!-- property: Generic attribute tag --> - <!ELEMENT property (#PCDATA | property)*> - <!ATTLIST property name CDATA #REQUIRED> - - -File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol - -E.16 Thread List Format -======================= - -To efficiently update the list of threads and their attributes, GDB -issues the `qXfer:threads:read' packet (*note qXfer threads read::) and -obtains the XML document with the following structure: - - <?xml version="1.0"?> - <threads> - <thread id="id" core="0"> - ... description ... - </thread> - </threads> - - Each `thread' element must have the `id' attribute that identifies -the thread (*note thread-id syntax::). The `core' attribute, if -present, specifies which processor core the thread was last executing -on. The content of the of `thread' element is interpreted as -human-readable auxilliary information. - - -File: gdb.info, Node: Traceframe Info Format, Prev: Thread List Format, Up: Remote Protocol - -E.17 Traceframe Info Format -=========================== - -To be able to know which objects in the inferior can be examined when -inspecting a tracepoint hit, GDB needs to obtain the list of memory -ranges, registers and trace state variables that have been collected in -a traceframe. - - This list is obtained using the `qXfer:traceframe-info:read' (*note -qXfer traceframe info read::) packet and is an XML document. - - GDB must be linked with the Expat library to support XML traceframe -info discovery. *Note Expat::. - - The top-level structure of the document is shown below: - - <?xml version="1.0"?> - <!DOCTYPE traceframe-info - PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN" - "http://sourceware.org/gdb/gdb-traceframe-info.dtd"> - <traceframe-info> - block... - </traceframe-info> - - Each traceframe block can be either: - - * A region of collected memory starting at ADDR and extending for - LENGTH bytes from there: - - <memory start="ADDR" length="LENGTH"/> - - - The formal DTD for the traceframe info format is given below: - - <!ELEMENT traceframe-info (memory)* > - <!ATTLIST traceframe-info version CDATA #FIXED "1.0"> - - <!ELEMENT memory EMPTY> - <!ATTLIST memory start CDATA #REQUIRED - length CDATA #REQUIRED> - - -File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top - -Appendix F The GDB Agent Expression Mechanism -********************************************* - -In some applications, it is not feasible for the debugger to interrupt -the program's execution long enough for the developer to learn anything -helpful about its behavior. If the program's correctness depends on its -real-time behavior, delays introduced by a debugger might cause the -program to fail, even when the code itself is correct. It is useful to -be able to observe the program's behavior without interrupting it. - - Using GDB's `trace' and `collect' commands, the user can specify -locations in the program, and arbitrary expressions to evaluate when -those locations are reached. Later, using the `tfind' command, she can -examine the values those expressions had when the program hit the trace -points. The expressions may also denote objects in memory -- -structures or arrays, for example -- whose values GDB should record; -while visiting a particular tracepoint, the user may inspect those -objects as if they were in memory at that moment. However, because GDB -records these values without interacting with the user, it can do so -quickly and unobtrusively, hopefully not disturbing the program's -behavior. - - When GDB is debugging a remote target, the GDB "agent" code running -on the target computes the values of the expressions itself. To avoid -having a full symbolic expression evaluator on the agent, GDB translates -expressions in the source language into a simpler bytecode language, and -then sends the bytecode to the agent; the agent then executes the -bytecode, and records the values for GDB to retrieve later. - - The bytecode language is simple; there are forty-odd opcodes, the -bulk of which are the usual vocabulary of C operands (addition, -subtraction, shifts, and so on) and various sizes of literals and -memory reference operations. The bytecode interpreter operates -strictly on machine-level values -- various sizes of integers and -floating point numbers -- and requires no information about types or -symbols; thus, the interpreter's internal data structures are simple, -and each bytecode requires only a few native machine instructions to -implement it. The interpreter is small, and strict limits on the -memory and time required to evaluate an expression are easy to -determine, making it suitable for use by the debugging agent in -real-time applications. - -* Menu: - -* General Bytecode Design:: Overview of the interpreter. -* Bytecode Descriptions:: What each one does. -* Using Agent Expressions:: How agent expressions fit into the big picture. -* Varying Target Capabilities:: How to discover what the target can do. -* Rationale:: Why we did it this way. - - -File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions - -F.1 General Bytecode Design -=========================== - -The agent represents bytecode expressions as an array of bytes. Each -instruction is one byte long (thus the term "bytecode"). Some -instructions are followed by operand bytes; for example, the `goto' -instruction is followed by a destination for the jump. - - The bytecode interpreter is a stack-based machine; most instructions -pop their operands off the stack, perform some operation, and push the -result back on the stack for the next instruction to consume. Each -element of the stack may contain either a integer or a floating point -value; these values are as many bits wide as the largest integer that -can be directly manipulated in the source language. Stack elements -carry no record of their type; bytecode could push a value as an -integer, then pop it as a floating point value. However, GDB will not -generate code which does this. In C, one might define the type of a -stack element as follows: - union agent_val { - LONGEST l; - DOUBLEST d; - }; - where `LONGEST' and `DOUBLEST' are `typedef' names for the largest -integer and floating point types on the machine. - - By the time the bytecode interpreter reaches the end of the -expression, the value of the expression should be the only value left -on the stack. For tracing applications, `trace' bytecodes in the -expression will have recorded the necessary data, and the value on the -stack may be discarded. For other applications, like conditional -breakpoints, the value may be useful. - - Separate from the stack, the interpreter has two registers: -`pc' - The address of the next bytecode to execute. - -`start' - The address of the start of the bytecode expression, necessary for - interpreting the `goto' and `if_goto' instructions. - - Neither of these registers is directly visible to the bytecode -language itself, but they are useful for defining the meanings of the -bytecode operations. - - There are no instructions to perform side effects on the running -program, or call the program's functions; we assume that these -expressions are only used for unobtrusive debugging, not for patching -the running code. - - Most bytecode instructions do not distinguish between the various -sizes of values, and operate on full-width values; the upper bits of the -values are simply ignored, since they do not usually make a difference -to the value computed. The exceptions to this rule are: -memory reference instructions (`ref'N) - There are distinct instructions to fetch different word sizes from - memory. Once on the stack, however, the values are treated as - full-size integers. They may need to be sign-extended; the `ext' - instruction exists for this purpose. - -the sign-extension instruction (`ext' N) - These clearly need to know which portion of their operand is to be - extended to occupy the full length of the word. - - - If the interpreter is unable to evaluate an expression completely for -some reason (a memory location is inaccessible, or a divisor is zero, -for example), we say that interpretation "terminates with an error". -This means that the problem is reported back to the interpreter's caller -in some helpful way. In general, code using agent expressions should -assume that they may attempt to divide by zero, fetch arbitrary memory -locations, and misbehave in other ways. - - Even complicated C expressions compile to a few bytecode -instructions; for example, the expression `x + y * z' would typically -produce code like the following, assuming that `x' and `y' live in -registers, and `z' is a global variable holding a 32-bit `int': - reg 1 - reg 2 - const32 address of z - ref32 - ext 32 - mul - add - end - - In detail, these mean: -`reg 1' - Push the value of register 1 (presumably holding `x') onto the - stack. - -`reg 2' - Push the value of register 2 (holding `y'). - -`const32 address of z' - Push the address of `z' onto the stack. - -`ref32' - Fetch a 32-bit word from the address at the top of the stack; - replace the address on the stack with the value. Thus, we replace - the address of `z' with `z''s value. - -`ext 32' - Sign-extend the value on the top of the stack from 32 bits to full - length. This is necessary because `z' is a signed integer. - -`mul' - Pop the top two numbers on the stack, multiply them, and push their - product. Now the top of the stack contains the value of the - expression `y * z'. - -`add' - Pop the top two numbers, add them, and push the sum. Now the top - of the stack contains the value of `x + y * z'. - -`end' - Stop executing; the value left on the stack top is the value to be - recorded. - - - -File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions - -F.2 Bytecode Descriptions -========================= - -Each bytecode description has the following form: - -`add' (0x02): A B => A+B - Pop the top two stack items, A and B, as integers; push their sum, - as an integer. - - - In this example, `add' is the name of the bytecode, and `(0x02)' is -the one-byte value used to encode the bytecode, in hexadecimal. The -phrase "A B => A+B" shows the stack before and after the bytecode -executes. Beforehand, the stack must contain at least two values, A -and B; since the top of the stack is to the right, B is on the top of -the stack, and A is underneath it. After execution, the bytecode will -have popped A and B from the stack, and replaced them with a single -value, A+B. There may be other values on the stack below those shown, -but the bytecode affects only those shown. - - Here is another example: - -`const8' (0x22) N: => N - Push the 8-bit integer constant N on the stack, without sign - extension. - - - In this example, the bytecode `const8' takes an operand N directly -from the bytecode stream; the operand follows the `const8' bytecode -itself. We write any such operands immediately after the name of the -bytecode, before the colon, and describe the exact encoding of the -operand in the bytecode stream in the body of the bytecode description. - - For the `const8' bytecode, there are no stack items given before the -=>; this simply means that the bytecode consumes no values from the -stack. If a bytecode consumes no values, or produces no values, the -list on either side of the => may be empty. - - If a value is written as A, B, or N, then the bytecode treats it as -an integer. If a value is written is ADDR, then the bytecode treats it -as an address. - - We do not fully describe the floating point operations here; although -this design can be extended in a clean way to handle floating point -values, they are not of immediate interest to the customer, so we avoid -describing them, to save time. - -`float' (0x01): => - Prefix for floating-point bytecodes. Not implemented yet. - -`add' (0x02): A B => A+B - Pop two integers from the stack, and push their sum, as an integer. - -`sub' (0x03): A B => A-B - Pop two integers from the stack, subtract the top value from the - next-to-top value, and push the difference. - -`mul' (0x04): A B => A*B - Pop two integers from the stack, multiply them, and push the - product on the stack. Note that, when one multiplies two N-bit - numbers yielding another N-bit number, it is irrelevant whether the - numbers are signed or not; the results are the same. - -`div_signed' (0x05): A B => A/B - Pop two signed integers from the stack; divide the next-to-top - value by the top value, and push the quotient. If the divisor is - zero, terminate with an error. - -`div_unsigned' (0x06): A B => A/B - Pop two unsigned integers from the stack; divide the next-to-top - value by the top value, and push the quotient. If the divisor is - zero, terminate with an error. - -`rem_signed' (0x07): A B => A MODULO B - Pop two signed integers from the stack; divide the next-to-top - value by the top value, and push the remainder. If the divisor is - zero, terminate with an error. - -`rem_unsigned' (0x08): A B => A MODULO B - Pop two unsigned integers from the stack; divide the next-to-top - value by the top value, and push the remainder. If the divisor is - zero, terminate with an error. - -`lsh' (0x09): A B => A<<B - Pop two integers from the stack; let A be the next-to-top value, - and B be the top value. Shift A left by B bits, and push the - result. - -`rsh_signed' (0x0a): A B => `(signed)'A>>B - Pop two integers from the stack; let A be the next-to-top value, - and B be the top value. Shift A right by B bits, inserting copies - of the top bit at the high end, and push the result. - -`rsh_unsigned' (0x0b): A B => A>>B - Pop two integers from the stack; let A be the next-to-top value, - and B be the top value. Shift A right by B bits, inserting zero - bits at the high end, and push the result. - -`log_not' (0x0e): A => !A - Pop an integer from the stack; if it is zero, push the value one; - otherwise, push the value zero. - -`bit_and' (0x0f): A B => A&B - Pop two integers from the stack, and push their bitwise `and'. - -`bit_or' (0x10): A B => A|B - Pop two integers from the stack, and push their bitwise `or'. - -`bit_xor' (0x11): A B => A^B - Pop two integers from the stack, and push their bitwise - exclusive-`or'. - -`bit_not' (0x12): A => ~A - Pop an integer from the stack, and push its bitwise complement. - -`equal' (0x13): A B => A=B - Pop two integers from the stack; if they are equal, push the value - one; otherwise, push the value zero. - -`less_signed' (0x14): A B => A<B - Pop two signed integers from the stack; if the next-to-top value - is less than the top value, push the value one; otherwise, push - the value zero. - -`less_unsigned' (0x15): A B => A<B - Pop two unsigned integers from the stack; if the next-to-top value - is less than the top value, push the value one; otherwise, push - the value zero. - -`ext' (0x16) N: A => A, sign-extended from N bits - Pop an unsigned value from the stack; treating it as an N-bit - twos-complement value, extend it to full length. This means that - all bits to the left of bit N-1 (where the least significant bit - is bit 0) are set to the value of bit N-1. Note that N may be - larger than or equal to the width of the stack elements of the - bytecode engine; in this case, the bytecode should have no effect. - - The number of source bits to preserve, N, is encoded as a single - byte unsigned integer following the `ext' bytecode. - -`zero_ext' (0x2a) N: A => A, zero-extended from N bits - Pop an unsigned value from the stack; zero all but the bottom N - bits. This means that all bits to the left of bit N-1 (where the - least significant bit is bit 0) are set to the value of bit N-1. - - The number of source bits to preserve, N, is encoded as a single - byte unsigned integer following the `zero_ext' bytecode. - -`ref8' (0x17): ADDR => A -`ref16' (0x18): ADDR => A -`ref32' (0x19): ADDR => A -`ref64' (0x1a): ADDR => A - Pop an address ADDR from the stack. For bytecode `ref'N, fetch an - N-bit value from ADDR, using the natural target endianness. Push - the fetched value as an unsigned integer. - - Note that ADDR may not be aligned in any particular way; the - `refN' bytecodes should operate correctly for any address. - - If attempting to access memory at ADDR would cause a processor - exception of some sort, terminate with an error. - -`ref_float' (0x1b): ADDR => D -`ref_double' (0x1c): ADDR => D -`ref_long_double' (0x1d): ADDR => D -`l_to_d' (0x1e): A => D -`d_to_l' (0x1f): D => A - Not implemented yet. - -`dup' (0x28): A => A A - Push another copy of the stack's top element. - -`swap' (0x2b): A B => B A - Exchange the top two items on the stack. - -`pop' (0x29): A => - Discard the top value on the stack. - -`pick' (0x32) N: A ... B => A ... B A - Duplicate an item from the stack and push it on the top of the - stack. N, a single byte, indicates the stack item to copy. If N - is zero, this is the same as `dup'; if N is one, it copies the - item under the top item, etc. If N exceeds the number of items on - the stack, terminate with an error. - -`rot' (0x33): A B C => C B A - Rotate the top three items on the stack. - -`if_goto' (0x20) OFFSET: A => - Pop an integer off the stack; if it is non-zero, branch to the - given offset in the bytecode string. Otherwise, continue to the - next instruction in the bytecode stream. In other words, if A is - non-zero, set the `pc' register to `start' + OFFSET. Thus, an - offset of zero denotes the beginning of the expression. - - The OFFSET is stored as a sixteen-bit unsigned value, stored - immediately following the `if_goto' bytecode. It is always stored - most significant byte first, regardless of the target's normal - endianness. The offset is not guaranteed to fall at any particular - alignment within the bytecode stream; thus, on machines where - fetching a 16-bit on an unaligned address raises an exception, you - should fetch the offset one byte at a time. - -`goto' (0x21) OFFSET: => - Branch unconditionally to OFFSET; in other words, set the `pc' - register to `start' + OFFSET. - - The offset is stored in the same way as for the `if_goto' bytecode. - -`const8' (0x22) N: => N -`const16' (0x23) N: => N -`const32' (0x24) N: => N -`const64' (0x25) N: => N - Push the integer constant N on the stack, without sign extension. - To produce a small negative value, push a small twos-complement - value, and then sign-extend it using the `ext' bytecode. - - The constant N is stored in the appropriate number of bytes - following the `const'B bytecode. The constant N is always stored - most significant byte first, regardless of the target's normal - endianness. The constant is not guaranteed to fall at any - particular alignment within the bytecode stream; thus, on machines - where fetching a 16-bit on an unaligned address raises an - exception, you should fetch N one byte at a time. - -`reg' (0x26) N: => A - Push the value of register number N, without sign extension. The - registers are numbered following GDB's conventions. - - The register number N is encoded as a 16-bit unsigned integer - immediately following the `reg' bytecode. It is always stored most - significant byte first, regardless of the target's normal - endianness. The register number is not guaranteed to fall at any - particular alignment within the bytecode stream; thus, on machines - where fetching a 16-bit on an unaligned address raises an - exception, you should fetch the register number one byte at a time. - -`getv' (0x2c) N: => V - Push the value of trace state variable number N, without sign - extension. - - The variable number N is encoded as a 16-bit unsigned integer - immediately following the `getv' bytecode. It is always stored - most significant byte first, regardless of the target's normal - endianness. The variable number is not guaranteed to fall at any - particular alignment within the bytecode stream; thus, on machines - where fetching a 16-bit on an unaligned address raises an - exception, you should fetch the register number one byte at a time. - -`setv' (0x2d) N: => V - Set trace state variable number N to the value found on the top of - the stack. The stack is unchanged, so that the value is readily - available if the assignment is part of a larger expression. The - handling of N is as described for `getv'. - -`trace' (0x0c): ADDR SIZE => - Record the contents of the SIZE bytes at ADDR in a trace buffer, - for later retrieval by GDB. - -`trace_quick' (0x0d) SIZE: ADDR => ADDR - Record the contents of the SIZE bytes at ADDR in a trace buffer, - for later retrieval by GDB. SIZE is a single byte unsigned - integer following the `trace' opcode. - - This bytecode is equivalent to the sequence `dup const8 SIZE - trace', but we provide it anyway to save space in bytecode strings. - -`trace16' (0x30) SIZE: ADDR => ADDR - Identical to trace_quick, except that SIZE is a 16-bit big-endian - unsigned integer, not a single byte. This should probably have - been named `trace_quick16', for consistency. - -`tracev' (0x2e) N: => A - Record the value of trace state variable number N in the trace - buffer. The handling of N is as described for `getv'. - -`end' (0x27): => - Stop executing bytecode; the result should be the top element of - the stack. If the purpose of the expression was to compute an - lvalue or a range of memory, then the next-to-top of the stack is - the lvalue's address, and the top of the stack is the lvalue's - size, in bytes. - - - -File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions - -F.3 Using Agent Expressions -=========================== - -Agent expressions can be used in several different ways by GDB, and the -debugger can generate different bytecode sequences as appropriate. - - One possibility is to do expression evaluation on the target rather -than the host, such as for the conditional of a conditional tracepoint. -In such a case, GDB compiles the source expression into a bytecode -sequence that simply gets values from registers or memory, does -arithmetic, and returns a result. - - Another way to use agent expressions is for tracepoint data -collection. GDB generates a different bytecode sequence for -collection; in addition to bytecodes that do the calculation, GDB adds -`trace' bytecodes to save the pieces of memory that were used. - - * The user selects trace points in the program's code at which GDB - should collect data. - - * The user specifies expressions to evaluate at each trace point. - These expressions may denote objects in memory, in which case - those objects' contents are recorded as the program runs, or - computed values, in which case the values themselves are recorded. - - * GDB transmits the tracepoints and their associated expressions to - the GDB agent, running on the debugging target. - - * The agent arranges to be notified when a trace point is hit. - - * When execution on the target reaches a trace point, the agent - evaluates the expressions associated with that trace point, and - records the resulting values and memory ranges. - - * Later, when the user selects a given trace event and inspects the - objects and expression values recorded, GDB talks to the agent to - retrieve recorded data as necessary to meet the user's requests. - If the user asks to see an object whose contents have not been - recorded, GDB reports an error. - - - -File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions - -F.4 Varying Target Capabilities -=============================== - -Some targets don't support floating-point, and some would rather not -have to deal with `long long' operations. Also, different targets will -have different stack sizes, and different bytecode buffer lengths. - - Thus, GDB needs a way to ask the target about itself. We haven't -worked out the details yet, but in general, GDB should be able to send -the target a packet asking it to describe itself. The reply should be a -packet whose length is explicit, so we can add new information to the -packet in future revisions of the agent, without confusing old versions -of GDB, and it should contain a version number. It should contain at -least the following information: - - * whether floating point is supported - - * whether `long long' is supported - - * maximum acceptable size of bytecode stack - - * maximum acceptable length of bytecode expressions - - * which registers are actually available for collection - - * whether the target supports disabled tracepoints - - - -File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions - -F.5 Rationale -============= - -Some of the design decisions apparent above are arguable. - -What about stack overflow/underflow? - GDB should be able to query the target to discover its stack size. - Given that information, GDB can determine at translation time - whether a given expression will overflow the stack. But this spec - isn't about what kinds of error-checking GDB ought to do. - -Why are you doing everything in LONGEST? - Speed isn't important, but agent code size is; using LONGEST - brings in a bunch of support code to do things like division, etc. - So this is a serious concern. - - First, note that you don't need different bytecodes for different - operand sizes. You can generate code without _knowing_ how big the - stack elements actually are on the target. If the target only - supports 32-bit ints, and you don't send any 64-bit bytecodes, - everything just works. The observation here is that the MIPS and - the Alpha have only fixed-size registers, and you can still get - C's semantics even though most instructions only operate on - full-sized words. You just need to make sure everything is - properly sign-extended at the right times. So there is no need - for 32- and 64-bit variants of the bytecodes. Just implement - everything using the largest size you support. - - GDB should certainly check to see what sizes the target supports, - so the user can get an error earlier, rather than later. But this - information is not necessary for correctness. - -Why don't you have `>' or `<=' operators? - I want to keep the interpreter small, and we don't need them. We - can combine the `less_' opcodes with `log_not', and swap the order - of the operands, yielding all four asymmetrical comparison - operators. For example, `(x <= y)' is `! (x > y)', which is `! (y - < x)'. - -Why do you have `log_not'? -Why do you have `ext'? -Why do you have `zero_ext'? - These are all easily synthesized from other instructions, but I - expect them to be used frequently, and they're simple, so I - include them to keep bytecode strings short. - - `log_not' is equivalent to `const8 0 equal'; it's used in half the - relational operators. - - `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed', - where S is the size of the stack elements; it follows `refM' and - REG bytecodes when the value should be signed. See the next - bulleted item. - - `zero_ext N' is equivalent to `constM MASK log_and'; it's used - whenever we push the value of a register, because we can't assume - the upper bits of the register aren't garbage. - -Why not have sign-extending variants of the `ref' operators? - Because that would double the number of `ref' operators, and we - need the `ext' bytecode anyway for accessing bitfields. - -Why not have constant-address variants of the `ref' operators? - Because that would double the number of `ref' operators again, and - `const32 ADDRESS ref32' is only one byte longer. - -Why do the `refN' operators have to support unaligned fetches? - GDB will generate bytecode that fetches multi-byte values at - unaligned addresses whenever the executable's debugging - information tells it to. Furthermore, GDB does not know the value - the pointer will have when GDB generates the bytecode, so it - cannot determine whether a particular fetch will be aligned or not. - - In particular, structure bitfields may be several bytes long, but - follow no alignment rules; members of packed structures are not - necessarily aligned either. - - In general, there are many cases where unaligned references occur - in correct C code, either at the programmer's explicit request, or - at the compiler's discretion. Thus, it is simpler to make the GDB - agent bytecodes work correctly in all circumstances than to make - GDB guess in each case whether the compiler did the usual thing. - -Why are there no side-effecting operators? - Because our current client doesn't want them? That's a cheap - answer. I think the real answer is that I'm afraid of - implementing function calls. We should re-visit this issue after - the present contract is delivered. - -Why aren't the `goto' ops PC-relative? - The interpreter has the base address around anyway for PC bounds - checking, and it seemed simpler. - -Why is there only one offset size for the `goto' ops? - Offsets are currently sixteen bits. I'm not happy with this - situation either: - - Suppose we have multiple branch ops with different offset sizes. - As I generate code left-to-right, all my jumps are forward jumps - (there are no loops in expressions), so I never know the target - when I emit the jump opcode. Thus, I have to either always assume - the largest offset size, or do jump relaxation on the code after I - generate it, which seems like a big waste of time. - - I can imagine a reasonable expression being longer than 256 bytes. - I can't imagine one being longer than 64k. Thus, we need 16-bit - offsets. This kind of reasoning is so bogus, but relaxation is - pathetic. - - The other approach would be to generate code right-to-left. Then - I'd always know my offset size. That might be fun. - -Where is the function call bytecode? - When we add side-effects, we should add this. - -Why does the `reg' bytecode take a 16-bit register number? - Intel's IA-64 architecture has 128 general-purpose registers, and - 128 floating-point registers, and I'm sure it has some random - control registers. - -Why do we need `trace' and `trace_quick'? - Because GDB needs to record all the memory contents and registers - an expression touches. If the user wants to evaluate an expression - `x->y->z', the agent must record the values of `x' and `x->y' as - well as the value of `x->y->z'. - -Don't the `trace' bytecodes make the interpreter less general? - They do mean that the interpreter contains special-purpose code, - but that doesn't mean the interpreter can only be used for that - purpose. If an expression doesn't use the `trace' bytecodes, they - don't get in its way. - -Why doesn't `trace_quick' consume its arguments the way everything else does? - In general, you do want your operators to consume their arguments; - it's consistent, and generally reduces the amount of stack - rearrangement necessary. However, `trace_quick' is a kludge to - save space; it only exists so we needn't write `dup const8 SIZE - trace' before every memory reference. Therefore, it's okay for it - not to consume its arguments; it's meant for a specific context in - which we know exactly what it should do with the stack. If we're - going to have a kludge, it should be an effective kludge. - -Why does `trace16' exist? - That opcode was added by the customer that contracted Cygnus for - the data tracing work. I personally think it is unnecessary; - objects that large will be quite rare, so it is okay to use `dup - const16 SIZE trace' in those cases. - - Whatever we decide to do with `trace16', we should at least leave - opcode 0x30 reserved, to remain compatible with the customer who - added it. - - - -File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top - -Appendix G Target Descriptions -****************************** - -*Warning:* target descriptions are still under active development, and -the contents and format may change between GDB releases. The format is -expected to stabilize in the future. - - One of the challenges of using GDB to debug embedded systems is that -there are so many minor variants of each processor architecture in use. -It is common practice for vendors to start with a standard processor -core -- ARM, PowerPC, or MIPS, for example -- and then make changes to -adapt it to a particular market niche. Some architectures have -hundreds of variants, available from dozens of vendors. This leads to -a number of problems: - - * With so many different customized processors, it is difficult for - the GDB maintainers to keep up with the changes. - - * Since individual variants may have short lifetimes or limited - audiences, it may not be worthwhile to carry information about - every variant in the GDB source tree. - - * When GDB does support the architecture of the embedded system at - hand, the task of finding the correct architecture name to give the - `set architecture' command can be error-prone. - - To address these problems, the GDB remote protocol allows a target -system to not only identify itself to GDB, but to actually describe its -own features. This lets GDB support processor variants it has never -seen before -- to the extent that the descriptions are accurate, and -that GDB understands them. - - GDB must be linked with the Expat library to support XML target -descriptions. *Note Expat::. - -* Menu: - -* Retrieving Descriptions:: How descriptions are fetched from a target. -* Target Description Format:: The contents of a target description. -* Predefined Target Types:: Standard types available for target - descriptions. -* Standard Target Features:: Features GDB knows about. - - -File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions - -G.1 Retrieving Descriptions -=========================== - -Target descriptions can be read from the target automatically, or -specified by the user manually. The default behavior is to read the -description from the target. GDB retrieves it via the remote protocol -using `qXfer' requests (*note qXfer: General Query Packets.). The -ANNEX in the `qXfer' packet will be `target.xml'. The contents of the -`target.xml' annex are an XML document, of the form described in *note -Target Description Format::. - - Alternatively, you can specify a file to read for the target -description. If a file is set, the target will not be queried. The -commands to specify a file are: - -`set tdesc filename PATH' - Read the target description from PATH. - -`unset tdesc filename' - Do not read the XML target description from a file. GDB will use - the description supplied by the current target. - -`show tdesc filename' - Show the filename to read for a target description, if any. - - -File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions - -G.2 Target Description Format -============================= - -A target description annex is an XML (http://www.w3.org/XML/) document -which complies with the Document Type Definition provided in the GDB -sources in `gdb/features/gdb-target.dtd'. This means you can use -generally available tools like `xmllint' to check that your feature -descriptions are well-formed and valid. However, to help people -unfamiliar with XML write descriptions for their targets, we also -describe the grammar here. - - Target descriptions can identify the architecture of the remote -target and (for some architectures) provide information about custom -register sets. They can also identify the OS ABI of the remote target. -GDB can use this information to autoconfigure for your target, or to -warn you if you connect to an unsupported target. - - Here is a simple target description: - - <target version="1.0"> - <architecture>i386:x86-64</architecture> - </target> - -This minimal description only says that the target uses the x86-64 -architecture. - - A target description has the following overall form, with [ ] marking -optional elements and ... marking repeatable elements. The elements -are explained further below. - - <?xml version="1.0"?> - <!DOCTYPE target SYSTEM "gdb-target.dtd"> - <target version="1.0"> - [ARCHITECTURE] - [OSABI] - [COMPATIBLE] - [FEATURE...] - </target> - -The description is generally insensitive to whitespace and line breaks, -under the usual common-sense rules. The XML version declaration and -document type declaration can generally be omitted (GDB does not -require them), but specifying them may be useful for XML validation -tools. The `version' attribute for `<target>' may also be omitted, but -we recommend including it; if future versions of GDB use an incompatible -revision of `gdb-target.dtd', they will detect and report the version -mismatch. - -G.2.1 Inclusion ---------------- - -It can sometimes be valuable to split a target description up into -several different annexes, either for organizational purposes, or to -share files between different possible target descriptions. You can -divide a description into multiple files by replacing any element of -the target description with an inclusion directive of the form: - - <xi:include href="DOCUMENT"/> - -When GDB encounters an element of this form, it will retrieve the named -XML DOCUMENT, and replace the inclusion directive with the contents of -that document. If the current description was read using `qXfer', then -so will be the included document; DOCUMENT will be interpreted as the -name of an annex. If the current description was read from a file, GDB -will look for DOCUMENT as a file in the same directory where it found -the original description. - -G.2.2 Architecture ------------------- - -An `<architecture>' element has this form: - - <architecture>ARCH</architecture> - - ARCH is one of the architectures from the set accepted by `set -architecture' (*note Specifying a Debugging Target: Targets.). - -G.2.3 OS ABI ------------- - -This optional field was introduced in GDB version 7.0. Previous -versions of GDB ignore it. - - An `<osabi>' element has this form: - - <osabi>ABI-NAME</osabi> - - ABI-NAME is an OS ABI name from the same selection accepted by -`set osabi' (*note Configuring the Current ABI: ABI.). - -G.2.4 Compatible Architecture ------------------------------ - -This optional field was introduced in GDB version 7.0. Previous -versions of GDB ignore it. - - A `<compatible>' element has this form: - - <compatible>ARCH</compatible> - - ARCH is one of the architectures from the set accepted by `set -architecture' (*note Specifying a Debugging Target: Targets.). - - A `<compatible>' element is used to specify that the target is able -to run binaries in some other than the main target architecture given -by the `<architecture>' element. For example, on the Cell Broadband -Engine, the main architecture is `powerpc:common' or -`powerpc:common64', but the system is able to run binaries in the `spu' -architecture as well. The way to describe this capability with -`<compatible>' is as follows: - - <architecture>powerpc:common</architecture> - <compatible>spu</compatible> - -G.2.5 Features --------------- - -Each `<feature>' describes some logical portion of the target system. -Features are currently used to describe available CPU registers and the -types of their contents. A `<feature>' element has this form: - - <feature name="NAME"> - [TYPE...] - REG... - </feature> - -Each feature's name should be unique within the description. The name -of a feature does not matter unless GDB has some special knowledge of -the contents of that feature; if it does, the feature should have its -standard name. *Note Standard Target Features::. - -G.2.6 Types ------------ - -Any register's value is a collection of bits which GDB must interpret. -The default interpretation is a two's complement integer, but other -types can be requested by name in the register description. Some -predefined types are provided by GDB (*note Predefined Target Types::), -and the description can define additional composite types. - - Each type element must have an `id' attribute, which gives a unique -(within the containing `<feature>') name to the type. Types must be -defined before they are used. - - Some targets offer vector registers, which can be treated as arrays -of scalar elements. These types are written as `<vector>' elements, -specifying the array element type, TYPE, and the number of elements, -COUNT: - - <vector id="ID" type="TYPE" count="COUNT"/> - - If a register's value is usefully viewed in multiple ways, define it -with a union type containing the useful representations. The `<union>' -element contains one or more `<field>' elements, each of which has a -NAME and a TYPE: - - <union id="ID"> - <field name="NAME" type="TYPE"/> - ... - </union> - - If a register's value is composed from several separate values, -define it with a structure type. There are two forms of the `<struct>' -element; a `<struct>' element must either contain only bitfields or -contain no bitfields. If the structure contains only bitfields, its -total size in bytes must be specified, each bitfield must have an -explicit start and end, and bitfields are automatically assigned an -integer type. The field's START should be less than or equal to its -END, and zero represents the least significant bit. - - <struct id="ID" size="SIZE"> - <field name="NAME" start="START" end="END"/> - ... - </struct> - - If the structure contains no bitfields, then each field has an -explicit type, and no implicit padding is added. - - <struct id="ID"> - <field name="NAME" type="TYPE"/> - ... - </struct> - - If a register's value is a series of single-bit flags, define it with -a flags type. The `<flags>' element has an explicit SIZE and contains -one or more `<field>' elements. Each field has a NAME, a START, and an -END. Only single-bit flags are supported. - - <flags id="ID" size="SIZE"> - <field name="NAME" start="START" end="END"/> - ... - </flags> - -G.2.7 Registers ---------------- - -Each register is represented as an element with this form: - - <reg name="NAME" - bitsize="SIZE" - [regnum="NUM"] - [save-restore="SAVE-RESTORE"] - [type="TYPE"] - [group="GROUP"]/> - -The components are as follows: - -NAME - The register's name; it must be unique within the target - description. - -BITSIZE - The register's size, in bits. - -REGNUM - The register's number. If omitted, a register's number is one - greater than that of the previous register (either in the current - feature or in a preceeding feature); the first register in the - target description defaults to zero. This register number is used - to read or write the register; e.g. it is used in the remote `p' - and `P' packets, and registers appear in the `g' and `G' packets - in order of increasing register number. - -SAVE-RESTORE - Whether the register should be preserved across inferior function - calls; this must be either `yes' or `no'. The default is `yes', - which is appropriate for most registers except for some system - control registers; this is not related to the target's ABI. - -TYPE - The type of the register. TYPE may be a predefined type, a type - defined in the current feature, or one of the special types `int' - and `float'. `int' is an integer type of the correct size for - BITSIZE, and `float' is a floating point type (in the - architecture's normal floating point format) of the correct size - for BITSIZE. The default is `int'. - -GROUP - The register group to which this register belongs. GROUP must be - either `general', `float', or `vector'. If no GROUP is specified, - GDB will not display the register in `info registers'. - - - -File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions - -G.3 Predefined Target Types -=========================== - -Type definitions in the self-description can build up composite types -from basic building blocks, but can not define fundamental types. -Instead, standard identifiers are provided by GDB for the fundamental -types. The currently supported types are: - -`int8' -`int16' -`int32' -`int64' -`int128' - Signed integer types holding the specified number of bits. - -`uint8' -`uint16' -`uint32' -`uint64' -`uint128' - Unsigned integer types holding the specified number of bits. - -`code_ptr' -`data_ptr' - Pointers to unspecified code and data. The program counter and - any dedicated return address register may be marked as code - pointers; printing a code pointer converts it into a symbolic - address. The stack pointer and any dedicated address registers - may be marked as data pointers. - -`ieee_single' - Single precision IEEE floating point. - -`ieee_double' - Double precision IEEE floating point. - -`arm_fpa_ext' - The 12-byte extended precision format used by ARM FPA registers. - -`i387_ext' - The 10-byte extended precision format used by x87 registers. - -`i386_eflags' - 32bit EFLAGS register used by x86. - -`i386_mxcsr' - 32bit MXCSR register used by x86. - - - -File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions - -G.4 Standard Target Features -============================ - -A target description must contain either no registers or all the -target's registers. If the description contains no registers, then GDB -will assume a default register layout, selected based on the -architecture. If the description contains any registers, the default -layout will not be used; the standard registers must be described in -the target description, in such a way that GDB can recognize them. - - This is accomplished by giving specific names to feature elements -which contain standard registers. GDB will look for features with -those names and verify that they contain the expected registers; if any -known feature is missing required registers, or if any required feature -is missing, GDB will reject the target description. You can add -additional registers to any of the standard features -- GDB will -display them just as if they were added to an unrecognized feature. - - This section lists the known features and their expected contents. -Sample XML documents for these features are included in the GDB source -tree, in the directory `gdb/features'. - - Names recognized by GDB should include the name of the company or -organization which selected the name, and the overall architecture to -which the feature applies; so e.g. the feature containing ARM core -registers is named `org.gnu.gdb.arm.core'. - - The names of registers are not case sensitive for the purpose of -recognizing standard features, but GDB will only display registers -using the capitalization used in the description. - -* Menu: - -* ARM Features:: -* i386 Features:: -* MIPS Features:: -* M68K Features:: -* PowerPC Features:: - - -File: gdb.info, Node: ARM Features, Next: i386 Features, Up: Standard Target Features - -G.4.1 ARM Features ------------------- - -The `org.gnu.gdb.arm.core' feature is required for non-M-profile ARM -targets. It should contain registers `r0' through `r13', `sp', `lr', -`pc', and `cpsr'. - - For M-profile targets (e.g. Cortex-M3), the `org.gnu.gdb.arm.core' -feature is replaced by `org.gnu.gdb.arm.m-profile'. It should contain -registers `r0' through `r13', `sp', `lr', `pc', and `xpsr'. - - The `org.gnu.gdb.arm.fpa' feature is optional. If present, it -should contain registers `f0' through `f7' and `fps'. - - The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it -should contain at least registers `wR0' through `wR15' and `wCGR0' -through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers -are optional. - - The `org.gnu.gdb.arm.vfp' feature is optional. If present, it -should contain at least registers `d0' through `d15'. If they are -present, `d16' through `d31' should also be included. GDB will -synthesize the single-precision registers from halves of the -double-precision registers. - - The `org.gnu.gdb.arm.neon' feature is optional. It does not need to -contain registers; it instructs GDB to display the VFP double-precision -registers as vectors and to synthesize the quad-precision registers -from pairs of double-precision registers. If this feature is present, -`org.gnu.gdb.arm.vfp' must also be present and include 32 -double-precision registers. - - -File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features - -G.4.2 i386 Features -------------------- - -The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. -It should describe the following registers: - - - `eax' through `edi' plus `eip' for i386 - - - `rax' through `r15' plus `rip' for amd64 - - - `eflags', `cs', `ss', `ds', `es', `fs', `gs' - - - `st0' through `st7' - - - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and - `fop' - - The register sets may be different, depending on the target. - - The `org.gnu.gdb.i386.sse' feature is optional. It should describe -registers: - - - `xmm0' through `xmm7' for i386 - - - `xmm0' through `xmm15' for amd64 - - - `mxcsr' - - The `org.gnu.gdb.i386.avx' feature is optional and requires the -`org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits -of YMM registers: - - - `ymm0h' through `ymm7h' for i386 - - - `ymm0h' through `ymm15h' for amd64 - - The `org.gnu.gdb.i386.linux' feature is optional. It should -describe a single register, `orig_eax'. - - -File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features - -G.4.3 MIPS Features -------------------- - -The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It -should contain registers `r0' through `r31', `lo', `hi', and `pc'. -They may be 32-bit or 64-bit depending on the target. - - The `org.gnu.gdb.mips.cp0' feature is also required. It should -contain at least the `status', `badvaddr', and `cause' registers. They -may be 32-bit or 64-bit depending on the target. - - The `org.gnu.gdb.mips.fpu' feature is currently required, though it -may be optional in a future version of GDB. It should contain -registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or -64-bit depending on the target. - - The `org.gnu.gdb.mips.linux' feature is optional. It should contain -a single register, `restart', which is used by the Linux kernel to -control restartable syscalls. - - -File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features - -G.4.4 M68K Features -------------------- - -``org.gnu.gdb.m68k.core'' -``org.gnu.gdb.coldfire.core'' -``org.gnu.gdb.fido.core'' - One of those features must be always present. The feature that is - present determines which flavor of m68k is used. The feature that - is present should contain registers `d0' through `d7', `a0' - through `a5', `fp', `sp', `ps' and `pc'. - -``org.gnu.gdb.coldfire.fp'' - This feature is optional. If present, it should contain registers - `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'. - - -File: gdb.info, Node: PowerPC Features, Prev: M68K Features, Up: Standard Target Features - -G.4.5 PowerPC Features ----------------------- - -The `org.gnu.gdb.power.core' feature is required for PowerPC targets. -It should contain registers `r0' through `r31', `pc', `msr', `cr', -`lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the -target. - - The `org.gnu.gdb.power.fpu' feature is optional. It should contain -registers `f0' through `f31' and `fpscr'. - - The `org.gnu.gdb.power.altivec' feature is optional. It should -contain registers `vr0' through `vr31', `vscr', and `vrsave'. - - The `org.gnu.gdb.power.vsx' feature is optional. It should contain -registers `vs0h' through `vs31h'. GDB will combine these registers -with the floating point registers (`f0' through `f31') and the altivec -registers (`vr0' through `vr31') to present the 128-bit wide registers -`vs0' through `vs63', the set of vector registers for POWER7. - - The `org.gnu.gdb.power.spe' feature is optional. It should contain -registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets -should provide 32-bit registers in `org.gnu.gdb.power.core' and provide -the upper halves in `ev0h' through `ev31h'. GDB will combine these to -present registers `ev0' through `ev31' to the user. - - -File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top - -Appendix H Operating System Information -*************************************** - -* Menu: - -* Process list:: - - Users of GDB often wish to obtain information about the state of the -operating system running on the target--for example the list of -processes, or the list of open files. This section describes the -mechanism that makes it possible. This mechanism is similar to the -target features mechanism (*note Target Descriptions::), but focuses on -a different aspect of target. - - Operating system information is retrived from the target via the -remote protocol, using `qXfer' requests (*note qXfer osdata read::). -The object name in the request should be `osdata', and the ANNEX -identifies the data to be fetched. - - -File: gdb.info, Node: Process list, Up: Operating System Information - -H.1 Process list -================ - -When requesting the process list, the ANNEX field in the `qXfer' -request should be `processes'. The returned data is an XML document. -The formal syntax of this document is defined in -`gdb/features/osdata.dtd'. - - An example document is: - - <?xml version="1.0"?> - <!DOCTYPE target SYSTEM "osdata.dtd"> - <osdata type="processes"> - <item> - <column name="pid">1</column> - <column name="user">root</column> - <column name="command">/sbin/init</column> - <column name="cores">1,2,3</column> - </item> - </osdata> - - Each item should include a column whose name is `pid'. The value of -that column should identify the process on the target. The `user' and -`command' columns are optional, and will be displayed by GDB. The -`cores' column, if present, should contain a comma-separated list of -cores that this process is running on. Target may provide additional -columns, which GDB currently ignores. - - -File: gdb.info, Node: Trace File Format, Next: Copying, Prev: Operating System Information, Up: Top - -Appendix I Trace File Format -**************************** - -The trace file comes in three parts: a header, a textual description -section, and a trace frame section with binary data. - - The header has the form `\x7fTRACE0\n'. The first byte is `0x7f' so -as to indicate that the file contains binary data, while the `0' is a -version number that may have different values in the future. - - The description section consists of multiple lines of ASCII text -separated by newline characters (`0xa'). The lines may include a -variety of optional descriptive or context-setting information, such as -tracepoint definitions or register set size. GDB will ignore any line -that it does not recognize. An empty line marks the end of this -section. - - The trace frame section consists of a number of consecutive frames. -Each frame begins with a two-byte tracepoint number, followed by a -four-byte size giving the amount of data in the frame. The data in the -frame consists of a number of blocks, each introduced by a character -indicating its type (at least register, memory, and trace state -variable). The data in this section is raw binary, not a hexadecimal -or other encoding; its endianness matches the target's endianness. - -`R BYTES' - Register block. The number and ordering of bytes matches that of a - `g' packet in the remote protocol. Note that these are the actual - bytes, in target order and GDB register order, not a hexadecimal - encoding. - -`M ADDRESS LENGTH BYTES...' - Memory block. This is a contiguous block of memory, at the 8-byte - address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH - bytes. - -`V NUMBER VALUE' - Trace state variable block. This records the 8-byte signed value - VALUE of trace state variable numbered NUMBER. - - - Future enhancements of the trace file format may include additional -types of blocks. - - -File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Trace File Format, Up: Top - -Appendix J GNU GENERAL PUBLIC LICENSE -************************************* - - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' - - Everyone is permitted to copy and distribute verbatim copies of this - license document, but changing it is not allowed. - -Preamble -======== - -The GNU General Public License is a free, copyleft license for software -and other kinds of works. - - The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom to -share and change all versions of a program--to make sure it remains -free software for all its users. We, the Free Software Foundation, use -the GNU General Public License for most of our software; it applies -also to any other work released this way by its authors. You can apply -it to your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - - To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the software, -or if you modify it: responsibilities to respect the freedom of others. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, receive -or can get the source code. And you must show them these terms so they -know their rights. - - Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - - For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - - Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those domains -in future versions of the GPL, as needed to protect the freedom of -users. - - Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish to -avoid the special danger that patents applied to a free program could -make it effectively proprietary. To prevent this, the GPL assures that -patents cannot be used to render the program non-free. - - The precise terms and conditions for copying, distribution and -modification follow. - -TERMS AND CONDITIONS -==================== - - 0. Definitions. - - "This License" refers to version 3 of the GNU General Public - License. - - "Copyright" also means copyright-like laws that apply to other - kinds of works, such as semiconductor masks. - - "The Program" refers to any copyrightable work licensed under this - License. Each licensee is addressed as "you". "Licensees" and - "recipients" may be individuals or organizations. - - To "modify" a work means to copy from or adapt all or part of the - work in a fashion requiring copyright permission, other than the - making of an exact copy. The resulting work is called a "modified - version" of the earlier work or a work "based on" the earlier work. - - A "covered work" means either the unmodified Program or a work - based on the Program. - - To "propagate" a work means to do anything with it that, without - permission, would make you directly or secondarily liable for - infringement under applicable copyright law, except executing it - on a computer or modifying a private copy. Propagation includes - copying, distribution (with or without modification), making - available to the public, and in some countries other activities as - well. - - To "convey" a work means any kind of propagation that enables other - parties to make or receive copies. Mere interaction with a user - through a computer network, with no transfer of a copy, is not - conveying. - - An interactive user interface displays "Appropriate Legal Notices" - to the extent that it includes a convenient and prominently visible - feature that (1) displays an appropriate copyright notice, and (2) - tells the user that there is no warranty for the work (except to - the extent that warranties are provided), that licensees may - convey the work under this License, and how to view a copy of this - License. If the interface presents a list of user commands or - options, such as a menu, a prominent item in the list meets this - criterion. - - 1. Source Code. - - The "source code" for a work means the preferred form of the work - for making modifications to it. "Object code" means any - non-source form of a work. - - A "Standard Interface" means an interface that either is an - official standard defined by a recognized standards body, or, in - the case of interfaces specified for a particular programming - language, one that is widely used among developers working in that - language. - - The "System Libraries" of an executable work include anything, - other than the work as a whole, that (a) is included in the normal - form of packaging a Major Component, but which is not part of that - Major Component, and (b) serves only to enable use of the work - with that Major Component, or to implement a Standard Interface - for which an implementation is available to the public in source - code form. A "Major Component", in this context, means a major - essential component (kernel, window system, and so on) of the - specific operating system (if any) on which the executable work - runs, or a compiler used to produce the work, or an object code - interpreter used to run it. - - The "Corresponding Source" for a work in object code form means all - the source code needed to generate, install, and (for an executable - work) run the object code and to modify the work, including - scripts to control those activities. However, it does not include - the work's System Libraries, or general-purpose tools or generally - available free programs which are used unmodified in performing - those activities but which are not part of the work. For example, - Corresponding Source includes interface definition files - associated with source files for the work, and the source code for - shared libraries and dynamically linked subprograms that the work - is specifically designed to require, such as by intimate data - communication or control flow between those subprograms and other - parts of the work. - - The Corresponding Source need not include anything that users can - regenerate automatically from other parts of the Corresponding - Source. - - The Corresponding Source for a work in source code form is that - same work. - - 2. Basic Permissions. - - All rights granted under this License are granted for the term of - copyright on the Program, and are irrevocable provided the stated - conditions are met. This License explicitly affirms your unlimited - permission to run the unmodified Program. The output from running - a covered work is covered by this License only if the output, - given its content, constitutes a covered work. This License - acknowledges your rights of fair use or other equivalent, as - provided by copyright law. - - You may make, run and propagate covered works that you do not - convey, without conditions so long as your license otherwise - remains in force. You may convey covered works to others for the - sole purpose of having them make modifications exclusively for - you, or provide you with facilities for running those works, - provided that you comply with the terms of this License in - conveying all material for which you do not control copyright. - Those thus making or running the covered works for you must do so - exclusively on your behalf, under your direction and control, on - terms that prohibit them from making any copies of your - copyrighted material outside their relationship with you. - - Conveying under any other circumstances is permitted solely under - the conditions stated below. Sublicensing is not allowed; section - 10 makes it unnecessary. - - 3. Protecting Users' Legal Rights From Anti-Circumvention Law. - - No covered work shall be deemed part of an effective technological - measure under any applicable law fulfilling obligations under - article 11 of the WIPO copyright treaty adopted on 20 December - 1996, or similar laws prohibiting or restricting circumvention of - such measures. - - When you convey a covered work, you waive any legal power to forbid - circumvention of technological measures to the extent such - circumvention is effected by exercising rights under this License - with respect to the covered work, and you disclaim any intention - to limit operation or modification of the work as a means of - enforcing, against the work's users, your or third parties' legal - rights to forbid circumvention of technological measures. - - 4. Conveying Verbatim Copies. - - You may convey verbatim copies of the Program's source code as you - receive it, in any medium, provided that you conspicuously and - appropriately publish on each copy an appropriate copyright notice; - keep intact all notices stating that this License and any - non-permissive terms added in accord with section 7 apply to the - code; keep intact all notices of the absence of any warranty; and - give all recipients a copy of this License along with the Program. - - You may charge any price or no price for each copy that you convey, - and you may offer support or warranty protection for a fee. - - 5. Conveying Modified Source Versions. - - You may convey a work based on the Program, or the modifications to - produce it from the Program, in the form of source code under the - terms of section 4, provided that you also meet all of these - conditions: - - a. The work must carry prominent notices stating that you - modified it, and giving a relevant date. - - b. The work must carry prominent notices stating that it is - released under this License and any conditions added under - section 7. This requirement modifies the requirement in - section 4 to "keep intact all notices". - - c. You must license the entire work, as a whole, under this - License to anyone who comes into possession of a copy. This - License will therefore apply, along with any applicable - section 7 additional terms, to the whole of the work, and all - its parts, regardless of how they are packaged. This License - gives no permission to license the work in any other way, but - it does not invalidate such permission if you have separately - received it. - - d. If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has - interactive interfaces that do not display Appropriate Legal - Notices, your work need not make them do so. - - A compilation of a covered work with other separate and independent - works, which are not by their nature extensions of the covered - work, and which are not combined with it such as to form a larger - program, in or on a volume of a storage or distribution medium, is - called an "aggregate" if the compilation and its resulting - copyright are not used to limit the access or legal rights of the - compilation's users beyond what the individual works permit. - Inclusion of a covered work in an aggregate does not cause this - License to apply to the other parts of the aggregate. - - 6. Conveying Non-Source Forms. - - You may convey a covered work in object code form under the terms - of sections 4 and 5, provided that you also convey the - machine-readable Corresponding Source under the terms of this - License, in one of these ways: - - a. Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by the - Corresponding Source fixed on a durable physical medium - customarily used for software interchange. - - b. Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by a - written offer, valid for at least three years and valid for - as long as you offer spare parts or customer support for that - product model, to give anyone who possesses the object code - either (1) a copy of the Corresponding Source for all the - software in the product that is covered by this License, on a - durable physical medium customarily used for software - interchange, for a price no more than your reasonable cost of - physically performing this conveying of source, or (2) access - to copy the Corresponding Source from a network server at no - charge. - - c. Convey individual copies of the object code with a copy of - the written offer to provide the Corresponding Source. This - alternative is allowed only occasionally and noncommercially, - and only if you received the object code with such an offer, - in accord with subsection 6b. - - d. Convey the object code by offering access from a designated - place (gratis or for a charge), and offer equivalent access - to the Corresponding Source in the same way through the same - place at no further charge. You need not require recipients - to copy the Corresponding Source along with the object code. - If the place to copy the object code is a network server, the - Corresponding Source may be on a different server (operated - by you or a third party) that supports equivalent copying - facilities, provided you maintain clear directions next to - the object code saying where to find the Corresponding Source. - Regardless of what server hosts the Corresponding Source, you - remain obligated to ensure that it is available for as long - as needed to satisfy these requirements. - - e. Convey the object code using peer-to-peer transmission, - provided you inform other peers where the object code and - Corresponding Source of the work are being offered to the - general public at no charge under subsection 6d. - - - A separable portion of the object code, whose source code is - excluded from the Corresponding Source as a System Library, need - not be included in conveying the object code work. - - A "User Product" is either (1) a "consumer product", which means - any tangible personal property which is normally used for personal, - family, or household purposes, or (2) anything designed or sold for - incorporation into a dwelling. In determining whether a product - is a consumer product, doubtful cases shall be resolved in favor of - coverage. For a particular product received by a particular user, - "normally used" refers to a typical or common use of that class of - product, regardless of the status of the particular user or of the - way in which the particular user actually uses, or expects or is - expected to use, the product. A product is a consumer product - regardless of whether the product has substantial commercial, - industrial or non-consumer uses, unless such uses represent the - only significant mode of use of the product. - - "Installation Information" for a User Product means any methods, - procedures, authorization keys, or other information required to - install and execute modified versions of a covered work in that - User Product from a modified version of its Corresponding Source. - The information must suffice to ensure that the continued - functioning of the modified object code is in no case prevented or - interfered with solely because modification has been made. - - If you convey an object code work under this section in, or with, - or specifically for use in, a User Product, and the conveying - occurs as part of a transaction in which the right of possession - and use of the User Product is transferred to the recipient in - perpetuity or for a fixed term (regardless of how the transaction - is characterized), the Corresponding Source conveyed under this - section must be accompanied by the Installation Information. But - this requirement does not apply if neither you nor any third party - retains the ability to install modified object code on the User - Product (for example, the work has been installed in ROM). - - The requirement to provide Installation Information does not - include a requirement to continue to provide support service, - warranty, or updates for a work that has been modified or - installed by the recipient, or for the User Product in which it - has been modified or installed. Access to a network may be denied - when the modification itself materially and adversely affects the - operation of the network or violates the rules and protocols for - communication across the network. - - Corresponding Source conveyed, and Installation Information - provided, in accord with this section must be in a format that is - publicly documented (and with an implementation available to the - public in source code form), and must require no special password - or key for unpacking, reading or copying. - - 7. Additional Terms. - - "Additional permissions" are terms that supplement the terms of - this License by making exceptions from one or more of its - conditions. Additional permissions that are applicable to the - entire Program shall be treated as though they were included in - this License, to the extent that they are valid under applicable - law. If additional permissions apply only to part of the Program, - that part may be used separately under those permissions, but the - entire Program remains governed by this License without regard to - the additional permissions. - - When you convey a copy of a covered work, you may at your option - remove any additional permissions from that copy, or from any part - of it. (Additional permissions may be written to require their own - removal in certain cases when you modify the work.) You may place - additional permissions on material, added by you to a covered work, - for which you have or can give appropriate copyright permission. - - Notwithstanding any other provision of this License, for material - you add to a covered work, you may (if authorized by the copyright - holders of that material) supplement the terms of this License - with terms: - - a. Disclaiming warranty or limiting liability differently from - the terms of sections 15 and 16 of this License; or - - b. Requiring preservation of specified reasonable legal notices - or author attributions in that material or in the Appropriate - Legal Notices displayed by works containing it; or - - c. Prohibiting misrepresentation of the origin of that material, - or requiring that modified versions of such material be - marked in reasonable ways as different from the original - version; or - - d. Limiting the use for publicity purposes of names of licensors - or authors of the material; or - - e. Declining to grant rights under trademark law for use of some - trade names, trademarks, or service marks; or - - f. Requiring indemnification of licensors and authors of that - material by anyone who conveys the material (or modified - versions of it) with contractual assumptions of liability to - the recipient, for any liability that these contractual - assumptions directly impose on those licensors and authors. - - All other non-permissive additional terms are considered "further - restrictions" within the meaning of section 10. If the Program as - you received it, or any part of it, contains a notice stating that - it is governed by this License along with a term that is a further - restriction, you may remove that term. If a license document - contains a further restriction but permits relicensing or - conveying under this License, you may add to a covered work - material governed by the terms of that license document, provided - that the further restriction does not survive such relicensing or - conveying. - - If you add terms to a covered work in accord with this section, you - must place, in the relevant source files, a statement of the - additional terms that apply to those files, or a notice indicating - where to find the applicable terms. - - Additional terms, permissive or non-permissive, may be stated in - the form of a separately written license, or stated as exceptions; - the above requirements apply either way. - - 8. Termination. - - You may not propagate or modify a covered work except as expressly - provided under this License. Any attempt otherwise to propagate or - modify it is void, and will automatically terminate your rights - under this License (including any patent licenses granted under - the third paragraph of section 11). - - However, if you cease all violation of this License, then your - license from a particular copyright holder is reinstated (a) - provisionally, unless and until the copyright holder explicitly - and finally terminates your license, and (b) permanently, if the - copyright holder fails to notify you of the violation by some - reasonable means prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is - reinstated permanently if the copyright holder notifies you of the - violation by some reasonable means, this is the first time you have - received notice of violation of this License (for any work) from - that copyright holder, and you cure the violation prior to 30 days - after your receipt of the notice. - - Termination of your rights under this section does not terminate - the licenses of parties who have received copies or rights from - you under this License. If your rights have been terminated and - not permanently reinstated, you do not qualify to receive new - licenses for the same material under section 10. - - 9. Acceptance Not Required for Having Copies. - - You are not required to accept this License in order to receive or - run a copy of the Program. Ancillary propagation of a covered work - occurring solely as a consequence of using peer-to-peer - transmission to receive a copy likewise does not require - acceptance. However, nothing other than this License grants you - permission to propagate or modify any covered work. These actions - infringe copyright if you do not accept this License. Therefore, - by modifying or propagating a covered work, you indicate your - acceptance of this License to do so. - - 10. Automatic Licensing of Downstream Recipients. - - Each time you convey a covered work, the recipient automatically - receives a license from the original licensors, to run, modify and - propagate that work, subject to this License. You are not - responsible for enforcing compliance by third parties with this - License. - - An "entity transaction" is a transaction transferring control of an - organization, or substantially all assets of one, or subdividing an - organization, or merging organizations. If propagation of a - covered work results from an entity transaction, each party to that - transaction who receives a copy of the work also receives whatever - licenses to the work the party's predecessor in interest had or - could give under the previous paragraph, plus a right to - possession of the Corresponding Source of the work from the - predecessor in interest, if the predecessor has it or can get it - with reasonable efforts. - - You may not impose any further restrictions on the exercise of the - rights granted or affirmed under this License. For example, you - may not impose a license fee, royalty, or other charge for - exercise of rights granted under this License, and you may not - initiate litigation (including a cross-claim or counterclaim in a - lawsuit) alleging that any patent claim is infringed by making, - using, selling, offering for sale, or importing the Program or any - portion of it. - - 11. Patents. - - A "contributor" is a copyright holder who authorizes use under this - License of the Program or a work on which the Program is based. - The work thus licensed is called the contributor's "contributor - version". - - A contributor's "essential patent claims" are all patent claims - owned or controlled by the contributor, whether already acquired or - hereafter acquired, that would be infringed by some manner, - permitted by this License, of making, using, or selling its - contributor version, but do not include claims that would be - infringed only as a consequence of further modification of the - contributor version. For purposes of this definition, "control" - includes the right to grant patent sublicenses in a manner - consistent with the requirements of this License. - - Each contributor grants you a non-exclusive, worldwide, - royalty-free patent license under the contributor's essential - patent claims, to make, use, sell, offer for sale, import and - otherwise run, modify and propagate the contents of its - contributor version. - - In the following three paragraphs, a "patent license" is any - express agreement or commitment, however denominated, not to - enforce a patent (such as an express permission to practice a - patent or covenant not to sue for patent infringement). To - "grant" such a patent license to a party means to make such an - agreement or commitment not to enforce a patent against the party. - - If you convey a covered work, knowingly relying on a patent - license, and the Corresponding Source of the work is not available - for anyone to copy, free of charge and under the terms of this - License, through a publicly available network server or other - readily accessible means, then you must either (1) cause the - Corresponding Source to be so available, or (2) arrange to deprive - yourself of the benefit of the patent license for this particular - work, or (3) arrange, in a manner consistent with the requirements - of this License, to extend the patent license to downstream - recipients. "Knowingly relying" means you have actual knowledge - that, but for the patent license, your conveying the covered work - in a country, or your recipient's use of the covered work in a - country, would infringe one or more identifiable patents in that - country that you have reason to believe are valid. - - If, pursuant to or in connection with a single transaction or - arrangement, you convey, or propagate by procuring conveyance of, a - covered work, and grant a patent license to some of the parties - receiving the covered work authorizing them to use, propagate, - modify or convey a specific copy of the covered work, then the - patent license you grant is automatically extended to all - recipients of the covered work and works based on it. - - A patent license is "discriminatory" if it does not include within - the scope of its coverage, prohibits the exercise of, or is - conditioned on the non-exercise of one or more of the rights that - are specifically granted under this License. You may not convey a - covered work if you are a party to an arrangement with a third - party that is in the business of distributing software, under - which you make payment to the third party based on the extent of - your activity of conveying the work, and under which the third - party grants, to any of the parties who would receive the covered - work from you, a discriminatory patent license (a) in connection - with copies of the covered work conveyed by you (or copies made - from those copies), or (b) primarily for and in connection with - specific products or compilations that contain the covered work, - unless you entered into that arrangement, or that patent license - was granted, prior to 28 March 2007. - - Nothing in this License shall be construed as excluding or limiting - any implied license or other defenses to infringement that may - otherwise be available to you under applicable patent law. - - 12. No Surrender of Others' Freedom. - - If conditions are imposed on you (whether by court order, - agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this - License. If you cannot convey a covered work so as to satisfy - simultaneously your obligations under this License and any other - pertinent obligations, then as a consequence you may not convey it - at all. For example, if you agree to terms that obligate you to - collect a royalty for further conveying from those to whom you - convey the Program, the only way you could satisfy both those - terms and this License would be to refrain entirely from conveying - the Program. - - 13. Use with the GNU Affero General Public License. - - Notwithstanding any other provision of this License, you have - permission to link or combine any covered work with a work licensed - under version 3 of the GNU Affero General Public License into a - single combined work, and to convey the resulting work. The terms - of this License will continue to apply to the part which is the - covered work, but the special requirements of the GNU Affero - General Public License, section 13, concerning interaction through - a network will apply to the combination as such. - - 14. Revised Versions of this License. - - The Free Software Foundation may publish revised and/or new - versions of the GNU General Public License from time to time. - Such new versions will be similar in spirit to the present - version, but may differ in detail to address new problems or - concerns. - - Each version is given a distinguishing version number. If the - Program specifies that a certain numbered version of the GNU - General Public License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that numbered version or of any later version published by the - Free Software Foundation. If the Program does not specify a - version number of the GNU General Public License, you may choose - any version ever published by the Free Software Foundation. - - If the Program specifies that a proxy can decide which future - versions of the GNU General Public License can be used, that - proxy's public statement of acceptance of a version permanently - authorizes you to choose that version for the Program. - - Later license versions may give you additional or different - permissions. However, no additional obligations are imposed on any - author or copyright holder as a result of your choosing to follow a - later version. - - 15. Disclaimer of Warranty. - - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY - APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE - COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" - WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, - INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE - RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. - SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL - NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. Limitation of Liability. - - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES - AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU - FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR - CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE - THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA - BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD - PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER - PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF - THE POSSIBILITY OF SUCH DAMAGES. - - 17. Interpretation of Sections 15 and 16. - - If the disclaimer of warranty and limitation of liability provided - above cannot be given local legal effect according to their terms, - reviewing courts shall apply local law that most closely - approximates an absolute waiver of all civil liability in - connection with the Program, unless a warranty or assumption of - liability accompanies a copy of the Program in return for a fee. - - -END OF TERMS AND CONDITIONS -=========================== - -How to Apply These Terms to Your New Programs -============================================= - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least the -"copyright" line and a pointer to where the full notice is found. - - ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. - Copyright (C) YEAR NAME OF AUTHOR - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or (at - your option) any later version. - - This program is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see `http://www.gnu.org/licenses/'. - - Also add information on how to contact you by electronic and paper -mail. - - If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - - PROGRAM Copyright (C) YEAR NAME OF AUTHOR - This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - - The hypothetical commands `show w' and `show c' should show the -appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an "about box". - - You should also get your employer (if you work as a programmer) or -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. For more information on this, and how to apply and follow -the GNU GPL, see `http://www.gnu.org/licenses/'. - - The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use the -GNU Lesser General Public License instead of this License. But first, -please read `http://www.gnu.org/philosophy/why-not-lgpl.html'. - - -File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top - -Appendix K GNU Free Documentation License -***************************************** - - Version 1.3, 3 November 2008 - - Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. - `http://fsf.org/' - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - The "publisher" means any person or entity that distributes copies - of the Document to the public. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included in an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warranty Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense, or distribute it is void, - and will automatically terminate your rights under this License. - - However, if you cease all violation of this License, then your - license from a particular copyright holder is reinstated (a) - provisionally, unless and until the copyright holder explicitly - and finally terminates your license, and (b) permanently, if the - copyright holder fails to notify you of the violation by some - reasonable means prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is - reinstated permanently if the copyright holder notifies you of the - violation by some reasonable means, this is the first time you have - received notice of violation of this License (for any work) from - that copyright holder, and you cure the violation prior to 30 days - after your receipt of the notice. - - Termination of your rights under this section does not terminate - the licenses of parties who have received copies or rights from - you under this License. If your rights have been terminated and - not permanently reinstated, receipt of a copy of some or all of - the same material does not give you any rights to use it. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. If the Document specifies that a proxy - can decide which future versions of this License can be used, that - proxy's public statement of acceptance of a version permanently - authorizes you to choose that version for the Document. - - 11. RELICENSING - - "Massive Multiauthor Collaboration Site" (or "MMC Site") means any - World Wide Web server that publishes copyrightable works and also - provides prominent facilities for anybody to edit those works. A - public wiki that anybody can edit is an example of such a server. - A "Massive Multiauthor Collaboration" (or "MMC") contained in the - site means any set of copyrightable works thus published on the MMC - site. - - "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 - license published by Creative Commons Corporation, a not-for-profit - corporation with a principal place of business in San Francisco, - California, as well as future copyleft versions of that license - published by that same organization. - - "Incorporate" means to publish or republish a Document, in whole or - in part, as part of another Document. - - An MMC is "eligible for relicensing" if it is licensed under this - License, and if all works that were first published under this - License somewhere other than this MMC, and subsequently - incorporated in whole or in part into the MMC, (1) had no cover - texts or invariant sections, and (2) were thus incorporated prior - to November 1, 2008. - - The operator of an MMC Site may republish an MMC contained in the - site under CC-BY-SA on the same site at any time before August 1, - 2009, provided the MMC is eligible for relicensing. - - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - 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 no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover -Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: gdb.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - -Index -***** - - -* Menu: - -* ! packet: Packets. (line 49) -* "No symbol "foo" in current context": Variables. (line 74) -* # (a comment): Command Syntax. (line 38) -* # in Modula-2: GDB/M2. (line 18) -* $: Value History. (line 13) -* $$: Value History. (line 13) -* $_ and info breakpoints: Set Breaks. (line 128) -* $_ and info line: Machine Code. (line 30) -* $_, $__, and value history: Memory. (line 109) -* $_, convenience variable: Convenience Vars. (line 64) -* $__, convenience variable: Convenience Vars. (line 73) -* $_exitcode, convenience variable: Convenience Vars. (line 79) -* $_sdata, collect: Tracepoint Actions. (line 65) -* $_sdata, inspect, convenience variable: Convenience Vars. (line 83) -* $_siginfo, convenience variable: Convenience Vars. (line 89) -* $_thread, convenience variable: Threads. (line 116) -* $_tlb, convenience variable: Convenience Vars. (line 95) -* $bpnum, convenience variable: Set Breaks. (line 6) -* $cdir, convenience variable: Source Path. (line 108) -* $cwd, convenience variable: Source Path. (line 108) -* $tpnum: Create and Delete Tracepoints. - (line 98) -* $trace_file: Tracepoint Variables. - (line 16) -* $trace_frame: Tracepoint Variables. - (line 6) -* $trace_func: Tracepoint Variables. - (line 19) -* $trace_line: Tracepoint Variables. - (line 13) -* $tracepoint: Tracepoint Variables. - (line 10) -* --annotate: Mode Options. (line 107) -* --args: Mode Options. (line 120) -* --batch: Mode Options. (line 23) -* --batch-silent: Mode Options. (line 41) -* --baud: Mode Options. (line 126) -* --cd: Mode Options. (line 82) -* --command: File Options. (line 51) -* --core: File Options. (line 43) -* --data-directory: Mode Options. (line 86) -* --directory: File Options. (line 67) -* --disable-gdb-index: Mode Options. (line 172) -* --epoch: Mode Options. (line 102) -* --eval-command: File Options. (line 57) -* --exec: File Options. (line 35) -* --fullname: Mode Options. (line 91) -* --interpreter: Mode Options. (line 147) -* --nowindows: Mode Options. (line 72) -* --nx: Mode Options. (line 11) -* --pid: File Options. (line 47) -* --quiet: Mode Options. (line 19) -* --readnow: File Options. (line 71) -* --return-child-result: Mode Options. (line 53) -* --se: File Options. (line 39) -* --silent: Mode Options. (line 19) -* --statistics: Mode Options. (line 164) -* --symbols: File Options. (line 31) -* --tty: Mode Options. (line 135) -* --tui: Mode Options. (line 138) -* --version: Mode Options. (line 168) -* --windows: Mode Options. (line 78) -* --with-gdb-datadir: Data Files. (line 19) -* --with-relocated-sources: Source Path. (line 89) -* --with-sysroot: Files. (line 434) -* --write: Mode Options. (line 159) -* -add-inferior: GDB/MI Miscellaneous Commands. - (line 288) -* -b: Mode Options. (line 126) -* -break-after: GDB/MI Breakpoint Commands. - (line 11) -* -break-commands: GDB/MI Breakpoint Commands. - (line 55) -* -break-condition: GDB/MI Breakpoint Commands. - (line 88) -* -break-delete: GDB/MI Breakpoint Commands. - (line 125) -* -break-disable: GDB/MI Breakpoint Commands. - (line 159) -* -break-enable: GDB/MI Breakpoint Commands. - (line 195) -* -break-info: GDB/MI Breakpoint Commands. - (line 230) -* -break-insert: GDB/MI Breakpoint Commands. - (line 250) -* -break-list: GDB/MI Breakpoint Commands. - (line 355) -* -break-passcount: GDB/MI Breakpoint Commands. - (line 430) -* -break-watch: GDB/MI Breakpoint Commands. - (line 442) -* -c: File Options. (line 43) -* -d: File Options. (line 67) -* -data-disassemble: GDB/MI Data Manipulation. - (line 12) -* -data-evaluate-expression: GDB/MI Data Manipulation. - (line 141) -* -data-list-changed-registers: GDB/MI Data Manipulation. - (line 179) -* -data-list-register-names: GDB/MI Data Manipulation. - (line 215) -* -data-list-register-values: GDB/MI Data Manipulation. - (line 255) -* -data-read-memory: GDB/MI Data Manipulation. - (line 345) -* -data-read-memory-bytes: GDB/MI Data Manipulation. - (line 452) -* -data-write-memory-bytes: GDB/MI Data Manipulation. - (line 527) -* -e: File Options. (line 35) -* -enable-pretty-printing: GDB/MI Variable Objects. - (line 116) -* -enable-timings: GDB/MI Miscellaneous Commands. - (line 384) -* -environment-cd: GDB/MI Program Context. - (line 33) -* -environment-directory: GDB/MI Program Context. - (line 56) -* -environment-path: GDB/MI Program Context. - (line 100) -* -environment-pwd: GDB/MI Program Context. - (line 141) -* -ex: File Options. (line 57) -* -exec-arguments: GDB/MI Program Context. - (line 9) -* -exec-continue: GDB/MI Program Execution. - (line 13) -* -exec-finish: GDB/MI Program Execution. - (line 56) -* -exec-interrupt: GDB/MI Program Execution. - (line 99) -* -exec-jump: GDB/MI Program Execution. - (line 149) -* -exec-next: GDB/MI Program Execution. - (line 173) -* -exec-next-instruction: GDB/MI Program Execution. - (line 204) -* -exec-return: GDB/MI Program Execution. - (line 240) -* -exec-run: GDB/MI Program Execution. - (line 283) -* -exec-step: GDB/MI Program Execution. - (line 348) -* -exec-step-instruction: GDB/MI Program Execution. - (line 390) -* -exec-until: GDB/MI Program Execution. - (line 431) -* -f: Mode Options. (line 91) -* -file-exec-and-symbols: GDB/MI File Commands. - (line 12) -* -file-exec-file: GDB/MI File Commands. - (line 40) -* -file-list-exec-source-file: GDB/MI File Commands. - (line 67) -* -file-list-exec-source-files: GDB/MI File Commands. - (line 93) -* -file-symbol-file: GDB/MI File Commands. - (line 123) -* -gdb-exit: GDB/MI Miscellaneous Commands. - (line 9) -* -gdb-set: GDB/MI Miscellaneous Commands. - (line 31) -* -gdb-show: GDB/MI Miscellaneous Commands. - (line 54) -* -gdb-version: GDB/MI Miscellaneous Commands. - (line 77) -* -inferior-tty-set: GDB/MI Miscellaneous Commands. - (line 335) -* -inferior-tty-show: GDB/MI Miscellaneous Commands. - (line 358) -* -interpreter-exec: GDB/MI Miscellaneous Commands. - (line 310) -* -l: Mode Options. (line 130) -* -list-features: GDB/MI Miscellaneous Commands. - (line 111) -* -list-target-features: GDB/MI Miscellaneous Commands. - (line 154) -* -list-thread-groups: GDB/MI Miscellaneous Commands. - (line 180) -* -n: Mode Options. (line 11) -* -nw: Mode Options. (line 72) -* -p: File Options. (line 47) -* -q: Mode Options. (line 19) -* -r: File Options. (line 71) -* -s: File Options. (line 31) -* -stack-info-depth: GDB/MI Stack Manipulation. - (line 35) -* -stack-info-frame: GDB/MI Stack Manipulation. - (line 9) -* -stack-list-arguments: GDB/MI Stack Manipulation. - (line 73) -* -stack-list-frames: GDB/MI Stack Manipulation. - (line 162) -* -stack-list-locals: GDB/MI Stack Manipulation. - (line 265) -* -stack-list-variables: GDB/MI Stack Manipulation. - (line 305) -* -stack-select-frame: GDB/MI Stack Manipulation. - (line 328) -* -symbol-list-lines: GDB/MI Symbol Query. (line 9) -* -t: Mode Options. (line 135) -* -target-attach: GDB/MI Target Manipulation. - (line 9) -* -target-detach: GDB/MI Target Manipulation. - (line 36) -* -target-disconnect: GDB/MI Target Manipulation. - (line 61) -* -target-download: GDB/MI Target Manipulation. - (line 85) -* -target-file-delete: GDB/MI File Transfer Commands. - (line 57) -* -target-file-get: GDB/MI File Transfer Commands. - (line 33) -* -target-file-put: GDB/MI File Transfer Commands. - (line 9) -* -target-select: GDB/MI Target Manipulation. - (line 198) -* -thread-info: GDB/MI Thread Commands. - (line 9) -* -thread-list-ids: GDB/MI Thread Commands. - (line 90) -* -thread-select: GDB/MI Thread Commands. - (line 118) -* -trace-define-variable: GDB/MI Tracepoint Commands. - (line 83) -* -trace-find: GDB/MI Tracepoint Commands. - (line 12) -* -trace-list-variables: GDB/MI Tracepoint Commands. - (line 100) -* -trace-save: GDB/MI Tracepoint Commands. - (line 143) -* -trace-start: GDB/MI Tracepoint Commands. - (line 160) -* -trace-status: GDB/MI Tracepoint Commands. - (line 176) -* -trace-stop: GDB/MI Tracepoint Commands. - (line 244) -* -var-assign: GDB/MI Variable Objects. - (line 474) -* -var-create: GDB/MI Variable Objects. - (line 134) -* -var-delete: GDB/MI Variable Objects. - (line 220) -* -var-evaluate-expression: GDB/MI Variable Objects. - (line 453) -* -var-info-expression: GDB/MI Variable Objects. - (line 391) -* -var-info-num-children: GDB/MI Variable Objects. - (line 269) -* -var-info-path-expression: GDB/MI Variable Objects. - (line 415) -* -var-info-type: GDB/MI Variable Objects. - (line 378) -* -var-list-children: GDB/MI Variable Objects. - (line 285) -* -var-set-format: GDB/MI Variable Objects. - (line 233) -* -var-set-frozen: GDB/MI Variable Objects. - (line 612) -* -var-set-update-range: GDB/MI Variable Objects. - (line 638) -* -var-set-visualizer: GDB/MI Variable Objects. - (line 661) -* -var-show-attributes: GDB/MI Variable Objects. - (line 439) -* -var-show-format: GDB/MI Variable Objects. - (line 256) -* -var-update: GDB/MI Variable Objects. - (line 498) -* -w: Mode Options. (line 78) -* -x: File Options. (line 51) -* ., Modula-2 scope operator: M2 Scope. (line 6) -* .build-id directory: Separate Debug Files. - (line 6) -* .debug subdirectories: Separate Debug Files. - (line 6) -* .debug_gdb_scripts section: .debug_gdb_scripts section. - (line 6) -* .gdb_index section: Index Files. (line 6) -* .gdbinit: Startup. (line 60) -* .gnu_debuglink sections: Separate Debug Files. - (line 78) -* .note.gnu.build-id sections: Separate Debug Files. - (line 96) -* .o files, reading symbols from: Files. (line 132) -* /proc: SVR4 Process Information. - (line 6) -* <architecture>: Target Description Format. - (line 73) -* <compatible>: Target Description Format. - (line 96) -* <feature>: Target Description Format. - (line 120) -* <flags>: Target Description Format. - (line 186) -* <osabi>: Target Description Format. - (line 83) -* <reg>: Target Description Format. - (line 199) -* <struct>: Target Description Format. - (line 164) -* <union>: Target Description Format. - (line 154) -* <vector>: Target Description Format. - (line 147) -* ? packet: Packets. (line 58) -* @, referencing memory as an array: Arrays. (line 6) -* ^connected: GDB/MI Result Records. - (line 22) -* ^done: GDB/MI Result Records. - (line 9) -* ^error: GDB/MI Result Records. - (line 25) -* ^exit: GDB/MI Result Records. - (line 29) -* ^running: GDB/MI Result Records. - (line 14) -* __init__ on Breakpoint: Breakpoints In Python. - (line 9) -* __init__ on Command: Commands In Python. (line 12) -* __init__ on Function: Functions In Python. (line 11) -* __init__ on Parameter: Parameters In Python. - (line 20) -* __init__ on Value: Values From Inferior. - (line 76) -* _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C. - (line 11) -* A packet: Packets. (line 65) -* abbreviation: Command Syntax. (line 13) -* abort (C-g): Miscellaneous Commands. - (line 10) -* accept-line (Newline or Return): Commands For History. - (line 6) -* acknowledgment, for GDB remote: Packet Acknowledgment. - (line 6) -* actions: Tracepoint Actions. (line 6) -* active targets: Active Targets. (line 6) -* Ada: Ada. (line 6) -* Ada exception catching: Set Catchpoints. (line 19) -* Ada mode, general: Ada Mode Intro. (line 6) -* Ada task switching: Ada Tasks. (line 115) -* Ada tasking and core file debugging: Ada Tasks and Core Files. - (line 6) -* Ada, deviations from: Additions to Ada. (line 6) -* Ada, omissions from: Omissions from Ada. (line 6) -* Ada, problems: Ada Glitches. (line 6) -* Ada, tasking: Ada Tasks. (line 6) -* add new commands for external monitor: Connecting. (line 105) -* add-inferior: Inferiors and Programs. - (line 60) -* add-shared-symbol-files: Files. (line 172) -* add-symbol-file: Files. (line 113) -* add-symbol-file-from-memory: Files. (line 162) -* addr_class: Symbols In Python. (line 71) -* address <1>: Lazy Strings In Python. - (line 27) -* address: Values From Inferior. - (line 45) -* address of a symbol: Symbols. (line 44) -* address size for remote targets: Remote Configuration. - (line 12) -* ADP (Angel Debugger Protocol) logging: ARM. (line 89) -* advance LOCATION: Continuing and Stepping. - (line 181) -* aggregates (Ada): Omissions from Ada. (line 44) -* AIX threads: Debugging Output. (line 28) -* alignment of remote memory accesses: Packets. (line 228) -* all-stop mode: All-Stop Mode. (line 6) -* Alpha stack: MIPS. (line 6) -* ambiguous expressions: Ambiguous Expressions. - (line 6) -* AMD 29K register stack: A29K. (line 6) -* annotations: Annotations Overview. - (line 6) -* annotations for errors, warnings and interrupts: Errors. (line 6) -* annotations for invalidation messages: Invalidation. (line 6) -* annotations for prompts: Prompting. (line 6) -* annotations for running programs: Annotations for Running. - (line 6) -* annotations for source display: Source Annotations. (line 6) -* append: Dump/Restore Files. (line 35) -* append data to a file: Dump/Restore Files. (line 6) -* apply command to several threads: Threads. (line 122) -* apropos: Help. (line 62) -* architecture debugging info: Debugging Output. (line 18) -* argument count in user-defined commands: Define. (line 25) -* arguments (to your program): Arguments. (line 6) -* arguments, to gdbserver: Server. (line 34) -* arguments, to user-defined commands: Define. (line 6) -* ARM 32-bit mode: ARM. (line 25) -* ARM RDI: ARM. (line 6) -* array aggregates (Ada): Omissions from Ada. (line 44) -* array on Type: Types In Python. (line 82) -* arrays: Arrays. (line 6) -* arrays in expressions: Expressions. (line 14) -* artificial array: Arrays. (line 6) -* assembly instructions: Machine Code. (line 36) -* assf: Files. (line 172) -* assignment: Assignment. (line 6) -* async output in GDB/MI: GDB/MI Output Syntax. - (line 98) -* async records in GDB/MI: GDB/MI Async Records. - (line 6) -* asynchronous execution: Background Execution. - (line 6) -* asynchronous execution, and process record and replay: Process Record and Replay. - (line 52) -* AT&T disassembly flavor: Machine Code. (line 127) -* attach: Attach. (line 6) -* attach to a program by name: Server. (line 79) -* attach&: Background Execution. - (line 38) -* auto-loading, Python: Auto-loading. (line 6) -* auto-retry, for remote TCP target: Remote Configuration. - (line 108) -* automatic display: Auto Display. (line 6) -* automatic hardware breakpoints: Set Breaks. (line 284) -* automatic overlay debugging: Automatic Overlay Debugging. - (line 6) -* automatic thread selection: All-Stop Mode. (line 28) -* auxiliary vector: OS Information. (line 21) -* AVR: AVR. (line 6) -* awatch: Set Watchpoints. (line 68) -* b (break): Set Breaks. (line 6) -* B packet: Packets. (line 92) -* b packet: Packets. (line 77) -* background execution: Background Execution. - (line 6) -* backtrace: Backtrace. (line 11) -* backtrace beyond main function: Backtrace. (line 93) -* backtrace limit: Backtrace. (line 129) -* backward-char (C-b): Commands For Moving. (line 15) -* backward-delete-char (Rubout): Commands For Text. (line 11) -* backward-kill-line (C-x Rubout): Commands For Killing. - (line 9) -* backward-kill-word (M-<DEL>): Commands For Killing. - (line 24) -* backward-word (M-b): Commands For Moving. (line 22) -* base name differences: Files. (line 501) -* baud rate for remote targets: Remote Configuration. - (line 21) -* bc packet: Packets. (line 97) -* bcache statistics: Maintenance Commands. - (line 223) -* beginning-of-history (M-<): Commands For History. - (line 19) -* beginning-of-line (C-a): Commands For Moving. (line 6) -* bell-style: Readline Init File Syntax. - (line 35) -* bind-tty-special-chars: Readline Init File Syntax. - (line 42) -* bits in remote address: Remote Configuration. - (line 12) -* block on Frame: Frames In Python. (line 83) -* block_for_pc: Blocks In Python. (line 17) -* blocks in python: Blocks In Python. (line 6) -* bookmark: Checkpoint/Restart. (line 6) -* BP_ACCESS_WATCHPOINT: Breakpoints In Python. - (line 131) -* BP_BREAKPOINT: Breakpoints In Python. - (line 119) -* BP_HARDWARE_WATCHPOINT: Breakpoints In Python. - (line 125) -* BP_READ_WATCHPOINT: Breakpoints In Python. - (line 128) -* BP_WATCHPOINT: Breakpoints In Python. - (line 122) -* break: Set Breaks. (line 6) -* break ... task TASKNO (Ada): Ada Tasks. (line 135) -* break ... thread THREADNO: Thread-Specific Breakpoints. - (line 10) -* break in overloaded functions: Debugging C Plus Plus. - (line 9) -* break on a system call.: Set Catchpoints. (line 48) -* break on fork/exec: Set Catchpoints. (line 43) -* BREAK signal instead of Ctrl-C: Remote Configuration. - (line 29) -* break, and Objective-C: Method Names in Commands. - (line 9) -* break-range: PowerPC Embedded. (line 38) -* breakpoint: Events In Python. (line 102) -* breakpoint address adjusted: Breakpoint-related Warnings. - (line 6) -* breakpoint annotation: Annotations for Running. - (line 47) -* breakpoint commands: Break Commands. (line 6) -* breakpoint commands for GDB/MI: GDB/MI Breakpoint Commands. - (line 6) -* breakpoint conditions: Conditions. (line 6) -* breakpoint numbers: Breakpoints. (line 41) -* breakpoint on events: Breakpoints. (line 33) -* breakpoint on memory address: Breakpoints. (line 20) -* breakpoint on variable modification: Breakpoints. (line 20) -* breakpoint ranges: Breakpoints. (line 48) -* breakpoint subroutine, remote: Stub Contents. (line 31) -* breakpointing Ada elaboration code: Stopping Before Main Program. - (line 6) -* breakpoints <1>: Basic Python. (line 32) -* breakpoints: Breakpoints. (line 6) -* breakpoints and tasks, in Ada: Ada Tasks. (line 135) -* breakpoints and threads: Thread-Specific Breakpoints. - (line 10) -* breakpoints at functions matching a regexp: Set Breaks. (line 92) -* breakpoints in overlays: Overlay Commands. (line 93) -* breakpoints in python: Breakpoints In Python. - (line 6) -* breakpoints, multiple locations: Set Breaks. (line 190) -* breakpoints-invalid annotation: Invalidation. (line 13) -* bs packet: Packets. (line 103) -* bt (backtrace): Backtrace. (line 11) -* bug criteria: Bug Criteria. (line 6) -* bug reports: Bug Reporting. (line 6) -* bugs in GDB: GDB Bugs. (line 6) -* build ID sections: Separate Debug Files. - (line 96) -* build ID, and separate debugging files: Separate Debug Files. - (line 6) -* building GDB, requirements for: Requirements. (line 6) -* built-in simulator target: Target Commands. (line 73) -* c (continue): Continuing and Stepping. - (line 15) -* c (SingleKey TUI key): TUI Single Key Mode. (line 10) -* C and C++: C. (line 6) -* C and C++ checks: C Checks. (line 6) -* C and C++ constants: C Constants. (line 6) -* C and C++ defaults: C Defaults. (line 6) -* C and C++ operators: C Operators. (line 6) -* C packet: Packets. (line 116) -* c packet: Packets. (line 110) -* C++: C. (line 10) -* C++ compilers: C Plus Plus Expressions. - (line 8) -* C++ exception handling: Debugging C Plus Plus. - (line 20) -* C++ overload debugging info: Debugging Output. (line 125) -* C++ scope resolution: Variables. (line 54) -* C++ symbol decoding style: Print Settings. (line 296) -* C++ symbol display: Debugging C Plus Plus. - (line 29) -* C-L: TUI Keys. (line 65) -* C-x 1: TUI Keys. (line 19) -* C-x 2: TUI Keys. (line 26) -* C-x a: TUI Keys. (line 11) -* C-x A: TUI Keys. (line 12) -* C-x C-a: TUI Keys. (line 10) -* C-x o: TUI Keys. (line 34) -* C-x s: TUI Keys. (line 41) -* caching data of remote targets: Caching Remote Data. (line 6) -* call: Calling. (line 10) -* call dummy stack unwinding: Calling. (line 35) -* call dummy stack unwinding on unhandled exception.: Calling. - (line 46) -* call overloaded functions: C Plus Plus Expressions. - (line 27) -* call stack: Stack. (line 9) -* call stack traces: Backtrace. (line 6) -* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) -* calling functions: Calling. (line 6) -* calling make: Shell Commands. (line 19) -* capitalize-word (M-c): Commands For Text. (line 49) -* case sensitivity in symbol names: Symbols. (line 27) -* case-insensitive symbol names: Symbols. (line 27) -* cast on Value: Values From Inferior. - (line 109) -* casts, in expressions: Expressions. (line 28) -* casts, to view memory: Expressions. (line 43) -* catch: Set Catchpoints. (line 10) -* catch Ada exceptions: Set Catchpoints. (line 19) -* catch exceptions, list active handlers: Frame Info. (line 60) -* catchpoints: Breakpoints. (line 33) -* catchpoints, setting: Set Catchpoints. (line 6) -* cd: Working Directory. (line 16) -* cdir: Source Path. (line 108) -* Cell Broadband Engine: SPU. (line 6) -* change working directory: Working Directory. (line 16) -* character sets: Character Sets. (line 6) -* character-search (C-]): Miscellaneous Commands. - (line 41) -* character-search-backward (M-C-]): Miscellaneous Commands. - (line 46) -* charset: Character Sets. (line 6) -* checkpoint: Checkpoint/Restart. (line 6) -* checkpoints and process id: Checkpoint/Restart. (line 80) -* checks, range: Type Checking. (line 65) -* checks, type: Checks. (line 31) -* checksum, for GDB remote: Overview. (line 20) -* children on pretty printer: Pretty Printing API. (line 12) -* choosing target byte order: Byte Order. (line 6) -* circular trace buffer: Starting and Stopping Trace Experiments. - (line 74) -* clear: Delete Breaks. (line 21) -* clear, and Objective-C: Method Names in Commands. - (line 9) -* clear-screen (C-l): Commands For Moving. (line 26) -* clearing breakpoints, watchpoints, catchpoints: Delete Breaks. - (line 6) -* clone-inferior: Inferiors and Programs. - (line 67) -* close, file-i/o system call: close. (line 6) -* closest symbol and offset for an address: Symbols. (line 54) -* code: Types In Python. (line 24) -* code address and its source line: Machine Code. (line 25) -* collect (tracepoints): Tracepoint Actions. (line 49) -* collected data discarded: Starting and Stopping Trace Experiments. - (line 6) -* colon, doubled as scope operator: M2 Scope. (line 6) -* colon-colon, context for variables/functions: Variables. (line 44) -* colon-colon, in Modula-2: M2 Scope. (line 6) -* command editing: Readline Bare Essentials. - (line 6) -* command files: Command Files. (line 6) -* command history: Command History. (line 6) -* command hooks: Hooks. (line 6) -* command interpreters: Interpreters. (line 6) -* command line editing: Editing. (line 6) -* command scripts, debugging: Messages/Warnings. (line 67) -* command tracing: Messages/Warnings. (line 62) -* COMMAND_BREAKPOINTS: Commands In Python. (line 145) -* COMMAND_DATA: Commands In Python. (line 115) -* COMMAND_FILES: Commands In Python. (line 126) -* COMMAND_MAINTENANCE: Commands In Python. (line 163) -* COMMAND_NONE: Commands In Python. (line 105) -* COMMAND_OBSCURE: Commands In Python. (line 157) -* COMMAND_RUNNING: Commands In Python. (line 109) -* COMMAND_STACK: Commands In Python. (line 120) -* COMMAND_STATUS: Commands In Python. (line 139) -* COMMAND_SUPPORT: Commands In Python. (line 132) -* COMMAND_TRACEPOINTS: Commands In Python. (line 151) -* commands <1>: Breakpoints In Python. - (line 157) -* commands: Break Commands. (line 11) -* commands annotation: Prompting. (line 27) -* commands for C++: Debugging C Plus Plus. - (line 6) -* commands in python: Commands In Python. (line 6) -* commands to access python: Python Commands. (line 6) -* comment: Command Syntax. (line 38) -* comment-begin: Readline Init File Syntax. - (line 47) -* COMMON blocks, Fortran: Special Fortran Commands. - (line 9) -* common targets: Target Commands. (line 46) -* compare-sections: Memory. (line 129) -* compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. - (line 6) -* compilation directory: Source Path. (line 108) -* compiling, on Sparclet: Sparclet. (line 16) -* complete: Help. (line 76) -* complete (<TAB>): Commands For Completion. - (line 6) -* complete on Command: Commands In Python. (line 73) -* COMPLETE_COMMAND: Commands In Python. (line 184) -* COMPLETE_FILENAME: Commands In Python. (line 177) -* COMPLETE_LOCATION: Commands In Python. (line 180) -* COMPLETE_NONE: Commands In Python. (line 174) -* COMPLETE_SYMBOL: Commands In Python. (line 188) -* completion: Completion. (line 6) -* completion of Python commands: Commands In Python. (line 72) -* completion of quoted strings: Completion. (line 57) -* completion of structure field names: Completion. (line 96) -* completion of union field names: Completion. (line 96) -* completion-query-items: Readline Init File Syntax. - (line 57) -* compressed debug sections: Requirements. (line 41) -* condition <1>: Breakpoints In Python. - (line 152) -* condition: Conditions. (line 45) -* conditional breakpoints: Conditions. (line 6) -* conditional tracepoints: Tracepoint Conditions. - (line 6) -* configuring GDB: Running Configure. (line 6) -* confirmation: Messages/Warnings. (line 50) -* connect on EventRegistry: Events In Python. (line 20) -* connection timeout, for remote TCP target: Remote Configuration. - (line 123) -* console i/o as part of file-i/o: Console I/O. (line 6) -* console interpreter: Interpreters. (line 21) -* console output in GDB/MI: GDB/MI Output Syntax. - (line 106) -* const on Type: Types In Python. (line 91) -* constants, in file-i/o protocol: Constants. (line 6) -* continue: Continuing and Stepping. - (line 15) -* continue&: Background Execution. - (line 53) -* continuing: Continuing and Stepping. - (line 6) -* continuing threads: Thread Stops. (line 6) -* control C, and remote debugging: Bootstrapping. (line 25) -* controlling terminal: Input/Output. (line 23) -* convenience functions: Convenience Vars. (line 106) -* convenience functions in python: Functions In Python. (line 6) -* convenience variables: Convenience Vars. (line 6) -* convenience variables for tracepoints: Tracepoint Variables. - (line 6) -* convenience variables, and trace state variables: Trace State Variables. - (line 17) -* convenience variables, initializing: Convenience Vars. (line 41) -* convert-meta: Readline Init File Syntax. - (line 67) -* copy-backward-word (): Commands For Killing. - (line 49) -* copy-forward-word (): Commands For Killing. - (line 54) -* copy-region-as-kill (): Commands For Killing. - (line 45) -* core dump file: Files. (line 6) -* core dump file target: Target Commands. (line 54) -* core-file: Files. (line 97) -* crash of debugger: Bug Criteria. (line 9) -* CRC algorithm definition: Separate Debug Files. - (line 140) -* CRC of memory block, remote request: General Query Packets. - (line 63) -* CRIS: CRIS. (line 6) -* CRIS mode: CRIS. (line 26) -* CRIS version: CRIS. (line 10) -* Ctrl-BREAK, MS-Windows: Cygwin Native. (line 9) -* ctrl-c message, in file-i/o protocol: The Ctrl-C Message. (line 6) -* Ctrl-o (operate-and-get-next): Command Syntax. (line 42) -* current Ada task ID: Ada Tasks. (line 105) -* current directory: Source Path. (line 108) -* current stack frame: Frames. (line 45) -* current thread: Threads. (line 45) -* current thread, remote request: General Query Packets. - (line 52) -* current_objfile: Objfiles In Python. (line 16) -* current_progspace: Progspaces In Python. - (line 15) -* cwd: Source Path. (line 108) -* Cygwin DLL, debugging: Cygwin Native. (line 42) -* Cygwin-specific commands: Cygwin Native. (line 6) -* D: D. (line 6) -* d (delete): Delete Breaks. (line 41) -* d (SingleKey TUI key): TUI Single Key Mode. (line 13) -* d packet: Packets. (line 122) -* D packet: Packets. (line 129) -* Darwin: Darwin. (line 6) -* data breakpoints: Breakpoints. (line 20) -* data manipulation, in GDB/MI: GDB/MI Data Manipulation. - (line 6) -* dcache line-size: Caching Remote Data. (line 48) -* dcache size: Caching Remote Data. (line 45) -* dead names, GNU Hurd: Hurd Native. (line 85) -* debug expression parser: Debugging Output. (line 131) -* debug formats and C++: C Plus Plus Expressions. - (line 8) -* debug link sections: Separate Debug Files. - (line 78) -* debug remote protocol: Debugging Output. (line 140) -* debug_chaos: M32R/D. (line 50) -* debugger crash: Bug Criteria. (line 9) -* debugging C++ programs: C Plus Plus Expressions. - (line 8) -* debugging information directory, global: Separate Debug Files. - (line 6) -* debugging information in separate files: Separate Debug Files. - (line 6) -* debugging libthread_db: Threads. (line 212) -* debugging multiple processes: Forks. (line 52) -* debugging optimized code: Optimized Code. (line 6) -* debugging stub, example: Remote Stub. (line 6) -* debugging target: Targets. (line 6) -* debugging the Cygwin DLL: Cygwin Native. (line 42) -* decimal floating point format: Decimal Floating Point. - (line 6) -* decode_line: Basic Python. (line 158) -* default collection action: Tracepoint Actions. (line 114) -* default data directory: Data Files. (line 19) -* default source path substitution: Source Path. (line 89) -* default system root: Files. (line 434) -* default_visualizer: Pretty Printing API. (line 86) -* define: Define. (line 37) -* define trace state variable, remote request: Tracepoint Packets. - (line 127) -* defining macros interactively: Macros. (line 52) -* definition, showing a macro's: Macros. (line 47) -* delete: Delete Breaks. (line 41) -* delete breakpoints: Delete Breaks. (line 41) -* delete checkpoint CHECKPOINT-ID: Checkpoint/Restart. (line 56) -* delete display: Auto Display. (line 45) -* delete mem: Memory Region Attributes. - (line 34) -* delete on Breakpoint: Breakpoints In Python. - (line 70) -* delete tracepoint: Create and Delete Tracepoints. - (line 101) -* delete tvariable: Trace State Variables. - (line 42) -* delete-char (C-d): Commands For Text. (line 6) -* delete-char-or-list (): Commands For Completion. - (line 30) -* delete-horizontal-space (): Commands For Killing. - (line 37) -* deleting breakpoints, watchpoints, catchpoints: Delete Breaks. - (line 6) -* deliver a signal to a program: Signaling. (line 6) -* demangling C++ names: Print Settings. (line 277) -* deprecated commands: Maintenance Commands. - (line 90) -* dereference on Value: Values From Inferior. - (line 115) -* derived type of an object, printing: Print Settings. (line 329) -* descriptor tables display: DJGPP Native. (line 24) -* detach: Attach. (line 36) -* detach (remote): Connecting. (line 91) -* detach from task, GNU Hurd: Hurd Native. (line 60) -* detach from thread, GNU Hurd: Hurd Native. (line 110) -* detach inferiors INFNO...: Inferiors and Programs. - (line 97) -* digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) -* dir: Source Path. (line 39) -* direct memory access (DMA) on MS-DOS: DJGPP Native. (line 75) -* directories for source files: Source Path. (line 6) -* directory: Source Path. (line 39) -* directory, compilation: Source Path. (line 108) -* directory, current: Source Path. (line 108) -* dis (disable): Disabling. (line 38) -* disable: Disabling. (line 38) -* disable display: Auto Display. (line 56) -* disable mem: Memory Region Attributes. - (line 38) -* disable pretty-printer: Pretty-Printer Commands. - (line 20) -* disable tracepoint: Enable and Disable Tracepoints. - (line 9) -* disable-completion: Readline Init File Syntax. - (line 73) -* disassemble: Machine Code. (line 36) -* disconnect: Connecting. (line 98) -* disconnect on EventRegistry: Events In Python. (line 25) -* disconnected tracing: Starting and Stopping Trace Experiments. - (line 38) -* displaced stepping debugging info: Debugging Output. (line 53) -* displaced stepping support: Maintenance Commands. - (line 56) -* displaced stepping, and process record and replay: Process Record and Replay. - (line 47) -* display: Auto Display. (line 23) -* display command history: Command History. (line 78) -* display derived types: Print Settings. (line 329) -* display disabled out of scope: Auto Display. (line 86) -* display GDB copyright: Help. (line 136) -* display of expressions: Auto Display. (line 6) -* display remote monitor communications: Target Commands. (line 108) -* display remote packets: Debugging Output. (line 140) -* display_hint on pretty printer: Pretty Printing API. (line 25) -* DJGPP debugging: DJGPP Native. (line 6) -* dll-symbols: Cygwin Native. (line 38) -* DLLs with no debugging symbols: Non-debug DLL Symbols. - (line 6) -* do (down): Selection. (line 40) -* do not print frame argument values: Print Settings. (line 135) -* do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. - (line 14) -* document: Define. (line 49) -* documentation: Formatting Documentation. - (line 22) -* don't repeat command: Define. (line 61) -* don't repeat Python command: Commands In Python. (line 43) -* dont-repeat: Define. (line 61) -* dont_repeat on Command: Commands In Python. (line 44) -* DOS file-name semantics of file names.: Files. (line 457) -* DOS serial data link, remote debugging: DJGPP Native. (line 121) -* DOS serial port status: DJGPP Native. (line 142) -* down: Selection. (line 40) -* Down: TUI Keys. (line 56) -* down-silently: Selection. (line 64) -* downcase-word (M-l): Commands For Text. (line 45) -* download server address (M32R): M32R/D. (line 27) -* download to Sparclet: Sparclet Download. (line 6) -* download to VxWorks: VxWorks Download. (line 6) -* DPMI: DJGPP Native. (line 6) -* dump: Dump/Restore Files. (line 13) -* dump all data collected at tracepoint: tdump. (line 6) -* dump core from inferior: Core File Generation. - (line 6) -* dump data to a file: Dump/Restore Files. (line 6) -* dump-functions (): Miscellaneous Commands. - (line 61) -* dump-macros (): Miscellaneous Commands. - (line 73) -* dump-variables (): Miscellaneous Commands. - (line 67) -* dump/restore files: Dump/Restore Files. (line 6) -* DVC register: PowerPC Embedded. (line 6) -* DWARF 2 compilation units cache: Maintenance Commands. - (line 281) -* DWARF-2 CFI and CRIS: CRIS. (line 18) -* DWARF2 DIEs: Debugging Output. (line 46) -* dynamic linking: Files. (line 113) -* dynamic varobj: GDB/MI Variable Objects. - (line 164) -* dynamic_cast on Value: Values From Inferior. - (line 131) -* dynamic_type: Values From Inferior. - (line 59) -* e (edit): Edit. (line 6) -* echo: Output. (line 12) -* edit: Edit. (line 6) -* editing: Editing. (line 15) -* editing command lines: Readline Bare Essentials. - (line 6) -* editing source files: Edit. (line 6) -* editing-mode: Readline Init File Syntax. - (line 78) -* eight-bit characters in strings: Print Settings. (line 222) -* elaboration phase: Starting. (line 90) -* else: Command Files. (line 75) -* Emacs: Emacs. (line 6) -* empty response, for unsupported packets: Overview. (line 96) -* enable: Disabling. (line 45) -* enable display: Auto Display. (line 65) -* enable mem: Memory Region Attributes. - (line 42) -* enable pretty-printer: Pretty-Printer Commands. - (line 25) -* enable tracepoint: Enable and Disable Tracepoints. - (line 15) -* enable-keypad: Readline Init File Syntax. - (line 84) -* enable/disable a breakpoint: Disabling. (line 6) -* enabled: Breakpoints In Python. - (line 75) -* encoding: Lazy Strings In Python. - (line 37) -* end: Blocks In Python. (line 40) -* end (breakpoint commands): Break Commands. (line 11) -* end (if/else/while commands): Command Files. (line 104) -* end (user-defined commands): Define. (line 49) -* end-kbd-macro (C-x )): Keyboard Macros. (line 9) -* end-of-history (M->): Commands For History. - (line 22) -* end-of-line (C-e): Commands For Moving. (line 9) -* entering numbers: Numbers. (line 6) -* environment (of your program): Environment. (line 6) -* errno values, in file-i/o protocol: Errno Values. (line 6) -* error annotation: Errors. (line 10) -* error on valid input: Bug Criteria. (line 12) -* error-begin annotation: Errors. (line 22) -* eval: Output. (line 117) -* event debugging info: Debugging Output. (line 61) -* event designators: Event Designators. (line 6) -* event handling: Set Catchpoints. (line 6) -* examine process image: SVR4 Process Information. - (line 6) -* examining data: Data. (line 6) -* examining memory: Memory. (line 9) -* exception handlers: Set Catchpoints. (line 6) -* exception handlers, how to list: Frame Info. (line 60) -* exceptionHandler: Bootstrapping. (line 38) -* exceptions, python: Exception Handling. (line 6) -* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. - (line 36) -* exec-file: Files. (line 39) -* executable file: Files. (line 16) -* executable file target: Target Commands. (line 50) -* executable file, for remote target: Remote Configuration. - (line 79) -* execute: Basic Python. (line 15) -* execute commands from a file: Command Files. (line 17) -* execute forward or backward in time: Reverse Execution. (line 87) -* execute remote command, remote request: General Query Packets. - (line 268) -* execution, foreground, background and asynchronous: Background Execution. - (line 6) -* exit_code: Events In Python. (line 72) -* exited annotation: Annotations for Running. - (line 18) -* exiting GDB: Quitting GDB. (line 6) -* expand macro once: Macros. (line 38) -* expand-tilde: Readline Init File Syntax. - (line 89) -* expanding preprocessor macros: Macros. (line 29) -* expression: Breakpoints In Python. - (line 146) -* expression debugging info: Debugging Output. (line 68) -* expression parser, debugging info: Debugging Output. (line 131) -* expressions: Expressions. (line 6) -* expressions in Ada: Ada. (line 11) -* expressions in C or C++: C. (line 6) -* expressions in C++: C Plus Plus Expressions. - (line 6) -* expressions in Modula-2: Modula-2. (line 12) -* extend GDB for remote targets: Connecting. (line 105) -* extending GDB: Extending GDB. (line 6) -* extra signal information: Signals. (line 102) -* f (frame): Selection. (line 11) -* f (SingleKey TUI key): TUI Single Key Mode. (line 16) -* F packet: Packets. (line 146) -* F reply packet: The F Reply Packet. (line 6) -* F request packet: The F Request Packet. - (line 6) -* fast tracepoints: Set Tracepoints. (line 24) -* fast tracepoints, setting: Create and Delete Tracepoints. - (line 40) -* fatal signal: Bug Criteria. (line 9) -* fatal signals: Signals. (line 15) -* features of the remote protocol: General Query Packets. - (line 328) -* fg (resume foreground execution): Continuing and Stepping. - (line 15) -* fields on Type: Types In Python. (line 41) -* file: Files. (line 16) -* file name canonicalization: Files. (line 501) -* file transfer: File Transfer. (line 6) -* file transfer, remote protocol: Host I/O Packets. (line 6) -* file-i/o examples: File-I/O Examples. (line 6) -* file-i/o overview: File-I/O Overview. (line 6) -* File-I/O remote protocol extension: File-I/O Remote Protocol Extension. - (line 6) -* file-i/o reply packet: The F Reply Packet. (line 6) -* file-i/o request packet: The F Request Packet. - (line 6) -* filename <1>: Symbol Tables In Python. - (line 41) -* filename <2>: Progspaces In Python. - (line 25) -* filename: Objfiles In Python. (line 29) -* fin (finish): Continuing and Stepping. - (line 110) -* find: Searching Memory. (line 9) -* find downloadable SREC files (M32R): M32R/D. (line 15) -* find trace snapshot: tfind. (line 6) -* find_sal on Frame: Frames In Python. (line 96) -* finish: Continuing and Stepping. - (line 110) -* finish&: Background Execution. - (line 56) -* flinching: Messages/Warnings. (line 50) -* float promotion: ABI. (line 29) -* floating point: Floating Point Hardware. - (line 6) -* floating point registers: Registers. (line 15) -* floating point, MIPS remote: MIPS Embedded. (line 60) -* flush: Basic Python. (line 122) -* flush_i_cache: Bootstrapping. (line 60) -* flushregs: Maintenance Commands. - (line 208) -* focus: TUI Commands. (line 40) -* focus of debugging: Threads. (line 45) -* foo: Symbol Errors. (line 50) -* foreground execution: Background Execution. - (line 6) -* fork, debugging programs which call: Forks. (line 6) -* format options: Print Settings. (line 6) -* formatted output: Output Formats. (line 6) -* Fortran: Summary. (line 40) -* Fortran Defaults: Fortran Defaults. (line 6) -* Fortran operators and expressions: Fortran Operators. (line 6) -* Fortran-specific support in GDB: Fortran. (line 6) -* forward-backward-delete-char (): Commands For Text. (line 15) -* forward-char (C-f): Commands For Moving. (line 12) -* forward-search: Search. (line 9) -* forward-search-history (C-s): Commands For History. - (line 30) -* forward-word (M-f): Commands For Moving. (line 18) -* FR-V shared-library debugging: Debugging Output. (line 158) -* frame debugging info: Debugging Output. (line 76) -* frame number: Frames. (line 28) -* frame pointer: Frames. (line 21) -* frame pointer register: Registers. (line 26) -* frame, command: Frames. (line 45) -* frame, definition: Frames. (line 6) -* frame, selecting: Selection. (line 11) -* frame_stop_reason_string: Frames In Python. (line 30) -* frameless execution: Frames. (line 34) -* frames in python: Frames In Python. (line 6) -* frames-invalid annotation: Invalidation. (line 9) -* free memory information (MS-DOS): DJGPP Native. (line 19) -* fstat, file-i/o system call: stat/fstat. (line 6) -* ftrace: Create and Delete Tracepoints. - (line 40) -* Fujitsu: Remote Stub. (line 69) -* full symbol tables, listing GDB's internal: Symbols. (line 291) -* fullname on Symtab: Symbol Tables In Python. - (line 58) -* Function: Functions In Python. (line 6) -* function: Blocks In Python. (line 43) -* function call arguments, optimized out: Backtrace. (line 71) -* function entry/exit, wrong values of variables: Variables. (line 58) -* function on Frame: Frames In Python. (line 86) -* functions without line info, and stepping: Continuing and Stepping. - (line 93) -* G packet: Packets. (line 180) -* g packet: Packets. (line 151) -* g++, GNU C++ compiler: C. (line 10) -* garbled pointers: DJGPP Native. (line 42) -* GCC and C++: C Plus Plus Expressions. - (line 8) -* gcore: Core File Generation. - (line 18) -* GDB bugs, reporting: Bug Reporting. (line 6) -* GDB internal error: Maintenance Commands. - (line 124) -* gdb module: Basic Python. (line 6) -* GDB reference card: Formatting Documentation. - (line 6) -* GDB startup: Startup. (line 6) -* GDB version number: Help. (line 126) -* gdb.Block: Blocks In Python. (line 6) -* gdb.block_for_pc: Blocks In Python. (line 16) -* gdb.BP_ACCESS_WATCHPOINT: Breakpoints In Python. - (line 131) -* gdb.BP_BREAKPOINT: Breakpoints In Python. - (line 119) -* gdb.BP_HARDWARE_WATCHPOINT: Breakpoints In Python. - (line 125) -* gdb.BP_READ_WATCHPOINT: Breakpoints In Python. - (line 128) -* gdb.BP_WATCHPOINT: Breakpoints In Python. - (line 122) -* gdb.Breakpoint: Breakpoints In Python. - (line 6) -* gdb.breakpoints: Basic Python. (line 31) -* gdb.COMMAND_BREAKPOINTS: Commands In Python. (line 145) -* gdb.COMMAND_DATA: Commands In Python. (line 115) -* gdb.COMMAND_FILES: Commands In Python. (line 126) -* gdb.COMMAND_MAINTENANCE: Commands In Python. (line 163) -* gdb.COMMAND_NONE: Commands In Python. (line 105) -* gdb.COMMAND_OBSCURE: Commands In Python. (line 157) -* gdb.COMMAND_RUNNING: Commands In Python. (line 109) -* gdb.COMMAND_STACK: Commands In Python. (line 120) -* gdb.COMMAND_STATUS: Commands In Python. (line 139) -* gdb.COMMAND_SUPPORT: Commands In Python. (line 132) -* gdb.COMMAND_TRACEPOINTS: Commands In Python. (line 151) -* gdb.COMPLETE_COMMAND: Commands In Python. (line 184) -* gdb.COMPLETE_FILENAME: Commands In Python. (line 177) -* gdb.COMPLETE_LOCATION: Commands In Python. (line 180) -* gdb.COMPLETE_NONE: Commands In Python. (line 174) -* gdb.COMPLETE_SYMBOL: Commands In Python. (line 188) -* gdb.current_objfile: Objfiles In Python. (line 15) -* gdb.current_progspace: Progspaces In Python. - (line 14) -* gdb.decode_line: Basic Python. (line 157) -* gdb.default_visualizer: Pretty Printing API. (line 85) -* gdb.error: Exception Handling. (line 22) -* gdb.execute: Basic Python. (line 14) -* gdb.flush: Basic Python. (line 121) -* gdb.Function: Functions In Python. (line 6) -* gdb.GdbError: Exception Handling. (line 42) -* gdb.history: Basic Python. (line 46) -* gdb.Inferior: Inferiors In Python. (line 6) -* gdb.InferiorThread: Threads In Python. (line 6) -* gdb.ini: Startup. (line 60) -* gdb.LazyString: Lazy Strings In Python. - (line 6) -* gdb.lookup_global_symbol: Symbols In Python. (line 33) -* gdb.lookup_symbol: Symbols In Python. (line 13) -* gdb.lookup_type: Types In Python. (line 11) -* gdb.MemoryError: Exception Handling. (line 30) -* gdb.newest_frame: Frames In Python. (line 26) -* gdb.Objfile: Objfiles In Python. (line 6) -* gdb.objfiles: Objfiles In Python. (line 21) -* gdb.PARAM_AUTO_BOOLEAN: Parameters In Python. - (line 93) -* gdb.PARAM_BOOLEAN: Parameters In Python. - (line 89) -* gdb.PARAM_ENUM: Parameters In Python. - (line 127) -* gdb.PARAM_FILENAME: Parameters In Python. - (line 119) -* gdb.PARAM_INTEGER: Parameters In Python. - (line 102) -* gdb.PARAM_OPTIONAL_FILENAME: Parameters In Python. - (line 116) -* gdb.PARAM_STRING: Parameters In Python. - (line 106) -* gdb.PARAM_STRING_NOESCAPE: Parameters In Python. - (line 112) -* gdb.PARAM_UINTEGER: Parameters In Python. - (line 98) -* gdb.PARAM_ZINTEGER: Parameters In Python. - (line 123) -* gdb.parameter: Basic Python. (line 35) -* gdb.Parameter: Parameters In Python. - (line 6) -* gdb.parse_and_eval: Basic Python. (line 58) -* gdb.post_event: Basic Python. (line 69) -* gdb.printing: gdb.printing. (line 6) -* gdb.Progspace: Progspaces In Python. - (line 6) -* gdb.progspaces: Progspaces In Python. - (line 18) -* gdb.PYTHONDIR: Basic Python. (line 11) -* gdb.read_memory: Inferiors In Python. (line 44) -* gdb.search_memory: Inferiors In Python. (line 57) -* gdb.selected_frame: Frames In Python. (line 22) -* gdb.selected_thread: Threads In Python. (line 13) -* gdb.solib_name: Basic Python. (line 153) -* gdb.STDERR: Basic Python. (line 111) -* gdb.STDLOG: Basic Python. (line 135) -* gdb.STDOUT: Basic Python. (line 129) -* gdb.string_to_argv: Commands In Python. (line 62) -* gdb.Symbol: Symbols In Python. (line 6) -* gdb.SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 117) -* gdb.SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 110) -* gdb.SYMBOL_LOC_ARG: Symbols In Python. (line 139) -* gdb.SYMBOL_LOC_BLOCK: Symbols In Python. (line 160) -* gdb.SYMBOL_LOC_COMPUTED: Symbols In Python. (line 174) -* gdb.SYMBOL_LOC_CONST: Symbols In Python. (line 130) -* gdb.SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 163) -* gdb.SYMBOL_LOC_LOCAL: Symbols In Python. (line 153) -* gdb.SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 171) -* gdb.SYMBOL_LOC_REF_ARG: Symbols In Python. (line 143) -* gdb.SYMBOL_LOC_REGISTER: Symbols In Python. (line 136) -* gdb.SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 148) -* gdb.SYMBOL_LOC_STATIC: Symbols In Python. (line 133) -* gdb.SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 156) -* gdb.SYMBOL_LOC_UNDEF: Symbols In Python. (line 128) -* gdb.SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 166) -* gdb.SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 107) -* gdb.SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 120) -* gdb.SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 100) -* gdb.SYMBOL_VAR_DOMAIN: Symbols In Python. (line 103) -* gdb.SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 113) -* gdb.Symtab: Symbol Tables In Python. - (line 6) -* gdb.Symtab_and_line: Symbol Tables In Python. - (line 6) -* gdb.target_charset: Basic Python. (line 142) -* gdb.target_wide_charset: Basic Python. (line 147) -* gdb.Type: Types In Python. (line 6) -* gdb.TYPE_CODE_ARRAY: Types In Python. (line 155) -* gdb.TYPE_CODE_BITSTRING: Types In Python. (line 193) -* gdb.TYPE_CODE_BOOL: Types In Python. (line 214) -* gdb.TYPE_CODE_CHAR: Types In Python. (line 211) -* gdb.TYPE_CODE_COMPLEX: Types In Python. (line 217) -* gdb.TYPE_CODE_DECFLOAT: Types In Python. (line 226) -* gdb.TYPE_CODE_ENUM: Types In Python. (line 164) -* gdb.TYPE_CODE_ERROR: Types In Python. (line 196) -* gdb.TYPE_CODE_FLAGS: Types In Python. (line 167) -* gdb.TYPE_CODE_FLT: Types In Python. (line 176) -* gdb.TYPE_CODE_FUNC: Types In Python. (line 170) -* gdb.TYPE_CODE_INT: Types In Python. (line 173) -* gdb.TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 229) -* gdb.TYPE_CODE_MEMBERPTR: Types In Python. (line 205) -* gdb.TYPE_CODE_METHOD: Types In Python. (line 199) -* gdb.TYPE_CODE_METHODPTR: Types In Python. (line 202) -* gdb.TYPE_CODE_NAMESPACE: Types In Python. (line 223) -* gdb.TYPE_CODE_PTR: Types In Python. (line 152) -* gdb.TYPE_CODE_RANGE: Types In Python. (line 185) -* gdb.TYPE_CODE_REF: Types In Python. (line 208) -* gdb.TYPE_CODE_SET: Types In Python. (line 182) -* gdb.TYPE_CODE_STRING: Types In Python. (line 188) -* gdb.TYPE_CODE_STRUCT: Types In Python. (line 158) -* gdb.TYPE_CODE_TYPEDEF: Types In Python. (line 220) -* gdb.TYPE_CODE_UNION: Types In Python. (line 161) -* gdb.TYPE_CODE_VOID: Types In Python. (line 179) -* gdb.types: gdb.types. (line 6) -* gdb.Value: Values From Inferior. - (line 6) -* gdb.WP_ACCESS: Breakpoints In Python. - (line 58) -* gdb.WP_READ: Breakpoints In Python. - (line 52) -* gdb.WP_WRITE: Breakpoints In Python. - (line 55) -* gdb.write: Basic Python. (line 103) -* gdb.write_memory: Inferiors In Python. (line 50) -* GDB/MI development: GDB/MI Development and Front Ends. - (line 6) -* GDB/MI General Design: GDB/MI General Design. - (line 6) -* GDB/MI, async records: GDB/MI Async Records. - (line 6) -* GDB/MI, breakpoint commands: GDB/MI Breakpoint Commands. - (line 6) -* GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI. - (line 6) -* GDB/MI, data manipulation: GDB/MI Data Manipulation. - (line 6) -* GDB/MI, input syntax: GDB/MI Input Syntax. (line 6) -* GDB/MI, its purpose: GDB/MI. (line 9) -* GDB/MI, output syntax: GDB/MI Output Syntax. - (line 6) -* GDB/MI, result records: GDB/MI Result Records. - (line 6) -* GDB/MI, simple examples: GDB/MI Simple Examples. - (line 6) -* GDB/MI, stream records: GDB/MI Stream Records. - (line 6) -* gdbarch debugging info: Debugging Output. (line 18) -* GDBHISTFILE, environment variable: Command History. (line 26) -* gdbserver: Server. (line 6) -* gdbserver, multiple processes: Server. (line 91) -* gdbserver, search path for libthread_db: Server. (line 188) -* GDT: DJGPP Native. (line 24) -* generate-core-file: Core File Generation. - (line 18) -* get thread information block address: General Query Packets. - (line 143) -* get thread-local storage address, remote request: General Query Packets. - (line 112) -* get_set_string on parameter: Parameters In Python. - (line 74) -* get_show_string on parameter: Parameters In Python. - (line 80) -* getDebugChar: Bootstrapping. (line 14) -* gettimeofday, file-i/o system call: gettimeofday. (line 6) -* global debugging information directory: Separate Debug Files. - (line 6) -* GNU C++: C. (line 10) -* GNU Emacs: Emacs. (line 6) -* GNU Hurd debugging: Hurd Native. (line 6) -* GNU/Hurd debug messages: Debugging Output. (line 83) -* GNU/Linux LWP async debug messages: Debugging Output. (line 111) -* GNU/Linux LWP debug messages: Debugging Output. (line 104) -* gnu_debuglink_crc32: Separate Debug Files. - (line 164) -* h (help): Help. (line 9) -* H packet: Packets. (line 191) -* handle: Signals. (line 45) -* handle_exception: Stub Contents. (line 15) -* handling signals: Signals. (line 27) -* hardware breakpoints: Set Breaks. (line 62) -* hardware debug registers: Maintenance Commands. - (line 307) -* hardware watchpoints: Set Watchpoints. (line 31) -* hash mark while downloading: Target Commands. (line 99) -* hbreak: Set Breaks. (line 62) -* help: Help. (line 6) -* help function: Convenience Vars. (line 112) -* help target: Target Commands. (line 19) -* help user-defined: Define. (line 66) -* heuristic-fence-post (Alpha, MIPS): MIPS. (line 14) -* history: Basic Python. (line 47) -* history events: Event Designators. (line 7) -* history expansion: History Interaction. (line 6) -* history expansion, turn on/off: Command History. (line 53) -* history file: Command History. (line 26) -* history number: Value History. (line 13) -* history of values printed by GDB: Value History. (line 6) -* history size: Command History. (line 45) -* history substitution: Command History. (line 26) -* history-preserve-point: Readline Init File Syntax. - (line 93) -* history-search-backward (): Commands For History. - (line 50) -* history-search-forward (): Commands For History. - (line 45) -* HISTSIZE, environment variable: Command History. (line 45) -* hit_count: Breakpoints In Python. - (line 135) -* hook: Hooks. (line 6) -* hookpost: Hooks. (line 11) -* hooks, for commands: Hooks. (line 6) -* hooks, post-command: Hooks. (line 11) -* hooks, pre-command: Hooks. (line 6) -* horizontal-scroll-mode: Readline Init File Syntax. - (line 98) -* host character set: Character Sets. (line 6) -* Host I/O, remote protocol: Host I/O Packets. (line 6) -* how many arguments (user-defined commands): Define. (line 25) -* HPPA support: HPPA. (line 6) -* htrace: OpenRISC 1000. (line 69) -* hwatch: OpenRISC 1000. (line 59) -* i (info): Help. (line 99) -* i packet: Packets. (line 205) -* I packet: Packets. (line 210) -* i/o: Input/Output. (line 6) -* I/O registers (Atmel AVR): AVR. (line 10) -* i386: Remote Stub. (line 57) -* i386-stub.c: Remote Stub. (line 57) -* IDT: DJGPP Native. (line 24) -* if: Command Files. (line 75) -* ignore: Conditions. (line 77) -* ignore count (of breakpoint): Conditions. (line 66) -* ignore_count: Breakpoints In Python. - (line 98) -* INCLUDE_RDB: VxWorks. (line 33) -* incomplete type: Symbols. (line 107) -* indentation in structure display: Print Settings. (line 198) -* index files: Index Files. (line 6) -* inferior: Inferiors and Programs. - (line 13) -* inferior debugging info: Debugging Output. (line 89) -* inferior events in Python: Events In Python. (line 6) -* inferior functions, calling: Calling. (line 6) -* inferior INFNO: Inferiors and Programs. - (line 49) -* inferior tty: Input/Output. (line 44) -* inferior_thread: Events In Python. (line 57) -* inferiors: Inferiors In Python. (line 15) -* inferiors in Python: Inferiors In Python. (line 6) -* infinite recursion in user-defined commands: Define. (line 76) -* info: Help. (line 99) -* info address: Symbols. (line 44) -* info all-registers: Registers. (line 15) -* info args: Frame Info. (line 51) -* info auto-load-scripts: Auto-loading. (line 29) -* info auxv: OS Information. (line 33) -* info breakpoints: Set Breaks. (line 128) -* info catch: Frame Info. (line 60) -* info checkpoints: Checkpoint/Restart. (line 31) -* info classes: Symbols. (line 205) -* info common: Special Fortran Commands. - (line 9) -* info copying: Help. (line 136) -* info dcache: Caching Remote Data. (line 34) -* info display: Auto Display. (line 78) -* info dll: Cygwin Native. (line 35) -* info dos: DJGPP Native. (line 15) -* info extensions: Show. (line 34) -* info f (info frame): Frame Info. (line 17) -* info files: Files. (line 191) -* info float: Floating Point Hardware. - (line 9) -* info for known .debug_gdb_scripts-loaded scripts: Maintenance Commands. - (line 216) -* info for known object files: Maintenance Commands. - (line 211) -* info frame: Frame Info. (line 17) -* info frame, show the source language: Show. (line 15) -* info functions: Symbols. (line 184) -* info handle: Signals. (line 33) -* info inferiors: Inferiors and Programs. - (line 25) -* info io_registers, AVR: AVR. (line 10) -* info line: Machine Code. (line 14) -* info line, and Objective-C: Method Names in Commands. - (line 9) -* info locals: Frame Info. (line 55) -* info macro: Macros. (line 47) -* info mem: Memory Region Attributes. - (line 45) -* info meminfo: SVR4 Process Information. - (line 78) -* info or1k spr: OpenRISC 1000. (line 20) -* info os: OS Information. (line 47) -* info os processes: OS Information. (line 52) -* info pidlist: SVR4 Process Information. - (line 74) -* info pretty-printer: Pretty-Printer Commands. - (line 6) -* info proc: SVR4 Process Information. - (line 16) -* info program: Stopping. (line 18) -* info record: Process Record and Replay. - (line 137) -* info registers: Registers. (line 11) -* info scope: Symbols. (line 138) -* info selectors: Symbols. (line 211) -* info serial: DJGPP Native. (line 142) -* info set: Help. (line 119) -* info share: Files. (line 326) -* info sharedlibrary: Files. (line 326) -* info signals: Signals. (line 33) -* info source: Symbols. (line 159) -* info source, show the source language: Show. (line 21) -* info sources: Symbols. (line 178) -* info spu: SPU. (line 10) -* info stack: Backtrace. (line 34) -* info static-tracepoint-markers: Listing Static Tracepoint Markers. - (line 6) -* info symbol: Symbols. (line 54) -* info target: Files. (line 191) -* info task TASKNO: Ada Tasks. (line 89) -* info tasks: Ada Tasks. (line 9) -* info terminal: Input/Output. (line 12) -* info threads: Threads. (line 66) -* info tp [N...]: Listing Tracepoints. (line 6) -* info tracepoints [N...]: Listing Tracepoints. (line 6) -* info tvariables: Trace State Variables. - (line 37) -* info types: Symbols. (line 124) -* info udot: OS Information. (line 16) -* info variables: Symbols. (line 196) -* info vector: Vector Unit. (line 9) -* info w32: Cygwin Native. (line 19) -* info warranty: Help. (line 140) -* info watchpoints [N...]: Set Watchpoints. (line 72) -* info win: TUI Commands. (line 18) -* information about static tracepoint markers: Listing Static Tracepoint Markers. - (line 6) -* information about tracepoints: Listing Tracepoints. (line 6) -* inheritance: Debugging C Plus Plus. - (line 25) -* init file: Startup. (line 11) -* init file name: Startup. (line 60) -* init-if-undefined: Convenience Vars. (line 41) -* initial frame: Frames. (line 12) -* initialization file, readline: Readline Init File. (line 6) -* inline functions, debugging: Inline Functions. (line 6) -* innermost frame: Frames. (line 12) -* input syntax for GDB/MI: GDB/MI Input Syntax. (line 6) -* input-meta: Readline Init File Syntax. - (line 105) -* insert-comment (M-#): Miscellaneous Commands. - (line 51) -* insert-completions (M-*): Commands For Completion. - (line 14) -* inspect: Data. (line 6) -* installation: Installing GDB. (line 6) -* instructions, assembly: Machine Code. (line 36) -* integral datatypes, in file-i/o protocol: Integral Datatypes. - (line 6) -* Intel: Remote Stub. (line 57) -* Intel disassembly flavor: Machine Code. (line 127) -* interaction, readline: Readline Interaction. - (line 6) -* internal commands: Maintenance Commands. - (line 6) -* internal errors, control of GDB behavior: Maintenance Commands. - (line 124) -* internal GDB breakpoints: Set Breaks. (line 333) -* interpreter-exec: Interpreters. (line 43) -* interrupt <1>: Quitting GDB. (line 13) -* interrupt: Background Execution. - (line 73) -* interrupt debuggee on MS-Windows: Cygwin Native. (line 9) -* interrupt remote programs: Remote Configuration. - (line 85) -* interrupting remote programs: Connecting. (line 78) -* interrupting remote targets: Bootstrapping. (line 25) -* interrupts (remote protocol): Interrupts. (line 6) -* invalid input: Bug Criteria. (line 16) -* invoke another interpreter: Interpreters. (line 37) -* invoke on Command: Commands In Python. (line 50) -* invoke on Function: Functions In Python. (line 21) -* is_argument: Symbols In Python. (line 77) -* is_constant: Symbols In Python. (line 80) -* is_exited on InferiorThread: Threads In Python. (line 61) -* is_function: Symbols In Python. (line 83) -* is_optimized_out: Values From Inferior. - (line 50) -* is_running on InferiorThread: Threads In Python. (line 58) -* is_stopped on InferiorThread: Threads In Python. (line 55) -* is_valid on Block: Blocks In Python. (line 24) -* is_valid on Breakpoint: Breakpoints In Python. - (line 62) -* is_valid on Frame: Frames In Python. (line 37) -* is_valid on Inferior: Inferiors In Python. (line 33) -* is_valid on InferiorThread: Threads In Python. (line 43) -* is_valid on Objfile: Objfiles In Python. (line 42) -* is_valid on Symbol: Symbols In Python. (line 91) -* is_valid on Symtab: Symbol Tables In Python. - (line 51) -* is_valid on Symtab_and_line: Symbol Tables In Python. - (line 31) -* is_variable: Symbols In Python. (line 86) -* isatty, file-i/o system call: isatty. (line 6) -* isearch-terminators: Readline Init File Syntax. - (line 112) -* JIT compilation interface: JIT Interface. (line 6) -* jump: Jumping. (line 10) -* jump, and Objective-C: Method Names in Commands. - (line 9) -* just-in-time compilation: JIT Interface. (line 6) -* just-in-time compilation, debugging messages: Debugging Output. - (line 98) -* k packet: Packets. (line 214) -* kernel crash dump: BSD libkvm Interface. - (line 6) -* kernel memory image: BSD libkvm Interface. - (line 6) -* KeyboardInterrupt: Exception Handling. (line 34) -* keymap: Readline Init File Syntax. - (line 119) -* kill: Kill Process. (line 6) -* kill inferiors INFNO...: Inferiors and Programs. - (line 103) -* kill ring: Readline Killing Commands. - (line 19) -* kill-line (C-k): Commands For Killing. - (line 6) -* kill-region (): Commands For Killing. - (line 41) -* kill-whole-line (): Commands For Killing. - (line 15) -* kill-word (M-d): Commands For Killing. - (line 19) -* killing text: Readline Killing Commands. - (line 6) -* kvm: BSD libkvm Interface. - (line 24) -* l (list): List. (line 6) -* languages: Languages. (line 6) -* last tracepoint number: Create and Delete Tracepoints. - (line 98) -* latest breakpoint: Set Breaks. (line 6) -* layout: TUI Commands. (line 21) -* lazy strings in python: Lazy Strings In Python. - (line 6) -* lazy_string on Value: Values From Inferior. - (line 172) -* LDT: DJGPP Native. (line 24) -* leaving GDB: Quitting GDB. (line 6) -* Left: TUI Keys. (line 59) -* length: Lazy Strings In Python. - (line 31) -* libkvm: BSD libkvm Interface. - (line 6) -* library list format, remote protocol: Library List Format. (line 6) -* limit hardware breakpoints and watchpoints: Remote Configuration. - (line 72) -* limit on number of printed array elements: Print Settings. (line 123) -* limits, in file-i/o protocol: Limits. (line 6) -* line: Symbol Tables In Python. - (line 25) -* linespec: Specify Location. (line 6) -* linkage_name: Symbols In Python. (line 62) -* Linux lightweight processes: Debugging Output. (line 111) -* list: List. (line 6) -* list active threads, remote request: General Query Packets. - (line 84) -* list of supported file-i/o calls: List of Supported Calls. - (line 6) -* list output in GDB/MI: GDB/MI Output Syntax. - (line 117) -* list, and Objective-C: Method Names in Commands. - (line 9) -* list, how many lines to display: List. (line 30) -* listing GDB's internal symbol tables: Symbols. (line 291) -* listing machine instructions: Machine Code. (line 36) -* listing mapped overlays: Overlay Commands. (line 60) -* load address, overlay's: How Overlays Work. (line 6) -* load FILENAME: Target Commands. (line 115) -* load shared library: Files. (line 323) -* load symbols from memory: Files. (line 162) -* local variables: Symbols. (line 138) -* locate address: Output Formats. (line 35) -* location: Breakpoints In Python. - (line 140) -* lock scheduler: All-Stop Mode. (line 37) -* log output in GDB/MI: GDB/MI Output Syntax. - (line 113) -* logging file name: Logging Output. (line 13) -* logging GDB output: Logging Output. (line 6) -* lookup_global_symbol: Symbols In Python. (line 34) -* lookup_symbol: Symbols In Python. (line 14) -* lookup_type: Types In Python. (line 12) -* loop_break: Command Files. (line 94) -* loop_continue: Command Files. (line 98) -* lseek flags, in file-i/o protocol: Lseek Flags. (line 6) -* lseek, file-i/o system call: lseek. (line 6) -* M packet: Packets. (line 241) -* m packet: Packets. (line 221) -* M32-EVA target board address: M32R/D. (line 21) -* M32R/Chaos debugging: M32R/D. (line 50) -* m680x0: Remote Stub. (line 60) -* m68k-stub.c: Remote Stub. (line 60) -* machine instructions: Machine Code. (line 36) -* macro define: Macros. (line 52) -* macro definition, showing: Macros. (line 47) -* macro exp1: Macros. (line 36) -* macro expand: Macros. (line 29) -* macro expansion, showing the results of preprocessor: Macros. - (line 29) -* macro list: Macros. (line 73) -* macro undef: Macros. (line 67) -* macros, example of debugging with: Macros. (line 76) -* macros, user-defined: Macros. (line 52) -* mailing lists: GDB/MI Development and Front Ends. - (line 35) -* maint agent: Maintenance Commands. - (line 12) -* maint agent-eval: Maintenance Commands. - (line 12) -* maint check-symtabs: Maintenance Commands. - (line 78) -* maint cplus first_component: Maintenance Commands. - (line 81) -* maint cplus namespace: Maintenance Commands. - (line 84) -* maint demangle: Maintenance Commands. - (line 87) -* maint deprecate: Maintenance Commands. - (line 90) -* maint dump-me: Maintenance Commands. - (line 98) -* maint info breakpoints: Maintenance Commands. - (line 25) -* maint info program-spaces: Inferiors and Programs. - (line 138) -* maint info psymtabs: Symbols. (line 291) -* maint info sections: Files. (line 200) -* maint info sol-threads: Threads. (line 98) -* maint info symtabs: Symbols. (line 291) -* maint internal-error: Maintenance Commands. - (line 103) -* maint internal-warning: Maintenance Commands. - (line 103) -* maint packet: Maintenance Commands. - (line 143) -* maint print architecture: Maintenance Commands. - (line 149) -* maint print c-tdesc: Maintenance Commands. - (line 153) -* maint print cooked-registers: Maintenance Commands. - (line 176) -* maint print dummy-frames: Maintenance Commands. - (line 158) -* maint print objfiles: Maintenance Commands. - (line 211) -* maint print psymbols: Symbols. (line 272) -* maint print raw-registers: Maintenance Commands. - (line 176) -* maint print reggroups: Maintenance Commands. - (line 192) -* maint print register-groups: Maintenance Commands. - (line 176) -* maint print registers: Maintenance Commands. - (line 176) -* maint print section-scripts: Maintenance Commands. - (line 216) -* maint print statistics: Maintenance Commands. - (line 223) -* maint print symbols: Symbols. (line 272) -* maint print target-stack: Maintenance Commands. - (line 236) -* maint print type: Maintenance Commands. - (line 248) -* maint print unwind, HPPA: HPPA. (line 17) -* maint set dwarf2 always-disassemble: Maintenance Commands. - (line 255) -* maint set dwarf2 max-cache-age: Maintenance Commands. - (line 277) -* maint set internal-error: Maintenance Commands. - (line 124) -* maint set internal-warning: Maintenance Commands. - (line 124) -* maint set profile: Maintenance Commands. - (line 291) -* maint set python print-stack: Python Commands. (line 31) -* maint set show-all-tib: Maintenance Commands. - (line 315) -* maint set show-debug-regs: Maintenance Commands. - (line 307) -* maint show dwarf2 always-disassemble: Maintenance Commands. - (line 255) -* maint show dwarf2 max-cache-age: Maintenance Commands. - (line 277) -* maint show internal-error: Maintenance Commands. - (line 124) -* maint show internal-warning: Maintenance Commands. - (line 124) -* maint show profile: Maintenance Commands. - (line 291) -* maint show show-all-tib: Maintenance Commands. - (line 315) -* maint show show-debug-regs: Maintenance Commands. - (line 307) -* maint space: Maintenance Commands. - (line 321) -* maint time: Maintenance Commands. - (line 328) -* maint translate-address: Maintenance Commands. - (line 339) -* maint undeprecate: Maintenance Commands. - (line 90) -* maintenance commands: Maintenance Commands. - (line 6) -* make: Shell Commands. (line 19) -* manual overlay debugging: Overlay Commands. (line 23) -* map an overlay: Overlay Commands. (line 30) -* mapinfo list, QNX Neutrino: SVR4 Process Information. - (line 78) -* mapped address: How Overlays Work. (line 6) -* mapped overlays: How Overlays Work. (line 6) -* mark-modified-lines: Readline Init File Syntax. - (line 132) -* mark-symlinked-directories: Readline Init File Syntax. - (line 137) -* markers, static tracepoints: Set Tracepoints. (line 28) -* match-hidden-files: Readline Init File Syntax. - (line 142) -* maximum value for offset of closest symbol: Print Settings. (line 70) -* may-insert-breakpoints: Observer Mode. (line 50) -* may-insert-fast-tracepoints: Observer Mode. (line 69) -* may-insert-tracepoints: Observer Mode. (line 59) -* may-interrupt: Observer Mode. (line 79) -* may-write-memory: Observer Mode. (line 41) -* may-write-registers: Observer Mode. (line 32) -* mem: Memory Region Attributes. - (line 22) -* member functions: C Plus Plus Expressions. - (line 18) -* memory address space mappings: SVR4 Process Information. - (line 32) -* memory map format: Memory Map Format. (line 6) -* memory region attributes: Memory Region Attributes. - (line 6) -* memory tracing: Breakpoints. (line 20) -* memory transfer, in file-i/o protocol: Memory Transfer. (line 6) -* memory used by commands: Maintenance Commands. - (line 321) -* memory used for symbol tables: Files. (line 311) -* memory, alignment and size of remote accesses: Packets. (line 228) -* memory, viewing as typed object: Expressions. (line 43) -* memset: Bootstrapping. (line 70) -* menu-complete (): Commands For Completion. - (line 18) -* meta-flag: Readline Init File Syntax. - (line 105) -* mi interpreter: Interpreters. (line 26) -* mi1 interpreter: Interpreters. (line 34) -* mi2 interpreter: Interpreters. (line 31) -* minimal language: Unsupported Languages. - (line 6) -* Minimal symbols and DLLs: Non-debug DLL Symbols. - (line 6) -* MIPS addresses, masking: MIPS. (line 61) -* MIPS boards: MIPS Embedded. (line 6) -* MIPS remote floating point: MIPS Embedded. (line 60) -* MIPS stack: MIPS. (line 6) -* miscellaneous settings: Other Misc Settings. (line 6) -* MMX registers (x86): Registers. (line 71) -* mode_t values, in file-i/o protocol: mode_t Values. (line 6) -* Modula-2: Summary. (line 29) -* Modula-2 built-ins: Built-In Func/Proc. (line 6) -* Modula-2 checks: M2 Checks. (line 6) -* Modula-2 constants: Built-In Func/Proc. (line 112) -* Modula-2 defaults: M2 Defaults. (line 6) -* Modula-2 operators: M2 Operators. (line 6) -* Modula-2 types: M2 Types. (line 6) -* Modula-2, deviations from: Deviations. (line 6) -* Modula-2, GDB support: Modula-2. (line 6) -* monitor: Connecting. (line 105) -* monitor commands, for gdbserver: Server. (line 171) -* Motorola 680x0: Remote Stub. (line 60) -* MS Windows debugging: Cygwin Native. (line 6) -* MS-DOS system info: DJGPP Native. (line 19) -* MS-DOS-specific commands: DJGPP Native. (line 6) -* multiple locations, breakpoints: Set Breaks. (line 190) -* multiple processes: Forks. (line 6) -* multiple processes with gdbserver: Server. (line 91) -* multiple targets: Active Targets. (line 6) -* multiple threads: Threads. (line 6) -* multiple threads, backtrace: Backtrace. (line 37) -* multiple-symbols menu: Ambiguous Expressions. - (line 51) -* multiprocess extensions, in remote protocol: General Query Packets. - (line 527) -* n (next): Continuing and Stepping. - (line 78) -* n (SingleKey TUI key): TUI Single Key Mode. (line 19) -* name <1>: Threads In Python. (line 20) -* name: Symbols In Python. (line 58) -* name a thread: Threads. (line 131) -* name on Frame: Frames In Python. (line 44) -* names of symbols: Symbols. (line 14) -* namespace in C++: C Plus Plus Expressions. - (line 22) -* native Cygwin debugging: Cygwin Native. (line 6) -* native DJGPP debugging: DJGPP Native. (line 6) -* negative breakpoint numbers: Set Breaks. (line 333) -* NetROM ROM emulator target: Target Commands. (line 88) -* New SYSTAG message: Threads. (line 51) -* newer on Frame: Frames In Python. (line 93) -* newest_frame: Frames In Python. (line 27) -* next: Continuing and Stepping. - (line 78) -* next&: Background Execution. - (line 47) -* next-history (C-n): Commands For History. - (line 16) -* nexti: Continuing and Stepping. - (line 203) -* nexti&: Background Execution. - (line 50) -* ni (nexti): Continuing and Stepping. - (line 203) -* non-incremental-forward-search-history (M-n): Commands For History. - (line 40) -* non-incremental-reverse-search-history (M-p): Commands For History. - (line 35) -* non-member C++ functions, set breakpoint in: Set Breaks. (line 108) -* non-stop mode: Non-Stop Mode. (line 6) -* non-stop mode, and breakpoint always-inserted: Set Breaks. (line 326) -* non-stop mode, and process record and replay: Process Record and Replay. - (line 52) -* non-stop mode, and set displaced-stepping: Maintenance Commands. - (line 73) -* non-stop mode, remote request: General Query Packets. - (line 220) -* noninvasive task options: Hurd Native. (line 73) -* nosharedlibrary: Files. (line 341) -* notation, readline: Readline Bare Essentials. - (line 6) -* notational conventions, for GDB/MI: GDB/MI. (line 25) -* notification packets: Notification Packets. - (line 6) -* notify output in GDB/MI: GDB/MI Output Syntax. - (line 102) -* NULL elements in arrays: Print Settings. (line 189) -* num <1>: Threads In Python. (line 30) -* num: Inferiors In Python. (line 20) -* number: Breakpoints In Python. - (line 102) -* number of array elements to print: Print Settings. (line 123) -* number representation: Numbers. (line 6) -* numbers for breakpoints: Breakpoints. (line 41) -* object files, relocatable, reading symbols from: Files. (line 132) -* Objective-C: Objective-C. (line 6) -* Objective-C, classes and selectors: Symbols. (line 205) -* Objective-C, print objects: The Print Command with Objective-C. - (line 6) -* objfile: Symbol Tables In Python. - (line 45) -* Objfile: Objfiles In Python. (line 6) -* OBJFILE-gdb.py: objfile-gdb.py file. (line 6) -* objfiles: Objfiles In Python. (line 22) -* objfiles in python: Objfiles In Python. (line 6) -* observer: Observer Mode. (line 22) -* observer debugging info: Debugging Output. (line 118) -* octal escapes in strings: Print Settings. (line 222) -* older on Frame: Frames In Python. (line 90) -* online documentation: Help. (line 6) -* opaque data types: Symbols. (line 241) -* open flags, in file-i/o protocol: Open Flags. (line 6) -* open, file-i/o system call: open. (line 6) -* OpenCL C: OpenCL C. (line 6) -* OpenCL C Datatypes: OpenCL C Datatypes. (line 6) -* OpenCL C Expressions: OpenCL C Expressions. - (line 6) -* OpenCL C Operators: OpenCL C Operators. (line 6) -* OpenRISC 1000: OpenRISC 1000. (line 6) -* OpenRISC 1000 htrace: OpenRISC 1000. (line 58) -* operating system information: Operating System Information. - (line 6) -* operating system information, process list: Process list. (line 6) -* optimized code, debugging: Optimized Code. (line 6) -* optimized code, wrong values of variables: Variables. (line 58) -* optimized out value in Python: Values From Inferior. - (line 49) -* optimized out, in backtrace: Backtrace. (line 71) -* optional debugging messages: Debugging Output. (line 6) -* optional warnings: Messages/Warnings. (line 6) -* or1k boards: OpenRISC 1000. (line 6) -* or1ksim: OpenRISC 1000. (line 16) -* OS ABI: ABI. (line 11) -* OS information: OS Information. (line 6) -* out-of-line single-stepping: Maintenance Commands. - (line 56) -* outermost frame: Frames. (line 12) -* output: Output. (line 35) -* output formats: Output Formats. (line 6) -* output syntax of GDB/MI: GDB/MI Output Syntax. - (line 6) -* output-meta: Readline Init File Syntax. - (line 149) -* overlay: Overlay Commands. (line 17) -* overlay area: How Overlays Work. (line 6) -* overlay example program: Overlay Sample Program. - (line 6) -* overlays: Overlays. (line 6) -* overlays, setting breakpoints in: Overlay Commands. (line 93) -* overload-choice annotation: Prompting. (line 32) -* overloaded functions, calling: C Plus Plus Expressions. - (line 27) -* overloaded functions, overload resolution: Debugging C Plus Plus. - (line 48) -* overloading in C++: Debugging C Plus Plus. - (line 15) -* overwrite-mode (): Commands For Text. (line 53) -* p packet: Packets. (line 254) -* P packet: Packets. (line 269) -* packet acknowledgment, for GDB remote: Packet Acknowledgment. - (line 6) -* packet size, remote protocol: General Query Packets. - (line 458) -* packets, notification: Notification Packets. - (line 6) -* packets, reporting on stdout: Debugging Output. (line 140) -* packets, tracepoint: Tracepoint Packets. (line 6) -* page tables display (MS-DOS): DJGPP Native. (line 56) -* page-completions: Readline Init File Syntax. - (line 154) -* PARAM_AUTO_BOOLEAN: Parameters In Python. - (line 93) -* PARAM_BOOLEAN: Parameters In Python. - (line 89) -* PARAM_ENUM: Parameters In Python. - (line 127) -* PARAM_FILENAME: Parameters In Python. - (line 119) -* PARAM_INTEGER: Parameters In Python. - (line 102) -* PARAM_OPTIONAL_FILENAME: Parameters In Python. - (line 116) -* PARAM_STRING: Parameters In Python. - (line 106) -* PARAM_STRING_NOESCAPE: Parameters In Python. - (line 112) -* PARAM_UINTEGER: Parameters In Python. - (line 98) -* PARAM_ZINTEGER: Parameters In Python. - (line 123) -* Parameter: Parameters In Python. - (line 6) -* parameter: Basic Python. (line 36) -* parameters in python: Parameters In Python. - (line 6) -* parse_and_eval: Basic Python. (line 59) -* partial symbol dump: Symbols. (line 272) -* partial symbol tables, listing GDB's internal: Symbols. (line 291) -* Pascal: Summary. (line 35) -* Pascal objects, static members display: Print Settings. (line 353) -* Pascal support in GDB, limitations: Pascal. (line 6) -* pass signals to inferior, remote request: General Query Packets. - (line 240) -* passcount: Tracepoint Passcounts. - (line 6) -* patching binaries: Patching. (line 6) -* patching object files: Files. (line 26) -* path: Environment. (line 14) -* pause current task (GNU Hurd): Hurd Native. (line 49) -* pause current thread (GNU Hurd): Hurd Native. (line 91) -* pauses in output: Screen Size. (line 6) -* pc: Symbol Tables In Python. - (line 21) -* pc on Frame: Frames In Python. (line 80) -* pending breakpoints: Set Breaks. (line 232) -* PgDn: TUI Keys. (line 50) -* PgUp: TUI Keys. (line 47) -* physical address from linear address: DJGPP Native. (line 81) -* physname: Debugging Output. (line 35) -* pid: Inferiors In Python. (line 23) -* pipe, target remote to: Connecting. (line 60) -* pipes: Starting. (line 62) -* pmon, MIPS remote: MIPS Embedded. (line 132) -* po (print-object): The Print Command with Objective-C. - (line 6) -* pointer on Type: Types In Python. (line 114) -* pointer values, in file-i/o protocol: Pointer Values. (line 6) -* pointer, finding referent: Print Settings. (line 79) -* port rights, GNU Hurd: Hurd Native. (line 85) -* port sets, GNU Hurd: Hurd Native. (line 85) -* possible-completions (M-?): Commands For Completion. - (line 11) -* post-commands annotation: Prompting. (line 27) -* post-overload-choice annotation: Prompting. (line 32) -* post-prompt annotation: Prompting. (line 24) -* post-prompt-for-continue annotation: Prompting. (line 40) -* post-query annotation: Prompting. (line 36) -* post_event: Basic Python. (line 70) -* PowerPC architecture: PowerPC. (line 6) -* pre-commands annotation: Prompting. (line 27) -* pre-overload-choice annotation: Prompting. (line 32) -* pre-prompt annotation: Prompting. (line 24) -* pre-prompt-for-continue annotation: Prompting. (line 40) -* pre-query annotation: Prompting. (line 36) -* prefix for data files: Data Files. (line 6) -* prefix for shared library file names: Files. (line 374) -* prefix-meta (<ESC>): Miscellaneous Commands. - (line 18) -* premature return from system calls: Interrupted System Calls. - (line 6) -* preprocessor macro expansion, showing the results of: Macros. - (line 29) -* pretty print arrays: Print Settings. (line 98) -* pretty print C++ virtual function tables: Print Settings. (line 364) -* pretty-printer commands: Pretty-Printer Commands. - (line 6) -* pretty_printers <1>: Objfiles In Python. (line 32) -* pretty_printers: Progspaces In Python. - (line 28) -* previous-history (C-p): Commands For History. - (line 12) -* print: Data. (line 6) -* print all frame argument values: Print Settings. (line 135) -* print an Objective-C object description: The Print Command with Objective-C. - (line 11) -* print array indexes: Print Settings. (line 108) -* print frame argument values for scalars only: Print Settings. - (line 135) -* print list of auto-loaded scripts: Auto-loading. (line 29) -* print messages on inferior start and exit: Inferiors and Programs. - (line 117) -* print messages on thread start and exit: Threads. (line 156) -* print messages when symbols are loaded: Symbols. (line 259) -* print settings: Print Settings. (line 6) -* print structures in indented form: Print Settings. (line 198) -* print-object: The Print Command with Objective-C. - (line 6) -* print/don't print memory addresses: Print Settings. (line 13) -* print_name: Symbols In Python. (line 66) -* printf: Output. (line 46) -* printing byte arrays: Output Formats. (line 60) -* printing data: Data. (line 6) -* printing frame argument values: Print Settings. (line 135) -* printing strings: Output Formats. (line 60) -* probe static tracepoint marker: Create and Delete Tracepoints. - (line 51) -* probing markers, static tracepoints: Set Tracepoints. (line 28) -* proc-trace-entry: SVR4 Process Information. - (line 70) -* proc-trace-exit: SVR4 Process Information. - (line 70) -* proc-untrace-entry: SVR4 Process Information. - (line 70) -* proc-untrace-exit: SVR4 Process Information. - (line 70) -* process detailed status information: SVR4 Process Information. - (line 40) -* process ID: SVR4 Process Information. - (line 16) -* process info via /proc: SVR4 Process Information. - (line 6) -* process list, QNX Neutrino: SVR4 Process Information. - (line 74) -* process record and replay: Process Record and Replay. - (line 6) -* process status register: Registers. (line 26) -* processes, multiple: Forks. (line 6) -* procfs API calls: SVR4 Process Information. - (line 53) -* profiling GDB: Maintenance Commands. - (line 291) -* program counter register: Registers. (line 26) -* program entry point: Backtrace. (line 93) -* programming in python: Python API. (line 6) -* Progspace: Progspaces In Python. - (line 6) -* progspaces: Progspaces In Python. - (line 19) -* progspaces in python: Progspaces In Python. - (line 6) -* prompt: Prompt. (line 6) -* prompt annotation: Prompting. (line 24) -* prompt-for-continue annotation: Prompting. (line 40) -* protocol basics, file-i/o: Protocol Basics. (line 6) -* protocol, GDB remote serial: Overview. (line 14) -* protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes. - (line 6) -* ptid: Threads In Python. (line 33) -* ptrace system call: OS Information. (line 9) -* ptype: Symbols. (line 85) -* putDebugChar: Bootstrapping. (line 20) -* pwd: Working Directory. (line 19) -* python: Python Commands. (line 9) -* python api: Python API. (line 6) -* python commands <1>: Commands In Python. (line 6) -* python commands: Python Commands. (line 6) -* python convenience functions: Functions In Python. (line 6) -* python directory: Python. (line 10) -* python exceptions: Exception Handling. (line 6) -* python functions: Basic Python. (line 6) -* python module: Basic Python. (line 6) -* python modules: Python modules. (line 6) -* python pagination: Python API. (line 6) -* python parameters: Parameters In Python. - (line 6) -* python scripting: Python. (line 6) -* python stdout: Python API. (line 6) -* Python, working with types: Types In Python. (line 6) -* python, working with values from inferior: Values From Inferior. - (line 6) -* PYTHONDIR: Basic Python. (line 12) -* q (quit): Quitting GDB. (line 6) -* q (SingleKey TUI key): TUI Single Key Mode. (line 22) -* q packet: Packets. (line 282) -* Q packet: Packets. (line 282) -* QAllow packet: General Query Packets. - (line 41) -* qAttached packet: General Query Packets. - (line 835) -* qC packet: General Query Packets. - (line 52) -* qCRC packet: General Query Packets. - (line 63) -* qfThreadInfo packet: General Query Packets. - (line 84) -* qGetTIBAddr packet: General Query Packets. - (line 143) -* qGetTLSAddr packet: General Query Packets. - (line 112) -* QNonStop packet: General Query Packets. - (line 220) -* QNX Neutrino: Neutrino. (line 6) -* qOffsets packet: General Query Packets. - (line 182) -* qP packet: General Query Packets. - (line 209) -* QPassSignals packet: General Query Packets. - (line 240) -* qRcmd packet: General Query Packets. - (line 268) -* qSearch:memory packet: General Query Packets. - (line 293) -* QStartNoAckMode packet: General Query Packets. - (line 313) -* qsThreadInfo packet: General Query Packets. - (line 84) -* qSupported packet: General Query Packets. - (line 328) -* qSymbol packet: General Query Packets. - (line 567) -* QTDPsrc packet: Tracepoint Packets. (line 96) -* QTDV packet: Tracepoint Packets. (line 127) -* qThreadExtraInfo packet: General Query Packets. - (line 612) -* qTV packet: Tracepoint Packets. (line 276) -* query annotation: Prompting. (line 36) -* query attached, remote request: General Query Packets. - (line 835) -* quit [EXPRESSION]: Quitting GDB. (line 6) -* quit annotation: Errors. (line 6) -* quoted-insert (C-q or C-v): Commands For Text. (line 20) -* quotes in commands: Completion. (line 57) -* quoting Ada internal identifiers: Additions to Ada. (line 76) -* quoting names: Symbols. (line 14) -* qXfer packet: General Query Packets. - (line 648) -* r (run): Starting. (line 6) -* r (SingleKey TUI key): TUI Single Key Mode. (line 25) -* r packet: Packets. (line 286) -* R packet: Packets. (line 291) -* raise exceptions: Set Catchpoints. (line 197) -* range checking: Type Checking. (line 65) -* range on Type: Types In Python. (line 104) -* ranged breakpoint: PowerPC Embedded. (line 30) -* ranges of breakpoints: Breakpoints. (line 48) -* Ravenscar Profile: Ravenscar Profile. (line 6) -* raw printing: Output Formats. (line 70) -* rbreak: Set Breaks. (line 92) -* rc (reverse-continue): Reverse Execution. (line 30) -* RDI heartbeat: ARM. (line 112) -* rdilogenable: ARM. (line 95) -* rdilogfile: ARM. (line 89) -* re-read-init-file (C-x C-r): Miscellaneous Commands. - (line 6) -* read special object, remote request: General Query Packets. - (line 648) -* read, file-i/o system call: read. (line 6) -* read-only sections: Files. (line 258) -* read_memory on Inferior: Inferiors In Python. (line 45) -* read_var on Frame: Frames In Python. (line 100) -* reading symbols from relocatable object files: Files. (line 132) -* reading symbols immediately: Files. (line 90) -* readline: Editing. (line 6) -* readnow: Files. (line 90) -* rec: Process Record and Replay. - (line 38) -* rec del: Process Record and Replay. - (line 155) -* rec s: Process Record and Replay. - (line 57) -* receive rights, GNU Hurd: Hurd Native. (line 85) -* recent tracepoint number: Create and Delete Tracepoints. - (line 98) -* record: Process Record and Replay. - (line 38) -* record aggregates (Ada): Omissions from Ada. (line 44) -* record delete: Process Record and Replay. - (line 155) -* record mode: Process Record and Replay. - (line 19) -* record restore: Process Record and Replay. - (line 85) -* record save: Process Record and Replay. - (line 80) -* record serial communications on file: Remote Configuration. - (line 57) -* record stop: Process Record and Replay. - (line 57) -* recording a session script: Bug Reporting. (line 104) -* recording inferior's execution and replaying it: Process Record and Replay. - (line 6) -* redirection: Input/Output. (line 6) -* redraw-current-line (): Commands For Moving. (line 30) -* reference card: Formatting Documentation. - (line 6) -* reference declarations: C Plus Plus Expressions. - (line 51) -* reference on Type: Types In Python. (line 110) -* refresh: TUI Commands. (line 58) -* register stack, AMD29K: A29K. (line 6) -* registers: Registers. (line 6) -* regs, Super-H: Super-H. (line 9) -* regular expression: Set Breaks. (line 92) -* reinterpret_cast on Value: Values From Inferior. - (line 135) -* reloading symbols: Symbols. (line 217) -* reloading the overlay table: Overlay Commands. (line 52) -* relocatable object files, reading symbols from: Files. (line 132) -* remote connection without stubs: Server. (line 6) -* remote debugging: Remote Debugging. (line 6) -* remote delete: File Transfer. (line 23) -* remote get: File Transfer. (line 19) -* remote memory comparison: Memory. (line 123) -* remote monitor prompt: MIPS Embedded. (line 107) -* remote packets, enabling and disabling: Remote Configuration. - (line 132) -* remote programs, interrupting: Connecting. (line 78) -* remote protocol debugging: Debugging Output. (line 140) -* remote protocol, binary data: Overview. (line 61) -* remote protocol, field separator: Overview. (line 53) -* remote put: File Transfer. (line 15) -* remote query requests: General Query Packets. - (line 6) -* remote serial debugging summary: Debug Session. (line 6) -* remote serial debugging, overview: Remote Stub. (line 14) -* remote serial protocol: Overview. (line 14) -* remote serial stub: Stub Contents. (line 6) -* remote serial stub list: Remote Stub. (line 54) -* remote serial stub, initialization: Stub Contents. (line 10) -* remote serial stub, main routine: Stub Contents. (line 15) -* remote stub, example: Remote Stub. (line 6) -* remote stub, support routines: Bootstrapping. (line 6) -* remote target: Target Commands. (line 58) -* remote target, file transfer: File Transfer. (line 6) -* remote target, limit break- and watchpoints: Remote Configuration. - (line 72) -* remote timeout: Remote Configuration. - (line 65) -* remotetimeout: Sparclet. (line 12) -* remove actions from a tracepoint: Tracepoint Actions. (line 21) -* remove-inferiors: Inferiors and Programs. - (line 86) -* rename, file-i/o system call: rename. (line 6) -* Renesas: Remote Stub. (line 63) -* repeated array elements: Print Settings. (line 176) -* repeating command sequences: Command Syntax. (line 42) -* repeating commands: Command Syntax. (line 21) -* replay log events, remote reply: Stop Reply Packets. (line 61) -* replay mode: Process Record and Replay. - (line 10) -* reporting bugs in GDB: GDB Bugs. (line 6) -* reprint the last value: Data. (line 23) -* reset SDI connection, M32R: M32R/D. (line 44) -* response time, MIPS debugging: MIPS. (line 10) -* restart: Checkpoint/Restart. (line 6) -* restart CHECKPOINT-ID: Checkpoint/Restart. (line 44) -* restore: Dump/Restore Files. (line 41) -* restore data from a file: Dump/Restore Files. (line 6) -* result records in GDB/MI: GDB/MI Result Records. - (line 6) -* resume threads of multiple processes simultaneously: All-Stop Mode. - (line 53) -* resuming execution: Continuing and Stepping. - (line 6) -* RET (repeat last command): Command Syntax. (line 21) -* retransmit-timeout, MIPS protocol: MIPS Embedded. (line 83) -* return: Returning. (line 6) -* returning from a function: Returning. (line 6) -* reverse execution: Reverse Execution. (line 6) -* reverse-continue: Reverse Execution. (line 30) -* reverse-finish: Reverse Execution. (line 77) -* reverse-next: Reverse Execution. (line 60) -* reverse-nexti: Reverse Execution. (line 69) -* reverse-search: Search. (line 16) -* reverse-search-history (C-r): Commands For History. - (line 26) -* reverse-step: Reverse Execution. (line 37) -* reverse-stepi: Reverse Execution. (line 52) -* revert-line (M-r): Miscellaneous Commands. - (line 25) -* rewind program state: Checkpoint/Restart. (line 6) -* Right: TUI Keys. (line 62) -* rn (reverse-next): Reverse Execution. (line 60) -* rni (reverse-nexti): Reverse Execution. (line 69) -* ROM at zero address, RDI: ARM. (line 102) -* rs (step): Reverse Execution. (line 37) -* rsi (reverse-stepi): Reverse Execution. (line 52) -* run: Starting. (line 6) -* run to main procedure: Starting. (line 79) -* run until specified location: Continuing and Stepping. - (line 118) -* run&: Background Execution. - (line 34) -* running: Starting. (line 6) -* running and debugging Sparclet programs: Sparclet Execution. - (line 6) -* running programs backward: Reverse Execution. (line 6) -* running VxWorks tasks: VxWorks Attach. (line 6) -* running, on Sparclet: Sparclet. (line 28) -* rwatch: Set Watchpoints. (line 64) -* s (SingleKey TUI key): TUI Single Key Mode. (line 28) -* s (step): Continuing and Stepping. - (line 46) -* S packet: Packets. (line 304) -* s packet: Packets. (line 298) -* save breakpoints: Save Breakpoints. (line 9) -* save breakpoints to a file for future sessions: Save Breakpoints. - (line 9) -* save command history: Command History. (line 36) -* save GDB output to a file: Logging Output. (line 6) -* save gdb-index: Index Files. (line 19) -* save tracepoints: save tracepoints. (line 6) -* save tracepoints for future sessions: save tracepoints. (line 6) -* save-tracepoints: save tracepoints. (line 6) -* scheduler locking mode: All-Stop Mode. (line 37) -* scope: M2 Scope. (line 6) -* scripting commands: Command Files. (line 6) -* scripting with python: Python. (line 6) -* sdireset: M32R/D. (line 44) -* sdistatus: M32R/D. (line 47) -* SDS protocol: PowerPC Embedded. (line 80) -* sds, a command: PowerPC Embedded. (line 91) -* search: Search. (line 9) -* search for a thread: Threads. (line 142) -* search path for libthread_db: Threads. (line 177) -* search_memory on Inferior: Inferiors In Python. (line 58) -* searching memory: Searching Memory. (line 6) -* searching memory, in remote debugging: General Query Packets. - (line 293) -* searching source files: Search. (line 6) -* section: Files. (line 182) -* section offsets, remote request: General Query Packets. - (line 182) -* segment descriptor tables: DJGPP Native. (line 24) -* select Ctrl-C, BREAK or BREAK-g: Remote Configuration. - (line 85) -* select on Frame: Frames In Python. (line 108) -* select trace snapshot: tfind. (line 6) -* select-frame: Frames. (line 51) -* selected frame: Stack. (line 19) -* selected_frame: Frames In Python. (line 23) -* selected_thread: Threads In Python. (line 14) -* selecting frame silently: Frames. (line 51) -* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 27) -* send command to remote monitor: Connecting. (line 105) -* send command to simulator: Embedded Processors. (line 9) -* send interrupt-sequence on start: Remote Configuration. - (line 98) -* send PMON command: MIPS Embedded. (line 132) -* send rights, GNU Hurd: Hurd Native. (line 85) -* sending files to remote systems: File Transfer. (line 6) -* separate debugging information files: Separate Debug Files. - (line 6) -* sequence-id, for GDB remote: Overview. (line 29) -* serial connections, debugging: Debugging Output. (line 140) -* serial line, target remote: Connecting. (line 18) -* serial protocol, GDB remote: Overview. (line 14) -* server prefix: Server Prefix. (line 6) -* server, command prefix: Command History. (line 20) -* set: Help. (line 107) -* set ABI for MIPS: MIPS. (line 32) -* set ada trust-PAD-over-XVS: Ada Glitches. (line 43) -* set annotate: Annotations Overview. - (line 29) -* set architecture: Targets. (line 21) -* set args: Arguments. (line 21) -* set arm: ARM. (line 18) -* set auto-load-scripts: Auto-loading. (line 23) -* set auto-solib-add: Files. (line 303) -* set backtrace: Backtrace. (line 104) -* set basenames-may-differ: Files. (line 517) -* set board-address: M32R/D. (line 21) -* set breakpoint always-inserted: Set Breaks. (line 314) -* set breakpoint auto-hw: Set Breaks. (line 294) -* set breakpoint pending: Set Breaks. (line 263) -* set breakpoints in many functions: Set Breaks. (line 92) -* set breakpoints on all functions: Set Breaks. (line 112) -* set can-use-hw-watchpoints: Set Watchpoints. (line 101) -* set case-sensitive: Symbols. (line 27) -* set charset: Character Sets. (line 46) -* set check range: Range Checking. (line 34) -* set check type: Type Checking. (line 42) -* set circular-trace-buffer: Starting and Stopping Trace Experiments. - (line 87) -* set coerce-float-to-double: ABI. (line 41) -* set com1base: DJGPP Native. (line 125) -* set com1irq: DJGPP Native. (line 125) -* set com2base: DJGPP Native. (line 125) -* set com2irq: DJGPP Native. (line 125) -* set com3base: DJGPP Native. (line 125) -* set com3irq: DJGPP Native. (line 125) -* set com4base: DJGPP Native. (line 125) -* set com4irq: DJGPP Native. (line 125) -* set complaints: Messages/Warnings. (line 29) -* set confirm: Messages/Warnings. (line 50) -* set cp-abi: ABI. (line 53) -* set cygwin-exceptions: Cygwin Native. (line 42) -* set data-directory: Data Files. (line 12) -* set dcache line-size: Caching Remote Data. (line 48) -* set dcache size: Caching Remote Data. (line 45) -* set debug: Debugging Output. (line 18) -* set debug darwin: Darwin. (line 9) -* set debug hppa: HPPA. (line 10) -* set debug libthread-db: Threads. (line 212) -* set debug mach-o: Darwin. (line 16) -* set debug mips: MIPS. (line 81) -* set debug monitor: Target Commands. (line 108) -* set debug nto-debug: Neutrino. (line 9) -* set debug-file-directory: Separate Debug Files. - (line 68) -* set debugevents: Cygwin Native. (line 71) -* set debugexceptions: Cygwin Native. (line 82) -* set debugexec: Cygwin Native. (line 78) -* set debugmemory: Cygwin Native. (line 86) -* set default-collect: Tracepoint Actions. (line 114) -* set demangle-style: Print Settings. (line 296) -* set detach-on-fork: Forks. (line 55) -* set directories: Source Path. (line 120) -* set disable-randomization: Starting. (line 136) -* set disassemble-next-line: Machine Code. (line 139) -* set disassembly-flavor: Machine Code. (line 127) -* set disconnected-tracing: Starting and Stopping Trace Experiments. - (line 48) -* set displaced-stepping: Maintenance Commands. - (line 56) -* set download-path: M32R/D. (line 15) -* set editing: Editing. (line 15) -* set endian: Byte Order. (line 13) -* set environment: Environment. (line 39) -* set exceptions, Hurd command: Hurd Native. (line 40) -* set exec-direction: Reverse Execution. (line 83) -* set exec-done-display: Debugging Output. (line 11) -* set exec-wrapper: Starting. (line 111) -* set extension-language: Show. (line 30) -* set fast tracepoint: Create and Delete Tracepoints. - (line 40) -* set follow-exec-mode: Forks. (line 101) -* set follow-fork-mode: Forks. (line 35) -* set gnutarget: Target Commands. (line 28) -* set hash, for remote monitors: Target Commands. (line 99) -* set height: Screen Size. (line 21) -* set history expansion: Command History. (line 65) -* set history filename: Command History. (line 26) -* set history save: Command History. (line 36) -* set history size: Command History. (line 45) -* set host-charset: Character Sets. (line 33) -* set inferior controlling terminal: Input/Output. (line 44) -* set inferior-tty: Input/Output. (line 49) -* set input-radix: Numbers. (line 14) -* set interactive-mode: Other Misc Settings. (line 6) -* set language: Manually. (line 9) -* set libthread-db-search-path: Threads. (line 177) -* set listsize: List. (line 33) -* set logging: Logging Output. (line 9) -* set mach-exceptions: Darwin. (line 27) -* set max-user-call-depth: Define. (line 76) -* set mem inaccessible-by-default: Memory Region Attributes. - (line 130) -* set mips abi: MIPS. (line 32) -* set mips mask-address: MIPS. (line 61) -* set mipsfpu: MIPS Embedded. (line 60) -* set monitor-prompt, MIPS remote: MIPS Embedded. (line 107) -* set monitor-warnings, MIPS remote: MIPS Embedded. (line 123) -* set multiple-symbols: Ambiguous Expressions. - (line 50) -* set new-console: Cygwin Native. (line 54) -* set new-group: Cygwin Native. (line 63) -* set non-stop: Non-Stop Mode. (line 38) -* set opaque-type-resolution: Symbols. (line 241) -* set osabi: ABI. (line 11) -* set output-radix: Numbers. (line 31) -* set overload-resolution: Debugging C Plus Plus. - (line 48) -* set pagination: Screen Size. (line 38) -* set powerpc: PowerPC Embedded. (line 48) -* set print: Print Settings. (line 11) -* set print frame-arguments: Print Settings. (line 135) -* set print inferior-events: Inferiors and Programs. - (line 117) -* set print symbol-loading: Symbols. (line 259) -* set print thread-events: Threads. (line 156) -* set processor: Targets. (line 31) -* set procfs-file: SVR4 Process Information. - (line 59) -* set procfs-trace: SVR4 Process Information. - (line 53) -* set prompt: Prompt. (line 16) -* set radix: Numbers. (line 44) -* set ravenscar task-switching off: Ravenscar Profile. (line 14) -* set ravenscar task-switching on: Ravenscar Profile. (line 10) -* set rdiheartbeat: ARM. (line 112) -* set rdiromatzero: ARM. (line 102) -* set record insn-number-max: Process Record and Replay. - (line 89) -* set record memory-query: Process Record and Replay. - (line 123) -* set record stop-at-limit: Process Record and Replay. - (line 109) -* set remote: Remote Configuration. - (line 6) -* set remote system-call-allowed: system. (line 38) -* set remote-mips64-transfers-32bit-regs: MIPS. (line 71) -* set remotecache: Caching Remote Data. (line 18) -* set remoteflow: Remote Configuration. - (line 41) -* set retransmit-timeout: MIPS Embedded. (line 83) -* set rstack_high_address: A29K. (line 6) -* set schedule-multiple: All-Stop Mode. (line 66) -* set script-extension: Extending GDB. (line 19) -* set sdstimeout: PowerPC Embedded. (line 84) -* set server-address: M32R/D. (line 27) -* set sh calling-convention: Super-H. (line 12) -* set shell: Cygwin Native. (line 90) -* set signal-thread: Hurd Native. (line 21) -* set signals, Hurd command: Hurd Native. (line 11) -* set sigs, Hurd command: Hurd Native. (line 11) -* set sigthread: Hurd Native. (line 21) -* set solib-absolute-prefix: Files. (line 374) -* set solib-search-path: Files. (line 443) -* set spu: SPU. (line 39) -* set stack-cache: Caching Remote Data. (line 26) -* set static tracepoint: Create and Delete Tracepoints. - (line 51) -* set step-mode: Continuing and Stepping. - (line 92) -* set stop-on-solib-events: Files. (line 351) -* set stopped, Hurd command: Hurd Native. (line 32) -* set struct-convention: i386. (line 7) -* set substitute-path: Source Path. (line 127) -* set symbol-reloading: Symbols. (line 224) -* set syn-garbage-limit, MIPS remote: MIPS Embedded. (line 98) -* set sysroot: Files. (line 374) -* set target-async: Background Execution. - (line 17) -* set target-charset: Character Sets. (line 28) -* set target-file-system-kind (unix|dos-based|auto): Files. (line 457) -* set target-wide-charset: Character Sets. (line 61) -* set task, Hurd commands: Hurd Native. (line 49) -* set tcp: Remote Configuration. - (line 107) -* set tdesc filename: Retrieving Descriptions. - (line 18) -* set thread, Hurd command: Hurd Native. (line 91) -* set timeout: MIPS Embedded. (line 83) -* set trace-commands: Messages/Warnings. (line 67) -* set tracepoint: Create and Delete Tracepoints. - (line 6) -* set trust-readonly-sections: Files. (line 258) -* set tui active-border-mode: TUI Configuration. (line 24) -* set tui border-kind: TUI Configuration. (line 9) -* set tui border-mode: TUI Configuration. (line 23) -* set unwind-on-terminating-exception: Calling. (line 46) -* set unwindonsignal: Calling. (line 35) -* set variable: Assignment. (line 16) -* set verbose: Messages/Warnings. (line 15) -* set watchdog: Maintenance Commands. - (line 357) -* set width: Screen Size. (line 21) -* set write: Patching. (line 15) -* set-mark (C-@): Miscellaneous Commands. - (line 32) -* set_debug_traps: Stub Contents. (line 10) -* set_doc: Parameters In Python. - (line 54) -* setting variables: Assignment. (line 6) -* setting watchpoints: Set Watchpoints. (line 6) -* SH: Remote Stub. (line 63) -* sh-stub.c: Remote Stub. (line 63) -* share: Files. (line 332) -* shared libraries: Files. (line 281) -* shared library events, remote reply: Stop Reply Packets. (line 56) -* sharedlibrary: Files. (line 332) -* shell: Shell Commands. (line 10) -* shell escape: Shell Commands. (line 10) -* show: Help. (line 112) -* show ada trust-PAD-over-XVS: Ada Glitches. (line 43) -* show all convenience functions: Convenience Vars. (line 112) -* show all user variables: Convenience Vars. (line 37) -* show annotate: Annotations Overview. - (line 34) -* show architecture: Targets. (line 21) -* show args: Arguments. (line 28) -* show arm: ARM. (line 22) -* show auto-load-scripts: Auto-loading. (line 26) -* show auto-solib-add: Files. (line 320) -* show backtrace: Backtrace. (line 111) -* show basenames-may-differ: Files. (line 520) -* show board-address: M32R/D. (line 24) -* show breakpoint always-inserted: Set Breaks. (line 314) -* show breakpoint auto-hw: Set Breaks. (line 294) -* show breakpoint pending: Set Breaks. (line 263) -* show can-use-hw-watchpoints: Set Watchpoints. (line 104) -* show case-sensitive: Symbols. (line 40) -* show charset: Character Sets. (line 52) -* show check range: Range Checking. (line 34) -* show check type: Type Checking. (line 42) -* show circular-trace-buffer: Starting and Stopping Trace Experiments. - (line 94) -* show coerce-float-to-double: ABI. (line 50) -* show com1base: DJGPP Native. (line 137) -* show com1irq: DJGPP Native. (line 137) -* show com2base: DJGPP Native. (line 137) -* show com2irq: DJGPP Native. (line 137) -* show com3base: DJGPP Native. (line 137) -* show com3irq: DJGPP Native. (line 137) -* show com4base: DJGPP Native. (line 137) -* show com4irq: DJGPP Native. (line 137) -* show commands: Command History. (line 78) -* show complaints: Messages/Warnings. (line 35) -* show confirm: Messages/Warnings. (line 58) -* show convenience: Convenience Vars. (line 37) -* show copying: Help. (line 136) -* show cp-abi: ABI. (line 53) -* show cygwin-exceptions: Cygwin Native. (line 50) -* show data-directory: Data Files. (line 16) -* show dcache line-size: Caching Remote Data. (line 56) -* show dcache size: Caching Remote Data. (line 52) -* show debug: Debugging Output. (line 22) -* show debug darwin: Darwin. (line 13) -* show debug libthread-db: Threads. (line 212) -* show debug mach-o: Darwin. (line 23) -* show debug mips: MIPS. (line 85) -* show debug monitor: Target Commands. (line 112) -* show debug nto-debug: Neutrino. (line 13) -* show debug-file-directory: Separate Debug Files. - (line 73) -* show default-collect: Tracepoint Actions. (line 123) -* show detach-on-fork: Forks. (line 71) -* show directories: Source Path. (line 124) -* show disassemble-next-line: Machine Code. (line 139) -* show disassembly-flavor: Machine Code. (line 136) -* show disconnected-tracing: Starting and Stopping Trace Experiments. - (line 55) -* show displaced-stepping: Maintenance Commands. - (line 56) -* show download-path: M32R/D. (line 18) -* show editing: Editing. (line 22) -* show environment: Environment. (line 33) -* show exceptions, Hurd command: Hurd Native. (line 46) -* show exec-done-display: Debugging Output. (line 14) -* show follow-fork-mode: Forks. (line 49) -* show gnutarget: Target Commands. (line 40) -* show hash, for remote monitors: Target Commands. (line 105) -* show height: Screen Size. (line 21) -* show history: Command History. (line 70) -* show host-charset: Character Sets. (line 55) -* show inferior-tty: Input/Output. (line 52) -* show input-radix: Numbers. (line 36) -* show interactive-mode: Other Misc Settings. (line 21) -* show language: Show. (line 10) -* show last commands: Command History. (line 78) -* show libthread-db-search-path: Threads. (line 209) -* show listsize: List. (line 37) -* show logging: Logging Output. (line 26) -* show mach-exceptions: Darwin. (line 34) -* show max-user-call-depth: Define. (line 76) -* show mem inaccessible-by-default: Memory Region Attributes. - (line 136) -* show mips abi: MIPS. (line 54) -* show mips mask-address: MIPS. (line 67) -* show mipsfpu: MIPS Embedded. (line 60) -* show monitor-prompt, MIPS remote: MIPS Embedded. (line 119) -* show monitor-warnings, MIPS remote: MIPS Embedded. (line 129) -* show multiple-symbols: Ambiguous Expressions. - (line 70) -* show new-console: Cygwin Native. (line 59) -* show new-group: Cygwin Native. (line 68) -* show non-stop: Non-Stop Mode. (line 42) -* show opaque-type-resolution: Symbols. (line 256) -* show osabi: ABI. (line 11) -* show output-radix: Numbers. (line 39) -* show overload-resolution: Debugging C Plus Plus. - (line 65) -* show pagination: Screen Size. (line 44) -* show paths: Environment. (line 29) -* show print: Print Settings. (line 39) -* show print inferior-events: Inferiors and Programs. - (line 125) -* show print symbol-loading: Symbols. (line 269) -* show print thread-events: Threads. (line 166) -* show processor: Targets. (line 31) -* show procfs-file: SVR4 Process Information. - (line 64) -* show procfs-trace: SVR4 Process Information. - (line 56) -* show prompt: Prompt. (line 19) -* show radix: Numbers. (line 44) -* show ravenscar task-switching: Ravenscar Profile. (line 22) -* show rdiheartbeat: ARM. (line 117) -* show rdiromatzero: ARM. (line 109) -* show record insn-number-max: Process Record and Replay. - (line 106) -* show record memory-query: Process Record and Replay. - (line 134) -* show record stop-at-limit: Process Record and Replay. - (line 120) -* show remote: Remote Configuration. - (line 6) -* show remote system-call-allowed: system. (line 42) -* show remote-mips64-transfers-32bit-regs: MIPS. (line 77) -* show remotecache: Caching Remote Data. (line 23) -* show remoteflow: Remote Configuration. - (line 45) -* show retransmit-timeout: MIPS Embedded. (line 83) -* show rstack_high_address: A29K. (line 17) -* show script-extension: Extending GDB. (line 19) -* show sdstimeout: PowerPC Embedded. (line 88) -* show server-address: M32R/D. (line 31) -* show sh calling-convention: Super-H. (line 25) -* show shell: Cygwin Native. (line 94) -* show signal-thread: Hurd Native. (line 28) -* show signals, Hurd command: Hurd Native. (line 17) -* show sigs, Hurd command: Hurd Native. (line 17) -* show sigthread: Hurd Native. (line 28) -* show solib-search-path: Files. (line 454) -* show spu: SPU. (line 44) -* show stack-cache: Caching Remote Data. (line 31) -* show stop-on-solib-events: Files. (line 357) -* show stopped, Hurd command: Hurd Native. (line 37) -* show struct-convention: i386. (line 15) -* show substitute-path: Source Path. (line 164) -* show symbol-reloading: Symbols. (line 238) -* show syn-garbage-limit, MIPS remote: MIPS Embedded. (line 103) -* show sysroot: Files. (line 440) -* show target-async: Background Execution. - (line 21) -* show target-charset: Character Sets. (line 58) -* show target-file-system-kind: Files. (line 457) -* show target-wide-charset: Character Sets. (line 67) -* show task, Hurd commands: Hurd Native. (line 57) -* show tcp: Remote Configuration. - (line 107) -* show tdesc filename: Retrieving Descriptions. - (line 25) -* show thread, Hurd command: Hurd Native. (line 101) -* show timeout: MIPS Embedded. (line 83) -* show unwind-on-terminating-exception: Calling. (line 54) -* show unwindonsignal: Calling. (line 42) -* show user: Define. (line 70) -* show values: Value History. (line 47) -* show verbose: Messages/Warnings. (line 21) -* show version: Help. (line 126) -* show warranty: Help. (line 140) -* show width: Screen Size. (line 21) -* show write: Patching. (line 26) -* show-all-if-ambiguous: Readline Init File Syntax. - (line 164) -* show-all-if-unmodified: Readline Init File Syntax. - (line 170) -* show_doc: Parameters In Python. - (line 60) -* si (stepi): Continuing and Stepping. - (line 190) -* signal: Signaling. (line 6) -* signal annotation: Annotations for Running. - (line 42) -* signal-name annotation: Annotations for Running. - (line 22) -* signal-name-end annotation: Annotations for Running. - (line 22) -* signal-string annotation: Annotations for Running. - (line 22) -* signal-string-end annotation: Annotations for Running. - (line 22) -* signalled annotation: Annotations for Running. - (line 22) -* signals: Signals. (line 6) -* SIGQUIT signal, dump core of GDB: Maintenance Commands. - (line 99) -* silent <1>: Break Commands. (line 43) -* silent: Breakpoints In Python. - (line 79) -* sim: Z8000. (line 15) -* sim, a command: Embedded Processors. (line 13) -* simulator, Z8000: Z8000. (line 6) -* size of remote memory accesses: Packets. (line 228) -* size of screen: Screen Size. (line 6) -* sizeof: Types In Python. (line 28) -* snapshot of a process: Checkpoint/Restart. (line 6) -* software watchpoints: Set Watchpoints. (line 31) -* solib_name: Basic Python. (line 154) -* source: Command Files. (line 17) -* source annotation: Source Annotations. (line 6) -* source file and line of a symbol: Print Settings. (line 51) -* source line and its code address: Machine Code. (line 6) -* source path: Source Path. (line 6) -* Sparc: Remote Stub. (line 66) -* sparc-stub.c: Remote Stub. (line 66) -* sparcl-stub.c: Remote Stub. (line 69) -* Sparclet: Sparclet. (line 6) -* SparcLite: Remote Stub. (line 69) -* Special Fortran commands: Special Fortran Commands. - (line 6) -* specifying location: Specify Location. (line 6) -* spr: OpenRISC 1000. (line 33) -* SPU: SPU. (line 6) -* SSE registers (x86): Registers. (line 71) -* stack frame: Frames. (line 6) -* stack on Alpha: MIPS. (line 6) -* stack on MIPS: MIPS. (line 6) -* stack pointer register: Registers. (line 26) -* stacking targets: Active Targets. (line 6) -* standard registers: Registers. (line 26) -* start <1>: Blocks In Python. (line 36) -* start: Starting. (line 78) -* start a new trace experiment: Starting and Stopping Trace Experiments. - (line 6) -* start-kbd-macro (C-x (): Keyboard Macros. (line 6) -* starting: Starting. (line 6) -* starting annotation: Annotations for Running. - (line 6) -* startup code, and backtrace: Backtrace. (line 93) -* stat, file-i/o system call: stat/fstat. (line 6) -* static members of C++ objects: Print Settings. (line 342) -* static members of Pascal objects: Print Settings. (line 353) -* static tracepoints: Set Tracepoints. (line 28) -* static tracepoints, in remote protocol: General Query Packets. - (line 563) -* static tracepoints, setting: Create and Delete Tracepoints. - (line 51) -* status of trace data collection: Starting and Stopping Trace Experiments. - (line 20) -* status output in GDB/MI: GDB/MI Output Syntax. - (line 94) -* STDERR: Basic Python. (line 132) -* STDLOG: Basic Python. (line 114) -* STDOUT: Basic Python. (line 129) -* step: Continuing and Stepping. - (line 46) -* step&: Background Execution. - (line 41) -* stepi: Continuing and Stepping. - (line 190) -* stepi&: Background Execution. - (line 44) -* stepping: Continuing and Stepping. - (line 6) -* stepping into functions with no line info: Continuing and Stepping. - (line 93) -* stop a running trace experiment: Starting and Stopping Trace Experiments. - (line 12) -* stop on C++ exceptions: Set Catchpoints. (line 13) -* stop on gdb.Breakpoint: Breakpoints In Python. - (line 25) -* stop reply packets: Stop Reply Packets. (line 6) -* stop, a pseudo-command: Hooks. (line 21) -* stop_signal: Events In Python. (line 91) -* stopped threads: Thread Stops. (line 6) -* stopping annotation: Annotations for Running. - (line 6) -* strace: Create and Delete Tracepoints. - (line 51) -* stream records in GDB/MI: GDB/MI Stream Records. - (line 6) -* string on Value: Values From Inferior. - (line 139) -* strip_typedefs on Type: Types In Python. (line 118) -* struct return convention: i386. (line 7) -* struct stat, in file-i/o protocol: struct stat. (line 6) -* struct timeval, in file-i/o protocol: struct timeval. (line 6) -* struct user contents: OS Information. (line 9) -* struct/union returned in registers: i386. (line 7) -* structure field name completion: Completion. (line 96) -* stub example, remote debugging: Remote Stub. (line 6) -* stupid questions: Messages/Warnings. (line 50) -* Super-H: Super-H. (line 6) -* superblock: Blocks In Python. (line 48) -* supported packets, remote query: General Query Packets. - (line 328) -* switch on InferiorThread: Threads In Python. (line 51) -* switching threads: Threads. (line 6) -* switching threads automatically: All-Stop Mode. (line 28) -* symbol decoding style, C++: Print Settings. (line 296) -* symbol dump: Symbols. (line 272) -* symbol from address: Symbols. (line 54) -* symbol lookup, remote request: General Query Packets. - (line 567) -* symbol names: Symbols. (line 14) -* symbol table: Files. (line 6) -* symbol tables in python: Symbol Tables In Python. - (line 6) -* symbol tables, listing GDB's internal: Symbols. (line 291) -* symbol, source file and line: Print Settings. (line 51) -* symbol-file: Files. (line 45) -* SYMBOL_FUNCTIONS_DOMAIN: Symbols In Python. (line 117) -* SYMBOL_LABEL_DOMAIN: Symbols In Python. (line 110) -* SYMBOL_LOC_ARG: Symbols In Python. (line 139) -* SYMBOL_LOC_BLOCK: Symbols In Python. (line 160) -* SYMBOL_LOC_COMPUTED: Symbols In Python. (line 174) -* SYMBOL_LOC_CONST: Symbols In Python. (line 130) -* SYMBOL_LOC_CONST_BYTES: Symbols In Python. (line 163) -* SYMBOL_LOC_LOCAL: Symbols In Python. (line 153) -* SYMBOL_LOC_OPTIMIZED_OUT: Symbols In Python. (line 171) -* SYMBOL_LOC_REF_ARG: Symbols In Python. (line 143) -* SYMBOL_LOC_REGISTER: Symbols In Python. (line 136) -* SYMBOL_LOC_REGPARM_ADDR: Symbols In Python. (line 148) -* SYMBOL_LOC_STATIC: Symbols In Python. (line 133) -* SYMBOL_LOC_TYPEDEF: Symbols In Python. (line 156) -* SYMBOL_LOC_UNDEF: Symbols In Python. (line 128) -* SYMBOL_LOC_UNRESOLVED: Symbols In Python. (line 166) -* SYMBOL_STRUCT_DOMAIN: Symbols In Python. (line 107) -* SYMBOL_TYPES_DOMAIN: Symbols In Python. (line 120) -* SYMBOL_UNDEF_DOMAIN: Symbols In Python. (line 100) -* SYMBOL_VAR_DOMAIN: Symbols In Python. (line 103) -* SYMBOL_VARIABLES_DOMAIN: Symbols In Python. (line 113) -* symbols in python: Symbols In Python. (line 6) -* symbols, reading from relocatable object files: Files. (line 132) -* symbols, reading immediately: Files. (line 90) -* symtab <1>: Symbols In Python. (line 53) -* symtab: Symbol Tables In Python. - (line 17) -* synchronize with remote MIPS target: MIPS Embedded. (line 98) -* syscall DSO: Files. (line 162) -* sysinfo: DJGPP Native. (line 19) -* system calls and thread breakpoints: Interrupted System Calls. - (line 6) -* system root, alternate: Files. (line 374) -* system, file-i/o system call: system. (line 6) -* system-wide init file: System-wide configuration. - (line 6) -* T packet: Packets. (line 316) -* t packet: Packets. (line 311) -* T packet reply: Stop Reply Packets. (line 22) -* tabset: TUI Commands. (line 84) -* tag: Types In Python. (line 33) -* target: Target Commands. (line 49) -* target architecture: Targets. (line 17) -* target array: MIPS Embedded. (line 49) -* target byte order: Byte Order. (line 6) -* target character set: Character Sets. (line 6) -* target dbug: M68K. (line 9) -* target ddb PORT: MIPS Embedded. (line 41) -* target debugging info: Debugging Output. (line 165) -* target descriptions: Target Descriptions. (line 6) -* target descriptions, ARM features: ARM Features. (line 6) -* target descriptions, i386 features: i386 Features. (line 6) -* target descriptions, inclusion: Target Description Format. - (line 54) -* target descriptions, M68K features: M68K Features. (line 6) -* target descriptions, MIPS features: MIPS Features. (line 6) -* target descriptions, PowerPC features: PowerPC Features. (line 6) -* target descriptions, predefined types: Predefined Target Types. - (line 6) -* target descriptions, standard features: Standard Target Features. - (line 6) -* target descriptions, XML format: Target Description Format. - (line 6) -* target dink32: PowerPC Embedded. (line 69) -* target jtag: OpenRISC 1000. (line 9) -* target lsi PORT: MIPS Embedded. (line 44) -* target m32r: M32R/D. (line 6) -* target m32rsdi: M32R/D. (line 9) -* target mips PORT: MIPS Embedded. (line 14) -* target on Type: Types In Python. (line 122) -* target op50n: PA. (line 6) -* target output in GDB/MI: GDB/MI Output Syntax. - (line 110) -* target pmon PORT: MIPS Embedded. (line 38) -* target ppcbug: PowerPC Embedded. (line 72) -* target ppcbug1: PowerPC Embedded. (line 73) -* target r3900: MIPS Embedded. (line 46) -* target rdi: ARM. (line 6) -* target rdp: ARM. (line 11) -* target record: Process Record and Replay. - (line 38) -* target remote: Connecting. (line 11) -* target sds: PowerPC Embedded. (line 77) -* target sim, with Z8000: Z8000. (line 15) -* target sparclite: Sparclite. (line 6) -* target stack description: Maintenance Commands. - (line 236) -* target tfile: Trace Files. (line 22) -* target vxworks: VxWorks. (line 6) -* target w89k: PA. (line 9) -* target_charset: Basic Python. (line 143) -* target_wide_charset: Basic Python. (line 148) -* task: Breakpoints In Python. - (line 92) -* task (Ada): Ada Tasks. (line 105) -* task attributes (GNU Hurd): Hurd Native. (line 49) -* task breakpoints, in Ada: Ada Tasks. (line 135) -* task exception port, GNU Hurd: Hurd Native. (line 68) -* task suspend count: Hurd Native. (line 60) -* task switching with program using Ravenscar Profile: Ravenscar Profile. - (line 10) -* tbreak: Set Breaks. (line 55) -* TCP port, target remote: Connecting. (line 29) -* tdump: tdump. (line 6) -* template_argument on Type: Types In Python. (line 137) -* terminal: Input/Output. (line 6) -* teval (tracepoints): Tracepoint Actions. (line 89) -* Text User Interface: TUI. (line 6) -* tfile: Trace Files. (line 22) -* tfind: tfind. (line 6) -* thbreak: Set Breaks. (line 82) -* this, inside C++ member functions: C Plus Plus Expressions. - (line 22) -* thread: Breakpoints In Python. - (line 87) -* thread apply: Threads. (line 122) -* thread attributes info, remote request: General Query Packets. - (line 612) -* thread breakpoints: Thread-Specific Breakpoints. - (line 10) -* thread breakpoints and system calls: Interrupted System Calls. - (line 6) -* thread default settings, GNU Hurd: Hurd Native. (line 131) -* thread find: Threads. (line 142) -* thread identifier (GDB): Threads. (line 63) -* thread identifier (system): Threads. (line 51) -* thread info (Solaris): Threads. (line 98) -* thread information, remote request: General Query Packets. - (line 209) -* thread list format: Thread List Format. (line 6) -* thread name: Threads. (line 131) -* thread number: Threads. (line 63) -* thread properties, GNU Hurd: Hurd Native. (line 91) -* thread suspend count, GNU Hurd: Hurd Native. (line 110) -* thread THREADNO: Threads. (line 100) -* THREAD-ID, in remote protocol: Packets. (line 20) -* threads and watchpoints: Set Watchpoints. (line 165) -* threads in python: Threads In Python. (line 6) -* threads of execution: Threads. (line 6) -* threads on Inferior: Inferiors In Python. (line 40) -* threads, automatic switching: All-Stop Mode. (line 28) -* threads, continuing: Thread Stops. (line 6) -* threads, stopped: Thread Stops. (line 6) -* time of command execution: Maintenance Commands. - (line 328) -* timeout for commands: Maintenance Commands. - (line 357) -* timeout for serial communications: Remote Configuration. - (line 65) -* timeout, for remote target connection: Remote Configuration. - (line 123) -* timeout, MIPS protocol: MIPS Embedded. (line 83) -* timestampping debugging info: Debugging Output. (line 176) -* tload, M32R: M32R/D. (line 39) -* to_string on pretty printer: Pretty Printing API. (line 54) -* trace: Create and Delete Tracepoints. - (line 6) -* trace experiment, status of: Starting and Stopping Trace Experiments. - (line 20) -* trace file format: Trace File Format. (line 6) -* trace files: Trace Files. (line 6) -* trace state variable value, remote request: Tracepoint Packets. - (line 276) -* trace state variables: Trace State Variables. - (line 6) -* traceback: Backtrace. (line 6) -* traceframe info format: Traceframe Info Format. - (line 6) -* tracepoint actions: Tracepoint Actions. (line 6) -* tracepoint conditions: Tracepoint Conditions. - (line 6) -* tracepoint data, display: tdump. (line 6) -* tracepoint deletion: Create and Delete Tracepoints. - (line 101) -* tracepoint number: Create and Delete Tracepoints. - (line 98) -* tracepoint packets: Tracepoint Packets. (line 6) -* tracepoint pass count: Tracepoint Passcounts. - (line 6) -* tracepoint restrictions: Tracepoint Restrictions. - (line 6) -* tracepoint variables: Tracepoint Variables. - (line 6) -* tracepoints: Tracepoints. (line 6) -* tracepoints support in gdbserver: Server. (line 207) -* trailing underscore, in Fortran symbols: Fortran. (line 9) -* translating between character sets: Character Sets. (line 6) -* transpose-chars (C-t): Commands For Text. (line 30) -* transpose-words (M-t): Commands For Text. (line 36) -* tsave: Trace Files. (line 12) -* tstart: Starting and Stopping Trace Experiments. - (line 6) -* tstatus: Starting and Stopping Trace Experiments. - (line 20) -* tstop: Starting and Stopping Trace Experiments. - (line 12) -* tty: Input/Output. (line 23) -* TUI: TUI. (line 6) -* TUI commands: TUI Commands. (line 6) -* TUI configuration variables: TUI Configuration. (line 6) -* TUI key bindings: TUI Keys. (line 6) -* tui reg: TUI Commands. (line 61) -* TUI single key mode: TUI Single Key Mode. (line 6) -* tvariable: Trace State Variables. - (line 26) -* type <1>: Symbols In Python. (line 48) -* type <2>: Values From Inferior. - (line 55) -* type <3>: Lazy Strings In Python. - (line 44) -* type: Breakpoints In Python. - (line 107) -* type casting memory: Expressions. (line 43) -* type chain of a data type: Maintenance Commands. - (line 248) -* type checking: Checks. (line 31) -* type conversions in C++: C Plus Plus Expressions. - (line 27) -* type on Frame: Frames In Python. (line 48) -* TYPE_CODE_ARRAY: Types In Python. (line 155) -* TYPE_CODE_BITSTRING: Types In Python. (line 193) -* TYPE_CODE_BOOL: Types In Python. (line 214) -* TYPE_CODE_CHAR: Types In Python. (line 211) -* TYPE_CODE_COMPLEX: Types In Python. (line 217) -* TYPE_CODE_DECFLOAT: Types In Python. (line 226) -* TYPE_CODE_ENUM: Types In Python. (line 164) -* TYPE_CODE_ERROR: Types In Python. (line 196) -* TYPE_CODE_FLAGS: Types In Python. (line 167) -* TYPE_CODE_FLT: Types In Python. (line 176) -* TYPE_CODE_FUNC: Types In Python. (line 170) -* TYPE_CODE_INT: Types In Python. (line 173) -* TYPE_CODE_INTERNAL_FUNCTION: Types In Python. (line 229) -* TYPE_CODE_MEMBERPTR: Types In Python. (line 205) -* TYPE_CODE_METHOD: Types In Python. (line 199) -* TYPE_CODE_METHODPTR: Types In Python. (line 202) -* TYPE_CODE_NAMESPACE: Types In Python. (line 223) -* TYPE_CODE_PTR: Types In Python. (line 152) -* TYPE_CODE_RANGE: Types In Python. (line 185) -* TYPE_CODE_REF: Types In Python. (line 208) -* TYPE_CODE_SET: Types In Python. (line 182) -* TYPE_CODE_STRING: Types In Python. (line 188) -* TYPE_CODE_STRUCT: Types In Python. (line 158) -* TYPE_CODE_TYPEDEF: Types In Python. (line 220) -* TYPE_CODE_UNION: Types In Python. (line 161) -* TYPE_CODE_VOID: Types In Python. (line 179) -* types in Python: Types In Python. (line 6) -* u (SingleKey TUI key): TUI Single Key Mode. (line 31) -* u (until): Continuing and Stepping. - (line 118) -* UDP port, target remote: Connecting. (line 49) -* undisplay: Auto Display. (line 45) -* undo (C-_ or C-x C-u): Miscellaneous Commands. - (line 22) -* union field name completion: Completion. (line 96) -* unions in structures, printing: Print Settings. (line 236) -* universal-argument (): Numeric Arguments. (line 10) -* unix-filename-rubout (): Commands For Killing. - (line 32) -* unix-line-discard (C-u): Commands For Killing. - (line 12) -* unix-word-rubout (C-w): Commands For Killing. - (line 28) -* unknown address, locating: Output Formats. (line 35) -* unlink, file-i/o system call: unlink. (line 6) -* unlinked object files: Files. (line 26) -* unload symbols from shared libraries: Files. (line 341) -* unmap an overlay: Overlay Commands. (line 39) -* unmapped overlays: How Overlays Work. (line 6) -* unqualified on Type: Types In Python. (line 99) -* unset environment: Environment. (line 55) -* unset substitute-path: Source Path. (line 156) -* unset tdesc filename: Retrieving Descriptions. - (line 21) -* unsupported languages: Unsupported Languages. - (line 6) -* until: Continuing and Stepping. - (line 118) -* until&: Background Execution. - (line 59) -* unwind stack in called functions: Calling. (line 35) -* unwind stack in called functions with unhandled exceptions: Calling. - (line 46) -* unwind_stop_reason on Frame: Frames In Python. (line 74) -* up: Selection. (line 35) -* Up: TUI Keys. (line 53) -* up-silently: Selection. (line 64) -* upcase-word (M-u): Commands For Text. (line 41) -* update: TUI Commands. (line 76) -* upload, M32R: M32R/D. (line 34) -* use only software watchpoints: Set Watchpoints. (line 93) -* use_dbt_break: M32R/D. (line 64) -* use_debug_dma: M32R/D. (line 53) -* use_ib_break: M32R/D. (line 61) -* use_mon_code: M32R/D. (line 57) -* user-defined command: Define. (line 6) -* user-defined macros: Macros. (line 52) -* user-defined variables: Convenience Vars. (line 6) -* v (SingleKey TUI key): TUI Single Key Mode. (line 34) -* value: Parameters In Python. - (line 66) -* value history: Value History. (line 6) -* value on LazyString: Lazy Strings In Python. - (line 21) -* values from inferior, with Python: Values From Inferior. - (line 6) -* variable name conflict: Variables. (line 36) -* variable object debugging info: Debugging Output. (line 185) -* variable objects in GDB/MI: GDB/MI Variable Objects. - (line 9) -* variable values, wrong: Variables. (line 58) -* variables, readline: Readline Init File Syntax. - (line 34) -* variables, setting: Assignment. (line 16) -* vAttach packet: Packets. (line 331) -* vCont packet: Packets. (line 351) -* vCont? packet: Packets. (line 393) -* vector unit: Vector Unit. (line 6) -* vector, auxiliary: OS Information. (line 21) -* verbose operation: Messages/Warnings. (line 6) -* verify remote memory image: Memory. (line 123) -* vFile packet: Packets. (line 404) -* vFlashDone packet: Packets. (line 452) -* vFlashErase packet: Packets. (line 408) -* vFlashWrite packet: Packets. (line 430) -* virtual functions (C++) display: Print Settings. (line 364) -* visible: Breakpoints In Python. - (line 112) -* visible-stats: Readline Init File Syntax. - (line 179) -* vKill packet: Packets. (line 460) -* volatile on Type: Types In Python. (line 95) -* vRun packet: Packets. (line 473) -* vStopped packet: Packets. (line 490) -* VTBL display: Print Settings. (line 364) -* VxWorks: VxWorks. (line 6) -* vxworks-timeout: VxWorks. (line 23) -* w (SingleKey TUI key): TUI Single Key Mode. (line 37) -* was_attached: Inferiors In Python. (line 27) -* watch: Set Watchpoints. (line 42) -* watchdog timer: Maintenance Commands. - (line 357) -* watchpoint annotation: Annotations for Running. - (line 50) -* watchpoints: Breakpoints. (line 20) -* watchpoints and threads: Set Watchpoints. (line 165) -* weak alias functions: Calling. (line 58) -* whatis: Symbols. (line 74) -* where: Backtrace. (line 34) -* where to look for shared libraries: Files. (line 369) -* while: Command Files. (line 86) -* while-stepping (tracepoints): Tracepoint Actions. (line 97) -* wild pointer, interpreting: Print Settings. (line 79) -* winheight: TUI Commands. (line 80) -* word completion: Completion. (line 6) -* working directory: Source Path. (line 108) -* working directory (of your program): Working Directory. (line 6) -* working language: Languages. (line 13) -* WP_ACCESS: Breakpoints In Python. - (line 58) -* WP_READ: Breakpoints In Python. - (line 52) -* WP_WRITE: Breakpoints In Python. - (line 55) -* write: Basic Python. (line 104) -* write data into object, remote request: General Query Packets. - (line 781) -* write, file-i/o system call: write. (line 6) -* write_memory on Inferior: Inferiors In Python. (line 51) -* writing a pretty-printer: Writing a Pretty-Printer. - (line 6) -* writing convenience functions: Functions In Python. (line 6) -* writing into corefiles: Patching. (line 6) -* writing into executables: Patching. (line 6) -* wrong values: Variables. (line 58) -* x (examine memory): Memory. (line 9) -* x command, default address: Machine Code. (line 30) -* X packet: Packets. (line 502) -* x(examine), and info line: Machine Code. (line 30) -* Xilinx MicroBlaze: MicroBlaze. (line 6) -* XInclude: Target Description Format. - (line 54) -* XMD, Xilinx Microprocessor Debugger: MicroBlaze. (line 6) -* XML parser debugging: Debugging Output. (line 193) -* yank (C-y): Commands For Killing. - (line 59) -* yank-last-arg (M-. or M-_): Commands For History. - (line 64) -* yank-nth-arg (M-C-y): Commands For History. - (line 55) -* yank-pop (M-y): Commands For Killing. - (line 62) -* yanking text: Readline Killing Commands. - (line 6) -* z packet: Packets. (line 515) -* Z packets: Packets. (line 515) -* Z0 packet: Packets. (line 530) -* z0 packet: Packets. (line 530) -* Z1 packet: Packets. (line 558) -* z1 packet: Packets. (line 558) -* Z2 packet: Packets. (line 580) -* z2 packet: Packets. (line 580) -* z3 packet: Packets. (line 595) -* Z3 packet: Packets. (line 595) -* Z4 packet: Packets. (line 610) -* z4 packet: Packets. (line 610) -* Z8000: Z8000. (line 6) -* Zilog Z8000 simulator: Z8000. (line 6) -* {TYPE}: Expressions. (line 43) - - - -Tag Table: -Node: Top1966 -Node: Summary5144 -Node: Free Software6946 -Node: Contributors12514 -Node: Sample Session20603 -Node: Invocation27445 -Node: Invoking GDB27989 -Node: File Options30302 -Node: Mode Options33039 -Node: Startup40151 -Ref: Startup-Footnote-142930 -Node: Quitting GDB43039 -Node: Shell Commands43936 -Node: Logging Output44778 -Node: Commands45624 -Node: Command Syntax46262 -Node: Completion48428 -Ref: Completion-Footnote-153634 -Node: Help53794 -Node: Running59035 -Node: Compilation60264 -Node: Starting62241 -Node: Arguments71131 -Node: Environment72401 -Node: Working Directory75669 -Node: Input/Output76777 -Node: Attach78748 -Node: Kill Process81215 -Node: Inferiors and Programs82196 -Node: Threads89441 -Node: Forks98604 -Node: Checkpoint/Restart104914 -Ref: Checkpoint/Restart-Footnote-1109443 -Node: Stopping109478 -Node: Breakpoints110637 -Node: Set Breaks114073 -Ref: Set Breaks-Footnote-1130385 -Node: Set Watchpoints130633 -Node: Set Catchpoints139162 -Node: Delete Breaks148358 -Node: Disabling150294 -Node: Conditions153147 -Node: Break Commands158096 -Node: Save Breakpoints161320 -Node: Error in Breakpoints162496 -Node: Breakpoint-related Warnings163227 -Node: Continuing and Stepping165554 -Node: Signals174914 -Ref: extra signal information179186 -Node: Thread Stops180689 -Node: All-Stop Mode181788 -Node: Non-Stop Mode185686 -Node: Background Execution189163 -Node: Thread-Specific Breakpoints191732 -Node: Interrupted System Calls193054 -Node: Observer Mode194568 -Node: Reverse Execution198007 -Ref: Reverse Execution-Footnote-1202634 -Ref: Reverse Execution-Footnote-2203261 -Node: Process Record and Replay203311 -Node: Stack210558 -Node: Frames212051 -Node: Backtrace214803 -Ref: Backtrace-Footnote-1220016 -Node: Selection220204 -Node: Frame Info223068 -Node: Source225399 -Node: List226465 -Node: Specify Location229078 -Node: Edit232724 -Ref: Edit-Footnote-1234199 -Node: Search234434 -Node: Source Path235242 -Ref: set substitute-path241609 -Node: Machine Code243830 -Node: Data250504 -Node: Expressions253174 -Node: Ambiguous Expressions255266 -Node: Variables258500 -Node: Arrays263003 -Node: Output Formats265534 -Ref: Output Formats-Footnote-1268722 -Node: Memory268879 -Node: Auto Display275033 -Node: Print Settings279575 -Node: Pretty Printing293179 -Node: Pretty-Printer Introduction293692 -Node: Pretty-Printer Example295447 -Node: Pretty-Printer Commands296225 -Node: Value History298649 -Node: Convenience Vars301070 -Node: Registers305805 -Ref: Registers-Footnote-1310482 -Node: Floating Point Hardware310877 -Node: Vector Unit311409 -Node: OS Information311796 -Node: Memory Region Attributes314441 -Node: Dump/Restore Files319111 -Node: Core File Generation321416 -Node: Character Sets322650 -Node: Caching Remote Data329015 -Ref: Caching Remote Data-Footnote-1331280 -Node: Searching Memory331518 -Node: Optimized Code334395 -Node: Inline Functions336005 -Node: Macros338975 -Node: Tracepoints346078 -Node: Set Tracepoints348139 -Node: Create and Delete Tracepoints351077 -Node: Enable and Disable Tracepoints355965 -Node: Tracepoint Passcounts356749 -Node: Tracepoint Conditions358176 -Node: Trace State Variables359870 -Node: Tracepoint Actions362060 -Node: Listing Tracepoints367400 -Node: Listing Static Tracepoint Markers368521 -Node: Starting and Stopping Trace Experiments370367 -Node: Tracepoint Restrictions374781 -Node: Analyze Collected Data378534 -Node: tfind379839 -Node: tdump384261 -Node: save tracepoints386776 -Node: Tracepoint Variables387272 -Node: Trace Files388400 -Node: Overlays389858 -Node: How Overlays Work390578 -Ref: A code overlay393138 -Node: Overlay Commands396576 -Node: Automatic Overlay Debugging400766 -Node: Overlay Sample Program402907 -Node: Languages404667 -Node: Setting405830 -Node: Filenames407532 -Node: Manually408343 -Node: Automatically409552 -Node: Show410613 -Node: Checks411935 -Node: Type Checking413325 -Node: Range Checking416058 -Node: Supported Languages418459 -Node: C419720 -Node: C Operators421011 -Node: C Constants425330 -Node: C Plus Plus Expressions427734 -Node: C Defaults431277 -Node: C Checks431960 -Node: Debugging C432683 -Node: Debugging C Plus Plus433167 -Node: Decimal Floating Point436354 -Node: D437613 -Node: Objective-C437879 -Node: Method Names in Commands438341 -Node: The Print Command with Objective-C440036 -Node: OpenCL C440687 -Node: OpenCL C Datatypes440962 -Node: OpenCL C Expressions441337 -Node: OpenCL C Operators441694 -Node: Fortran441926 -Node: Fortran Operators442648 -Node: Fortran Defaults443504 -Node: Special Fortran Commands443889 -Node: Pascal444395 -Node: Modula-2444910 -Node: M2 Operators445885 -Node: Built-In Func/Proc448884 -Node: M2 Constants451745 -Node: M2 Types453346 -Node: M2 Defaults456565 -Node: Deviations457165 -Node: M2 Checks458266 -Node: M2 Scope459084 -Node: GDB/M2460108 -Node: Ada461020 -Node: Ada Mode Intro462083 -Node: Omissions from Ada463993 -Node: Additions to Ada468347 -Node: Stopping Before Main Program472277 -Node: Ada Tasks472806 -Node: Ada Tasks and Core Files479219 -Node: Ravenscar Profile480137 -Node: Ada Glitches481207 -Node: Unsupported Languages484001 -Node: Symbols484691 -Node: Altering499089 -Node: Assignment500058 -Node: Jumping503163 -Node: Signaling505298 -Node: Returning506429 -Node: Calling509781 -Node: Patching512808 -Node: GDB Files513885 -Node: Files514530 -Ref: Shared Libraries527365 -Ref: Files-Footnote-1538718 -Node: Separate Debug Files538893 -Node: Index Files550463 -Node: Symbol Errors551806 -Node: Data Files555419 -Node: Targets556375 -Node: Active Targets557855 -Node: Target Commands558929 -Ref: load563202 -Node: Byte Order564183 -Node: Remote Debugging565160 -Node: Connecting566422 -Node: File Transfer571362 -Node: Server572302 -Ref: Monitor Commands for gdbserver579952 -Ref: Server-Footnote-1584606 -Node: Remote Configuration584726 -Ref: set remotebreak585750 -Ref: set remote hardware-watchpoint-limit587214 -Ref: set remote hardware-breakpoint-limit587214 -Ref: set remote exec-file587496 -Node: Remote Stub593764 -Node: Stub Contents596661 -Node: Bootstrapping598772 -Node: Debug Session602581 -Node: Configurations604141 -Node: Native604910 -Node: HP-UX605545 -Node: BSD libkvm Interface605834 -Node: SVR4 Process Information606905 -Node: DJGPP Native610335 -Node: Cygwin Native616915 -Node: Non-debug DLL Symbols620864 -Node: Hurd Native625412 -Node: Neutrino630675 -Node: Darwin631065 -Node: Embedded OS632323 -Node: VxWorks632799 -Node: VxWorks Connection635016 -Node: VxWorks Download635950 -Node: VxWorks Attach637685 -Node: Embedded Processors638083 -Node: ARM639262 -Node: M32R/D643383 -Node: M68K645085 -Node: MicroBlaze645378 -Node: MIPS Embedded646828 -Node: OpenRISC 1000651778 -Node: PowerPC Embedded654633 -Node: PA658261 -Node: Sparclet658550 -Node: Sparclet File660034 -Node: Sparclet Connection660914 -Node: Sparclet Download661392 -Node: Sparclet Execution662441 -Node: Sparclite663032 -Node: Z8000663407 -Node: AVR664791 -Node: CRIS665154 -Node: Super-H666132 -Node: Architectures667247 -Node: i386667669 -Node: A29K668351 -Node: Alpha669190 -Node: MIPS669323 -Node: HPPA671947 -Node: SPU672466 -Node: PowerPC674654 -Node: Controlling GDB675372 -Node: Prompt676198 -Node: Editing676977 -Node: Command History677920 -Node: Screen Size681324 -Node: Numbers683158 -Node: ABI685135 -Node: Messages/Warnings688064 -Ref: confirmation requests689490 -Node: Debugging Output690697 -Node: Other Misc Settings697255 -Node: Extending GDB698282 -Node: Sequences699773 -Node: Define700368 -Node: Hooks703981 -Node: Command Files706348 -Node: Output711418 -Node: Python716351 -Node: Python Commands717270 -Node: Python API718945 -Node: Basic Python720753 -Node: Exception Handling727724 -Node: Values From Inferior730223 -Node: Types In Python738733 -Node: Pretty Printing API746823 -Node: Selecting Pretty-Printers750722 -Node: Writing a Pretty-Printer753055 -Node: Inferiors In Python758369 -Node: Events In Python761285 -Node: Threads In Python765736 -Node: Commands In Python768367 -Node: Parameters In Python777183 -Node: Functions In Python782638 -Node: Progspaces In Python784751 -Node: Objfiles In Python786113 -Node: Frames In Python788045 -Node: Blocks In Python792273 -Node: Symbols In Python794477 -Node: Symbol Tables In Python801197 -Node: Breakpoints In Python803734 -Node: Lazy Strings In Python810585 -Node: Auto-loading812859 -Node: objfile-gdb.py file814755 -Node: .debug_gdb_scripts section816010 -Node: Which flavor to choose?817387 -Node: Python modules819204 -Node: gdb.printing819512 -Node: gdb.types820587 -Node: Interpreters821574 -Node: TUI823673 -Node: TUI Overview824640 -Node: TUI Keys827073 -Node: TUI Single Key Mode829377 -Node: TUI Commands830252 -Node: TUI Configuration832636 -Node: Emacs833932 -Node: GDB/MI839409 -Node: GDB/MI General Design841257 -Node: Context management843780 -Node: Asynchronous and non-stop modes846915 -Node: Thread groups848907 -Node: GDB/MI Command Syntax851185 -Node: GDB/MI Input Syntax851428 -Node: GDB/MI Output Syntax852982 -Node: GDB/MI Compatibility with CLI856554 -Node: GDB/MI Development and Front Ends857291 -Node: GDB/MI Output Records858948 -Node: GDB/MI Result Records859320 -Node: GDB/MI Stream Records860326 -Node: GDB/MI Async Records861591 -Node: GDB/MI Frame Information867888 -Node: GDB/MI Thread Information868966 -Node: GDB/MI Ada Exception Information869945 -Node: GDB/MI Simple Examples870368 -Node: GDB/MI Command Description Format872545 -Node: GDB/MI Breakpoint Commands873425 -Node: GDB/MI Program Context891421 -Node: GDB/MI Thread Commands895689 -Node: GDB/MI Program Execution899642 -Node: GDB/MI Stack Manipulation911423 -Node: GDB/MI Variable Objects922325 -Ref: -var-set-format932057 -Ref: -var-list-children933175 -Ref: -var-update941352 -Ref: -var-set-frozen944049 -Ref: -var-set-update-range944845 -Ref: -var-set-visualizer945375 -Node: GDB/MI Data Manipulation946872 -Node: GDB/MI Tracepoint Commands964457 -Node: GDB/MI Symbol Query971786 -Node: GDB/MI File Commands972475 -Node: GDB/MI Target Manipulation975812 -Node: GDB/MI File Transfer Commands982034 -Node: GDB/MI Miscellaneous Commands983356 -Ref: -interpreter-exec992888 -Node: Annotations995197 -Node: Annotations Overview996116 -Node: Server Prefix998579 -Node: Prompting999313 -Node: Errors1000830 -Node: Invalidation1001726 -Node: Annotations for Running1002203 -Node: Source Annotations1003723 -Node: JIT Interface1004648 -Node: Declarations1006366 -Node: Registering Code1007753 -Node: Unregistering Code1008725 -Node: GDB Bugs1009326 -Node: Bug Criteria1010055 -Node: Bug Reporting1010932 -Node: Command Line Editing1018555 -Node: Introduction and Notation1019207 -Node: Readline Interaction1020827 -Node: Readline Bare Essentials1022016 -Node: Readline Movement Commands1023803 -Node: Readline Killing Commands1024766 -Node: Readline Arguments1026684 -Node: Searching1027726 -Node: Readline Init File1029875 -Node: Readline Init File Syntax1030938 -Node: Conditional Init Constructs1042870 -Node: Sample Init File1045401 -Node: Bindable Readline Commands1048516 -Node: Commands For Moving1049571 -Node: Commands For History1050430 -Node: Commands For Text1053552 -Node: Commands For Killing1056276 -Node: Numeric Arguments1058416 -Node: Commands For Completion1059553 -Node: Keyboard Macros1061095 -Node: Miscellaneous Commands1061664 -Node: Readline vi Mode1065023 -Node: Using History Interactively1065940 -Node: History Interaction1066442 -Node: Event Designators1067864 -Node: Word Designators1068797 -Node: Modifiers1070434 -Node: In Memoriam1071659 -Node: Formatting Documentation1072542 -Ref: Formatting Documentation-Footnote-11075879 -Node: Installing GDB1075955 -Node: Requirements1076527 -Ref: Expat1077096 -Node: Running Configure1079541 -Node: Separate Objdir1083170 -Node: Config Names1086090 -Node: Configure Options1087547 -Node: System-wide configuration1089917 -Node: Maintenance Commands1091212 -Ref: maint info breakpoints1092396 -Node: Remote Protocol1106431 -Node: Overview1107020 -Ref: Binary Data1109582 -Node: Packets1111841 -Ref: thread-id syntax1112741 -Ref: extended mode1114186 -Ref: bc1115907 -Ref: bs1116117 -Ref: read registers packet1117543 -Ref: cycle step packet1119387 -Ref: write register packet1121263 -Ref: step with signal packet1122170 -Ref: vStopped packet1128451 -Ref: X packet1128794 -Ref: insert breakpoint or watchpoint packet1129080 -Node: Stop Reply Packets1131842 -Node: General Query Packets1136582 -Ref: QNonStop1145522 -Ref: QPassSignals1146146 -Ref: qSearch memory1148223 -Ref: QStartNoAckMode1148721 -Ref: qSupported1149251 -Ref: multiprocess extensions1158193 -Ref: qXfer read1162023 -Ref: qXfer auxiliary vector read1162517 -Ref: qXfer target description read1162866 -Ref: qXfer library list read1163310 -Ref: qXfer memory map read1163956 -Ref: qXfer sdata read1164342 -Ref: qXfer siginfo read1164806 -Ref: qXfer spu read1165202 -Ref: qXfer threads read1165725 -Ref: qXfer traceframe info read1166127 -Ref: qXfer osdata read1166544 -Ref: qXfer write1167746 -Ref: qXfer siginfo write1168303 -Ref: qXfer spu write1168699 -Ref: General Query Packets-Footnote-11170786 -Node: Architecture-Specific Protocol Details1171113 -Node: Tracepoint Packets1172626 -Node: Host I/O Packets1189073 -Node: Interrupts1193215 -Node: Notification Packets1195118 -Node: Remote Non-Stop1197389 -Node: Packet Acknowledgment1201648 -Node: Examples1203763 -Node: File-I/O Remote Protocol Extension1204389 -Node: File-I/O Overview1204851 -Node: Protocol Basics1207048 -Node: The F Request Packet1209280 -Node: The F Reply Packet1210181 -Node: The Ctrl-C Message1211099 -Node: Console I/O1212728 -Node: List of Supported Calls1213945 -Node: open1214307 -Node: close1216801 -Node: read1217183 -Node: write1217790 -Node: lseek1218557 -Node: rename1219435 -Node: unlink1220831 -Node: stat/fstat1221770 -Node: gettimeofday1222657 -Node: isatty1223092 -Node: system1223688 -Node: Protocol-specific Representation of Datatypes1225230 -Node: Integral Datatypes1225607 -Node: Pointer Values1226414 -Node: Memory Transfer1227122 -Node: struct stat1227742 -Node: struct timeval1229944 -Node: Constants1230461 -Node: Open Flags1230910 -Node: mode_t Values1231251 -Node: Errno Values1231743 -Node: Lseek Flags1232554 -Node: Limits1232739 -Node: File-I/O Examples1233099 -Node: Library List Format1234215 -Node: Memory Map Format1236979 -Node: Thread List Format1239539 -Node: Traceframe Info Format1240357 -Node: Agent Expressions1241814 -Node: General Bytecode Design1244635 -Node: Bytecode Descriptions1249435 -Node: Using Agent Expressions1261581 -Node: Varying Target Capabilities1263559 -Node: Rationale1264721 -Node: Target Descriptions1272107 -Node: Retrieving Descriptions1274167 -Node: Target Description Format1275252 -Node: Predefined Target Types1284302 -Node: Standard Target Features1285687 -Node: ARM Features1287458 -Node: i386 Features1288950 -Node: MIPS Features1290054 -Node: M68K Features1290999 -Node: PowerPC Features1291662 -Node: Operating System Information1292946 -Node: Process list1293784 -Node: Trace File Format1294846 -Node: Copying1296827 -Node: GNU Free Documentation License1334414 -Node: Index1359572 - -End Tag Table |